Skip to main content
Yoryantra

Developer · Guide

JSON Files Explained Through Real Examples and Parsing Errors

Understand JSON files through valid and invalid examples, types, escaping, nested data, parser errors, numeric precision and practical debugging.

By Varoun Sonawane
In this articleJump to a section
In this articleJump to a section

You download a configuration file, open it, and see a wall of braces, quotes and commas. The file is called settings.json, so you expect the application to read it. Instead, the application says the JSON is invalid. Sometimes the problem is a trailing comma. Sometimes the JSON is perfectly valid but contains a value the application cannot use. Those are different failures, and distinguishing them saves a surprising amount of debugging time.

JSON stands for JavaScript Object Notation. Despite the name, it is a language-independent text format for exchanging structured data. A JSON document can hold an object, an array, a string, a number, true, false or null. JavaScript, Python, Go and other languages can read it, but their runtime values and numeric limits do not always match. The syntax is specified by RFC 8259, not by whichever formatter happens to accept your input.

JSON syntax and escaping errors can stop a file from parsing. Even valid JSON may fail when its fields or value types do not match an application's expectations. Yoryantra's formatting and validation tools help inspect the text; the examples below show how to interpret the results.

If a JSON file fails immediately, check its syntax and escaping. If the text parses but your application still rejects it, look at the fields and value types the application expects.

Read the structure before changing anything

Consider a profile configuration that belongs to Sneha's development environment:

{
  "name": "Sneha",
  "enabled": true,
  "roles": ["developer", "reviewer"],
  "retryPolicy": {
    "attempts": 3,
    "delayMs": 1500
  },
  "lastError": null
}

The outer braces contain an object. Each member has a quoted string name, a colon and a value. roles holds an array, so the position of each array item matters. retryPolicy holds another object; nesting is how JSON represents more complicated relationships without inventing a new delimiter. enabled is a Boolean, not the string "true". lastError is an explicit null value, which is different from omitting lastError altogether.

The distinction between a JSON value and its textual appearance is easy to miss. "3" is a string. 3 is a number. The number is useful for arithmetic, but a postcode, account identifier or long numeric-looking reference often belongs in a string. Choosing the wrong type may produce a perfectly valid document that fails later when an application tries to compare, sort or serialize it.

Whitespace outside strings does not normally change the meaning. This compact text represents the same object values as the formatted version above:

{"name":"Sneha","enabled":true,"roles":["developer","reviewer"],"retryPolicy":{"attempts":3,"delayMs":1500},"lastError":null}

That is why a formatter can improve readability and a minifier can remove spacing. Neither operation adds a field your server requires or turns an unsupported type into a supported one. If you are investigating a contract failure, readability is the first aid, not the diagnosis.

JSON syntax is stricter than a JavaScript object

The following is common JavaScript syntax. It is not valid JSON:

const settings = {
  name: 'Sneha',
  enabled: true,
  retries: 3,
};

JSON requires quoted member names and double quotes around strings. A JavaScript const declaration, single-quoted string, trailing comma or comment is outside the JSON grammar. An object literal inside a .js file is code; a .json document is data. Copying an object literal into a JSON file without checking it is one of the quickest ways to get a parse error.

Here is a compact way to recognize the most frequent mistakes:

Input fragmentWhy it fails as JSONWhat the JSON text needs
{name:"Sneha"}Member name is not quoted{"name":"Sneha"}
{'name':'Sneha'}JSON strings use double quotes{"name":"Sneha"}
{"roles":["dev",]}Trailing comma in array{"roles":["dev"]}
{"timeout":NaN}NaN is not a JSON numberUse a defined number, null or application-specific representation
{"enabled":True}JSON literals are lowercase{"enabled":true}
// settingsComments are not part of standard JSONPut comments in documentation or use an explicitly supported alternative format

An error message such as “Unexpected token” points to where one parser first stopped accepting the text. It does not necessarily identify the author's underlying mistake. A missing quote earlier in the document can make a later comma look wrong. When the error points near the end, look for an unclosed string, array or object before changing the final character.

Some editors permit JSON with comments, often called JSONC, and some JavaScript tools accept JSON5. Those formats deliberately relax the rules. They are useful in their own ecosystems, but the server or CLI receiving your file must explicitly support them. A browser JSON.parse call will not become JSONC-aware because the filename or editor suggests it should.

A valid JSON document can still be unusable

