A JSON debug checklist after API or config changes

Broken JSON usually fails late: in a deploy hook, a mobile client, or a spreadsheet import. By then the bad payload is already on a branch, in a ticket, or in a Slack thread. A short local checklist catches syntax and shape issues while the response is still on your clipboard.

If you regularly work across encoders, tables, and formatters in developer tools on Utilido, treat this list as the gate between “it worked on my machine” and “staging is red.”

What “broken” means in practice

JSON problems split into layers:

1. Syntax: invalid tokens, trailing commas, smart quotes, truncated paste.
2. Shape: array vs object, missing wrapper, wrong key casing, null vs absent field.
3. Semantics: string where a number was required, epoch in seconds vs milliseconds, enum values the server no longer accepts.
4. Transport: double-encoded strings, HTML entities, gzip mistaken for text.

Fix layer 1 before you debate layer 3. The JSON formatter is the fastest way to see line-level syntax errors on pasted text.

Local validation workflow

Work through these steps in order. Stop at the first failure and fix it before you move on.

Step 1: Paste and fix syntax first

• Copy the raw body from curl, browser devtools, or your log aggregator.
• Paste into the JSON formatter. Fix the reported line before anything else.
• If the formatter says the input is not JSON, check whether you copied headers, status line, or multiple responses glued together.
• Replace smart quotes (" ") and stray backticks from rich text editors.
• Remove trailing commas after the last array or object member. They are invalid in standard JSON.

{
  "ok": true,
  "items": [1, 2, 3],
}

The trailing comma after 3 breaks strict parsers. Some tools accept it; production APIs often do not.

{
  "ok": true,
  "items": [1, 2, 3]
}

The same payload without the trailing comma is what strict parsers expect in production.

Step 2: Confirm the root shape

APIs drift from { "data": [...] } to a bare array, or from snake_case to camelCase, without a loud version bump.

• Does the consumer expect an array or a single object?
• Are empty results [], {}, or null?
• Did pagination move from meta to links?

Search the codebase or OpenAPI spec for the old key names. One missing wrapper causes “cannot read property of undefined” on the client while the server returns 200.

Step 3: Compare wire size vs pretty diff

In git you often diff indented JSON while production sends minified JSON. Same data, noisy diff.

• Store a canonical pretty-printed fixture in tests for human review.
• Compare minified hashes or normalized parses in CI when you care about wire equality.
• When reviewing a PR, re-format both sides with the same indent before eyeballing.

If two blobs look identical in the formatter but differ on the wire, check key order (usually irrelevant), whitespace, or Unicode normalization in string values.

Step 4: Spot type and null traps

Symptom	Often means
1970-01-01 dates	epoch in seconds read as ms or vice versa
IDs with scientific notation	number type in JS or Excel, not string
"true" as string	CSV round trip or form encoding
Missing field vs null	API started omitting keys; client used == null checks

Coerce in one place on the client or document server guarantees. Do not fix the same field in three components differently.

Step 5: Five-row table parity with CSV

When the API accepts tables or you export fixtures for finance, run a small CSV sample through the full path:

1. Export five rows from the sheet or API.
2. Convert with CSV to JSON.
3. Validate JSON, apply transforms, convert back with JSON to CSV.
4. Open the CSV and confirm headers and row count.

Header shift and comma breakage are shape bugs that syntax tools never see. For field-level pitfalls, read CSV and JSON round trips without breaking data.

Step 6: Config files and secrets in logs

JSON often sits inside YAML, environment files, or Kubernetes manifests. A valid outer file can hide invalid inner JSON strings.

