Schema Registry · Analysis

01 · Frame the problem

Understand the central challenge

Design a registry for a deliberately restricted record-schema language. Producers register schemas before publishing events. Compatibility depends on which reader must understand which writer, not just whether two JSON documents look similar.

A schema version has immutable meaning, while compatibility depends on the declared reader/writer direction. Concurrent registrations must validate against the same authoritative predecessor instead of independently approving incompatible futures.

02 · Find the design pressure

Start simple, then identify the gap

Begin with canonical schema identity and subject history. A generic JSON equality check cannot prove compatibility. Restrict supported semantics, define direction explicitly and serialize registration using the subject's expected version.

Register canonical immutable schema documents with explicit subject/version relationships and a restricted reader/writer compatibility model. Atomic version-checked registration prevents concurrent changes bypassing policy. Define the supported record schema and reader defaults/unknown-field behavior. Validate and canonicalize schemas, excluding only semantically irrelevant formatting under a versioned canonicalization rule. For backward checks, ensure the new reader can obtain every required field from each selected old writer or a valid default. For forward checks invert reader/writer roles; reject unsupported type changes conservatively. Under a subject transaction verify expected latest version and compatibility against the configured latest/transitive set. Insert or reuse an immutable schema ID and append the new subject version. Events carry schema ID. Consumers cache immutable schemas by ID with bounded memory; unknown IDs fail explicitly or retry registry lookup rather than decode under the latest schema. Authorization scopes subjects and administrative policy changes.

03 · Define success

Requirements to preserve

Assign immutable schema IDs and subject-scoped versions.
Define backward/forward compatibility for the supported schema subset.
Serialize registration under an expected subject version.
Keep event schema identity and registry-cache behavior explicit.

Workload: 20,000 reads/s, 100 writes/s, 1000 B records, 150 ms read p99 target. These are exercise assumptions; the Solution includes capacity formulas.

04 · Identify the correctness boundary

Consistency, ownership and failure boundaries

Canonicalize schemas before identity comparison and evaluate compatibility against the documented reader/writer model. Registration must compare the subject's expected version so concurrent candidates cannot both validate against an outdated base. Immutable historical versions remain available to decode existing messages.

05 · Make it concrete

Reason through a worked example

Versions 4A and 4B both validate against subject version 3. Only one conditional registration becomes version 4; the other reloads and revalidates. Compatibility checks apply in the declared direction: a new reader accepting old data does not automatically mean old readers accept new data.