axonops-schema-registry

README

AxonOps Schema Registry

High-Performance Kafka Schema Registry with Multi-Backend Storage and Enterprise Security

Getting Started | Documentation | API Reference | Report Issue

---

Overview

AxonOps Schema Registry is a schema registry for Apache Kafka® that manages and enforces schemas for event-driven architectures. It stores versioned Avro, Protobuf, and JSON Schema definitions, validates compatibility between schema versions, and ensures producers and consumers agree on data formats.

Unlike Confluent Schema Registry, which uses Kafka itself (a special _schemas topic) as its storage backend, AxonOps Schema Registry does not require Kafka for storage -- it uses standard databases (PostgreSQL, MySQL, or Cassandra) while remaining fully API-compatible with Confluent's REST API, serializers, and client libraries.

100% Free & Open Source

Apache 2.0 Licensed -- No hidden costs -- No premium tiers -- No license keys

Contents

• Why AxonOps Schema Registry?
• Feature Comparison
• Quick Start
• Features
• Architecture
• API Compatibility
• Strict Specification Compliance
• Documentation
• Development
• Community & Support
• License
• Legal Notices

New to schema registries? Read the Fundamentals guide to understand what a schema registry is, why it matters, and how it fits into an event-driven architecture. Ready to design your schemas? See Best Practices for patterns, naming conventions, and evolution strategies.

Why AxonOps Schema Registry?

• No Kafka Dependency -- uses standard databases (PostgreSQL, MySQL, Cassandra) instead of Kafka for storage
• Single Binary -- ~50 MB memory footprint, zero runtime dependencies
• Full API Compatibility -- works with Confluent serializers for Java, Go, and Python
• Enterprise Security -- LDAP, OIDC, mTLS, API keys, JWT, and RBAC out of the box
• Cloud Native -- designed for Kubernetes with health checks, Prometheus metrics, and graceful shutdown
• Multi-Datacenter -- active-active deployments with Cassandra's native cross-DC replication
• Enterprise Features, Zero Cost -- RBAC, data contracts, CSFLE encryption, audit logging, and rate limiting are included free under Apache 2.0. With Confluent, these require a commercial Enterprise license.
• Strict Specification Compliance -- enforces Avro, Protobuf, and JSON Schema specifications more faithfully than Confluent, catching invalid schemas at registration time rather than at runtime (details)
• Built-in API Documentation -- OpenAPI spec with Swagger UI and ReDoc, always in sync with the codebase

Feature Comparison

Comparison based on upstream/default configurations. Third-party plugins may extend capabilities.

Feature	AxonOps	Confluent OSS	Confluent Enterprise	Karapace
License	Apache 2.0	Confluent Community	Commercial	Apache 2.0
Language	Go	Java	Java	Python
API Compatibility	Full	N/A	N/A	Full
Avro	✅	✅	✅	✅
Protobuf	✅	✅	✅	✅
JSON Schema	✅	✅	✅	✅
Schema References	✅	✅	✅	✅
All 7 Compat Modes	✅	✅	✅	✅
Storage: Kafka	❌	✅	✅	✅
Storage: PostgreSQL	✅	❌	❌	❌
Storage: MySQL	✅	❌	❌	❌
Storage: Cassandra	✅	❌	❌	❌
No Kafka Dependency	✅	❌	❌	❌
Basic Auth	✅	✅ ³	✅	⚠️ ⁴
API Keys	✅	❌	✅	❌
LDAP/AD	✅	⚠️ ³	✅	❌
OIDC/OAuth2	✅	✅ ³	✅	❌
mTLS	✅	✅	✅	✅
RBAC	✅	❌	✅	⚠️ Limited
Audit Logging	✅	❌	✅	❌
Rate Limiting	✅	❌	❌	❌
Prometheus Metrics	✅	✅	✅	✅
REST Proxy	❌	Separate	Separate	✅
Schema Validation	✅	✅	✅	✅
Strict Spec Compliance	✅	❌	❌	⚠️ Partial
Data Contracts	✅	❌	✅	❌
Multi-Tenant Contexts	✅	✅	✅	❌
DEK Registry (CSFLE)	✅	❌	✅	❌
KMS Providers	2 + 3 ¹	❌	✅	❌
Exporter API ²	✅	❌	✅	❌
Single Binary	✅	❌	❌	❌
Memory Footprint	~50MB	~500MB+	~500MB+	~200MB+

