Schema Registry

Gluendo's starter kit for GitOps-driven schema governance — canonical JSON Schema definitions, versioning, validation tooling, and CI templates for integration platforms.

Browse the catalog

What is this?

A Git-backed registry of JSON Schema definitions that describe the canonical messages flowing through an integration platform. Producers own their schemas, consumers discover and validate against them.

This repository serves as:

• A starter kit — battle-tested reference schemas and tooling that Gluendo uses to bootstrap client integration platforms
• A living catalog — browsable at gluendo.github.io/schema-registry
• A governance framework — ADRs, CI validation, and contribution workflows for schema lifecycle management

Quick start

Browse schemas

Visit the catalog or explore the schemas/ directory:

schemas/
  _common/                    # Shared types and enums
  domains/
    hr/employee/
      employee.schema.json    # Current version (edit in place)
      policies/               # Current policies
      v1.0.0/                 # Frozen snapshot (created by CI)
      v1.1.0/                 # Frozen snapshot

Add a new schema

# 1. Create the folder structure
mkdir -p schemas/domains/{domain}/{entity}

# 2. Copy the template
cp templates/entity.schema.json schemas/domains/{domain}/{entity}/{entity}.schema.json

# 3. Edit, commit, open a PR — CI snapshots the version on merge

See CONTRIBUTING.md for the full guide.

Validate locally

make hooks           # Install pre-commit hook (validates schemas before commit)
make all             # Run all checks (validate, format, lint, compat)
make build           # Build catalog + EventCatalog for production
make preview         # Build and serve locally (mimics GitHub Pages)
make ec-dev          # Run EventCatalog dev server

Run the catalog locally

cd catalog && npm install && npm run dev
# Open http://localhost:3000/schema-registry

EventCatalog is also available at /schema-registry/eventcatalog/ — it provides service dependency graphs, domain exploration, and schema visualization.

Architecture decisions

The design is documented in Architecture Decision Records:

#	Decision
001	Git as source of truth
002	JSON Schema (draft 2020-12)
003	Producer ownership of schemas
004	Semantic versioning + backward compatibility
005	Starter kit + optional shared commons
006	Domain-driven folder structure
007	CloudEvents envelope standard
008	Fat / delta / skinny event patterns
009	Audience segmentation via policy-as-code
010	Runtime validation strategy
011	Schema catalog app (GitHub Pages)

CI/CD

Workflow	Trigger	What it does
Validate Schemas	PR + push to main	Validates JSON, formatting, $ref targets, compatibility, version checks
Schema Diff	PR touching schemas/	Posts a PR comment with field-level changes and semver recommendation
Snapshot Schemas	Push to main	Creates frozen version snapshots from current files
Deploy Catalog	Push to main	Builds catalog + EventCatalog, deploys to GitHub Pages

Repository structure

schemas/
  _common/              Shared types and ISO enums
  domains/              Domain schemas (current file + version snapshots)
adr/                    Architecture Decision Records
catalog/                Next.js catalog app (GitHub Pages)
eventcatalog/           EventCatalog integration (services, visualizations)
tools/
  schema-tools.py       Validate, format, bundle, diff, snapshot
  lint.sh               Vacuum linter wrapper
templates/              Schema template for new entities
.githooks/              Pre-commit hook for schema validation

License

Proprietary — Gluendo.