JSON Guide

01 Introduction — The Data Format of the Web

JSON (JavaScript Object Notation) is a lightweight, text-based format for representing structured data. It began as a subset of JavaScript syntax, but it is now language-independent and standardised as RFC 8259 and ECMA-404. Every mainstream language — Python, Go, Rust, Java, C#, PHP, Ruby — can read and write it out of the box.

Its job is simple: move data between programs. A server serialises an object to JSON text, ships it over HTTP, and the browser parses it back into a usable object. The same format also stores configuration, logs, telemetry, and entire databases.

Where you will meet JSON

• REST and GraphQL APIs — request bodies and responses
• Config files — package.json, tsconfig.json, settings.json
• Databases — MongoDB documents, PostgreSQL jsonb columns
• Logs and events — structured logging, analytics pipelines
• Integrations — webhooks, message queues, CI/CD metadata
• Browser storage — saved state in localStorage

JSON is not JavaScript

A JavaScript object literal and a JSON document look similar, but JSON is stricter. Key differences:

• Keys must be double-quoted strings — { name: "Laksh" } is JavaScript, not JSON
• No comments — // and /* */ are invalid
• No trailing commas — the last item must not have one
• No functions, undefined, NaN or Infinity
• Strings use double quotes only — single quotes are invalid

02 Syntax & Data Types Beginner

JSON has exactly six data types. Every value in every document is one of them.

A complete document

{
  "name": "Laksh",
  "age": 25,
  "isDeveloper": true,
  "nickname": null,
  "skills": ["JavaScript", "Linux", "Git"],
  "address": {
    "city": "Mangalore",
    "country": "India"
  }
}Copy

The rules in one place

• Keys are always strings wrapped in double quotes
• Colon separates a key from its value; commas separate pairs
• Whitespace is ignored — pretty-printing is purely cosmetic
• Values may be any of the six types, nested to any depth
• Duplicate keys are technically allowed, but the last one wins — avoid them
• No trailing comma after the final key/value pair or array item

Valid vs invalid — spot the difference

// ❌ Invalid JSON
{
  name: 'Laksh',          // unquoted key, single quotes
  "age": 25,              // trailing comma
  "active": true
}

// ✅ Valid JSON
{
  "name": "Laksh",
  "age": 25,
  "active": true
}Copy

03 Objects, Arrays & Nesting Beginner

Objects — unordered key/value pairs

An object maps names to values. The order of keys is not guaranteed by the spec — never rely on it when reading data.

{
  "id": 101,
  "title": "First post",
  "published": true
}Copy

Arrays — ordered lists

An array holds values in a definite order. Items can be of any type, including mixed types and nested arrays.

["apple", "banana", "cherry"]
[1, 2, 3, 4, 5]
[true, null, "mixed", { "nested": true }]
[[1, 2], [3, 4]]Copy

The shape you will see most: an array of objects

APIs almost always return a list of records. This is the canonical JSON response shape.

{
  "users": [
    { "id": 1, "name": "Ada", "role": "admin" },
    { "id": 2, "name": "Linus", "role": "developer" },
    { "id": 3, "name": "Grace", "role": "developer" }
  ],
  "total": 3
}Copy

Empty values

{
  "object": {},
  "array": [],
  "string": "",
  "number": 0,
  "boolean": false,
  "nothing": null
}Copy

04 Strings, Numbers & Escapes Intermediate

Escape sequences

A few characters cannot appear literally inside a JSON string. Escape them with a backslash.

"quote: \"hello\""
"backslash: \\"
"newline: \n"
"tab: \t"
"carriage return: \r"
"unicode: \u00e9  (é)"
"emoji: \ud83d\ude80  (🚀)"Copy

Numbers have no type distinction

JSON does not separate integers from floats. Everything numeric is one number type, and the spec does not define a precision or range.

42
-3.14
1.5e10
0.0001
6.02214076e23Copy

Invalid numbers include leading zeros (007), hexadecimal (0xFF), the special values NaN and Infinity, and a leading +.

Dates are just strings

JSON has no date type. By convention, dates travel as ISO 8601 strings, and the consumer converts them.

{
  "createdAt": "2026-10-19T09:30:00.000Z",
  "updatedAt": "2026-10-19T12:00:00Z"
}Copy

05 JSON in JavaScript Intermediate

Every modern JavaScript runtime — browser, Node.js, Deno, Bun — provides exactly two methods through the global JSON object: parse and stringify.

Parsing — text to object

const text = '{"name":"Laksh","skills":["JS","Git"]}';
const user = JSON.parse(text);

console.log(user.name);    // "Laksh"
console.log(user.skills[0]); // "JS"Copy

Stringifying — object to text

const user = {
  name: "Laksh",
  skills: ["JS", "Git"],
  active: true
};

JSON.stringify(user);
// '{"name":"Laksh","skills":["JS","Git"],"active":true}'

JSON.stringify(user, null, 2);  // pretty-print with 2 spacesCopy

Handling parse errors

Malformed input throws a SyntaxError. Always wrap parsing of external data.

function safeParse(text) {
  try {
    return { ok: true, value: JSON.parse(text) };
  } catch (err) {
    return { ok: false, error: err.message };
  }
}

const result = safeParse('{ "broken": }');
// { ok: false, error: "Unexpected token } ..." }Copy

Replacer and reviver

Both methods accept an optional hook. The replacer filters or transforms values while encoding; the reviver transforms values while decoding.

// Replacer: omit sensitive fields
JSON.stringify(user, (key, value) =>
  key === "password" ? undefined : value
);

// Reviver: turn ISO strings into Date objects
const data = JSON.parse(text, (key, value) =>
  key.endsWith("At") ? new Date(value) : value
);Copy

What stringify silently drops

• Functions and undefined values are omitted from objects
• Symbol-keyed properties are ignored
• NaN and Infinity become null
• Date objects become ISO strings via their toJSON()
• Circular references throw a TypeError
• Class instances lose their prototype — only own enumerable properties survive

06 JSON & HTTP APIs Intermediate

JSON is the default body format for web APIs. The two headers that matter are Content-Type (what you send) and Accept (what you want back).

Reading a JSON response

const res = await fetch("https://api.example.com/users");

if (!res.ok) {
  throw new Error(`HTTP ${res.status}`);
}

const users = await res.json();
console.log(users[0].name);Copy

Sending JSON in a request

const res = await fetch("https://api.example.com/users", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Accept": "application/json"
  },
  body: JSON.stringify({
    name: "Laksh",
    role: "developer"
  })
});

const created = await res.json();Copy

Checking before parsing

res.json() throws if the body is empty or is not JSON — common for 204 No Content and error responses that return HTML. Check status and content type first.

const type = res.headers.get("content-type") || "";
const data = type.includes("application/json")
  ? await res.json()
  : await res.text();Copy

Common status codes

07 Validation & JSON Schema Advanced

A document can be syntactically valid JSON and still be wrong for your program. JSON Schema is the standard way to describe the expected shape and validate against it.

A small schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "required": ["id", "name", "email"],
  "properties": {
    "id":    { "type": "integer", "minimum": 1 },
    "name":  { "type": "string", "minLength": 1 },
    "email": { "type": "string", "format": "email" },
    "role":  { "type": "string", "enum": ["admin", "developer", "viewer"] },
    "tags":  { "type": "array", "items": { "type": "string" } }
  },
  "additionalProperties": false
}Copy

Common keywords

Validating in code

Ajv is the most widely used validator for JavaScript and Node.js. Similar libraries exist for every language.

import Ajv from "ajv";
const ajv = new Ajv();

const validate = ajv.compile(schema);

if (!validate(data)) {
  console.error(validate.errors);
} else {
  console.log("Valid!");
}Copy

Quick checks without code

• VS Code validates package.json and tsconfig.json automatically using built-in schemas
• jsonlint.com — paste a document to check syntax
• jq — jq . file.json pretty-prints and fails loudly on invalid JSON
• JSON Schema Store — community schemas for thousands of config formats

08 Variants & Related Formats Advanced

Strict JSON is deliberately minimal. Several extensions and sibling formats fill the gaps — just know which one a tool expects.

JSONL / NDJSON — one document per line

JSON Lines stores one complete JSON value per line. It is ideal for streaming, logs and big datasets because a consumer can process line by line without loading the whole file.

{"id":1,"event":"login","user":"ada"}
{"id":2,"event":"logout","user":"ada"}
{"id":3,"event":"login","user":"linus"}Copy

JSON5 — JSON for humans

JSON5 allows comments, unquoted keys, single quotes, trailing commas and multi-line strings. It is popular in config files, but it is not standard JSON — APIs will reject it.

{
  // comments are allowed
  unquotedKey: 'single quotes',
  trailing: true,
}Copy

JSONC — JSON with Comments

VS Code's settings.json and TypeScript's tsconfig.json accept comments and trailing commas. The file is JSONC even though its extension says .json — a strict validator will complain.

How the formats compare

09 Pitfalls & Best Practices Intermediate

The classic mistakes

• Trailing commas — valid in JavaScript, fatal in JSON
• Comments — valid in JSONC/JSON5, fatal in strict JSON
• Unquoted or single-quoted keys — not JSON
• Smart quotes — copying from a word processor inserts “ ”, which are not ASCII quotes
• Hidden BOM characters — a byte-order mark at the start of a file breaks some parsers
• Encoding — JSON must be UTF-8; mismatched encodings produce mojibake

Security and correctness

• Never use eval to parse JSON — use JSON.parse, which cannot execute code
• Prototype pollution — a "__proto__" or "constructor" key in untrusted JSON can poison object prototypes when merged blindly. Validate and strip unknown keys.
• Big numbers — IDs above the safe integer limit must be strings
• Deep nesting — extremely deep documents can exhaust the call stack in recursive parsers; validate shape and depth on the server
• Huge payloads — set size limits and stream large data instead of loading it all at once
• Duplicate keys — behaviour is implementation-defined; the last value usually wins, which can mask bugs

Best practices

• Use camelCase keys consistently, matching the target language's conventions
• Send dates as ISO 8601 UTC strings, never as local timestamps
• Prefer null for intentional absence and omit fields that are not applicable
• Version your API payloads if the shape may evolve
• Pretty-print files that humans edit, minify payloads that machines transfer
• Validate with a schema at every boundary — client, server and database
• Wrap parsing in try/catch and surface a useful error

10 Cheat Sheet

Valid JSON in ten seconds

• Double quotes around every key and string
• No comments, no trailing commas, no single quotes
• Only six value types — no undefined, functions, NaN or Infinity
• Top level is usually an object or array
• Dates are ISO strings; big IDs are strings
• Parse with JSON.parse, never eval