suaveplan/openspec/archive/2026-04-19-enterprise-schema-registry/proposal.md

OpenSpec Change: enterprise-schema-registry

• Change ID: enterprise-schema-registry
• Package: @suaveplan/schema-registry
• Category: universal
• Target path: universal/validation/schema-registry
• Status: PROPOSED
• Date: 2026-04-19
• Reference spec: /mnt/s/web/suaveplan/enterprise/schema-registry.md

Summary

Greenfield rebuild of @suaveplan/schema-registry — Kafka-/Confluent-style schema registry. Stores versioned schemas per subject, runs backward/forward/full compatibility checks, emits structured diffs, and exposes pluggable stores (in-memory + database adapter). Used by event-sourcing, api contracts, and future utils package.

Current-state audit (genesis)

Package does not exist yet — fresh build.

Dependencies

• Workspace: @suaveplan/error, @suaveplan/types
• External (via catalog): zod, tslib, @opentelemetry/api
• Dev (via catalog): vitest, @vitest/coverage-istanbul, fast-check, mitata

Preserved public surface

Registry

• SchemaRegistry, createSchemaRegistry, SchemaRegistryConfig
• createSchemaIncompatibleError, SchemaCompatibilityError

Versioning / store

• createSchemaVersion, MemorySchemaStore, DatabaseSchemaStore, resolveCompatibility

Compatibility

• checkCompatibility, checkTransitiveCompatibility
• buildTransitiveReport, checkTransitiveAgainstAll, isTransitiveMode, stripTransitive, TransitiveReport, TransitiveVersionResult

Diff

• diffSchemas, formatDiffReport

Utils / constants

• canonicalizeSchema, computeFingerprint, djb2Hash, flattenFields, isOptionalOrHasDefault
• DEFAULT_COMPATIBILITY, DEFAULT_MAX_VERSIONS

Types / error codes

CompatibilityMode, CompatibilityResult, DatabaseAdapter, DiffChangeType, LookupOptions, RegisterOptions, SchemaDefinition, SchemaDiffChange, SchemaDiffResult, SchemaField, SchemaStoreAdapter, SchemaType, SchemaVersion, SubjectConfig, SchemaRegistryErrorCode, registerSchemaRegistryErrorCodes, SCHEMA_REGISTRY_ERROR_METADATA.

New genesis additions

• Codes via defineCodes: SCHEMA_REGISTRY.SUBJECT_NOT_FOUND, SCHEMA_REGISTRY.VERSION_NOT_FOUND, SCHEMA_REGISTRY.INCOMPATIBLE, SCHEMA_REGISTRY.STORE_ERROR, SCHEMA_REGISTRY.INVALID_SCHEMA.
• OTel counters schema_registry.register.total, schema_registry.incompatible.total; histogram schema_registry.compatibility.duration_ms.
• Property tests: registering the same canonicalised schema twice returns the same version; compatibility transitivity across N versions.

Impact

• Adds one new package: universal/validation/schema-registry
• Adds one new spec capability: schema-registry
• Unblocks utils (which currently depends on schema-registry on main).