Parsing checks whether the text follows JSON syntax. But an application may need more than valid syntax. For example, a port field might have to contain a number instead of text. Checking those rules is called validation against a schema (a description of the fields and types the application expects). are the expected properties present, do they have usable types, and do their values satisfy the rules?

These two documents both parse successfully:

{"timeoutMs":1500,"roles":["developer"]}

{"timeoutMs":"fast","roles":"developer"}

The second could break code expecting an integer timeout and an array of roles. A syntax validator should accept it as JSON. A schema validator with timeoutMs defined as an integer and roles defined as an array should reject it. A formatter that changes the second text into neat indentation will not solve the mismatch.

The same distinction appears with API responses. An HTTP response may contain well-formed JSON and still violate the client’s expectations. The client should check the HTTP status and then validate the parsed shape before assuming a property exists:

async function loadSettings() {
  const response = await fetch('/api/settings');
  if (!response.ok) {
    throw new Error(`Settings request failed: ${response.status}`);
  }

  const data = await response.json();
  if (data === null || typeof data !== 'object' || Array.isArray(data)) {
    throw new TypeError('Expected a settings object');
  }
  if (!Array.isArray(data.roles) || !data.roles.every(x => typeof x === 'string')) {
    throw new TypeError('Expected roles to be an array of strings');
  }
  return data;
}

This deliberately checks only part of the contract. A real application may also need required keys, number ranges, permitted role names or cross-field rules. JSON Schema and application-level validators address those needs. response.json() parses; it is not a schema validator, and it does not guarantee that an error response contains the expected shape.

For an API with a stable contract, a JSON Schema can make those expectations explicit. The following illustrative schema requires a nonnegative integer timeout and an array of string roles:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "required": ["timeoutMs", "roles"],
  "properties": {
    "timeoutMs": { "type": "integer", "minimum": 0 },
    "roles": { "type": "array", "items": { "type": "string" } }
  },
  "additionalProperties": false
}

Under that schema, {"timeoutMs":1500,"roles":["developer"]} passes these particular structural checks. A missing roles property, a negative timeout or an unexpected additional property fails. The strict additionalProperties choice is deliberate, not universally correct: some APIs need forwards-compatible extension fields, so rejecting every unknown field may be too aggressive. Schema rules should reflect the actual contract, versioning policy and consumers, not just whatever defaults a generator offers.

Schema validation still cannot prove business correctness by itself. A timeout of 1500 may be within the defined numeric range but inappropriate for a particular service. A role name may be a string but not one your authorization system recognizes. Keep that boundary clear when reporting “valid JSON” to a colleague: state whether you tested syntax, a declared schema or an application-specific rule.

Strings are where escaping mistakes hide

Inside a JSON string, \n represents a line feed, \t a tab and \" a quotation mark. A backslash itself must be escaped as \. A literal control character such as a raw line break inside a quoted JSON string is not allowed. This difference often becomes visible when a Windows file path or a pasted error message enters an API payload.

For example, this represents a Windows path with the required escaping:

{"path":"C:\\Users\\Sneha\\logs","message":"First line\nSecond line"}

If an application generates JSON for you with a serializer, let the serializer handle those escapes. Hand-building JSON with string concatenation is error-prone, particularly for quotes, backslashes, control characters and user-provided text. In JavaScript, JSON.stringify is usually the right starting point for data you have already represented as native values.

Encoding is another quiet source of trouble. RFC 8259 requires UTF-8 for JSON exchanged between systems outside a closed ecosystem. It also says generators must not add a byte-order mark to network-transmitted JSON, although parsers may choose to ignore one. If a parser unexpectedly rejects the first character of a file, inspect the actual bytes before assuming the braces are wrong. Not every invisible character is ordinary whitespace.

Unicode also has edges worth understanding. JSON can express characters directly or with \u escapes. Some escaped surrogate sequences represent a character as a pair; unmatched surrogates can be syntactically expressible yet cause unpredictable handling between implementations. This is one reason to avoid treating “my parser accepted it” as proof of interoperability with every consumer.

Numbers and duplicate names can change after parsing

RFC 8259 does not set an application-wide precision policy for numbers. JavaScript uses IEEE 754 binary64 for ordinary Number values, so integers outside its exact safe range can be rounded. Consider a reference number:

{"orderId":9007199254740993}

That JSON text is syntactically valid. But a JavaScript consumer using JSON.parse may lose the exact integer. If the digits are an identifier rather than a quantity for arithmetic, a string representation is often safer:

