Apicurio Registry is a central store for the contracts that services share: event schemas such as Avro, Protobuf and JSON Schema, and API definitions such as OpenAPI and AsyncAPI. It keeps every version of each artifact, checks new versions against validity and compatibility rules, and serves them to applications through a REST API and Kafka serializers. It addresses a common failure of event-driven systems: a producer changes a message format, and consumers break because no one agreed or checked the change. With a registry, a producer cannot publish an incompatible schema, and a consumer can always find the exact schema a message was written with. Apicurio Registry grew from the Apicurio community, long sponsored by Red Hat, and was accepted into the CNCF at the Sandbox level on March 12, 2026.
CNCF daily · Sprint 3, post 4 of 21 · Streaming & Messaging
At a glance
| Category | App Definition and Development › Streaming & Messaging |
| CNCF status | Sandbox. Accepted March 12, 2026 |
| Written in | Java, on the Quarkus framework |
| License | Apache 2.0 |
| Artifact types | Avro, Protobuf, JSON Schema, OpenAPI, AsyncAPI, GraphQL, XML Schema, WSDL and others |
| Rules | Validity and compatibility (backward, forward, full or none) per artifact or globally |
| Storage | In-memory for development; a SQL database such as PostgreSQL, or a Kafka-based store, for production |
| Interfaces | Native REST API (v3), a Confluent-compatible API, web UI, Kafka serializers and deserializers |
Architecture
flowchart TB
DEV[Developer or CI<br/>schema in Git] ==>|register artifact<br/>REST API| REG[Apicurio Registry<br/>rules and versions]
REG ==>|SQL| DB[PostgreSQL<br/>artifact store]
PROD[Kafka producer<br/>Apicurio serializer] ==>|fetch or register schema<br/>by id| REG
PROD ==>|message with schema id<br/>in header or payload| KAF[Kafka topic]
KAF ==>|message| CONS[Kafka consumer<br/>Apicurio deserializer]
CONS ==>|resolve schema id<br/>cached after first call| REG
UI[Web UI and API clients] -.->|browse search compare| REG
CC[Confluent compatible clients] -.->|ccompat API| REG
REG -.->|compatibility check<br/>reject incompatible version| DEV
classDef core fill:#0f766e,stroke:#064e4a,stroke-width:2px,color:#ffffff
classDef data fill:#e3f2fd,stroke:#1565c0,stroke-width:1.5px,color:#1d1c1a
classDef actor fill:#eceff1,stroke:#455a64,stroke-width:1.5px,color:#1d1c1a
class REG core
class DB,KAF,PROD,CONS data
class DEV,UI,CC actor
Key: teal is Apicurio Registry, blue are stores and Kafka applications, grey are people, CI and other clients. Thick arrows carry schemas and messages, dashed arrows browsing, compatibility and alternate APIs.
| Component | Responsibility |
|---|---|
| Registry server | Stores artifacts and versions, applies rules, and exposes the REST API and web UI. |
| Groups, artifacts, versions | The data model. A group holds artifacts, such as orders-value, and each artifact has ordered versions. |
| Rules | Validity (the content parses) and compatibility (the new version works with earlier ones) checks, run on every registration. |
| Kafka serdes | Serializers and deserializers that put a schema identifier into each message and look the schema up on read. |
| Storage backend | A SQL database or Kafka topic that holds the artifacts. |
Design principle. Agree the contract before the data moves. The schema lives in one governed place, producers and consumers reference it by identifier, and incompatible changes are rejected at registration time rather than discovered in production.
Production reference design
A typical Kubernetes deployment places the registry beside the Kafka cluster, backed by a managed or operator-run database.
- Provide storage. Use PostgreSQL with backups, since schema loss would make existing messages unreadable.
- Deploy the registry. Run at least two replicas behind a service. The registry can be installed by its Kubernetes operator or from the container image, configured with the database settings. Configuration names vary by release, so use the documentation for yours. The shape is:
env: - { name: APICURIO_STORAGE_KIND, value: sql } - { name: APICURIO_STORAGE_SQL_KIND, value: postgresql } - { name: APICURIO_DATASOURCE_URL, value: "jdbc:postgresql://pg-rw.data:5432/registry" } - { name: APICURIO_DATASOURCE_USERNAME, valueFrom: { secretKeyRef: { name: registry-db, key: username } } } - { name: APICURIO_DATASOURCE_PASSWORD, valueFrom: { secretKeyRef: { name: registry-db, key: password } } } - Set rules. Turn on a global compatibility rule such as
BACKWARD, so every new version must remain readable by consumers of the previous one. - Register schemas from CI. Publish schemas on merge, so the registry follows Git. The Confluent-compatible API offers a familiar call:
curl -X POST -H "Content-Type: application/vnd.schemaregistry.v1+json" \ --data '{"schema": "{\"type\":\"record\",\"name\":\"Order\",\"fields\":[{\"name\":\"id\",\"type\":\"long\"}]}"}' \ https://registry.example.com/apis/ccompat/v7/subjects/orders-value/versions - Configure clients. For a Java producer using the native serdes:
Disabling auto-registration in production keeps schema changes inside the reviewed pipeline.value.serializer=io.apicurio.registry.serde.avro.AvroKafkaSerializer apicurio.registry.url=https://registry.example.com/apis/registry/v3 apicurio.registry.auto-register=false
Typical uses include governing Kafka event schemas, sharing API definitions between teams, validating CI changes, and documenting event contracts for catalogues. A registry fits naturally beside Kafka clusters managed by Strimzi and events described with CloudEvents.
Operational considerations
- The registry is on the data path. Clients cache schemas after the first lookup, but cold starts and new schemas need it. Run replicas and watch latency and error rates.
- Durability. Back up the database. Treat schemas as irreplaceable, since messages reference them by identifier.
- Compatibility policy. Pick a rule per use case and apply it consistently. A rule that is too loose allows breaking changes, and one that is too strict blocks legitimate evolution.
- Security. Enable authentication and role-based access, because write access to a schema is the ability to break every consumer.
- Client library versions. Serializer and registry versions must be compatible. Test upgrades with real consumers and check the API version in client configuration.
Adoption
- Red Hat has long sponsored the project and ships it as part of its products, including its service registry offerings.
- The project lists community users on its website and in its repository. Because it joined the CNCF in 2026, the CNCF adopter record is still short, so teams should check for recent references.
Alternatives
| Solution | Model | Best suited to |
|---|---|---|
| Confluent Schema Registry | Kafka schema registry from Confluent | Confluent Platform users; community licence terms apply |
| Karapace | Open-source, API-compatible registry (Aiven) | Confluent API compatibility with a permissive licence |
| AWS Glue Schema Registry | Managed registry | AWS-centred streaming workloads |
| Buf Schema Registry | Protobuf-focused registry | Teams standardised on Protobuf and gRPC |
| Strimzi with CloudEvents only | Broker operator and event envelope | Systems that do not yet need schema governance; see the Strimzi brief |
Strengths and limitations
| Strengths | Limitations |
|---|---|
| Supports many artifact types, not only Kafka schemas | New to the CNCF, with a short adopter record there |
| Compatibility rules catch breaking changes early | Java and Quarkus runtime with its own sizing needs |
| Confluent-compatible API eases migration | Native API changed between major versions |
| Flexible storage, including PostgreSQL | Another critical component on the event path |
| Open source under Apache 2.0 | Governance process still needed around who may register |
Recommendation
Adopt for teams running Kafka at any scale who need schema governance, with PostgreSQL storage, a global backward compatibility rule and CI-driven registration. Disable auto-registration in production and review schema changes like code. If you already run Confluent Schema Registry or Karapace, migration is mainly a client configuration change through the compatible API, so compare operational fit before switching.
References: CNCF project page · Apicurio website · Apicurio Registry repository · CNCF Landscape