Understand the four compatibility levels: BACKWARD (new schema can read data written by old schema), FORWARD (old schema can read data written by new schema), FULL (both directions), and NONE (no checks).
Set the default compatibility mode for the registry globally, then override per-subject if certain topics require stricter or looser rules: use the Schema Registry REST API subjects endpoint to update the compatibility for a specific subject.
For BACKWARD compatibility, only add fields with defaults and never remove or rename required fields; adding a field without a default breaks backward compatibility.
Register a new schema version before deploying producers that use it; this ensures consumers can fetch the schema by ID before any messages with the new version arrive.
Use schema references for shared types (e.g., a common Address type referenced by multiple event schemas) to avoid duplicating definitions and to track compatibility across the reference graph.
Test schema evolution in a non-production registry namespace before promoting; use the compatibility check endpoint to validate a candidate schema against the current version without registering it.
Known gotchas
Schema IDs are registry-global integers, not semantic versions; never hard-code a schema ID in application code—always resolve it by subject and version at startup.
BACKWARD compatibility only ensures old consumers can read new data; it does not protect old producers writing to a new schema—coordinate producer and consumer deployments carefully.
Renaming a field is a breaking change in all compatibility modes because Avro uses field names for matching; use aliases (avro 'aliases' attribute) if a rename is unavoidable, but test that your deserializer version supports alias resolution.
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