# Features

Copy as Markdown[View as Markdown](/docs/plugins/apicurio/features.md)

***

## Schema Version Management[​](#schema-version-management "Direct link to Schema Version Management")

### Track All Schema Versions[​](#track-all-schema-versions "Direct link to Track All Schema Versions")

The Apicurio Registry plugin supports comprehensive schema version management through the `includeAllVersions` configuration option.

When `includeAllVersions` is set to `true`, the plugin will:

* Import all versions of each schema from your Apicurio Registry
* Create versioned entries in EventCatalog for each schema version
* Maintain version history for your schemas
* Allow you to view and compare different versions

When `includeAllVersions` is set to `false` (default):

* Only the latest version of each schema is imported
* This is useful for keeping your catalog focused on current schemas

**Example:**

```
{
  registryUrl: 'http://localhost:8080',
  includeAllVersions: true, // Import all versions
}
```

**Use cases for version tracking:**

* Understanding schema evolution over time
* Maintaining backwards compatibility documentation
* Tracking breaking changes in your schemas
* Compliance and audit requirements

### Adding Semantic Meaning to Schemas[​](#adding-semantic-meaning-to-schemas "Direct link to Adding Semantic Meaning to Schemas")

Using the Apicurio Registry plugin, you can import your schemas and then add business context and semantic meaning to them.

When you import a schema into EventCatalog, an event, command, or query will be created with the schema attached. Each message has its own `index.mdx` file where you can add:

* Title and summary
* Detailed descriptions
* Business context and use cases
* Custom components and visualizations
* Ownership and team information

This gives you the opportunity to add meaning to your schemas and make them easier to understand for teams across your organization.

**Important:** When you reimport your schemas, your semantic meaning will persist between imports. The plugin will:

* Download the latest version of the schema from Apicurio Registry
* Update the schema file in EventCatalog
* Preserve your markdown documentation and business context

## Integration with OpenAPI and AsyncAPI Generators[​](#integration-with-openapi-and-asyncapi-generators "Direct link to Integration with OpenAPI and AsyncAPI Generators")

One of the powerful features of the Apicurio Registry plugin is its ability to work with other EventCatalog generators.

You can store OpenAPI and AsyncAPI specifications in your Apicurio Registry and use them to generate comprehensive service documentation automatically.

Plugin Licenses Required

The OpenAPI and AsyncAPI generators are separate licensed plugins. You'll need to obtain license keys for each plugin you want to use from [EventCatalog Cloud](https://eventcatalog.cloud). A 14-day free trial is available for both plugins.

See the [OpenAPI Plugin](/docs/plugins/openapi/intro.md) and [AsyncAPI Plugin](/docs/plugins/asyncapi/intro.md) documentation for more details on installation and configuration.

### How it works[​](#how-it-works "Direct link to How it works")

1. Store your OpenAPI/AsyncAPI specifications in Apicurio Registry
2. Configure the Apicurio plugin to attach these specifications to services
3. Specify which EventCatalog generator should process each specification
4. The plugin will fetch the specification and run the appropriate generator

### Benefits[​](#benefits "Direct link to Benefits")

* **Centralized Storage**: Keep all your schemas and specifications in one place (Apicurio Registry)
* **Automated Documentation**: Generate service documentation from specifications automatically
* **Consistent Workflow**: Use the same import process for schemas and specifications
* **Domain Awareness**: Specifications inherit domain configuration from the Apicurio plugin

### Example Configuration[​](#example-configuration "Direct link to Example Configuration")

```
services: [{
  id: 'Orders Service',
  version: '1.0.0',
  specifications: [
    {
      type: 'openapi',
      artifactId: 'OrdersAPI-OPENAPI',
      version: 'latest',
      generator: ['@eventcatalog/generator-openapi', {
        // OpenAPI generator options
      }]
    },
    {
      type: 'asyncapi',
      artifactId: 'OrdersEvents-ASYNCAPI',
      version: '2.0.0',
      generator: ['@eventcatalog/generator-asyncapi', {
        // AsyncAPI generator options
      }]
    }
  ]
}]
```

