Skip to main content
Mapagam

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

Example: Wire format

[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

Was this article helpful?

Related Cheat Sheets