@suaveplan/schema-registry - Versioned schema registry with forward/backward compatibility checking for evolving data contracts

Summary

Versioned schema registry with forward/backward/full compatibility checking for evolving data contracts. Register schemas by subject name, enforce evolution rules, and detect breaking changes before they reach production.

Documentation tree

compatibility — (no submodules)
- compatibility — (no submodules)
registry — (no submodules)
- schema-registry — (no submodules)
errors — (no submodules)
- schema-registry-error — (no submodules)

- [compatibility](./src/core/compatibility/compatibility.md) — _(no submodules)_- [registry](./src/core/registry/schema-registry.md) — _(no submodules)_- [schema-registry](./src/core/registry/schema-registry.md) — _(no submodules)_- [errors](./src/errors/schema-registry-error.md) — _(no submodules)_- [schema-registry-error](./src/errors/schema-registry-error.md) — _(no submodules)_- [compatibility](./src/core/compatibility/compatibility.md) — _(no submodules)_- [registry](./src/core/registry/schema-registry.md) — _(no submodules)_- [schema-registry](./src/core/registry/schema-registry.md) — _(no submodules)_- [errors](./src/errors/schema-registry-error.md) — _(no submodules)_- [schema-registry-error](./src/errors/schema-registry-error.md) — _(no submodules)_- [compatibility](./src/core/compatibility/compatibility.md) — _(no submodules)_- [registry](./src/core/registry/schema-registry.md) — _(no submodules)_- [schema-registry](./src/core/registry/schema-registry.md) — _(no submodules)_- [errors](./src/errors/schema-registry-error.md) — _(no submodules)_- [schema-registry-error](./src/errors/schema-registry-error.md) — _(no submodules)_- [compatibility](./src/core/compatibility/compatibility.md) — _(no submodules)_- [registry](./src/core/registry/schema-registry.md) — _(no submodules)_ - [schema-registry](./src/core/registry/schema-registry.md) — _(no submodules)_- [errors](./src/errors/schema-registry-error.md) — _(no submodules)_ - [schema-registry-error](./src/errors/schema-registry-error.md) — _(no submodules)_

Features

Versioned storage — schemas are registered per subject with auto-incremented versions
Compatibility enforcement — BACKWARD, FORWARD, FULL, or NONE modes
Per-subject overrides — setCompatibility() lets subjects opt into different rules
Dry-run checks — checkCompatibility() validates without registering
OTel instrumentation — schema_registry.register.total counter and schema_registry.check.duration_ms histogram
Structured errors — SchemaRegistryError with stable SCHEMA_REGISTRY.* codes
JSON Schema deep analysis — inspects required, properties, and type fields
Format-aware — zod, avro, and custom formats accepted with informational notes

Installation

bun add @suaveplan/schema-registry

Quick Start

import { createRegistry } from "@suaveplan/schema-registry";

const registry = createRegistry();

// Register v1
registry.register("UserCreated", {
  type: "object",
  properties: { id: { type: "string" }, name: { type: "string" } },
  required: ["id"],
});

// Register v2 (backward-compatible — adds optional field)
registry.register("UserCreated", {
  type: "object",
  properties: {
    id:    { type: "string" },
    name:  { type: "string" },
    email: { type: "string" },
  },
  required: ["id"],
});

const latest = registry.getLatest("UserCreated");
console.log(latest.version); // 2

Modules

Subpath	Description
`@suaveplan/schema-registry`	Full barrel export
`@suaveplan/schema-registry/registry`	`SchemaRegistry` class and `createRegistry` factory
`@suaveplan/schema-registry/compatibility`	`checkCompatibility` pure function
`@suaveplan/schema-registry/errors`	`SchemaRegistryError` and `SCHEMA_REGISTRY_CODES`

Compatibility Levels

Level	Description
`BACKWARD` (default)	New schema can read data written with old schema
`FORWARD`	Old schema can read data written with new schema
`FULL`	Both BACKWARD and FORWARD must pass
`NONE`	No compatibility checks — any schema accepted

Error Codes

Code	Description
`SCHEMA_REGISTRY.SCHEMA_NOT_FOUND`	Requested version does not exist
`SCHEMA_REGISTRY.INCOMPATIBLE_SCHEMA`	Registration rejected by compatibility rule
`SCHEMA_REGISTRY.INVALID_SCHEMA`	Schema definition fails validation
`SCHEMA_REGISTRY.SUBJECT_NOT_FOUND`	Subject has no registered versions