A JSON Validation Workflow That Catches API Problems Before Deployment

An API payload can be valid JSON and still be wrong for the system that consumes it. A missing field, a number represented as a string, or an array returned as an object may pass a basic parser while breaking a client, a database write, or a downstream job. JSON validation is most useful when it checks the contract the application expects, not only whether braces and commas are in the right places. ## Begin with the actual contract Before checking a sample, write down what one payload represents and which fields are required. A response for one user is different from a response containing a list of users. Record the expected type of each field, whether null is allowed, and whether an empty string has a distinct meaning. If the API uses pagination, define whether the next-page value is a URL, a token, or null at the end. Ambiguity in the contract becomes a production bug later. Keep a small valid example and several invalid examples. The valid example should include realistic nesting and at least one optional field. Invalid examples should cover a missing required property, a wrong primitive type, an unexpected null, and an empty collection where the consumer assumes at least one item. These examples are more valuable than a very large fixture because a reviewer can understand them quickly. ## Parse first, then inspect meaning Run the payload through a JSON validator before looking at application behavior. A syntax error should be fixed first because later checks cannot be trusted when the document does not parse. Pay attention to the exact error location. A comma missing several lines above the reported position is common in hand-edited JSON, especially after adding the final object in an array. Once parsing succeeds, inspect types and keys. JSON has strings, numbers, booleans, null, arrays, and objects, but it does not carry a date or decimal type by itself. A value such as `2026-09-08` is a string unless the application assigns a meaning to it. Likewise, large integer identifiers may exceed the safe precision of a JavaScript number. If precision matters, keep the value as a string and document that choice. ## Compare producer and consumer assumptions Check the code that writes the payload and the code or SDK that reads it. A producer may rename `user_id` to `userId` while both versions look reasonable in isolation. A frontend may treat an absent property as “loading” but treat null as “known to be empty.” A database adapter may coerce a numeric string today and reject it after a library upgrade. Validation should reflect these real assumptions rather than an idealized schema. For changes that affect public clients, preserve backwards compatibility when possible. Add a field before removing an old one, accept both representations during a migration, and measure which clients still rely on the old shape. Do not use a formatter or minifier as a substitute for a schema check. Formatting improves readability; it cannot prove that the response is useful. ## Make validation part of delivery Run the validator in tests and in the deployment pipeline. Keep the fixture small enough to review in a pull request, and fail with an error that names the path, such as `items[2].price`, rather than only saying “invalid response.” For integration tests, validate a response captured from the real endpoint and check status code, content type, authorization behavior, and error shape as well. The CalcSnippets JSON Validator is a quick first pass when a payload arrives in a ticket, log, or terminal. Use it to separate syntax problems from contract problems, then apply the service's schema and integration tests. That two-step habit catches cheap mistakes early without pretending that valid JSON automatically means a compatible API.