All lessons T
Data Transformation intermediate 15 min

Plan a JSON Contract Change

Turn Current and Proposed examples into declared contract intent, local artifacts, and a reviewable rollout plan.

Scenario

An API response will rename displayName to name, add a defaulted locale, and keep the old field for one release. The examples show a possible shape, but they do not prove a safe rollout.

Broken input

{ "user": { "id": "usr_182", "displayName": "Ada", "locale": "en" } }

Goal

Create a local Current-to-Proposed plan that keeps structural evidence, declared intent, rollout assumptions, and generated review artifacts separate.

Tool sequence

  1. Open Toolzy JSON Plan and create Current and Proposed from a known sample.
  2. Edit Proposed deliberately: add name, retain displayName, and add the defaulted locale field.
  3. Record declarations for the rename, deprecation, and addition; include a rationale and rollout assumption where the samples cannot decide.
  4. Review producer, consumer, and rollout impact separately. Keep uncertain cases as needs review.
  5. Review the local Markdown, schema, TypeScript, fixture, and bundle artifacts before exporting any of them.

Checkpoint output

Current:  $.user.displayName
Proposed: $.user.name + $.user.displayName (deprecated) + $.user.locale
Review:   producer and consumer impact recorded separately

The plan explains what will change and what still needs a decision; it does not pretend that one example proves compatibility.

Common mistakes

  • Deleting the old field while calling the action a deprecation.
  • Treating a sample-added field as automatically required.
  • Exporting artifacts before resolving missing rationale or rollout assumptions.
  • Using a comparison baseline as if it were a declared contract plan.

Related tools and lessons