JSON Parser

What a JSON Parser Actually Does

A parser converts text into a data structure in two distinct stages. The first is lexing, sometimes called tokenizing: the input is scanned character by character and grouped into meaningful units. The scanner does not care about nesting or correctness, only about recognizing the next token.

input: {"id": 12, "ok": true}

{        left brace
"id"     string
:        colon
12       number
,        comma
"ok"     string
:        colon
true     literal
}        right brace

The second stage walks that token stream and builds the value tree according to the grammar. Seeing a left brace, the parser expects either a right brace or a string key. After a key it demands a colon, then a value, then either a comma or a closing brace. Encountering anything else at any of those points is a syntax error.

This is why parse errors report a position. The parser knows exactly which character index it was reading when its expectation was violated, so it can hand you that offset. The offset points at where the document stopped making sense, which is not always where the mistake is: a missing closing brace on line 8 is often only detected at the end of the file, because everything in between was still grammatically plausible.

How JSON.parse Behaves in JavaScript

JSON.parse takes an optional second argument called a reviver, a function called once for every key and value pair as the tree is built, from the innermost values outward. Whatever it returns replaces the value, and returning undefined deletes the key entirely. It is the standard place to rehydrate types that JSON cannot express.

const ISO = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?Z$/;

const data = JSON.parse(text, (key, value) => {
  if (typeof value === "string" && ISO.test(value)) {
    return new Date(value);
  }
  return value;
});

data.createdAt instanceof Date;  // true

The same hook handles other conversions: turning decimal strings into a big-decimal type for money, stripping internal fields by returning undefined for keys beginning with an underscore, or normalizing a legacy field name. Keep the test narrow, since a reviver runs on every node and a loose regular expression on a large document is measurably slow.

Large integers lose precision

This is the most damaging JSON bug in practice because it is silent. JavaScript numbers are IEEE 754 doubles, so integers are only exact up to Number.MAX_SAFE_INTEGER, which is 9007199254740991, a little over nine quadrillion. Sixteen digits is fine, nineteen is not. Snowflake IDs, Twitter and Discord identifiers, and any 64-bit database key exceed that range comfortably.

JSON.parse('{"id": 9007199254740993}').id
// 9007199254740992   the last digit changed

JSON.parse('{"id": 1234567890123456789}').id
// 1234567890123456800   the last three digits are gone

No error is raised. The record simply points at a different row, or a lookup returns nothing, and the cause is invisible until someone compares the id they sent with the id that came back. The standard workaround is to transport such values as strings, which is why so many APIs return both an id and an id_str field, or return every identifier quoted.

{"id": "1234567890123456789"}   // exact, always

// or parse the raw text with a reviver that uses BigInt
// on the fields you know are 64-bit identifiers

Duplicate keys are allowed

The specification permits an object to contain the same key twice and declares the result undefined, leaving the behaviour to the implementation. JavaScript, Python, and most mainstream parsers take the last occurrence and silently discard the earlier ones.

JSON.parse('{"mode": "safe", "mode": "debug"}').mode
// "debug"

Because the document is technically valid, a plain parser will never warn you. Duplicates usually arise from a template that emits a field twice or from two config fragments concatenated by hand, and the effect is that a setting you can plainly see in the file is being overridden by one further down.

Reading Parse Error Messages

Two messages account for most failures, and each has a small set of likely causes.

Unexpected token means the scanner found a character that cannot legally start a value at that point. If it names a letter, you probably have an unquoted key or a bare identifier. If it names a single quote, the string delimiters are wrong. If it names a closing brace or bracket, you almost certainly have a trailing comma just before it. A special case worth knowing: unexpected token less-than at position 0 nearly always means the server returned an HTML error page rather than JSON, so read the response body before debugging the parser.

Unexpected end of JSON input means the document ended while the parser was still waiting for something. The usual causes are an unclosed brace or bracket, a truncated response from a connection that dropped mid-transfer, an empty string passed in where a body was expected, or a file that was read before writing finished. Check the length of the input first: if it is zero, the problem is upstream of the parser entirely.

Parsing Is Not Validation

A successful parse tells you the text was syntactically well formed. It tells you nothing whatsoever about whether the data is correct. This document parses perfectly and is useless.

{
  "email": 42,
  "age": "not telling",
  "status": "purple",
  "items": {}
}

Every rule that matters here is a schema rule, not a syntax rule: email must be a string matching an address pattern, age must be a non-negative integer, status must be one of a fixed set, items must be an array. A parser has no opinion on any of it. That second layer of checking is what JSON Schema exists for, describing required fields, types, formats, numeric bounds, enumerations, and nesting rules in a machine-readable document.

Run both checks in order. Parse first to confirm the text is JSON, then validate the resulting structure against a schema before trusting it. You can do the second step with the JSON Schema Validator, which also generates a starting schema from a sample document.

The JSON Validator covers the syntax layer and the JSON Viewer helps you inspect the parsed result. Browse the full collection of free JSON tools to find the right one for the job.