api-guidelines
api-guidelines copied to clipboard
[new rule] must provide compatibility mode for produced messages
(i) This issue has been manually transferred from a former internal repository, as a private repository issue cannot be transferred to a public repository.
Context
Messages may evolve over time. In order to signal a consumer what a compatible change is, the compatibility mode must be documented for produced messages.
The following modes exist:
| Mode | Changes allowed | Compatible against | Description |
|---|---|---|---|
| FORWARD | - Add fields - Delete optional fields |
previous version | Older clients can read events written with the next newer schema. |
| FORWARD_TRANSITIVE | see FORWARD | all previous versions | Older clients can read events written with all newer schemas. |
| FULL | - Add optional fields - Delete optional fields |
previous version | Older clients can read events written with the next newer schema. Newer clients can read events written with the previous schema version. |
| FULL_TRANSITIVE | see FULL | all previous version | Older clients can read events written with a newer schema. Newer client can read events written with all previous schema versions. |
Other common modes such as backward and none should not be allowed, as they break existing clients.
Analyze if exemptions can be made to this rule if all consumers are prepared for a breaking change.
Reference
- https://github.com/asyncapi/spec/issues/727
- https://docs.confluent.io/platform/current/schema-registry/avro.html#