Generate production-ready, type-safe messaging SDKs from xRegistry message catalog definitions. One command gives you compile-ready producer/consumer code with tests, dependency management, and protocol-specific bindings.
1. Install (Docker or pip):
# Docker (recommended - no Python needed)
docker pull ghcr.io/xregistry/codegen/xrcg:latest
# Or via pip
pip install git+https://github.com/xregistry/codegen.git2. Generate a Kafka producer from a sample definition:
# Using Docker (Linux/macOS)
docker run --rm -v $(pwd):/work ghcr.io/xregistry/codegen/xrcg:latest \
generate --projectname PrinterEvents --language py --style kafkaproducer \
--definitions https://raw.githubusercontent.com/xregistry/codegen/main/samples/message-definitions/inkjet.xreg.json \
--output ./generated# Using Docker (Windows PowerShell)
docker run --rm -v ${PWD}:/work ghcr.io/xregistry/codegen/xrcg:latest `
generate --projectname PrinterEvents --language py --style kafkaproducer `
--definitions https://raw.githubusercontent.com/xregistry/codegen/main/samples/message-definitions/inkjet.xreg.json `
--output ./generated# Or with pip install (any platform)
xrcg generate --projectname PrinterEvents --language py --style kafkaproducer \
--definitions https://raw.githubusercontent.com/xregistry/codegen/main/samples/message-definitions/inkjet.xreg.json \
--output ./generatedThis produces a complete Python project with:
- Type-safe producer classes for each message type
- Strongly-typed data classes generated from Avro schema
- Integration tests using Testcontainers
- Ready to use:
cd generated && pip install -e . && pytest
3. Or generate for a different platform — same definition, different target:
xrcg generate --projectname ContosoEvents --language cs --style ehproducer \
--definitions ./contoso-erp.xreg.json --output ./generated # C# Event Hubs
xrcg generate --projectname ContosoEvents --language ts --style mqttclient \
--definitions ./contoso-erp.xreg.json --output ./generated # TypeScript MQTT
xrcg generate --projectname ContosoEvents --language py --style kafkaconsumer \
--definitions ./contoso-erp.xreg.json --output ./generated # Python KafkaUnlike snippet generators, this tool produces complete SDK-like projects:
| Feature | What's Generated |
|---|---|
| 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 |
Supported Languages: Java 21+, C# (.NET 6+), Python 3.9+, TypeScript/JavaScript
Supported Protocols: Apache Kafka, MQTT 5.0, AMQP 1.0, Azure Event Hubs, Azure Service Bus, Azure Event Grid, HTTP/CloudEvents
For complete command documentation, see Command Reference.
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, asyncapi, openapi |
--style |
Protocol binding: kafkaproducer, ehconsumer, mqttclient, etc. |
--definitions |
Path or URL to xRegistry JSON/YAML definition |
--output |
Output directory (will be created/overwritten) |
--templates |
Custom template directory (optional) |
--template-args |
Extra args as key=value (optional) |
Run xrcg list to see all available language/style combinations:
├── java: Java 21+
│ ├── kafkaproducer, kafkaconsumer # Apache Kafka
│ ├── ehproducer, ehconsumer # Azure Event Hubs
│ ├── sbproducer, sbconsumer # Azure Service Bus
│ ├── amqpproducer, amqpconsumer # AMQP 1.0 (RabbitMQ 4+, Artemis, Qpid)
│ └── mqttclient # MQTT 5.0
├── cs: C# / .NET 6.0+
│ ├── kafkaproducer, kafkaconsumer
│ ├── ehproducer, ehconsumer, ehazfn # Event Hubs + Azure Functions
│ ├── sbproducer, sbconsumer, sbazfn
│ ├── egproducer, egazfn # Event Grid
│ ├── amqpproducer, amqpconsumer
│ └── mqttclient
├── py: Python 3.9+
│ ├── kafkaproducer, kafkaconsumer
│ ├── ehproducer, ehconsumer
│ └── mqttclient
├── ts: TypeScript
│ ├── kafkaproducer, kafkaconsumer
│ ├── ehproducer, ehconsumer
│ ├── sbproducer, sbconsumer
│ ├── egproducer, amqpproducer, amqpconsumer
│ └── mqttclient
├── asyncapi: AsyncAPI 3.0 definitions
└── openapi: OpenAPI 3.0 definitions
AMQP 1.0 (RabbitMQ, Artemis, Qpid)
# Generate Java producer
xrcg generate --language java --style amqpproducer \
--projectname MyProducer --definitions ./catalog.json --output ./out
# Generate C# consumer
xrcg generate --language cs --style amqpconsumer \
--projectname MyConsumer --definitions ./catalog.json --output ./outSee RabbitMQ AMQP 1.0 Setup Guide for broker configuration.
AsyncAPI / OpenAPI Generation
# Generate AsyncAPI producer definition
xrcg generate --language asyncapi --style producer \
--projectname MyAPI --definitions ./catalog.json --output ./out
# With binary CloudEvents mode
xrcg generate --language asyncapi --style producer \
--projectname MyAPI --definitions ./catalog.json --output ./out \
--template-args ce_content_mode=binary
# Generate OpenAPI for HTTP producer
xrcg generate --language openapi --style producer \
--projectname MyAPI --definitions ./catalog.json --output ./outOverride built-in templates or add new language/style combinations:
xrcg generate --templates ./my-templates --language java --style myproducer ...Template directory structure mirrors the built-in templates. See Authoring Templates.
docker pull ghcr.io/xregistry/codegen/xrcg:latestCreate a shell alias for convenience:
# Linux/macOS (.bashrc or .zshrc)
alias xrcg='docker run --rm -v $(pwd):/work ghcr.io/xregistry/codegen/xrcg:latest'
# Windows PowerShell (profile)
function xrcg { docker run --rm -v ${PWD}:/work ghcr.io/xregistry/codegen/xrcg:latest $args }Note: File paths must be relative to your current directory due to Docker volume mapping.
Requires Python 3.10+:
pip install git+https://github.com/xregistry/codegen.gitFor development setup, see Development Environment.
The generator consumes xRegistry message catalog documents—JSON/YAML files that describe schemas, messages, and endpoints. You can:
- Use existing definition files (see samples/message-definitions/)
- Create definitions manually following the xRegistry spec
- Manage definitions using the CLI's
manifestorcatalogcommands
| Sample | Description |
|---|---|
| contoso-erp.xreg.json | ERP system events (orders, payments, inventory) |
| fabrikam-motorsports.xreg.json | Motorsports telemetry stream |
| inkjet.xreg.json | IoT printer events |
Manifest Mode (Local Files)
Work with local JSON files for version-controlled, offline workflows:
# Create a message group
xrcg manifest messagegroup add --manifest=./catalog.json --id=orders --envelope=CloudEvents/1.0
# Add a message definition
xrcg manifest message add --manifest=./catalog.json --messagegroupid=orders \
--id=OrderPlaced --description="Order was placed"
# Validate the file
xrcg validate --definitions ./catalog.jsonCatalog Mode (Remote Registry)
Interact with a remote xRegistry HTTP API for team collaboration:
# Configure registry connection
xrcg config set registry.base_url https://registry.example.com
xrcg config set registry.auth_token <token>
# Work with remote registry
xrcg catalog messagegroup add --id=orders ...
xrcg catalog message list --messagegroupid=ordersCurrently supports xrserver registry.
Check definition files for errors:
xrcg validate --definitions ./catalog.json
xrcg validate --definitions https://example.com/catalog.jsonStore defaults to avoid repetition:
xrcg config set defaults.language java
xrcg config set defaults.output_dir ./generated
xrcg config listConfig location: ~/.config/xrcg/config.json (Linux), %APPDATA%\xrcg\config.json (Windows)
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.
- Slack: #cloudevents on CNCF Slack
- Mailing list: cncf-cloudevents@lists.cncf.io
- Governance: GOVERNANCE.md
- Contributing: CONTRIBUTING.md
![@dependabot[bot]](https://avatars.githubusercontent.com/in/29110?s=64&v=4){kind=small}