Copy as Markdown[View as Markdown](/docs/plugins/azure-schema-registry/plugin-configuration.md) *** # Plugin Configuration ## Overview[​](#overview "Direct link to Overview") The EventCatalog Azure Schema Registry plugin is configured in the `eventcatalog.config.js` file inside the `generators` array. Authentication The plugin uses Azure's REST API with Bearer token authentication. You must set the `AZURE_SCHEMA_REGISTRY_TOKEN` environment variable. Example .env file ``` # EventCatalog license key export EVENTCATALOG_LICENSE_KEY_AZURE_SCHEMA_REGISTRY=your-license-key # Azure Schema Registry access token export AZURE_SCHEMA_REGISTRY_TOKEN=your-azure-access-token ``` Get the token using Azure CLI: ``` az account get-access-token --resource https://eventhubs.azure.net --query accessToken -o tsv ``` ## Required Configuration Options[​](#required-configuration-options "Direct link to Required Configuration Options") | Option | Type | Required | Description | | ------------------- | -------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `schemaRegistryUrl` | `string` | Yes | The URL of your Azure Schema Registry (e.g., `https://your-namespace.servicebus.windows.net`). You can find this in the Azure Portal under your Event Hubs namespace. | | `services` | `array` | Yes | List of services and their schema mappings. **Note:** Unlike Confluent, Azure Schema Registry doesn't provide an API to list all schemas, so you must explicitly define which schemas to fetch. | ## Optional Configuration Options[​](#optional-configuration-options "Direct link to Optional Configuration Options") ### Services[​](#services "Direct link to Services") You can assign schemas to services (producers/consumers) in your architecture. | Option | Type | Default | Description | | ---------------------- | --------------------------------------- | --------------- | ---------------------------------------------------------------------------------------------------------------------------- | | `services` | `array` | - | List of services to document with their schemas. | | `services[].id` | `string` | - | EventCatalog ID for the service (e.g., `orders-service`). | | `services[].name` | `string` | `services[].id` | Display name for the service (e.g., `Orders Service`). | | `services[].version` | `string` | - | Version of the service (e.g., `1.0.0`). | | `services[].sends` | `array` | - | Array of schema filters for messages this service sends. | | `services[].receives` | `array` | - | Array of schema filters for messages this service receives. | | `services[].writesTo` | `array[{id: string, version?: string}]` | - | Array of [data stores](/docs/development/guides/data/introduction.md) id and version (optional) that the service writes to. | | `services[].readsFrom` | `array[{id: string, version?: string}]` | - | Array of [data stores](/docs/development/guides/data/introduction.md) id and version (optional) that the service reads from. | ### Schema Filters (sends/receives)[​](#schema-filters-sendsreceives "Direct link to Schema Filters (sends/receives)") Each schema in `sends` and `receives` arrays can have the following properties: | Option | Type | Default | Description | | ------------------- | --------------------------------- | -------------------------- | ----------------------------------------------------------------------------------------------------------------- | | `id` | `string` | **Required** | The schema name in the Azure Schema Registry. | | `schemaGroup` | `string` | **Required** | The schema group name in the registry. | | `name` | `string` | `id` | Custom display name for the schema in EventCatalog. Useful for making technical schema names more user-friendly. | | `messageType` | `'event' \| 'command' \| 'query'` | `'event'` | The type of message this schema represents. | | `schemaRegistryUrl` | `string` | Global `schemaRegistryUrl` | Override the registry URL for this specific schema. Useful when schemas are in different Azure Schema Registries. | ### Domains[​](#domains "Direct link to Domains") You can define and assign domains to organize your services. | Option | Type | Default | Description | | ---------------- | -------- | ------- | ------------------------------------------------------- | | `domain` | `object` | - | Optional domain configuration to group services. | | `domain.id` | `string` | - | EventCatalog ID for the domain (e.g., `orders-domain`). | | `domain.name` | `string` | - | Display name of the domain (e.g., `Orders Domain`). | | `domain.version` | `string` | - | Version of the domain (e.g., `1.0.0`). | ### License[​](#license "Direct link to License") | Option | Type | Default | Description | | ------------ | -------- | ------------ | -------------------------------------------------------------------------------------------------------------------- | | `licenseKey` | `string` | From env var | EventCatalog license key. Can also be set via `EVENTCATALOG_LICENSE_KEY_AZURE_SCHEMA_REGISTRY` environment variable. | ## Example Configurations[​](#example-configurations "Direct link to Example Configurations") ### Basic Configuration[​](#basic-configuration "Direct link to Basic Configuration") Import schemas from Azure Schema Registry and assign them to services: eventcatalog.config.js ``` generators: [ [ '@eventcatalog/generator-azure-schema-registry', { schemaRegistryUrl: 'https://your-namespace.servicebus.windows.net', services: [ { id: 'orders-service', name: 'Orders Service', version: '1.0.0', sends: [ { id: 'order-created', schemaGroup: 'com.example.orders', }, ], receives: [ { id: 'payment-received', schemaGroup: 'com.example.payments', }, ], }, ], }, ], ]; ``` ### Custom Schema Names[​](#custom-schema-names "Direct link to Custom Schema Names") Provide user-friendly display names for your schemas: eventcatalog.config.js ``` generators: [ [ '@eventcatalog/generator-azure-schema-registry', { schemaRegistryUrl: 'https://your-namespace.servicebus.windows.net', services: [ { id: 'orders-service', version: '1.0.0', sends: [ { id: 'app.orders.created.v1', schemaGroup: 'com.example.orders', name: 'Order Created Event', // Custom friendly name }, ], }, ], }, ], ]; ``` ### Message Types (Events, Commands, Queries)[​](#message-types-events-commands-queries "Direct link to Message Types (Events, Commands, Queries)") Document different message types to better represent your architecture: eventcatalog.config.js ``` generators: [ [ '@eventcatalog/generator-azure-schema-registry', { schemaRegistryUrl: 'https://your-namespace.servicebus.windows.net', services: [ { id: 'orders-service', version: '1.0.0', sends: [ { id: 'order-created', schemaGroup: 'com.example.orders', name: 'Order Created Event', messageType: 'event', // Event message }, { id: 'create-order', schemaGroup: 'com.example.orders', name: 'Create Order Command', messageType: 'command', // Command message }, ], receives: [ { id: 'get-order', schemaGroup: 'com.example.orders', name: 'Get Order Query', messageType: 'query', // Query message }, ], }, ], }, ], ]; ``` ### Multiple Schema Registries[​](#multiple-schema-registries "Direct link to Multiple Schema Registries") Fetch schemas from multiple Azure Schema Registries in one configuration: eventcatalog.config.js ``` generators: [ [ '@eventcatalog/generator-azure-schema-registry', { // Default registry URL schemaRegistryUrl: 'https://primary-namespace.servicebus.windows.net', services: [ { id: 'orders-service', version: '1.0.0', sends: [ { id: 'order-created', schemaGroup: 'com.example.orders', // Uses default schemaRegistryUrl }, { id: 'order-shipped', schemaGroup: 'com.example.shipping', name: 'Order Shipped Event', // Override to fetch from different registry schemaRegistryUrl: 'https://shipping-namespace.servicebus.windows.net', }, ], }, ], }, ], ]; ``` ### With Domains[​](#with-domains "Direct link to With Domains") Organize your services into domains: eventcatalog.config.js ``` generators: [ [ '@eventcatalog/generator-azure-schema-registry', { schemaRegistryUrl: 'https://your-namespace.servicebus.windows.net', domain: { id: 'orders-domain', name: 'Orders Domain', version: '1.0.0', }, services: [ { id: 'orders-service', name: 'Orders Service', version: '1.0.0', sends: [ { id: 'order-created', schemaGroup: 'com.example.orders' }, ], }, { id: 'inventory-service', name: 'Inventory Service', version: '1.0.0', receives: [ { id: 'order-created', schemaGroup: 'com.example.orders' }, ], }, ], }, ], ]; ``` ### Multiple Domains[​](#multiple-domains "Direct link to Multiple Domains") You can configure the plugin multiple times to document different domains: eventcatalog.config.js ``` generators: [ // Orders Domain [ '@eventcatalog/generator-azure-schema-registry', { schemaRegistryUrl: 'https://your-namespace.servicebus.windows.net', domain: { id: 'orders-domain', name: 'Orders Domain', version: '1.0.0', }, services: [ { id: 'orders-service', version: '1.0.0', sends: [ { id: 'order-created', schemaGroup: 'com.example.orders' }, ], }, ], }, ], // Payments Domain [ '@eventcatalog/generator-azure-schema-registry', { schemaRegistryUrl: 'https://your-namespace.servicebus.windows.net', domain: { id: 'payments-domain', name: 'Payments Domain', version: '1.0.0', }, services: [ { id: 'payments-service', version: '1.0.0', sends: [ { id: 'payment-received', schemaGroup: 'com.example.payments' }, ], }, ], }, ], ]; ``` ## Schema Group Naming[​](#schema-group-naming "Direct link to Schema Group Naming") Azure Schema Registry organizes schemas into schema groups. When configuring the plugin, make sure to use the exact schema group name as it appears in your Azure Schema Registry. Common schema group naming patterns: * Namespace style: `com.example.orders`, `com.example.payments` * Application style: `myapp-orders`, `myapp-inventory` * Environment-based: `production.orders`, `staging.orders` You can find your schema groups in the Azure Portal under your Event Hubs namespace > Schema Registry. ## Supported Schema Formats[​](#supported-schema-formats "Direct link to Supported Schema Formats") The plugin supports the following schema formats from Azure Schema Registry: * **Avro** - Schemas with `.avsc` file extension * **JSON Schema** - Schemas with `.json` file extension The plugin automatically detects the schema format and generates the appropriate documentation in EventCatalog. ## Troubleshooting[​](#troubleshooting "Direct link to Troubleshooting") ### Authentication Issues[​](#authentication-issues "Direct link to Authentication Issues") If you encounter authentication errors: 1. **Token not set**: Ensure `AZURE_SCHEMA_REGISTRY_TOKEN` environment variable is set 2. **Token expired**: Azure access tokens expire after 1 hour. Re-run `az account get-access-token` to get a fresh token 3. **Invalid token**: Verify you're using the correct resource (`https://eventhubs.azure.net`) when obtaining the token 4. **Permission errors**: Ensure your Azure user/service principal has "Azure Event Hubs Data Receiver" or "Azure Event Hubs Data Owner" role on the Event Hubs namespace ### Schema Not Found[​](#schema-not-found "Direct link to Schema Not Found") If the plugin can't find a schema: 1. Verify the `schemaGroup` and `id` values match exactly what's in Azure Schema Registry 2. Check that your authenticated user/identity has read permissions on the schema registry 3. Ensure the schema exists in the specified schema group ### License Key Issues[​](#license-key-issues "Direct link to License Key Issues") If you have problems with your license key: 1. Ensure `https://api.eventcatalog.cloud` is not blocked by your firewall 2. Verify your license key is correctly set in the `.env` file or passed via configuration 3. Check your license hasn't expired at [EventCatalog Cloud](https://eventcatalog.cloud) ## Need Help?[​](#need-help "Direct link to Need Help?") * [GitHub Issues](https://github.com/event-catalog/eventcatalog/issues) * [Discord Community](https://eventcatalog.dev/discord) * Email: