Use Avro Schemas

Avro is the most widely used format with the Schema Registry. It’s compact on the wire, has a well-specified resolution algorithm for reading data written under a different schema, and its compatibility rules are the most predictable of the three formats.

Configure the serializer

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

And the deserializer:

props.put(ConsumerConfig.KEY_DESERIALIZER_CLASS_CONFIG, StringDeserializer.class);
props.put(ConsumerConfig.VALUE_DESERIALIZER_CLASS_CONFIG, KafkaAvroDeserializer.class);
props.put(KafkaAvroDeserializerConfig.SCHEMA_REGISTRY_URL_CONFIG, schemaRegistryUrl);
props.put(KafkaAvroDeserializerConfig.SPECIFIC_AVRO_READER_CONFIG, true);

Add the dependency:

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

The Confluent artifacts come from Confluent’s Maven repository:

<repository>
  <id>confluent</id>
  <url>https://packages.confluent.io/maven/</url>
</repository>

SpecificRecord or GenericRecord

Avro gives you two ways to represent a record in Java, and the choice affects how schema changes reach your code.

SpecificRecord

Generate a class from an .avsc file with the Avro Maven plugin, and work with typed getters and setters:

Producer<String, Order> producer = new KafkaProducer<>(props);
Order order = Order.newBuilder()
    .setId("order-1")
    .setTotal(42.0)
    .build();
producer.send(new ProducerRecord<>("orders", order.getId().toString(), order));

props.put(KafkaAvroDeserializerConfig.SPECIFIC_AVRO_READER_CONFIG, true);

Consumer<String, Order> consumer = new KafkaConsumer<>(props);
for (ConsumerRecord<String, Order> record : consumer.poll(Duration.ofSeconds(1))) {
    Order order = record.value();
    System.out.println(order.getTotal());
}

Use it when the schema is stable and you want compile-time safety. The trade-off is that a schema change means regenerating the class and redeploying—which is a feature, not a bug, if you want schema drift to surface at build time.

GenericRecord

Work with the schema at runtime, addressing fields by name:

Schema schema = new Schema.Parser().parse(schemaString);
GenericRecord order = new GenericData.Record(schema);
order.put("id", "order-1");
order.put("total", 42.0);

producer.send(new ProducerRecord<>("orders", "order-1", order));

// SPECIFIC_AVRO_READER_CONFIG defaults to false
for (ConsumerRecord<String, GenericRecord> record : consumer.poll(Duration.ofSeconds(1))) {
    Object total = record.value().get("total");
}

Use it when you don’t know the schema at build time—routers, sinks, format converters, and any application that handles whatever arrives. The cost is no compile-time checking: a renamed field becomes a runtime null.

Most applications should use SpecificRecord. Reach for GenericRecord when the code is genuinely schema-agnostic, not merely when generating classes feels like a chore.

Compatibility rules

Avro compatibility follows the Avro schema resolution rules. The practical version:

Change	Backward compatible	Forward compatible
Add a field with a default	Yes	Yes
Add a field without a default	No	Yes
Delete a field that had a default	Yes	Yes
Delete a field without a default	Yes	No
Rename a field	Only with an alias	Only with an alias
Widen a type within Avro’s promotion rules (`int` → `long` → `float` → `double`)	Yes	No
Narrow a type	No	Yes
Add a value to an enum	No	Yes
Add a branch to a union	No	Yes

Defaults are what make evolution work. A field with no default gives a reader nothing to fall back on when the writer’s data omits it, so almost every safe addition is an addition with a default. To rename a field without breaking readers, keep the old name as an alias:

{"name": "orderTotal", "type": "double", "aliases": ["total"]}

The default compatibility mode is BACKWARD. See Evolution and compatibility.

Logical types

Avro logical types—timestamp-millis, decimal, uuid, date—annotate a primitive with semantic meaning:

{"name": "createdAt", "type": {"type": "long", "logicalType": "timestamp-millis"}}

Compatibility is evaluated on the underlying primitive, so changing the logical type while keeping the primitive passes the check but may change how your application interprets the value. Treat a logical-type change as a breaking change even when the registry accepts it.

Schema references

Avro references a schema by its fully qualified record name. See Schema references.

Normalization

?normalize=true performs real normalization for Avro, so schemas differing only in field ordering or whitespace resolve to the same schema ID.

Introduction

Get Started

Kafka Clusters

Process

Lakehouse

Governance

Migrate

Kafka Clients

Configure the serializer

SpecificRecord or GenericRecord

SpecificRecord

GenericRecord

Compatibility rules

Logical types

Schema references

Normalization

Next steps

Protobuf

JSON Schema

​Configure the serializer

​SpecificRecord or GenericRecord

​SpecificRecord

​GenericRecord

​Compatibility rules

​Logical types

​Schema references

​Normalization

​Next steps

Protobuf

JSON Schema

Configure the serializer

SpecificRecord or GenericRecord

SpecificRecord

GenericRecord

Compatibility rules

Logical types

Schema references

Normalization

Next steps