Skip to main content

Features

The EventCatalog Azure Schema Registry plugin provides a comprehensive set of features to help you document and visualize your Azure Event Hubs architecture.

Schema Import and Synchronization​

Import Schemas from Azure Schema Registry​

The plugin connects to your Azure Schema Registry and imports schemas based on your configuration. Unlike some other registries, Azure Schema Registry requires explicit schema definitions since it doesn't provide a "list all schemas" API.

{
  schemaRegistryUrl: 'https://your-namespace.servicebus.windows.net',
  services: [
    {
      id: 'orders-service',
      version: '1.0.0',
      sends: [
        { id: 'order-created', schemaGroup: 'com.example.orders' },
      ],
    },
  ],
}

Automatic Multi-Version Support​

The plugin automatically fetches and documents the latest 5 versions of each schema from Azure Schema Registry. This happens automatically without any configuration needed.

How it works:

  1. Plugin fetches up to 5 most recent versions of each configured schema
  2. Latest version is written to the root directory (e.g., /events/order-created/)
  3. Older versions are stored in versioned folders (e.g., /events/order-created/versioned/1/)
  4. Custom documentation (markdown, badges, owners) is persisted between versions

Example: If your order-created schema has versions 1, 2, 3, and 4:

  • Version 4 (latest) → /events/order-created/ (root)
  • Version 3 → /events/order-created/versioned/3/
  • Version 2 → /events/order-created/versioned/2/
  • Version 1 → /events/order-created/versioned/1/

Benefits:

  • Complete version history without extra configuration
  • See how schemas evolved over time
  • Compare different versions side-by-side
  • Understand breaking vs non-breaking changes
  • Teams can reference specific versions they're using

This ensures your documentation stays in sync with your schemas while preserving the semantic meaning you've added across all versions.

Multiple Schema Formats​

The plugin supports both schema formats available in Azure Schema Registry:

  • Avro - Binary serialization format with compact data representation
  • JSON Schema - JSON-based schema definition for flexible data structures

The plugin automatically detects the format and displays it correctly in your catalog.

Message Type Classification​

Events, Commands, and Queries​

Document your messages using different types to better represent your architecture:

sends: [
  {
    id: 'order-created',
    schemaGroup: 'com.example.orders',
    messageType: 'event', // Something that happened
  },
  {
    id: 'create-order',
    schemaGroup: 'com.example.orders',
    messageType: 'command', // Request to do something
  },
],
receives: [
  {
    id: 'get-order',
    schemaGroup: 'com.example.orders',
    messageType: 'query', // Request for information
  },
]

Benefits:

  • Clear architectural patterns in your documentation
  • Better understanding of message flow and intent
  • Improved discoverability for teams

Custom Schema Names​

User-Friendly Display Names​

Provide readable names for technical schema identifiers:

{
  id: 'app.orders.created.v2.avro',
  schemaGroup: 'com.company.orders',
  name: 'Order Created Event', // User-friendly name
}

Benefits:

  • Technical schema IDs preserved in the catalog
  • User-friendly names for documentation
  • Better search and discovery for non-technical users

Multi-Registry Support​

Fetch from Multiple Azure Schema Registries​

Override the registry URL per schema to fetch from multiple registries:

{
  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 registry
        },
        {
          id: 'order-shipped',
          schemaGroup: 'com.example.shipping',
          schemaRegistryUrl: 'https://shipping-namespace.servicebus.windows.net',
          // Uses different registry
        },
      ],
    },
  ],
}

Use Cases:

  • Multi-region deployments
  • Separate registries for different business units
  • Development/staging/production registries
  • Legacy and new registry migrations

Domain-Driven Documentation​

Organize Services into Domains​

Group related services into domains for better organization:

{
  domain: {
    id: 'orders-domain',
    name: 'Orders Domain',
    version: '1.0.0',
  },
  services: [
    { id: 'orders-service', version: '1.0.0', /* ... */ },
    { id: 'inventory-service', version: '1.0.0', /* ... */ },
  ],
}

