Use JSON Schemas

JSON Schema is the most flexible of the three formats and the trickiest to evolve. Its compatibility semantics hinge on one keyword—additionalProperties—and getting that wrong produces the error most people meet first.

The JSON schema type means JSON Schema: a schema document that constrains the data. Producing unschematized JSON isn’t a registry feature—a record still carries the schema ID prefix.

Configure the serializer

props.put(ProducerConfig.VALUE_SERIALIZER_CLASS_CONFIG, KafkaJsonSchemaSerializer.class);
props.put(KafkaJsonSchemaSerializerConfig.SCHEMA_REGISTRY_URL_CONFIG, schemaRegistryUrl);
props.put(KafkaJsonSchemaSerializerConfig.BASIC_AUTH_CREDENTIALS_SOURCE, "USER_INFO");
props.put(KafkaJsonSchemaSerializerConfig.USER_INFO_CONFIG, String.format("%s:%s", "any-user", apiKey));

And the deserializer:

props.put(ConsumerConfig.VALUE_DESERIALIZER_CLASS_CONFIG, KafkaJsonSchemaDeserializer.class);
props.put(KafkaJsonSchemaDeserializerConfig.SCHEMA_REGISTRY_URL_CONFIG, schemaRegistryUrl);
props.put(KafkaJsonSchemaDeserializerConfig.JSON_VALUE_TYPE, Order.class);

Add the dependency:

<dependency>
  <groupId>io.confluent</groupId>
  <artifactId>kafka-json-schema-serializer</artifactId>
  <version>7.5.0</version>
</dependency>

Provide the schema

Annotate your class so the serializer can derive a schema from it:

@Schema(value = "{"
    + "\"type\":\"object\","
    + "\"properties\":{"
    + "  \"id\":{\"type\":\"string\"},"
    + "  \"total\":{\"type\":\"number\"}"
    + "},"
    + "\"required\":[\"id\"],"
    + "\"additionalProperties\":false"
    + "}", refs = {})
public class Order {
    public String id;
    public double total;
}

Or send a JsonNode directly when you have no class to annotate—the serializer uses the schema registered for the subject.

Open and closed content models

This is the concept that governs JSON Schema evolution.

Closed ("additionalProperties": false)—the document may contain only the declared properties. Anything else fails validation.
Open (additionalProperties absent or true)—undeclared properties are permitted.

The default is open, because additionalProperties defaults to true in JSON Schema. An open model makes adding a property awkward. Under an open schema, data written before the property existed may already have contained a value under that name with a different type—so the registry can’t prove that adding it is safe.

Adding a property to an open schema produces:

The new schema has an open content model and has a property not present in the old schema

Two ways out:

Close the model. Set "additionalProperties": false on the original schema before you add properties. This is the durable fix, and worth doing on any new subject from the start.
Declare the new property on the old schema too, so both versions agree it exists.

Closing the model on a schema that already has versions is itself a compatibility change, so make that decision when you create the subject.

Compatibility rules per construct

Construct	Backward-compatible change
Primitive types	Widening only—`integer` → `number`. Narrowing is breaking.
Objects	Add an optional property to a closed model. Remove a property from `required`. Adding a required property is breaking.
Enums	Add a value only if readers tolerate unknown values. Removing a value is breaking.
Arrays	Relax `items` constraints. Tightening them is breaking.
Unions (`oneOf`, `anyOf`)	Add a branch under forward compatibility. Removing a branch is breaking.

Moving a property between required and optional is the most common intentional change, and the direction matters: making a property optional is backward compatible, making one required is not. The default compatibility mode is BACKWARD. See Evolution and compatibility.

Schema references

JSON Schema references another schema through $ref, with the reference name matching the $ref value:

{
  "type": "object",
  "properties": {
    "address": {"$ref": "address.json"}
  },
  "additionalProperties": false
}

"references": [
  {"name": "address.json", "subject": "com.acme.Address", "version": 1}
]

A $ref pointing at an external URL—https://example.com/schemas/address.json—is rejected. Every reference must resolve to a schema registered in this registry. See Schema references.

Normalization for JSON Schema

?normalize=true performs real normalization for Avro and Protobuf. For JSON Schema it does not add semantic normalization—however, the schema is still reserialized before storage, so whitespace-only differences between two submissions don’t create separate schemas. The gap is field ordering: two JSON schemas that are semantically identical but list properties in a different order are stored as two distinct schemas with two distinct IDs, and each registration creates a new version. If your build serializes schemas non-deterministically, you can accumulate versions that are semantically identical. Serialize your schemas with sorted keys and a stable property order before registering them.

Introduction

Get Started

Kafka Clusters

Process

Lakehouse

Governance

Migrate

Kafka Clients

Configure the serializer

Provide the schema

Open and closed content models

Compatibility rules per construct

Schema references

Normalization for JSON Schema

Next steps

Avro

Protobuf

​Configure the serializer

​Provide the schema

​Open and closed content models

​Compatibility rules per construct

​Schema references

​Normalization for JSON Schema

​Next steps

Avro

Protobuf

Configure the serializer

Provide the schema

Open and closed content models

Compatibility rules per construct

Schema references

Normalization for JSON Schema

Next steps