¹ HashiCorp Vault and OpenBao Transit are production-ready. AWS KMS, Azure Key Vault, and GCP KMS support is coming soon.

² Confluent-compatible exporter management API for schema replication configuration. AxonOps stores exporter definitions; active cross-registry replication requires an external agent.

³ Confluent OSS authentication requires Java JAAS LoginModule configuration. AxonOps provides all authentication methods as built-in features with simple YAML configuration -- no Java runtime, no external plugins, no license keys.

⁴ Karapace uses its own ACL-based credential mechanism rather than standard HTTP Basic Authentication.

In short: AxonOps gives you Confluent Enterprise-grade capabilities -- data contracts, client-side encryption, RBAC, audit logging, multi-tenant contexts, and rate limiting -- under the Apache 2.0 license, in a single ~50 MB binary, with no Kafka dependency for storage. If you need enterprise support, AxonOps offers commercial support plans.

Quick Start

# Start with Docker (in-memory storage, no database required)
docker run -d -p 8081:8081 ghcr.io/axonops/axonops-schema-registry:latest

# Verify
curl http://localhost:8081/

# Register a schema
curl -X POST http://localhost:8081/subjects/users-value/versions \
  -H "Content-Type: application/vnd.schemaregistry.v1+json" \
  -d '{"schema": "{\"type\": \"record\", \"name\": \"User\", \"fields\": [{\"name\": \"id\", \"type\": \"int\"}, {\"name\": \"name\", \"type\": \"string\"}]}"}'

# Check compatibility
curl -X POST http://localhost:8081/compatibility/subjects/users-value/versions/latest \
  -H "Content-Type: application/vnd.schemaregistry.v1+json" \
  -d '{"schema": "{\"type\": \"record\", \"name\": \"User\", \"fields\": [{\"name\": \"id\", \"type\": \"int\"}, {\"name\": \"name\", \"type\": \"string\"}, {\"name\": \"email\", \"type\": [\"null\", \"string\"], \"default\": null}]}"}'

See the Getting Started guide for Kafka client integration examples in Java, Go, and Python.

---

Features

Schema Management

• Multi-Format -- Avro, Protocol Buffers (proto2/proto3), JSON Schema
• Schema References -- cross-subject dependencies for all three schema types
• 7 Compatibility Modes -- NONE, BACKWARD, FORWARD, FULL, and transitive variants
• Normalization -- canonical form generation for content-addressed deduplication
• Soft Delete -- recoverable deletion with permanent delete option
• Multi-Tenant Contexts -- namespace isolation with independent schema IDs, subjects, compatibility config, and modes per context (docs)
• Data Contracts -- schema metadata (tags, properties, sensitive fields), rule sets (domain rules, migration rules, encoding rules), and config-level defaults/overrides with 3-layer merge (docs)

Encryption

• DEK Registry -- Client-Side Field Level Encryption (CSFLE) with KEK/DEK management, compatible with Confluent's Enterprise CSFLE feature (docs)
• KMS Providers -- HashiCorp Vault and OpenBao Transit for production use. AWS KMS, Azure Key Vault, and GCP KMS coming soon.
• Exporter API -- Confluent-compatible exporter management API for schema replication configuration (docs)

Storage Backends

Backend	Use Case	Concurrency Model
PostgreSQL	Production	ACID transactions with row-level locking
MySQL	Production	ACID transactions with SELECT ... FOR UPDATE
Cassandra 5+	Distributed / HA	Lightweight transactions (LWT) + SAI indexes
Memory	Development	Mutex-based, no persistence

Note: The Cassandra storage backend requires Cassandra 5.0 or later. Earlier versions are not supported.

Auth storage can optionally be separated into HashiCorp Vault.

Security

• Authentication -- Basic Auth, API Keys, JWT, LDAP/AD, OIDC, mTLS
• Authorization -- RBAC with 4 built-in roles (super_admin, admin, developer, readonly)
• Rate Limiting -- Token bucket algorithm, per-client or per-endpoint
• Audit Logging -- Structured JSON events to file or stdout
• TLS -- Auto-reload certificates, configurable minimum version, mutual TLS

