JSON Schema演进报错：新Schema与旧版本不兼容问题排查

This is a common gotcha with Schema Registries (like Confluent's) that enforce JSON Schema compatibility checks—let's break down what's happening and how to fix it:

The Root Cause #

Most Schema Registries default to BACKWARD compatibility mode, which requires that old consumers using the previous schema can successfully validate data produced with the new schema.

Your old schema doesn't explicitly set the additionalProperties keyword. While JSON Schema Draft-07 technically defaults additionalProperties to true (allowing extra fields), many Schema Registry implementations (including Confluent's) take a stricter approach here: they assume that if additionalProperties isn't explicitly defined, the schema does not allow unknown fields.

When you add myField2 to the new schema, the Registry thinks old consumers (using the original schema) would reject data containing this new field—hence the "incompatible" error.

Fixes You Can Try #

1. Adjust the Schema Registry Compatibility Mode #

If your use case allows it, switch the compatibility mode to FORWARD (or FULL if you need bidirectional compatibility):

• FORWARD mode ensures that the new schema can validate data produced with the old schema (which it does, since myField2 is non-required). This is safe for scenarios where you're updating producers first, then consumers.
• To change it via API (adjust the URL and subject name to match your setup):

  curl -X PUT -H "Content-Type: application/vnd.schemaregistry.v1+json" \
    --data '{"compatibility": "FORWARD"}' \
    http://your-registry-url/subjects/your-subject-name/config
  

  You can also update this setting directly in your Schema Registry UI if it supports it.

2. Explicitly Allow Additional Properties in the Schema #

If you can modify the old schema (or are starting fresh), add "additionalProperties": true to explicitly permit extra fields. This makes your original schema explicitly accept any unlisted fields, so adding myField2 (non-required) will pass BACKWARD compatibility checks:

{
  "$id": "http://example.com/myURI.schema.json",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "properties": { "myField1": { "type": "integer" } },
  "required": ["myField1"],
  "type": "object",
  "additionalProperties": true
}

3. Use Transitive Compatibility Modes (If Needed) #

If you have multiple existing schema versions, switch to BACKWARD_TRANSITIVE or FORWARD_TRANSITIVE to ensure compatibility with all previous versions, not just the immediate one.

内容的提问来源于stack exchange，提问作者Francisco Albert