42 lines
2.5 KiB
Markdown
42 lines
2.5 KiB
Markdown
# 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}`.
|