Operations

• Prometheus Metrics -- 19 metrics covering requests, schemas, compatibility, storage, cache, auth, and rate limiting
• Health Checks -- GET / for load balancer and Kubernetes probes
• Swagger UI -- Built-in interactive API documentation at GET /docs
• Graceful Shutdown -- Clean connection draining on SIGTERM/SIGINT
• Database Migrations -- Automatic schema creation and upgrades

---

Architecture

AxonOps Schema Registry is a single stateless binary that connects to any supported storage backend. There is no leader election and no inter-instance coordination -- database-level constraints handle concurrency.

• Single instance -- one binary, one database connection. Suitable for development or low-traffic production.
• High availability -- multiple stateless instances behind a load balancer with database-level locking (PostgreSQL/MySQL).
• Multi-datacenter -- active-active across datacenters using Cassandra's native cross-DC replication and lightweight transactions.

See Deployment for detailed architecture diagrams, topology options, and production configuration.

---

API Compatibility

AxonOps Schema Registry implements the Confluent Schema Registry REST API v1:

• All endpoints -- schemas, subjects, compatibility, config, mode, import, DEK Registry (CSFLE), and Exporters (Schema Linking)
• All serializers -- compatible with Confluent's Avro, Protobuf, and JSON Schema serializers
• All client libraries -- works with confluent-kafka-go, confluent-kafka-python, and Java Kafka clients
• DEK Registry -- full Confluent Enterprise CSFLE parity (KEK/DEK management with 5 KMS providers), available at no additional cost
• Error format -- HTTP status codes and error response JSON match Confluent behavior

Known differences:

• Contexts -- Both Confluent and AxonOps Schema Registry support contexts for multi-tenancy. Subjects can be qualified with a context prefix (e.g., :.mycontext:my-subject), and schema IDs are unique within each context. AxonOps also supports URL prefix routing (/contexts/.mycontext/subjects/...) as an alternative. See the Contexts guide for full documentation.
• Cluster coordination -- Confluent uses Kafka's group protocol for leader election between registry instances. AxonOps instances are fully stateless with no leader election -- database-level constraints (transactions, LWTs) handle coordination instead.

---

Strict Specification Compliance

AxonOps Schema Registry enforces Avro, Protobuf, and JSON Schema specifications more faithfully than Confluent Schema Registry. This catches invalid schemas at registration time -- before they enter your pipeline and cause failures during serialization, deserialization, or code generation.

Schema Fingerprinting and Deduplication

AxonOps uses specification-correct canonical forms for schema fingerprinting, producing better deduplication than Confluent's raw-string approach.

Behavior	AxonOps	Confluent	Why AxonOps is Better
Avro Parsing Canonical Form	Follows the Avro spec PCF: strips doc, aliases, and order from the fingerprint	Includes doc, aliases, and order in the fingerprint	Two schemas that differ only in documentation or field ordering hints are logically identical. AxonOps correctly assigns them the same global ID, avoiding unnecessary schema proliferation.
JSON Schema key ordering	Normalizes JSON key order before fingerprinting	Hashes the raw JSON string, so {"type":"object","properties":...} and {"properties":...,"type":"object"} get different IDs	JSON objects are unordered by specification (RFC 8259). AxonOps correctly treats key-reordered schemas as identical.

Stricter Schema Validation

Confluent accepts several schemas that violate their respective specifications. AxonOps rejects them at registration time with a 422 error, preventing invalid schemas from entering the registry.

Invalid Schema	AxonOps	Confluent	Specification Reference
Avro: invalid default type (e.g., "default": "not_a_number" on an int field)	Rejects (422)	Accepts (200)	Avro spec: "A default value for this field, only used when reading instances that lack this field for schema evolution purposes. [...] The value type must match the field's schema type."
Avro: enum with empty symbols ("symbols": [])	Rejects (422)	Accepts (200)	Avro spec: "symbols: a JSON array, listing symbols, as JSON strings. All symbols in an enum must be unique." An empty array produces an unusable enum type with no valid values.
Avro: fixed with size 0 ("size": 0)	Rejects (422)	Accepts (200)	Avro spec: "size: an integer, specifying the number of bytes per value." A zero-byte fixed type is meaningless and will fail during serialization.
Protobuf: duplicate field numbers (two fields with the same number in one message)	Rejects (422)	Accepts (200)	Protobuf spec: "Each field in the message definition has a unique number." Duplicate field numbers produce ambiguous wire format encoding.
Protobuf: unresolvable imports (import "nonexistent/file.proto")	Rejects (422)	Accepts (200)	Protobuf spec: Imports must resolve to a known .proto file. An unresolvable import will fail at compile time in any language.

