Using Schema Registry
1. Understanding Schema Registry Role
| Aspect |
Description |
Detail |
| Central Store |
Versioned schemas |
Avro/Protobuf/JSON |
| Schema ID |
Embedded in message |
5-byte prefix |
| Compatibility |
Enforce evolution rules |
Safe changes |
[magic byte 0x00][4-byte schema id][avro payload]
2. Installing Schema Registry
| Step |
Description |
Detail |
| Package |
Confluent Platform |
schema-registry |
| Backing Store |
_schemas topic |
Compacted |
| Port |
HTTP 8081 |
Default |
Example: Start registry
schema-registry-start etc/schema-registry/schema-registry.properties
3. Configuring Schema Registry URL
| Config |
Description |
Detail |
| schema.registry.url |
Client → registry |
Required |
| Serializer |
KafkaAvroSerializer |
Auto-register |
| Multiple |
Comma list for HA |
Failover |
Example: Client config
props.put("value.serializer",
"io.confluent.kafka.serializers.KafkaAvroSerializer");
props.put("schema.registry.url", "http://localhost:8081");
4. Registering Schemas
| Aspect |
Description |
Detail |
| Auto |
Serializer registers |
On first send |
| Manual |
POST to subject |
REST API |
| Subject |
topic-value / topic-key |
Naming strategy |
Example: Register schema
curl -X POST -H "Content-Type: application/vnd.schemaregistry.v1+json" \
--data '{"schema":"{\"type\":\"string\"}"}' \
http://localhost:8081/subjects/orders-value/versions
5. Retrieving Schemas
| Endpoint |
Description |
Detail |
| /schemas/ids/{id} |
By global ID |
Raw schema |
/subjects/{s}/ versions/{v} |
By subject+version |
latest allowed |
| latest |
Most recent version |
Convenience |
Example: Get latest
curl http://localhost:8081/subjects/orders-value/versions/latest
6. Listing Subjects
| Endpoint |
Description |
Detail |
| /subjects |
All registered subjects |
Array |
/subjects/{s}/ versions |
Version list |
Per subject |
| ?deleted=true |
Include soft-deleted |
History |
Example: List subjects
curl http://localhost:8081/subjects
7. Deleting Schema Versions
| Type |
Description |
Detail |
| Soft Delete |
Mark deleted |
Recoverable |
| Hard Delete |
?permanent=true |
Irreversible |
| Scope |
Version or whole subject |
Granular |
Warning: Permanent deletes are irreversible and can break consumers still reading old data.
Example: Delete a version
curl -X DELETE http://localhost:8081/subjects/orders-value/versions/1
8. Setting Compatibility Mode
| Mode |
Description |
Detail |
| BACKWARD |
New reads old |
Default |
| FORWARD |
Old reads new |
Producer-first |
| FULL |
Both directions |
Strict |
Example: Set subject compatibility
curl -X PUT -H "Content-Type: application/vnd.schemaregistry.v1+json" \
--data '{"compatibility":"FULL"}' \
http://localhost:8081/config/orders-value
9. Checking Compatibility
| Endpoint |
Description |
Detail |
/compatibility/ subjects/{s}/... |
Test new schema |
No register |
| is_compatible |
Boolean result |
true/false |
| CI Gate |
Validate before deploy |
Safety |
Example: Check compatibility
curl -X POST -H "Content-Type: application/vnd.schemaregistry.v1+json" \
--data @new-schema.json \
http://localhost:8081/compatibility/subjects/orders-value/versions/latest
10. Exporting Schemas
| Aspect |
Description |
Detail |
| Backup |
Dump all subjects |
Disaster recovery |
| Exporter |
Schema Linking |
Cross-cluster |
| _schemas Topic |
Mirror for backup |
Source of truth |
Example: Export all subjects
for s in $(curl -s http://localhost:8081/subjects | jq -r '.[]'); do
curl -s http://localhost:8081/subjects/$s/versions/latest > "$s.json"
done