Skip to main content
A schema reference lets one schema point at another registered schema instead of inlining its definition. Define a shared Address type once and reference it from Customer, Order, and Invoice, and a change to Address propagates instead of drifting across three copies. The StreamNative Kafka Schema Registry supports references for all three formats, including references that themselves contain references.

​
Register a referenced schema

Register the shared schema first:
Then register the schema that uses it, listing the reference:
Each entry in references has three fields:

​
Per-format syntax

Avro—reference a record by its fully qualified name, as in the example above. The name in the reference entry is that fully qualified name. Protobuf—reference through an import statement. The name is the import path:
JSON Schema—reference through $ref, with the name matching the $ref value:
A JSON Schema $ref that points at an external URL is rejected. Every reference must resolve to a schema registered in this registry.

​
Find what references a schema

The response is an array of schema IDs. Resolve each one with GET /schemas/ids/{id}/subjects to see which subjects hold it.

​
References block deletion

You cannot delete a schema while another schema references it. The attempt returns error code 42206. Delete the referencing schemas first, or use referencedby to find them. This applies to soft and hard deletes alike, and it’s the most common reason a delete you expected to succeed doesn’t.

​
Evolving referenced schemas

A reference pins a specific version. Registering Address version 2 does not change what Customer resolves to—it still points at version 1. To adopt the new version, register a new version of the referencing schema with the reference updated to "version": 2. That new version goes through the referencing subject’s own compatibility check, so a breaking change to Address surfaces as a failure on customers-value rather than silently altering it.
Because references pin versions, a shared type can evolve without forcing every consumer to move at once. That’s the main reason to use references rather than inlining.

​
Next steps

Serializers and deserializers

How the client registers and resolves schemas.

Evolution and compatibility

How compatibility checks treat a changed reference.