PlayTools

JSON Validation for APIs: Syntax, Types and Safe Parsing

Developers · Updated November 5, 2026 · 4 min read

Most modern APIs speak JSON. The format looks simple — curly braces, double-quoted keys, arrays — but small mistakes cause production outages: a trailing comma in a config file, a single-quoted key copied from JavaScript, or a number too large for JavaScript’s IEEE double. This guide walks through what “valid JSON” means, how to validate payloads locally before you ship them, and how to harden client-side parsing when you consume third-party APIs.

Everything here runs in the browser on PlayTools: paste a payload into the JSON formatter to pretty-print and validate, convert YAML or CSV when you are migrating configs, and decode JWTs when you are inspecting auth tokens (without sending secrets to a server).

What RFC 8259 actually requires

  • Keys and string values must use double quotes — single quotes are invalid.
  • No trailing commas after the last element in an object or array.
  • Numbers must be finite decimal; no NaN, Infinity, or hex literals.
  • No comments — unlike JavaScript or YAML, JSON has no # or // syntax.
  • The root value must be an object, array, string, number, true, false, or null — not undefined.

JavaScript’s JSON.parse() follows these rules strictly. If you export an object with undefined properties from Node, JSON.stringify drops those keys — but if you hand-edit a file and leave undefined as text, validation fails immediately.

Common copy-paste failures

Pasting from Slack or Word often swaps straight quotes for “smart quotes”, which parsers reject. Excel exports sometimes produce CSV with embedded quotes that were never meant to become JSON. When moving from YAML, remember that YAML allows tabs, unquoted strings, and anchors — none of which are valid in JSON until converted.

A practical workflow: paste into the formatter, fix the reported line/column, then copy the minified or pretty-printed output into your repo. Keep a golden sample in version control and re-validate after every edit.

Schema vs syntax

Syntax validation only checks that the text is legal JSON. Schema validation checks that required fields exist and types match — for example that user.id is a string and items is an array. OpenAPI and JSON Schema are the usual standards for HTTP APIs.

For quick manual checks, assert a few invariants in your head or in a unit test: status codes are numbers, ISO-8601 dates are strings, money amounts are strings or integers in minor units — never floats if you can avoid them.

// Safer parse wrapper for fetch() responses
async function readJson(res) {
  const text = await res.text();
  if (!text.trim()) return null;
  try {
    return JSON.parse(text);
  } catch (e) {
    throw new Error(`Invalid JSON (${res.url}): ${e.message}`);
  }
}

Large numbers and precision

JSON numbers are text; JavaScript parses them into 64-bit floats. Integers above 2^53-1 (9007199254740991) lose precision — a problem for Twitter snowflake IDs and some blockchain values. If an API returns big integers, treat them as strings in the contract or use a bigint-aware parser on the server.

Financial amounts should be stored as integer cents in JSON, not 19.99 as a float, to avoid 0.1 + 0.2 rounding surprises when several services aggregate totals.

JWTs are JSON too

A JSON Web Token is base64url-encoded header and payload plus a signature. Decoding the payload shows claims such as sub, exp, and scope. Signature verification must happen on the server with the issuer’s public key — client-side decode is for debugging only.

Never paste production bearer tokens into untrusted websites. PlayTools decodes locally in your browser; still treat tokens as secrets and rotate them if leaked.

Checklist before you deploy config JSON

  1. Validate syntax with a strict parser (formatter tool or jq).
  2. Run CI tests that load the file and assert required keys.
  3. Diff against the previous version in pull requests — noisy diffs catch accidental array merges.
  4. Minify for production only after validation; keep pretty source in git for reviews.
  5. Log parse errors with the request id, not the full payload, to avoid leaking PII.

Streaming and partial JSON

Server-sent events and some AI APIs stream JSON objects line by line (JSON Lines / NDJSON). Each line must be a complete value; you cannot pretty-print the whole file until the stream ends. Parsers should read line by line with JSON.parse on each non-empty row.

For large arrays, consider paginated APIs instead of a single giant JSON file. Browsers hold the entire response in memory; a 200 MB export can crash a tab even if syntax is valid.

Converting from CSV or YAML

CSV to JSON tools infer column types from the first rows — a column of zip codes may become numbers and lose leading zeros. Force string types when identifiers look numeric.

YAML merge keys and multiple documents are convenient for ops teams but must be flattened to a single JSON object before an API accepts them. Validate after conversion every time; do not assume round-trip fidelity.

Security notes

Never eval() JSON text. Prototype pollution attacks used to target libraries that merged parsed objects unsafely; use Object.assign on null prototypes or structured cloning when merging unknown objects.

When logging API traffic in development, redact authorization headers and tokens. Pretty JSON in logs is useful; full production payloads may contain personal data subject to retention policies.

Set Content-Type: application/json on responses so intermediaries do not misinterpret payloads. For JSONP-style callbacks, avoid entirely — use CORS with fetch instead.

Rate-limit public endpoints that accept large JSON bodies to reduce denial-of-service risk from megabyte payloads sent by bots.

Tools used in this guide