Plugin Configuration

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

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

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 id and version (optional) that the service writes to.
services[].readsFrom	array[{id: string, version?: string}]	-	Array of data stores id and version (optional) that the service reads from.

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

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

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

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

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)

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

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

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

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

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

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

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

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

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

Need Help?

• GitHub Issues
• Discord Community
• Email: hello@eventcatalog.dev