• Extract the inner string and format it alone.
• Watch for escaped newlines and quotes (\", \n) that must round trip through your deploy tool.
• If the value is Base64, decode before you call it JSON. Padding and URL-safe alphabets trip people up; see Base64 in config files and logs.

Never paste production secrets into shared tickets because a decoder runs locally. Local processing reduces exposure; it does not make secrets safe to broadcast.

Step 7: JWT and signed payloads

A JWT looks like JSON but is not a single JSON document. It is three Base64url segments. Use the JWT decoder for claims inspection, not as a substitute for signature verification on the server.

When exp looks wrong, pair claim review with the Unix timestamp seconds vs milliseconds guide before you blame the auth service.

Five-minute checklist

• Paste into JSON formatter; fix syntax line reported.
• Confirm root is array or object as documented.
• Search for trailing commas and smart quotes.
• Compare a normalized pretty print to your last known good fixture.
• Check numeric IDs and epochs for type and unit.
• If tables are involved, run five rows through CSV to JSON and back.
• If the payload is wrapped in Base64, decode and re-run syntax checks.

Syntax before semantics Until the formatter parses the text, stop guessing about business logic bugs. Half of “API regression” threads are a paste error or a trailing comma.

Paste sources and common breaks

Source	What goes wrong	Quick fix
Browser devtools preview	Smart quotes, truncated tree	Copy raw response body
Slack or email	Line breaks inside strings	Paste into formatter first
Log aggregator	Multiple JSON lines glued	Isolate one object or array
OpenAPI example	Comments or undefined	Strip to strict JSON

When two teammates paste the “same” response and get different formatter results, compare byte length and the first character. A BOM or leading { from a previous copy is a frequent silent difference.

Schema checks and version control habits

After syntax is green, optional checks before merge:

• Validate against JSON Schema or OpenAPI response schema in CI.
• Assert required keys on critical paths (id, status, error).
• Fail builds when unknown keys appear if your API promises a closed set.

Syntax tools will not catch a valid JSON object with the wrong business fields. That is where fixtures from the last release help more than another hour in the network tab.

In git, commit small redacted fixtures, not full production dumps. Prefer deterministic ordering in test fixtures when your serializer allows it. In PR review, ask for the formatter-cleaned sample when someone says “JSON looks fine.”

When to escalate beyond local JSON checks

You need server logs, correlation IDs, or live traffic when payloads are huge, errors are intermittent, or the bug is authorization rather than serialization. This checklist is for the moment you have a body and need to know if it is valid JSON in the right shape before it travels further. If the formatter is green and fixtures match but clients still fail, stop re-pasting the same body and move to tracing, auth headers, and deployment version skew.

What I do before I blame the API team

I re-copy from the Network tab with “copy response” rather than selecting text in the preview pane. I have shipped smart quotes and truncated braces that way. I paste into the formatter, fix syntax, then diff against the previous release tag’s fixture file. If the formatter is green and the diff is only new fields we documented, I escalate. If not, I stay on my laptop until the payload is valid. That order has saved a lot of cross-team noise, and I attach the cleaned sample to the ticket so the next person does not re-debug the same paste error.

FAQ

Why does JSON work in Postman but fail in my app?

Postman often tolerates trailing commas or comments. Your runtime parser may not. Format the same body in the JSON formatter and use what it accepts as the source of truth.

Is a trailing comma ever valid JSON?

No in RFC 8259 JSON. Some tools and JSON5-style parsers allow it during development. Do not rely on that in production APIs.

How do I diff two large JSON files?

Normalize both through the same formatter indent, or parse and compare objects in a small script. For git, consider a JSON-aware diff or canonical serialization so key order does not drown signal.

Should I minify JSON before sending to an API?

Minified is fine if syntax is valid. Pretty print is for humans. Size limits are about bytes, not spaces. Validate after minify in CI if your pipeline strips whitespace.

When should I use CSV tools during JSON debug?

When the bug appears after a spreadsheet export or a table import. Run CSV to JSON on a tiny sample and inspect keys before you touch application code.

Can I debug JWTs with the JSON formatter alone?

Only after you split and decode the payload segment, or use a JWT-specific tool. Treat decode as inspection; verify signatures on the server.