Confluent Schema Registry: Kafka Schema Management

What is Confluent Schema Registry?

Confluent Schema Registry is a serving layer for schema metadata that runs alongside a Kafka cluster, exposing a RESTful interface for storing and retrieving Avro, JSON Schema, and Protobuf schemas. It keeps a versioned history of every schema under a subject name, applies configurable compatibility settings, and ships serializers that plug into Kafka clients so producers and consumers handle schema storage and retrieval automatically.

Core Features for Schema Management

• ✓A RESTful HTTP API for registering a new schema version under a subject, listing subjects, and fetching schemas by subject/version or by a globally unique schema ID, per the README's own curl examples.
• ✓Versioned schema history: every schema registered under a subject is tracked by version number, based on a specified subject name strategy.
• ✓Configurable compatibility settings applied globally via PUT /config or per subject via PUT /config/{subject} — the README's examples show setting compatibility to BACKWARD or NONE.
• ✓A dedicated compatibility-check endpoint (POST /compatibility/subjects/{subject}/versions/latest) that returns is_compatible: true or false before you commit to a schema change.
• ✓Serializers and deserializers for Avro, JSON Schema, and Protobuf that plug into Apache Kafka clients, handling schema storage and retrieval for messages automatically.
• ✓An OpenAPI (Swagger) spec generated automatically by swagger-maven-plugin during the Maven compile phase.
• ✓A built-in Jetty server exposing the REST interface, started and stopped with the bin/schema-registry-start and bin/schema-registry-stop wrapper scripts.

Interacting with the Schema Registry API

Every request goes over plain HTTP with an `application/vnd.schemaregistry.v1+json` content type, so curl or any REST client works fine — no client library is required. To register a new schema version, POST a JSON payload with a `schema` field to `/subjects/{subject}/versions`; the response is the schema's global ID. `GET /subjects` lists every subject Kafka Schema Registry currently tracks, and `GET /subjects/{subject}/versions` lists the version numbers under one of them. You can fetch a schema by its global ID with `GET /schemas/ids/{id}`, or fetch a specific or latest version with `GET /subjects/{subject}/versions/{version}` and `GET /subjects/{subject}/versions/latest`. Before registering a change, `POST` the candidate schema to `/compatibility/subjects/{subject}/versions/latest` and check the `is_compatible` field in the response. Compatibility rules themselves are read and set with `GET /config` and `PUT /config` (global) or `PUT /config/{subject}` (per subject); the README's own examples set this to BACKWARD or NONE. Deleting a version or an entire subject both use `DELETE` on the matching path.

Setting Up Schema Registry

There are two documented paths. The simplest is downloading a prebuilt version as part of the Confluent Platform. To build from source, you first need development versions of two sibling Confluent repos — common and rest-utils — installed, then you build Schema Registry itself with Maven: `mvn compile` to build, `mvn test` for unit and integration tests, and `mvn package` (optionally with `-DskipTests`) to produce packaged output under `package-schema-registry/target/` and `package-kafka-serde-tools/target/`. A `standalone` Maven profile (`mvn package -P standalone`) bundles all dependencies into a single fat JAR instead. Once built, the REST interface runs on a built-in Jetty server, started and stopped with the `bin/schema-registry-start` and `bin/schema-registry-stop` wrapper scripts — that's the README's recommended way to run it. An OpenAPI (Swagger) spec is generated automatically by swagger-maven-plugin during the Maven compile phase. Day-to-day configuration beyond that isn't detailed in this README; it points to separate Confluent documentation for installation and configuration.

Exploring Other Schema Solutions

Frequently Asked Questions

The problem it solves

Kafka moves bytes, not types — a producer and consumer only agree on message shape by convention, so a field rename or type change on one side can silently break the other side's deserializer at runtime, often after the bad message is already in the log. Confluent Schema Registry exists to turn that convention into an enforced, queryable source of truth: a central place where producers and consumers check a schema before serializing or deserializing, plus a compatibility check that can reject a breaking change before it's ever registered.

Best use cases

• •Giving Kafka producers and consumers a single subject-based source of truth for Avro, JSON Schema, or Protobuf message formats instead of coordinating schema changes by convention.
• •Rejecting a breaking schema change before it ships, by running it through the compatibility-check endpoint against BACKWARD (or whatever compatibility level is configured) first.
• •Wiring the Avro/JSON Schema/Protobuf serializers directly into Kafka producer and consumer code so schema registration and lookup happen automatically per message.
• •Building internal tooling — a schema browser, a CI gate, a migration script — directly against the plain REST API rather than a proprietary SDK.
• •Running Schema Registry as part of a Confluent Platform deployment, using the prebuilt package instead of a from-source build.

Who should try it — and who should skip

Try Confluent Schema Registry if you're running Kafka and want enforced, versioned schema contracts for Avro, JSON Schema, or Protobuf messages, with a compatibility check you can run before a change ships. Skip it — or at least read the license files first — if you need every component of your stack under an OSI-approved open-source license, since the core server sits under the Confluent Community License rather than Apache 2.0 or similar; the client and serializer modules are the exception, not the rule.

Related repositories