Avro Schema Evolution

1. Pick a compatibility mode

Meridian topics default to BACKWARD compatibility, meaning consumers using the new schema can read messages written with older schemas. Switch to FORWARD when producers upgrade first, or FULL when you need both directions to hold simultaneously.

2. Apply safe change patterns

The safe operations under BACKWARD compatibility are adding optional fields with defaults, removing fields that already have defaults, and widening numeric types (int to long, float to double). Renaming fields, changing types without defaults, or removing required fields will fail registration.

3. Register the new version

Push the new schema to the Meridian schema registry. The registry validates compatibility before assigning a version id and rejects any breaking change.

{
  "type": "record",
  "name": "OrderEvent",
  "namespace": "io.meridian.orders",
  "fields": [
    { "name": "order_id", "type": "string" },
    { "name": "amount_cents", "type": "long" },
    {
      "name": "currency",
      "type": "string",
      "default": "USD"
    },
    {
      "name": "promo_code",
      "type": ["null", "string"],
      "default": null
    }
  ]
}