2.5 KiB
Capability Spec: schema-registry
Package: @suaveplan/schema-registry
Version: 0.0.0 (genesis)
Status: ADDED
ADDED Requirements
SR-01 — Subject + version model
A subject MUST carry SubjectConfig and a sequence of SchemaVersion { id, subject, version, schema, fingerprint, createdAt }. version MUST be monotonic starting at 1. fingerprint MUST be stable over canonicalised schema output.
SR-02 — Canonicalisation
canonicalizeSchema(schema) MUST produce a deterministic, lexically sorted representation such that semantically identical schemas yield identical canonical output. computeFingerprint(schema) MUST hash the canonical form. djb2Hash MUST be a reference 32-bit DJB2 implementation.
SR-03 — Compatibility modes
CompatibilityMode MUST include 'none' | 'backward' | 'backward-transitive' | 'forward' | 'forward-transitive' | 'full' | 'full-transitive'. checkCompatibility(current, candidate, mode) MUST return CompatibilityResult { compatible, violations }. checkTransitiveCompatibility(history, candidate, mode) MUST evaluate against every prior version per the transitive mode.
SR-04 — Register contract
SchemaRegistry.register(subject, schema, options?) MUST canonicalise, compute a fingerprint, look up an existing version by fingerprint, and reuse it if found. Otherwise it MUST check compatibility against the latest (or full history if transitive) and either persist a new version or throw SchemaCompatibilityError with code SCHEMA_REGISTRY.INCOMPATIBLE.
SR-05 — Lookup
get(subject, version?) MUST return the latest version when version is omitted. getByFingerprint(subject, fingerprint) MUST be supported. Unknown subject MUST throw SCHEMA_REGISTRY.SUBJECT_NOT_FOUND; unknown version MUST throw SCHEMA_REGISTRY.VERSION_NOT_FOUND.
SR-06 — Store contract
SchemaStoreAdapter MUST provide list, put, get, getLatest, delete. MemorySchemaStore MUST implement it synchronously; DatabaseSchemaStore MUST accept a DatabaseAdapter for durable storage. Both MUST pass the same contract test suite.
SR-07 — Diff
diffSchemas(prev, next) MUST return SchemaDiffResult listing SchemaDiffChange entries (added | removed | modified | type-changed | optionality-changed). formatDiffReport MUST produce a human-readable Markdown summary.
SR-08 — Observability
Every register / compatibility / diff call MUST record its corresponding OTel metric; incompatible registrations MUST increment schema_registry.incompatible.total{subject, mode}.