Save contract and consumer versions first
List the consumers using the field and the versions they run. Record current name, type, required conditions and meaning. Changing an editorial label in a CMS is not necessarily a change to the API field.
In a fictional course example, duration might be a numeric count of minutes. Replacing it with the text half-day changes type and meaning. A consumer sorting numerically needs a plan even if the new text looks fine in a new view.
Test shape and meaning separately
Choose cases for unchanged value, missing field, empty text, null and an extra property. Add a wrong type and a semantic change that keeps the same type. Define expected outcomes before the consumer reads the responses.
Schemas can support type and required-field checks but need correct rules and validator settings. They do not determine whether a number means minutes or hours. Review languages, references and presentation too.
| Change | Risk to test | Expected outcome must define |
|---|---|---|
| Field removed | Older consumer requires it | Rejection, fallback or separate version |
| Null instead of absent | Different empty-value code paths | Agreed meaning and presentation |
| New optional property | Strict rejection of unknown fields | Actual older-consumer support |
| Type change | Calculation or rendering breaks | Agreed migration rather than silent coercion |
| Same type, new meaning | Technical validation passes | Meaning retained or contract separated |
Run older and newer consumers against fixtures
Follow schema checks with the actual consumer route: fetch, read and relevant presentation or calculation. Include long text, another language and missing references where the model requires them.
Record which contract and consumer combinations work. Backward compatibility is not a promise for every future consumer. A breaking transition needs an agreed migration or parallel support for a defined period.
Make switching and rollback traceable
Decide who updates each consumer and the evidence needed before changing delivery. Keep the earlier contract, representative fictional responses and an agreed rollback route. Do not use private real records as regression fixtures.
After switching, repeat the matrix against the version actually served. Record remaining older consumers, retirement decisions and owners. A version number alone does not prevent the wrong response from reaching an old channel.