All lessons T
Data Transformation intermediate 14 min

Review Breaking JSON Contract Impact

Review producer, consumer, and rollout consequences without pretending that an inferred sample settles compatibility.

Scenario

A team proposes removing a response field that an older mobile client still reads. The proposed payload is valid JSON and may even validate against a new schema, but consumer compatibility depends on rollout facts outside the sample.

Broken input

{ "account": { "id": "acct_2048", "legacyPlan": "pro", "plan": "pro" } }

Goal

Review a declared contract change from the producer, consumer, and rollout perspectives, preserve the reason codes, and record an override only when the team has evidence outside the JSON samples.

Tool sequence

  1. Open Toolzy JSON Plan with Current and Proposed samples.
  2. Declare the removal or deprecation instead of relying on a value diff alone.
  3. Set the contract context, consumer strictness, and rollout order explicitly.
  4. Read the producer, consumer, and rollout classifications with their reason codes.
  5. If you override a classification, write the operational evidence that makes the override safe enough to review.

Checkpoint output

Change:    remove $.account.legacyPlan
Producer:  compatible only after the old field is intentionally omitted
Consumer:  needs review — old clients may still require the field
Rollout:   needs review — consumer adoption is unknown

The plan keeps its conservative result and the reviewer’s recorded decision side by side.

Common mistakes

  • Calling a removal compatible because a new producer accepts its own output.
  • Replacing a reason code with a color-only severity label.
  • Assuming tolerant consumers without recording the evidence.
  • Hiding unresolved rollout questions in an export summary.

Related tools and lessons