Clemens Vasters

Football. Cloud. Tech. Politics. Pictures. Principal Architect for Messaging/Eventing at Microsoft.

xRegistry hits RC3: one spec to describe — and generate — your entire messaging fabric

The CNCF xRegistry working group has shipped Release Candidate 3 (RC3) of the xRegistry specification set — the last feedback window before 1.0.

If you run anything event-driven, this is worth 5 minutes. xRegistry can now describe what you send to, and expect back from, practically any standard messaging channel — a Kafka topic, an AMQP queue, an MQTT topic tree — and generate the producer and consumer code from that description.

Why it matters

CloudEvents harmonized the shape of an event. It left four questions unanswered:

  • Discovery — Where do I produce or consume this? What endpoints exist?
  • Validation — How do I check an event's structure and its metadata?
  • Versioning — How do events and endpoints evolve without breaking consumers?
  • Serialization — What envelope and schema format is on the wire?

Schema registries answer some of this — but every broker ships its own, each vendor- and protocol-specific. When an event crosses brokers, clients wrestle with mismatched registries. xRegistry is the vendor-neutral layer that makes the metadata portable across all of them.

What it is

A generic, extensible framework for managing metadata of any kind. At its core, an xRegistry is a simple tree:

Registry → Group → Resource → Version

Groups collect related Resources (think folders). Resources are the items of interest (think files), each optionally carrying a domain-specific document — like a schema — and optionally versioned. That's the whole model. Everything else is extension.

The defining trait: one symmetric shape, three forms. The same registry can live as:

  • A file — a single JSON manifest you check into Git next to your code.
  • A static website — one file per entity on plain storage (S3, GitHub Pages). No compute, no server logic.
  • A full API — a live service with search, filter, and write access for multiple teams.

You can start as a hand-written file and export your way up to an API as you grow — no rewrite, because the representations are designed to be symmetric.

What it does for messaging

Layered on that core is a messaging and eventing catalog built from three companion specs — Endpoints, Messages, and Schemas.

Together they let you declare structured data flows over the protocols people actually use — AMQP, MQTT, Kafka, HTTP, and NATS — with or without the CloudEvents envelope, against a schema registry of your choice (JSON Schema, Avro, Protobuf, and more).

The payoff: a single manifest can fully describe an interface — the endpoints, the messages that flow over them, each message's Kafka key / AMQP subject / MQTT topic, a shared base CloudEvent definition, and the payload schemas each message points to.

From description to running code

This is where it stops being documentation and starts saving work.

  • Generate data contracts — because schemas live beside the code in source control, tooling recreates typed data classes exactly in sync with the schema version.
  • Generate producers and consumers — from a vendor-agnostic definition, tooling emits broker-specific senders and receivers.
  • Validate on publish — a server can reject events that don't match the contract, killing poison messages at the door.
  • Shrink payloads — with schemas centralized, you can drop schema info from the wire and still analyze data accurately.

The reference codegen is an extensible, Jinja2-based framework that produces senders and receivers in several languages, honoring every declared attribute.

Overlay it on what you already have

xRegistry doesn't demand you move your assets into it. Via the xrproxy project, an API server can project other registries into the xRegistry model and proxy them — leaving the source of truth in place.

In one live demo, a single xRegistry API sits in front of PyPI, npm, Maven, NuGet, Microsoft's OCI container registry, and the Model Context Protocol registry. Each has its own xRegistry model, so all six become one navigable, type-safe metadata graph — with cross-references between a container, the package inside it, the endpoint it exposes, and the event schemas that endpoint accepts.

See it running

Four things you can open right now:

Go deeper

A few design choices worth knowing before you build:

  • Federation by shadowing, not syncing. There's no synchronization API by design. Instead, registries layer: a local registry overrides or extends an underlying one without copying it — a file can shadow a folder, a folder can shadow an API, an API can shadow another API. For 1.0, treat shadowing as an emerging best practice — powerful, but still gaining real-world mileage.
  • Catalog, not container. A registry references far more than it stores. Documents can be embedded (inline or base64) or linked by URL — so you can catalog existing files where they already sit.
  • Flat groups, dotted names. The tree is deliberately one level deep (Groups don't nest). Hierarchy comes from dot-notation IDs like Contoso.ERP.Orders and from free-form labels for cross-cutting queries — without the complexity of nested containers.
  • Deliberately out of scope. Authentication and authorization are left to the hosting environment. So are formal relationships between channels — the focus for 1.0 is describing a single channel precisely first.

What's next

RC3 is the final call for feedback before xRegistry 1.0. If you work with events, schemas, or package/container/API registries, this is the moment to pressure-test the model against your use case.

The bottom line

xRegistry turns scattered, broker-specific metadata into one portable graph you can discover, version, validate, and generate code from — as a document when at rest, an API when live, and the same shape either way. RC3 is your last chance to shape it before 1.0.

Categories:

Updated:

Share on Twitter, Reddit, Facebook or LinkedIn