API JSON Validation Checklist: What to Check After Syntax Passes

A successful JSON.parse only proves that the text follows JSON syntax. It does not prove that the response matches your API contract. A response can be valid JSON while missing required fields, returning the wrong type, using an expired enum, or turning money into an unsafe floating-point value.

1. Check the HTTP layer first

Before reading the body, record the status code, Content-Type, charset, and request ID. JSON APIs should usually return application/json or a compatible media type. A 204 response should not be force-parsed as JSON, and error responses should use a stable JSON shape rather than sometimes returning HTML.

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
X-Request-Id: req_123

If a proxy or WAF wraps a login page as a 200 response, the parser error will be misleading. Inspecting headers and the first bytes of the body saves time.

2. Validate syntax and encoding

Paste the response into the JSON Validator to check braces, commas, quotes, and escapes. Include samples with non-English text, emoji, newlines, backslashes, and Unicode escapes. Server and client should agree on UTF-8 so visible garbling is not mistaken for business data.

3. Confirm root shape and required fields

The contract should state whether the root is an object, array, or scalar. A paginated endpoint might promise {items, page, total} and should not become an empty array when there is no data. Distinguish three states for each field: missing, explicit null, and present with a value.

Ask these questions for each endpoint: Which fields are required? Can optional fields be null? Is an empty string equivalent to missing? Are unknown fields ignored, stored, or rejected? Can old clients safely handle new fields?

4. Check field types strictly

JSON has strings, numbers, booleans, null, objects, and arrays. Dates, UUIDs, money, and identifiers need extra rules. Common mistakes include returning numbers as strings, returning a single object where an array is expected, or treating false as missing.

Large identifiers should often be strings to avoid JavaScript precision loss:

{
  "userId": "9007199254740993",
  "enabled": false,
  "createdAt": "2026-07-17T08:30:00Z"
}

5. Use JSON Schema for executable contracts

JSON Schema can turn required fields, types, lengths, formats, enums, and nested rules into a versioned contract. Use it in backend input validation, contract tests, and client generation. During development, strict additionalProperties: false can catch typos, while public APIs need a deliberate compatibility policy.

6. Cover failures and boundaries

Your pre-release test set should include minimal and full valid objects, each required field missing, wrong field types, nulls, long strings, empty arrays, deep nesting, duplicate values, unknown enums, large integers, invalid dates, and consistent 401, 403, 404, 409, 422, 429, and 500 error shapes.

Summary

API JSON validation should move through HTTP, syntax, structure, types, business rules, and compatibility. Parsing success is only the first gate. Real confidence comes from Schema, failure samples, contract tests, and consistent error responses.