xRegistry Codegen

Generate production-ready messaging code from xRegistry message and endpoint definitions for multiple languages and protocols.

View Gallery GitHub

Quick Start

Docker

Recommended

docker pull ghcr.io/xregistry/codegen/xrcg:latest

No Python required. Works on Linux, macOS, and Windows.

Note: File paths must be relative to your current directory due to Docker volume mapping.

View command reference →

Shell alias for convenience

Linux/macOS

alias xrcg='docker run --rm -v $(pwd):/work ghcr.io/xregistry/codegen/xrcg:latest'

PowerShell

function xrcg { docker run --rm -v ${PWD}:/work ghcr.io/xregistry/codegen/xrcg:latest $args }

Python

pip install xrcg

Requires Python 3.10+

View command reference →

Generate your first SDK

xrcg generate --language py --style kafkaproducer -d https://raw.githubusercontent.com/xregistry/codegen/main/samples/message-definitions/inkjet.xreg.json --output ./output --projectname PrinterEvents

Multi-Language Support

Generate code for C#, Java, Python, TypeScript, and Go with idiomatic patterns for each language.

📡

Multiple Protocols

AMQP, MQTT, Kafka, HTTP, Azure Event Hubs, Azure Service Bus, Azure Event Grid, and more.

📋

Schema Format Flexibility

Works with Apache Avro, JSON Schema, Protocol Buffers (protobuf), and XSD schema formats.

CloudEvents Native

First-class support for CloudEvents message format with proper type mappings and metadata handling.

🔧

Extensible Templates

Customizable Jinja2 templates allow you to tailor the generated code to your specific needs.

✅

Production Ready

Generated code includes proper error handling, logging, tests, and follows best practices.

What You Get

Unlike snippet generators, this tool produces complete SDK-like projects:

🎯 Type-safe Clients

Producer/consumer classes with strongly-typed methods per message

📦 Data Classes

Schema-derived classes via Avrotize (JSON Schema, Avro, Protobuf)

🔧 Build Files

pom.xml, .csproj, package.json, pyproject.toml with correct dependencies

🧪 Integration Tests

Docker-based tests using Testcontainers for Kafka, MQTT, AMQP brokers

📁 Project Structure

Language-idiomatic layout ready for IDE import

📚 Documentation

Generated README and inline documentation

Command Reference

The Generate Command

xrcg generate --projectname <name> --language <lang> --style <style> \
  --definitions <file-or-url> --output <dir>

Option	Description
`--projectname`	Project/namespace name for generated code
`--language`	Target language: `java`, `cs`, `py`, `ts`, `go`, `asyncapi`, `openapi`
`--style`	Protocol binding: `kafkaproducer`, `ehconsumer`, `mqttclient`, etc.
`--definitions`, `-d`	Path or URL to xRegistry JSON/YAML definition
`--output`, `-o`	Output directory (will be created/overwritten)
`--templates`	Custom template directory (optional)
`--template-args`	Extra args as key=value (optional)

Other Commands

List available templates

xrcg list

Validate definition files

xrcg validate --definitions ./catalog.json

Configure defaults

xrcg config set defaults.language java
xrcg config set defaults.output_dir ./generated
xrcg config list

Example Usage

Apache Kafka

# Python Kafka Producer
xrcg generate --language py --style kafkaproducer -d contoso-erp.xreg.json -o ./output

# C# Kafka Consumer  
xrcg generate --language cs --style kafkaconsumer -d contoso-erp.xreg.json -o ./output

# Java Kafka Producer
xrcg generate --language java --style kafkaproducer -d contoso-erp.xreg.json -o ./output

Azure Event Hubs

# TypeScript Event Hubs Producer
xrcg generate --language ts --style ehproducer -d fabrikam-motorsports.xreg.json -o ./output

# C# Event Hubs Consumer
xrcg generate --language cs --style ehconsumer -d fabrikam-motorsports.xreg.json -o ./output

MQTT 5.0

# Python MQTT Client
xrcg generate --language py --style mqttclient -d lightbulb.xreg.json -o ./output

# Java MQTT Client
xrcg generate --language java --style mqttclient -d lightbulb.xreg.json -o ./output

AMQP 1.0 (RabbitMQ, Artemis, Qpid)

# C# AMQP Producer
xrcg generate --language cs --style amqpproducer -d inkjet.xreg.json -o ./output

# Python AMQP Producer
xrcg generate --language py --style amqpproducer -d inkjet.xreg.json -o ./output

AsyncAPI / OpenAPI

# Generate AsyncAPI 3.0 spec
xrcg generate --language asyncapi --style consumer -d contoso-erp.xreg.json -o ./output

# Generate OpenAPI 3.0 spec
xrcg generate --language openapi --style producer -d contoso-erp.xreg.json -o ./output

Available Templates

C# / .NET 6+

kafkaproducer, kafkaconsumer
ehproducer, ehconsumer, ehazfn
sbproducer, sbconsumer, sbazfn
egproducer, egazfn
amqpproducer, amqpconsumer
mqttclient

Java 21+

kafkaproducer, kafkaconsumer
ehproducer, ehconsumer
sbproducer, sbconsumer
amqpproducer, amqpconsumer
mqttclient

Python 3.9+

kafkaproducer, kafkaconsumer
ehproducer, ehconsumer
amqpproducer, amqpconsumer
mqttclient

TypeScript

kafkaproducer, kafkaconsumer
ehproducer, ehconsumer
sbproducer, sbconsumer
egproducer
amqpproducer, amqpconsumer
mqttclient

Go

kafkaproducer, kafkaconsumer

📄 Specifications

asyncapi - AsyncAPI 3.0
openapi - OpenAPI 3.0
Azure Stream Analytics

What is xRegistry?

xRegistry is a CNCF project defining a standard format for describing messaging and eventing infrastructure. A message catalog document contains:

Schema groups — Payload schemas (JSON Schema, Avro, Protobuf)
Message groups — Message definitions with CloudEvents envelope metadata
Endpoints — Protocol bindings (Kafka topics, AMQP queues, HTTP endpoints)

The code generator follows references between these elements to produce cohesive, type-safe SDKs.

Sample Definitions

Try these sample definitions from the repository:

File	Description
`contoso-erp.xreg.json`	ERP system events (orders, payments, inventory)
`fabrikam-motorsports.xreg.json`	Motorsports telemetry stream (Avro schema)
`inkjet.xreg.json`	IoT printer events (Avro schema)
`smartoven-jsonschema.xreg.json`	Smart oven IoT events (JSON Schema)
`lightbulb.xreg.json`	Smart lightbulb device events (Avro schema)

Community

💬 #cloudevents on CNCF Slack 📧 Mailing List GitHub