Benefits:

  • Logical grouping of related services
  • Better navigation for large architectures
  • Align with domain-driven design principles
  • Visualize domain boundaries

Flexible Authentication​

REST API with Bearer Token​

The plugin uses Azure's REST API with Bearer token authentication for maximum compatibility and flexibility.

Getting an Access Token​

For Local Development:

export AZURE_SCHEMA_REGISTRY_TOKEN=$(az account get-access-token --resource https://eventhubs.azure.net --query accessToken -o tsv)

For CI/CD:

# Using service principal
export AZURE_SCHEMA_REGISTRY_TOKEN=$(az login --service-principal \
  --username $AZURE_CLIENT_ID \
  --password $AZURE_CLIENT_SECRET \
  --tenant $AZURE_TENANT_ID && \
  az account get-access-token --resource https://eventhubs.azure.net --query accessToken -o tsv)

Benefits:

  • Works across all environments
  • No Azure SDK packages required
  • Simple Bearer token authentication
  • Easy to integrate with CI/CD pipelines
  • Compatible with any Azure authentication method
Token Expiration

Azure access tokens typically expire after 1 hour. For long-running processes, you may need to refresh the token periodically.

Metadata Persistence​

Preserve Custom Documentation​

When schemas are versioned, the plugin preserves:

  • Custom markdown - Your detailed documentation
  • Badges - Visual indicators and labels
  • Owners - Team and individual assignments
  • Attachments - Related files and links
  • Repository links - Source code references

Example:

# Order Created Event

This event is emitted when a new order is successfully placed in the system.

## Business Rules
- Only emitted after payment is confirmed
- Includes customer and line item details
- Triggers inventory reservation

## Related Documentation
- [Order Processing Guide](link)
- [Payment Integration](link)

This markdown persists when the schema is updated to version 2, 3, etc.

Service Documentation​

Document Producers and Consumers​

Clearly define which services send and receive which messages:

{
  id: 'orders-service',
  version: '1.0.0',
  sends: [
    { id: 'order-created', schemaGroup: 'com.example.orders' },
  ],
  receives: [
    { id: 'payment-received', schemaGroup: 'com.example.payments' },
  ],
}

In EventCatalog, you can see:

  • All messages a service produces
  • All messages a service consumes
  • Service dependencies
  • Message flow visualization

Search and Discovery​

Find Schemas Easily​

EventCatalog provides powerful search capabilities:

  • Search by schema name
  • Filter by domain
  • Filter by service
  • Filter by message type (event/command/query)
  • Full-text search across documentation

Versioning and History​

Track Schema Evolution​

The plugin automatically imports the latest 5 versions of each schema, giving you complete visibility into schema evolution:

Features:

  • Automatic version import - No configuration needed, fetches latest 5 versions
  • Version timeline - See all versions of each schema
  • Side-by-side comparison - Compare versions to understand changes
  • Latest in root - Current version easily accessible, older versions organized in versioned folders
  • Breaking change detection - Understand impact of schema changes
  • Version-specific references - Teams can reference the exact version they're using

Example Structure:

/events/order-created/           ← Latest version (v4)
/events/order-created/versioned/1/  ← Older version
/events/order-created/versioned/2/  ← Older version
/events/order-created/versioned/3/  ← Older version

This comprehensive versioning support helps teams understand how schemas have evolved and make informed decisions about upgrades.

Data Store Integration​

Document Data Dependencies​

Link services to their data stores:

{
  id: 'orders-service',
  version: '1.0.0',
  writesTo: [
    { id: 'orders-database', version: '1.0.0' },
  ],
  readsFrom: [
    { id: 'customer-cache', version: '1.0.0' },
  ],
}

Configuration Validation​

Catch Errors Early​

The plugin validates your configuration and provides helpful error messages:

  • Missing required fields
  • Invalid schema group references
  • Authentication issues
  • Registry connectivity problems

Need a Feature?​

Have a feature request? Let us know: