# @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.

<!-- begin:auto-docs -->
## Documentation tree

- [compatibility](./src/core/compatibility/compatibility.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
  - [compatibility](./src/core/compatibility/compatibility.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
- [registry](./src/core/registry/schema-registry.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
  - [schema-registry](./src/core/registry/schema-registry.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
- [errors](./src/errors/schema-registry-error.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
  - [schema-registry-error](./src/errors/schema-registry-error.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
<!-- end:auto-docs -->  - [compatibility](./src/core/compatibility/compatibility.md) — <!-- begin:auto-docs --> _(no submodules)_- [registry](./src/core/registry/schema-registry.md) — <!-- begin:auto-docs --> _(no submodules)_- [schema-registry](./src/core/registry/schema-registry.md) — <!-- begin:auto-docs --> _(no submodules)_- [errors](./src/errors/schema-registry-error.md) — <!-- begin:auto-docs --> _(no submodules)_- [schema-registry-error](./src/errors/schema-registry-error.md) — <!-- begin:auto-docs --> _(no submodules)_- [compatibility](./src/core/compatibility/compatibility.md) — <!-- begin:auto-docs --> _(no submodules)_- [registry](./src/core/registry/schema-registry.md) — <!-- begin:auto-docs --> _(no submodules)_- [schema-registry](./src/core/registry/schema-registry.md) — <!-- begin:auto-docs --> _(no submodules)_- [errors](./src/errors/schema-registry-error.md) — <!-- begin:auto-docs --> _(no submodules)_- [schema-registry-error](./src/errors/schema-registry-error.md) — <!-- begin:auto-docs --> _(no submodules)_- [compatibility](./src/core/compatibility/compatibility.md) — <!-- begin:auto-docs --> _(no submodules)_- [registry](./src/core/registry/schema-registry.md) — <!-- begin:auto-docs --> _(no submodules)_- [schema-registry](./src/core/registry/schema-registry.md) — <!-- begin:auto-docs --> _(no submodules)_- [errors](./src/errors/schema-registry-error.md) — <!-- begin:auto-docs --> _(no submodules)_- [schema-registry-error](./src/errors/schema-registry-error.md) — <!-- begin:auto-docs --> _(no submodules)_- [compatibility](./src/core/compatibility/compatibility.md) — <!-- begin:auto-docs --> _(no submodules)_- [registry](./src/core/registry/schema-registry.md) — <!-- begin:auto-docs --> _(no submodules)_  - [schema-registry](./src/core/registry/schema-registry.md) — <!-- begin:auto-docs --> _(no submodules)_- [errors](./src/errors/schema-registry-error.md) — <!-- begin:auto-docs --> _(no submodules)_  - [schema-registry-error](./src/errors/schema-registry-error.md) — <!-- begin:auto-docs --> _(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

```bash
bun add @suaveplan/schema-registry
```

## Quick Start

```ts
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`](src/core/registry/schema-registry.md) | `SchemaRegistry` class and `createRegistry` factory |
| [`@suaveplan/schema-registry/compatibility`](src/core/compatibility/compatibility.md) | `checkCompatibility` pure function |
| [`@suaveplan/schema-registry/errors`](src/errors/schema-registry-error.md) | `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 |