{"orderId":"9007199254740993"}

This choice must be agreed with the receiving API; changing types without checking its contract can introduce another error. Similarly, Infinity and NaN are available as concepts in some programming languages but are not JSON numeric literals. JavaScript's JSON.stringify has its own conversion behavior for unsupported values, so serialization is not a guarantee that every original runtime value is preserved.

Duplicate object names are a second interoperability trap:

{"environment":"staging","environment":"production"}

RFC 8259 says object names should be unique. It does not make duplicate-name handling identical across parsers. Some implementations keep the last occurrence, others report an error, and some can expose both. If a formatter parses and re-serializes this text, it may silently discard one occurrence. A pretty-printed result may therefore look tidy while concealing a data-quality problem from the original input.

When exact preservation matters, especially for signed payloads, audit records or cross-language integrations, do not assume that parsing and formatting are byte-preserving operations. Whitespace, escape choices, numeric rendering and member order may change. A signature over the original bytes is a different problem from comparing the logical values inside the JSON document.

There is another consequence for developers comparing payloads in source control. Two JSON documents with differently ordered object members can describe equivalent application data, while two files that look nearly identical can differ in number precision or duplicate names. A text diff is useful for reviewing edits but is not a complete semantic comparison. If you need canonical bytes for signing or hashing, use an explicitly agreed canonicalization scheme and confirm that every producer follows it. Ordinary pretty-printing is not a canonicalization contract.

Formatting, validation and minification

Suppose a colleague sends you an unreadable API response. You can paste it into Yoryantra's JSON Formatter to inspect nesting and line structure. If the formatter rejects it, start with the syntax problem and its location. If it succeeds but the application still fails, compare the resulting shape with the expected contract rather than repeatedly reformatting the same text.

OperationUseful questionImportant limitation
FormattingWhere do objects, arrays and fields begin and endDoes not fix a missing field or wrong type
Syntax validationDoes the text satisfy JSON syntaxDoes not prove the application accepts the data
Schema validationDoes the parsed value match stated rulesOnly covers the rules defined by that schema
MinificationCan unnecessary whitespace outside strings be removedMay make manual inspection harder and does not make large data intrinsically efficient

Yoryantra also provides a JSON Validator and JSON Minifier for those distinct jobs. The tools work on the text you supply; an article like this is where the broader decisions belong. Use the tool result as evidence and move on to the relevant layer instead of treating every data failure as a formatting failure.

When the file parses on one machine but not another

First confirm that both applications received the same bytes. A .json extension alone does not prove the content is JSON, and an HTTP Content-Type header can be incorrect. A proxy may return an HTML error page with status 200, or a command may capture warning text before the JSON value. Inspect the status, media type and first bytes rather than feeding every failure straight to the JSON formatter.

Next check whether the failing system uses strict JSON or a more permissive configuration format. Comments and trailing commas tolerated by one editor can fail in another. If both parse the file, compare types and field names. Property-name casing, null versus missing values, and arrays versus objects commonly cause application-level surprises that no parser should correct for you.

Large files raise a different problem. Parsing a whole document typically constructs the entire value in memory. A multi-gigabyte event export may need a streaming parser or a newline-delimited format such as NDJSON, where each line holds an independent JSON value. NDJSON is useful, but an entire NDJSON file containing multiple top-level lines is not one ordinary JSON document. A successful parse of one record does not validate the whole stream.

For untrusted JSON, set reasonable request-size and depth limits in the surrounding application. Parsing JSON does not execute JavaScript, so do not use eval to read it. Risks still arise when software recursively walks unusually deep values, trusts fields without checks, or merges attacker-controlled object keys into sensitive application objects. Syntax acceptance is the start of input handling, not the end of security review.

A reliable sequence when JSON is failing

First find the actual JSON text. Is it a .json file, an API response, or JSON inside another string? The distinction matters because the problem may be how the data was transported rather than the JSON itself. Confirm its real encoding and transport format. Validate JSON syntax once, capture the exact failure, and inspect nearby delimiters and quotes. If the text parses, stop changing its formatting and test the receiving application's contract. For cross-language problems, pay particular attention to large numbers, duplicate names, null handling and escaping.

When you have a minimal reproducible input, keep it. A five-line sample showing the same failure is more useful than another screenshot of a thousand-line payload. It can become a unit test and prevent the same parsing mistake from returning during the next release.