This configuration will:

1. Fetch the OpenAPI specification from Apicurio Registry
2. Save it to the service directory
3. Run the OpenAPI generator to document REST endpoints
4. Fetch the AsyncAPI specification
5. Run the AsyncAPI generator to document async events
6. All within the context of the Orders Service and its domain

## Flexible Filtering System[​](#flexible-filtering-system "Direct link to Flexible Filtering System")

The Apicurio Registry plugin provides a powerful filtering system to control which schemas are assigned to services.

### Filter Types[​](#filter-types "Direct link to Filter Types")

* **Exact Matching**: Match schemas by exact artifact ID
* **Prefix Matching**: Match schemas that start with a specific string
* **Suffix Matching**: Match schemas that end with a specific string
* **Includes Matching**: Match schemas that contain a specific string

### Use Cases[​](#use-cases "Direct link to Use Cases")

**Exact matching** is useful when you know the specific schemas a service interacts with:

```
sends: [{ events: ['order-placed', 'order-cancelled'] }]
```

**Prefix matching** is useful for namespaced schemas:

```
sends: [{ events: { prefix: 'order-' } }]
// Matches: order-placed, order-cancelled, order-updated, etc.
```

**Suffix matching** is useful for schema naming conventions:

```
receives: [{ commands: { suffix: '-command' } }]
// Matches: place-order-command, cancel-order-command, etc.
```

**Includes matching** is useful for flexible pattern matching:

```
receives: [{ events: { includes: 'inventory' } }]
// Matches: inventory-updated, check-inventory, inventory-low, etc.
```

## Message Type Classification[​](#message-type-classification "Direct link to Message Type Classification")

Document your schemas with semantic meaning by classifying them as:

* **Events**: Things that have happened (past tense) - e.g., `order-placed`, `user-registered`
* **Commands**: Requests to do something (imperative) - e.g., `place-order`, `cancel-order`
* **Queries**: Requests for information - e.g., `get-order-status`, `find-user`

This classification helps teams understand the intent and purpose of each message in your architecture.

```
services: [{
  id: 'Orders Service',
  sends: [
    { events: ['order-placed', 'order-cancelled'] }
  ],
  receives: [
    { commands: ['place-order', 'cancel-order'] },
    { queries: ['get-order-status'] }
  ]
}]
```

## Authentication Support[​](#authentication-support "Direct link to Authentication Support")

**Added in** `eventcatalog@0.1.0`

The Apicurio Registry plugin supports Bearer token authentication for secured registries.

Simply set the `APICURIO_ACCESS_TOKEN` environment variable and the plugin will automatically include the Authorization header in all requests:

```
# .env file
APICURIO_ACCESS_TOKEN=your-access-token-here
```

The plugin handles authentication transparently - all API requests will include the Bearer token when the environment variable is set.

## Visualize Schemas, Services and Domains[​](#visualize-schemas-services-and-domains "Direct link to Visualize Schemas, Services and Domains")

When you import your schemas into EventCatalog and assign them to services, you can use the EventCatalog Visualizer to see exactly how your schemas, services and domains are connected.

The visualizer helps you:

* Understand message flow between services
* Identify dependencies and relationships
* See your domain boundaries
* Navigate your event-driven architecture visually

## Downloading Schemas[​](#downloading-schemas "Direct link to Downloading Schemas")

EventCatalog supports any schema format (Avro, JSON Schema, Protobuf, etc.). When you import your schemas from Apicurio Registry you can:

* View the schema directly in EventCatalog
* Download the schema for local development
* See schema metadata and version information
* Compare different versions of the same schema

## Missing a Feature?[​](#missing-a-feature "Direct link to Missing a Feature?")

If you are missing a feature, please let us know by opening an issue on [GitHub](https://github.com/event-catalog/eventcatalog/issues) or joining our [Discord community](https://eventcatalog.dev/discord).

## Examples[​](#examples "Direct link to Examples")

See the [eventcatalog-apicurio-example](https://github.com/event-catalog/generators/tree/main/examples/generator-apicurio) for working examples.