A source system may add a field without trouble, then break an important report by changing a unit or making a previously optional value mandatory. A data contract records both the expected structure and the meaning that consuming systems rely on.
Related service: Custom software development- 01Describe the proposed field change.
- 02Identify affected readers and outputs.
- 03Test compatibility with representative data.
- 04Deploy the agreed transition.
- 05Confirm migration before retiring the old contract.
SECTION 01
Document semantics as well as field names
For important fields, record type, allowed values, whether absence is permitted, units and who owns the definition. Explain whether a timestamp means created, approved or received. A numeric quantity that changes from individual units to cartons may still pass a basic number check while producing a serious reporting error.
JSON Schema documents required properties and rules for additional fields. Semantic Versioning provides a convention for communicating compatibility changes in a declared public interface. Neither detects the business meaning automatically. Ask the agency to include examples and consumer tests alongside a machine-readable schema.
SECTION 02
Illustrative example: changing a delivery-status field
Imagine an integration currently sends status values of pending, dispatched and delivered. The source adds partially dispatched. A consumer that treats every unknown value as delivered would create false completion records. A consumer that rejects the entire batch may stop unrelated orders. The transition must define the intended outcome explicitly.
Provide sample partial shipments and update the relevant readers before enabling the new value broadly. Keep monitoring for unsupported values and preserve the original payload for authorized investigation under the agreed retention policy. This hypothetical change shows why an apparently additive field update may still affect real business behavior.
SECTION 03
Plan the overlap and the removal
Identify each consumer, its owner and the release evidence required. Where necessary, support an old and a new representation during migration. Avoid maintaining two competing meanings indefinitely; name the retirement condition and explain how remaining usage will be detected before removal.
Acceptance should cover old records, missing fields, new allowed values and inconsistent units. Compare downstream reports as well as API responses. A schema change process can be lightweight for a small integration: a versioned definition, examples, an owner and repeatable tests may be enough. The goal is a predictable change, not a large approval ceremony disconnected from the code people actually run.
SECTION 04
Frequently asked questions
Is adding an optional field always safe?
Not necessarily. Some consumers reject unknown fields, and new values can affect interpretation. Test the consumers that actually use the data.
Can a schema validate business meaning?
It can enforce selected structural rules, but units, ownership and interpretation also require documented definitions and representative tests.
When can the old contract be removed?
After the agreed consumers have migrated and usage checks support removal, with a recovery plan for unexpected dependencies.
PRIMARY REFERENCES
Sources and further reading
These references cover the standards, platforms, or published prices discussed in the guide. Worked examples and checklists are our editorial guidance.
- Object properties and required fieldsJSON Schema
- Semantic Versioning specificationSemantic Versioning
EDITORIAL METHOD
About this guide
We use AI to assist with drafting and editing. Catapult AI Work is responsible for the published content. Examples illustrate possible approaches; they are not client case studies unless identified as such.
Budget examples are not Catapult package prices. Check linked provider pages for current fees and plan limits before making a purchase.
Read the editorial policy