JSON Schema Draft-07 Boolean Root Schemas

AxonOps supports boolean root schemas (true and false as standalone schemas), which are valid in JSON Schema Draft-07 but uncommon. true accepts any instance, false rejects all instances.

Impact on Migration

If you are migrating from Confluent and have schemas that contain the invalid patterns listed above, those schemas will be rejected by AxonOps during import. This is by design -- it surfaces latent problems in your schema definitions. You should fix the invalid schemas before migrating.

For the fingerprinting differences, schemas that Confluent stored as separate global IDs (because they differ only in doc, aliases, order, or JSON key ordering) will be correctly deduplicated to a single global ID in AxonOps.

---

Documentation

Guide	Description
Fundamentals	What is a schema registry, core concepts, and how it fits into Kafka
Best Practices	Schema design patterns, naming conventions, evolution strategies, and common mistakes
Getting Started	Run the registry and register your first schemas in five minutes
Installation	Docker, APT, YUM, binary, Kubernetes, and from-source installation
Configuration	Complete YAML reference with all fields, defaults, and environment variables
Storage Backends	PostgreSQL, MySQL, Cassandra, and in-memory backend setup and tuning
Schema Types	Avro, Protobuf, and JSON Schema support with reference examples
Compatibility	All 7 compatibility modes with per-type rules and configuration
Contexts	Multi-tenancy via contexts: namespace isolation, qualified subjects, URL routing
Data Contracts	Metadata, rule sets, config defaults/overrides, and governance policies
API Reference	All 47+ endpoints with parameters, examples, and error codes
Authentication	All 6 auth methods, RBAC, user management, and admin CLI
Security	TLS, rate limiting, audit logging, credential storage, and hardening checklist
Deployment	Architecture diagrams, topologies, Docker Compose, Kubernetes manifests, systemd, and health checks
Monitoring	Prometheus metrics, alerting rules, structured logging, and Grafana queries
Migration	Migrating from Confluent Schema Registry with preserved schema IDs
Testing Strategy	Testing philosophy, all test layers, how to run and write tests
Development	Building from source, running the test suite, and contributing
Encryption	DEK Registry, Client-Side Field Level Encryption (CSFLE), and KMS providers
Exporters	Schema Linking via exporter management API
Troubleshooting	Common issues, diagnostic commands, and error code reference

---

Development

Building from Source

git clone https://github.com/axonops/axonops-schema-registry.git
cd axonops-schema-registry
make build

Running Tests

# Unit tests
make test

# Integration tests (requires Docker)
make test-integration

# BDD tests
make test-bdd

# All tests with coverage
make test-coverage

See the Development guide for the full build, test, and contribution workflow.

Contributing

We welcome contributions from the community. Please read the Development guide before submitting pull requests. It covers:

• Code conventions and project structure
• Testing philosophy and how to write tests
• Step-by-step developer workflows
• How to update the API and regenerate documentation

---

Community & Support

• GitHub Issues -- Report bugs or request features
• GitHub Discussions -- Ask questions and share ideas
• Commercial Support -- axonops.com for enterprise support plans
• Website -- axonops.com

If you find AxonOps Schema Registry useful, please consider giving us a star!

---

License

Apache License 2.0 -- see LICENSE for details.

---

Legal Notices

This project may contain trademarks or logos for projects, products, or services. Any use of third-party trademarks or logos is subject to those third parties' policies.

• AxonOps is a registered trademark of AxonOps Limited.
• Apache, Apache Cassandra, Cassandra, Apache Kafka, and Kafka are either registered trademarks or trademarks of the Apache Software Foundation or its subsidiaries in Canada, the United States, and/or other countries.
• Confluent is a registered trademark of Confluent, Inc.

---

Made with ❤ by the AxonOps team

Copyright © 2026 AxonOps Limited