Why JSON validation needs a checklist
JSON is simple enough that teams often treat it casually. A payload is copied from a log, adjusted in a note, pasted into a test, and reused in documentation. The problem is that one missing comma, one accidental trailing comma, or one string that should have been a number can break the next step. A JSON validator is useful, but the validator is only one part of the workflow. Teams also need a repeatable checklist that explains what to validate and why.
The goal is not to make JSON work ceremonial. The goal is to remove avoidable mistakes from API debugging, onboarding, documentation, and support work. A small checklist lets developers quickly move from “does this parse” to “does this represent the contract we meant to test.” That difference matters when payloads become examples that other people trust.
Start with syntax before semantics
The first check is always syntax. Can the payload be parsed as JSON by a normal parser? This catches missing quotes, invalid escape sequences, misplaced braces, and comments that were copied from a configuration file format that is not actually JSON. Syntax validation should happen before anyone debates whether a field name is correct or whether a value has the right business meaning.
This order saves time. If the text is not valid JSON, semantic review becomes noise. A validator can provide the failure message, and a formatter can help reveal where the structure breaks. Once the syntax is valid, the team can inspect the shape calmly. That makes discussions about contract behavior more concrete.
Confirm the top-level shape
After syntax passes, check whether the top-level value is the expected type. Some endpoints return an object, some return an array, and some return a wrapper object with data, pagination, or error fields. A payload can be valid JSON and still be the wrong shape for the use case. This is common when examples are copied from a different endpoint or from an older version of the API.
Write down the expected shape in the checklist. For a list endpoint, the team may expect an object containing an items array and a nextCursor value. For a detail endpoint, the team may expect a single object with stable identity fields. Being explicit prevents reviewers from accepting valid but misleading examples.
Check field names and casing
Field naming mistakes are easy to miss in a large payload. A frontend might expect updatedAt, while a backend example uses updated_at. A third-party API might return uppercase enum strings, while internal code expects lowercase values. JSON validation does not know the correct naming convention. The team must check names against the contract, schema, or current implementation.
This step is especially important for documentation. Readers copy examples directly. If the example uses the wrong casing, their code may fail even though the page looked polished. A good checklist asks reviewers to compare field names with the canonical source, not with memory.
Validate value types
A JSON value can look reasonable while using the wrong type. IDs may appear as numbers in one example and strings in another. Boolean flags may be represented as "true" instead of true. Timestamps may be numbers, strings, seconds, milliseconds, or ISO dates. These choices affect clients, validators, and downstream storage.
When reviewing a payload, mark the fields where type matters most. Identity fields, timestamps, amounts, status values, and nested arrays deserve attention. If the API contract allows multiple representations, document that explicitly. If it does not, correct the example before it spreads.
Treat example data as product surface
Example JSON is not throwaway text. It shapes how developers understand the product. Use realistic but non-sensitive values. Avoid production user names, real tokens, internal IDs, private URLs, and customer data. Replace them with values that teach the structure without leaking context. A good example should be safe to publish and easy to read.
The safest workflow is to build sample payloads intentionally instead of copying from production logs. If a log is the only available source, redact it first, then validate and format it. Do not rely on memory after redaction, because removing one field can break surrounding commas or nested structure.
Compare request and response contracts
Many API mistakes happen because request and response payloads are mixed together. A create request might send name and type, while the response includes id, createdAt, and status. A copied response is not always a valid request. A copied request is not always a complete response. Validation should include a contract context: request example, success response, error response, or event payload.
Labeling examples helps reviewers catch mismatches. If the payload is a request body, ask whether it includes server-generated fields by mistake. If it is a response, ask whether required output fields are missing. If it is an error response, ask whether it reflects the current error model.
Use formatting to make review easier
Formatting does not change the meaning of JSON, but it makes review much easier. Indentation reveals nested objects, repeated array items, and misplaced fields. A compact one-line payload may be fine for a log, but it is hard to review in documentation or code review. Format the payload before asking teammates to inspect it.
Formatting also helps reduce accidental edits. When each field is on its own line, diffs become more precise. Reviewers can see which values changed. This is useful in tests, documentation examples, and API fixtures. The combination of validation and formatting turns JSON from a fragile text blob into a reviewable artifact.
Keep the checklist small
A useful JSON checklist should be short enough to use under time pressure. A practical version can ask: does it parse, is the top-level shape correct, are field names current, are value types correct, is sample data safe, is the payload labeled as request or response, and is it formatted for review. That is enough for most everyday work.
Teams can add schema validation or contract tests when risk is higher, but the checklist should remain useful for quick tasks. The best process is the one people actually use. A browser-based JSON validator and formatter can support that process without requiring a database, account, or backend call.