Skip to main content

Schema Registry

Each configured catalog is a resource for referencing versioned schemas and other artifacts. Catalogs decouple Zilla's configuration from any single API or schema format: a model references a catalog by name, and the catalog resolves the actual schema at runtime.

name: zilla-namespace

catalogs:
  host_filesystem:
    type: filesystem
    options:
      subjects:
        petstore:
          path: petstore.yaml

Local Catalogs

Local catalogs bootstrap a config quickly or package a schema that rarely changes alongside the Zilla install.

Filesystem

A filesystem catalog reads schemas, API definitions, or proto files directly from disk, relative to zilla.yaml. There's no network round trip and no external registry to run, which makes it a good fit for local development, CI, or any deployment where the schema set is packaged alongside Zilla.

catalogs:
  my_catalog:
    type: filesystem
    options:
      subjects:
        my_local_file:
          path: path/to/local_file.txt

Each entry under subjects maps a name, referenced by a model's catalog field, to a file path.

Use a filesystem catalog to bootstrap a config quickly, or to package a schema that rarely changes alongside the Zilla install rather than depending on a remote registry. The http.kafka.proto.json example uses a filesystem catalog to validate a Protobuf object sent as JSON over HTTP before it's converted and produced onto Kafka.

See the filesystem catalog reference for the full set of options.

Inline

An inline catalog defines a schema directly inside zilla.yaml, next to the rest of the configuration. There's no file to package and no registry to run, so it's the fastest way to get schema validation working, at the cost of keeping the schema in the config itself.

catalog:
  type: inline
  options:
    subjects:
      items-snapshots:
        schema: |
          {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "status": {
                "type": "string"
              }
            },
            "required": [
              "id",
              "status"
            ]
          }

Each entry under subjects names a schema that a model can reference by subject.

Inline catalogs suit small, stable schemas and quick prototypes, where introducing a filesystem path or a remote registry adds more overhead than value. The http.json.schema example uses an inline catalog to validate HTTP requests and responses against a JSON Schema with no external dependency. For schemas that change independently of zilla.yaml, use a Filesystem catalog or a remote registry instead.

See the inline catalog reference for the full set of options.

Remote Catalogs

Remote catalogs fetch schemas from an external registry, so Kafka Gateway always validates against the latest published schema without a redeploy. Zilla can also pin a specific schema version or ID.

Apicurio Registry

Apicurio Registry is an open source schema and API registry. As a Kafka Gateway catalog, it lets Zilla fetch Avro, JSON, and Protobuf schemas at runtime instead of embedding them in zilla.yaml, so schema updates published to Apicurio take effect without a config change or redeploy.

catalog:
  type: apicurio-registry
  options:
    url: http://localhost:8080
    group-id: schemas
    use-id: globalId
    id-encoding: default

group-id scopes lookups to an artifact group in Apicurio. use-id and id-encoding control how Zilla encodes the schema identifier embedded in each message, and must match how producers and consumers encode it.

Reach for Apicurio Registry when your organization already centralizes schemas there, or needs AsyncAPI/OpenAPI-driven governance across services. The Petstore demo uses Apicurio to validate REST requests and responses against a JSON Schema, with updates picked up automatically as the registry changes.

See the apicurio-registry catalog reference for the full set of options.

Karapace Schema Registry

Karapace is an open source schema registry compatible with the Confluent Schema Registry API. As a Kafka Gateway catalog, it lets Zilla fetch and validate against schemas managed in Karapace, so producers and consumers stay in sync without redeploying Zilla when a schema changes.

catalog:
  type: karapace-schema-registry
  options:
    url: http://reg.example.com:8081
    context: default

context scopes schema lookups to an independent namespace within the registry, useful for separating environments or tenants sharing the same Karapace instance.

Use Karapace when Kafka clients already publish and consume schemas through it. The http.kafka.avro.json example validates Kafka messages against Avro schemas fetched from Karapace, ensuring every producer and consumer agrees on the message shape.

See the karapace-schema-registry catalog reference for the full set of options, including TLS and credential settings.

AWS Glue

Available in Zilla Plus

AWS Glue is a managed data catalog and schema registry. As a Kafka Gateway catalog, it lets Zilla fetch schemas from AWS Glue at runtime, so producers and consumers on AWS validate against a schema managed centrally rather than one embedded in zilla.yaml.

catalog:
  type: aws-glue
  options:
    registry: zilla
    max-age: 30
    compression: zlib

registry identifies the AWS Glue Registry to query. max-age controls how long a resolved schema is cached before Zilla checks for a newer version, and compression matches the compression used when serializing message payloads.

Choose AWS Glue when your Kafka workloads already run on AWS and schemas are managed through Glue's Schema Registry, avoiding the need to operate a separate registry.

See the aws-glue catalog reference for the full set of options.

Confluent Schema Registry

Available in Zilla Plus

Confluent Schema Registry is a centralized schema management service for Kafka. As a Kafka Gateway catalog, it lets Zilla fetch schemas from Confluent Schema Registry at runtime, keeping message validation in sync with schemas published there.

catalog:
  type: confluent-schema-registry
  options:
    url: http://reg.example.com:8081
    context: default

context scopes schema lookups to an independent namespace within the registry, useful for separating environments or tenants that share the same Confluent Schema Registry deployment.

Choose Confluent Schema Registry when Kafka producers and consumers already publish schemas through it, typically alongside Confluent Platform or Confluent Cloud.

See the confluent-schema-registry catalog reference for the full set of options, including TLS and credential settings.

Once registered, reference any catalog from a model to fetch schemas by subject, topic, or ID.

Apicurio in the Petstore REST Demo