Developer · THE NO-PANIC PLAN
Compare two JSON API payloads before adopting an update
A JSON diff reports structural changes; it does not decide whether an API change is safe. This workflow compares two authorized, representative payloads, validates their JSON syntax, reviews path-level differences with Nirmion's JSON Diff, and then checks each changed field against the API's OpenAPI or JSON Schema contract and compatibility policy. Object member order is insignificant in JSON, while array order is significant. Treat additions, removals, type changes, nullability, defaults, and behavior changes according to actual consumers and the service's stated policy. Use synthetic or redacted data, and test the affected clients before release.
MISSION Compare representative old and new JSON API payloads, classify each change against the API's documented compatibility policy, and verify consumer behavior before adopting the update.
Compare JSON payloads and review each change against the API contractTHE REAL-WORLD BIT
What happens outside this browser tab?
Choose equivalent and authorized old/new samples; remove secrets and normalize only irrelevant volatile values; validate syntax; review a path-level diff; classify each change against the versioned API contract and its compatibility policy; run focused consumer and security tests; then document the decision and retain a repeatable regression fixture.
YOUR CHECKLIST, WITH FEWER DRAMATIC SIGHES
One step at a time.
Follow the order below. If a step names a Nirmion tool, its link is right there with it.
- 01
Choose equivalent, authorized payload samples
Select one representative response from the current API version and one from the proposed version for the same endpoint, request conditions, account role, locale, and feature flags. Use a documented fixture or synthetic data where possible. If production examples are necessary, confirm authorization and redact tokens, personal data, identifiers, and confidential values before processing. Keep the unmodified originals in a controlled location and record endpoint, API version, timestamp, and conditions so an apparent difference is not caused by comparing unrelated requests. Do not compare a success response with an error response unless that is the specific behavior under review. (Sources 1, 3, 6)
- 02
Normalize only values that are truly irrelevant
Make temporary comparison copies and remove or replace secrets with stable placeholders. If timestamps, request IDs, generated URLs, or other volatile values obscure the review, normalize only those fields and keep a record of every normalization. Do not sort arrays, coerce numbers to strings, convert null to an empty value, or remove fields merely to make the diff smaller: JSON arrays are ordered, and these transformations can hide real contract changes. JSON object member order is not semantically significant, so a formatter may improve readability without changing the object data model. (Sources 1, 2)
- 03
Check that both files are valid JSON
Validate each comparison copy independently before diffing. Nirmion's JSON Validator checks JSON syntax and reports root type, depth, and structural counts; it does not validate an API schema or prove that a payload is accepted by a service. Correct malformed syntax in a separate working copy and preserve the original evidence. Confirm both samples have the intended root type and expected endpoint context. If either is invalid or its provenance is uncertain, stop and obtain a trustworthy fixture rather than interpreting parser errors as API changes. (Sources 1, 3)
- 04
Review the path-level differences
Compare the old and new JSON copies with Nirmion's JSON Diff and inspect every reported path. The tool lists bounded structural differences; it does not know your API contract, infer business meaning, or declare a change backward compatible. For each difference, record whether a property was added, removed, renamed, changed type, changed from or to null, or changed value; inspect nested objects and arrays in context. Ignore object key ordering as a semantic change, but investigate array reordering because array positions are meaningful in JSON. Recheck any normalized field against the original samples. (Sources 1, 2, 3)
- 05
Classify each change using the actual contract and policy
Open the API's versioned OpenAPI description and any JSON Schema it references. Check changed fields against required status, type, enum, format, nullability, defaults, constraints, request/response direction, and documented behavior. Then apply the service's explicit compatibility policy and identify affected clients. Do not assume that adding an optional JSON property is always safe: some clients reject unknown fields, and compatibility depends on the service and consumers. A structural diff alone cannot establish this. Mark each change as acceptable, breaking, or unresolved under your policy, and ask the API owner when the contract or compatibility rule is ambiguous. (Sources 2, 3, 4, 5)
- 06
Run focused consumer and security checks
For every changed path, run contract tests and representative consumer tests against the proposed version in an authorized non-production environment. Cover missing fields, null values, type changes, enum additions, array order, error responses, and relevant authorization states where applicable. Follow the API's documented validation and security rules; use test data without secrets and avoid sending sensitive samples to public services. A passing syntax check or diff review is not an integration test. If a consumer fails or the result is uncertain, stop rollout, preserve the failing fixture, and resolve the contract or implementation before release. (Sources 3, 4, 6)
- 07
Record the decision and preserve a regression fixture
Save the redacted or synthetic before/after fixtures, API version and contract revision, comparison date, normalization notes, changed paths, compatibility classification, consumer test results, and reviewer decision in the team's change record. Link unresolved items to an owner and do not label them compatible until the responsible policy owner resolves them. Keep a regression test for any accepted behavioral change and update the API description when the contract changes. Retain only data permitted by the team's retention rules; delete temporary copies securely when they are no longer needed. (Sources 3, 4, 5, 6)
THE HELPER CREW
Tools for the fiddly bits.
These are the currently published Nirmion tools matched to this guide. Open a tool page for its accepted inputs and limits.
RECEIPTS, PLEASE
Sources & review notes
Each source is linked to the steps it supports. Open it to check its scope and current guidance.
Source checked 2026-10-10