Register the shared/imported schema first under its own subject: POST /subjects/common-proto/versions with schemaType=PROTOBUF and the .proto content
When registering the dependent schema, include a references array in the request body: [{"name": "common.proto", "subject": "common-proto", "version": 1}] — the name field must exactly match the import statement in the .proto file
Set the subject naming strategy on producers/consumers via value.subject.name.strategy=io.confluent.kafka.serializers.subject.TopicNameStrategy (default) or RecordNameStrategy if multiple message types share a topic
Validate the reference is resolvable: GET /subjects/my-topic-value/versions/latest/referencedby to confirm the dependency graph is intact
Evolve the shared schema carefully: bump its version, then update the dependent schema's references array to point to the new version
Test with the Confluent CLI: confluent schema-registry schema describe --subject my-topic-value --version latest --show-references
Known gotchas
The name in the references array must be the literal string used in the proto import statement (e.g. 'common/types.proto'), not the subject name — a mismatch causes deserialization failures at runtime
Deleting a referenced schema version is blocked by default while any dependent subject still references it; you must update or delete dependents first
Protobuf references are the only format where the serializer auto-registers nested references; for Avro and JSON Schema, each referenced schema must be manually pre-registered
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp