Schema compatibility rules in Kafka - Commands & Configuration

Introduction

When you use Kafka to send data, you often use schemas to define the data format. Schema compatibility rules help ensure that new versions of schemas work well with old data, so your apps don't break when you change data formats.

When you want to update your data format without breaking existing consumers.

When multiple teams produce and consume data on the same Kafka topic and need to agree on data structure changes.

When you want to enforce rules on how schemas evolve over time to avoid data errors.

When you want to safely add new fields to your messages without affecting old consumers.

When you want to prevent incompatible schema changes that could cause data processing failures.

Commands

This command sends a message to the Kafka topic 'example-topic' using an Avro schema that defines a record with a single string field 'name'. It shows how to produce data with a schema.

Terminal

kafka-avro-console-producer --broker-list localhost:9092 --topic example-topic --property value.schema='{"type":"record","name":"User","fields":[{"name":"name","type":"string"}]}'

Expected Output

No output (command runs silently)

→

--broker-list - Specifies the Kafka broker address to connect to.

→

--topic - Specifies the Kafka topic to send messages to.

→

--property value.schema - Defines the Avro schema for the message value.

This command sets the schema compatibility rule for the topic 'example-topic' to BACKWARD. This means new schemas must be compatible with previous schemas so old data can still be read.

Terminal

curl -X PUT -H "Content-Type: application/vnd.schemaregistry.v1+json" --data '{"compatibility":"BACKWARD"}' http://localhost:8081/config/example-topic

Expected Output

{"compatibility":"BACKWARD"}

This command retrieves the current schema compatibility setting for the topic 'example-topic' to verify the rule is set correctly.

Terminal

curl -X GET http://localhost:8081/config/example-topic

Expected Output

{"compatibility":"BACKWARD"}

Key Concept

If you remember nothing else from schema compatibility rules, remember: they protect your data consumers by ensuring new schema versions work with old data.

Common Mistakes

Setting compatibility to NONE and then changing schemas freely.

This can cause consumers to fail because they expect data in a certain format that no longer matches.

Use a compatibility rule like BACKWARD or FORWARD to ensure safe schema evolution.

Not verifying the compatibility setting after changing it.

You might think the rule is applied but it is not, leading to unexpected schema conflicts.

Always check the compatibility setting with a GET request after updating it.

Summary

Use schema compatibility rules to control how schemas evolve in Kafka topics.

Set compatibility modes like BACKWARD to keep new schemas compatible with old data.

Verify compatibility settings with API calls to avoid breaking consumers.

Practice

1. What does the BACKWARD compatibility rule in Kafka Schema Registry ensure?

easy

A. Both old and new schemas can read each other's data

B. Old schema can read data produced with the new schema

C. No compatibility checks are enforced

D. New schema can read data produced with the previous schema

Solution

1. Step 1: Understand BACKWARD compatibility meaning

   BACKWARD compatibility means new schema can read data written with the old schema.

2. Step 2: Compare options with definition

   New schema can read data produced with the previous schema matches this definition exactly, others describe different rules.

3. Final Answer:

   New schema can read data produced with the previous schema -> Option D

4. Quick Check:

   BACKWARD = New reads old [OK]

Hint: Backward means new schema reads old data [OK]

Common Mistakes:

• Confusing backward with forward compatibility
• Thinking backward means old reads new
• Assuming no compatibility checks

2. Which of the following is the correct way to set schema compatibility to FULL using Kafka Schema Registry REST API?

easy

A. POST /config -d '{"compatibilityLevel": "FULL"}'

B. PUT /config -d '{"compatibilityLevel": "FULL"}'

C. PUT /config -d '{"compatibility": "FULL"}'

D. GET /config -d '{"compatibility": "FULL"}'

Solution

1. Step 1: Identify correct HTTP method and endpoint

   Setting compatibility uses PUT on /config endpoint.

2. Step 2: Check correct JSON field name

   The field is "compatibilityLevel", not "compatibility".

3. Final Answer:

   PUT /config -d '{"compatibilityLevel": "FULL"}' -> Option B

4. Quick Check:

   PUT + compatibilityLevel = FULL [OK]

Hint: Use PUT and compatibilityLevel field [OK]

Common Mistakes:

• Using POST instead of PUT
• Using wrong JSON field name
• Using GET method to set config

3. Given the following schemas, which is the most restrictive compatibility rule that will allow the new schema to be registered without error?

Old schema: {"type": "record", "name": "User", "fields": [{"name": "name", "type": "string"}]}
New schema: {"type": "record", "name": "User", "fields": [{"name": "name", "type": "string"}, {"name": "age", "type": ["null", "int"], "default": null}]}

medium

A. FULL

B. FORWARD

C. NONE

D. BACKWARD

Solution

1. Step 1: Analyze schema change

   The new schema adds a field with a default value, which is backward and forward compatible.

2. Step 2: Determine compatibility rules allowing this

   FULL compatibility requires both backward and forward compatibility, which this change satisfies.

3. Final Answer:

   FULL -> Option A

4. Quick Check:

   Adding default field = FULL compatible [OK]

Hint: Adding default fields supports full compatibility [OK]

Common Mistakes:

• Thinking adding fields breaks backward compatibility
• Confusing NONE with allowing all changes
• Ignoring default values in new fields

4. You try to register a new schema that removes a required field from the old schema under BACKWARD compatibility. What is the likely result?

medium

A. Schema registration succeeds without errors

B. Schema registration succeeds but consumers break at runtime

C. Schema registration fails due to compatibility violation

D. Schema registration succeeds but producers reject data

Solution

1. Step 1: Understand backward compatibility rules

   Backward compatibility requires new schema to read old data, so removing required fields breaks this.

2. Step 2: Predict schema registry behavior

   Registry rejects schemas violating compatibility rules, so registration fails.

3. Final Answer:

   Schema registration fails due to compatibility violation -> Option C

4. Quick Check:

   Removing required field breaks backward = fail [OK]

Hint: Removing required fields breaks backward compatibility [OK]

Common Mistakes:

• Assuming registration always succeeds
• Confusing runtime errors with registration errors
• Thinking producers reject data on schema mismatch

5. You have a Kafka topic with schema compatibility set to FORWARD. You want to add a new optional field to the schema without breaking existing consumers. Which approach should you take?

hard

A. Add the new field with a default value or make it nullable

B. Remove an existing required field to simplify the schema

C. Add the new field without a default value

D. Change the type of an existing field to a different primitive type

Solution

1. Step 1: Understand FORWARD compatibility

   FORWARD compatibility means old schema can read data written with new schema.

2. Step 2: Determine safe schema changes

   Adding optional fields with defaults or nullable types preserves forward compatibility.

3. Step 3: Evaluate options

   Only Add the new field with a default value or make it nullable adds a field safely; others break compatibility or cause errors.

4. Final Answer:

   Add the new field with a default value or make it nullable -> Option A

5. Quick Check:

   Forward compatible additions need defaults or nullable [OK]

Hint: Add optional fields with defaults for forward compatibility [OK]

Common Mistakes:

• Adding required fields without defaults
• Removing fields under forward compatibility
• Changing field types without compatibility checks