JSON

JSON as data text

JSON (JavaScript Object Notation) is a small text format for data. It can describe strings, finite numbers, booleans, null, arrays, and plain objects with double-quoted property names. That is why the curriculum summary says JSON helps you send and store data as text.

JSON looks like JavaScript object and array literals, but it is stricter and smaller. It has no comments, no single-quoted strings, no functions, no undefined, no symbols, no BigInt, and no special Date value. The reward for those limits is portability: almost every programming language can read it.

You have already met objects and references, numbers, BigInt, and symbols. This lesson shows how those values behave when they cross the JSON border. Later, the Fetch & JSON lesson in Stage 7 will use the same ideas to read responses from servers.

JSON.stringify(value) packs a supported JavaScript value into JSON text. JSON.parse(text) reads JSON text and returns fresh JavaScript values. Fresh matters: a JSON round trip can act like a deep copy for plain data, but the Objects & references lesson’s warning still applies: it is not a perfect clone.

1const order = {Run2  item: "keyboard",3  quantity: 2,4  shipped: false,5};6 7const text = JSON.stringify(order, null, 2);8const copy = JSON.parse(text);9console.log(text);10console.log(copy.item);

The second argument to JSON.stringify can customize values. The third argument controls pretty-printing. Passing 2 means two spaces; passing 0 or omitting it gives compact JSON.

1const value = {2  name: "Ava",3  address: { city: "Pune", country: "IN" },4  roles: ["admin", "editor"],5};

{
  "name": "Ava",
  "address": {
    "city": "Pune",
    "country": "IN"
  },
  "roles": [
    "admin",
    "editor"
  ]
}

{
  "name": "Ava",
  "address": {
    "city": "Pune",
    "country": "IN"
  },
  "roles": [
    "admin",
    "editor"
  ]
}

Try each preset. A nested user survives; a Date comes back as text; undefined, functions, and symbols disappear or become null; Map and Set become empty objects; BigInt and circular references throw TypeError. Those are real browser results, not hand-written examples.

A replacer is a function or an array passed to JSON.stringify. A function replacer is called for the wrapper and each property; returning undefined removes an object property. Think of it as a customs officer checking every item before shipping.

1const account = {Run2  name: "Ava",3  password: "rosebud",4  profile: { password: "also-secret", theme: "dark" },5};6 7const safeText = JSON.stringify(account, (key, value) => {8  if (key === "password") return undefined;9  return value;10}, 2);11console.log(safeText);

A replacer array is simpler: JSON.stringify(user, ["name", "email"]) whitelists those property names. It is useful for small, flat output, but a function is clearer when you need rules such as “remove every password key.”

A reviver is the matching hook for JSON.parse. It receives each parsed key and value and can return a replacement. A common use is restoring an ISO date string into a Date object. Date basics are in the next module, so here the key idea is only that JSON stores the Date as text.

1const text = '{"name":"Ava","joined":"2024-01-01T00:00:00.000Z"}';Run2 3const user = JSON.parse(text, (key, value) => {4  if (key === "joined") return new Date(value);5  return value;6});7 8console.log(user.joined instanceof Date);9console.log(user.joined.toISOString());

Before JSON.stringify writes an object, it checks for a toJSON method. If the method exists, stringify serializes the method’s return value instead of the original object. That is why Dates become ISO strings: Date.prototype.toJSON already exists.

1const price = {2  cents: 1250,3  currency: "USD",4  toJSON() {5    return "12.50 USD";6  },7};8 9console.log(JSON.stringify({ price }));

A class can use this to publish a deliberate data shape. For example, a money object may store cents internally but ship as "12.50 USD". Keep toJSON boring and predictable: it should return JSON-friendly data, not depend on the current time or hidden global state.

JSON is excellent for simple data, but it is lossy outside that lane. Here are the edge cases recorded from real JavaScript behavior.

This is why a JSON round trip is only a limited deep-copy trick. It can copy plain data, but structuredClone is the more honest tool for many JavaScript values. The BigInt lesson explains why 1n is not the same type as 1, and Numbers explains why huge numeric IDs can lose precision.

Recent engines add two tools for advanced JSON work. First, a reviver can receive a third context argument for primitive values. context.source is the exact JSON source text for that value. That matters for huge numbers because JSON.parse normally converts them to Number before your code sees them.

1const text = '{"id": 12345678901234567890}';2 3const rounded = JSON.parse(text).id;4const safe = JSON.parse(text, (key, value, context) => {5  if (key === "id") return BigInt(context.source);6  return value;7}).id;8 9console.log(rounded);10console.log(safe);

In Node 22, JSON.parse('{"id": 12345678901234567890}').id is the rounded number 12345678901234567000. With context.source, the reviver can read the original digits and create 12345678901234567890n. Second, JSON.rawJSON("12345678901234567890") creates a trusted raw JSON value so JSON.stringify({ id: JSON.rawJSON("12345678901234567890") }) outputs a raw number token.

1const id = JSON.rawJSON("12345678901234567890");2const text = JSON.stringify({ id });3console.log(text);

Feature-detect in browsers after mount with typeof JSON.rawJSON === "function", JSON.isRawJSON, and a small parse test for context.source. These additions are useful, but strings remain the simplest cross-platform way to move big IDs safely.

Where you will use this

JSON appears anywhere data crosses a boundary: saving settings in storage, putting data into a file, sending request bodies, reading API responses, logging safe snapshots, and writing tests with fixture data. Stage 7’s Fetch & JSON lesson will combine fetch with response.json(); the JSON rules here are the same rules underneath.

Common misconceptions

• “JSON is any JavaScript object text.” No. JSON has stricter grammar: double quotes, no comments, no trailing commas.
• “JSON.parse restores the original objects.” It creates fresh plain objects and arrays. Prototypes and methods are gone unless you revive or rebuild them.
• “Dates survive JSON.” They become strings through Date.prototype.toJSON.
• “Map serializes like an object.” A Map’s entries are not enumerable string-keyed properties, so it becomes {} unless you convert it.
• “Big numbers are always safe in JSON.” JSON text may contain many digits, but JavaScript Number precision is limited. Use strings or context.source plus BigInt when available.
• “A replacer and reviver run at the same time.” Replacer runs while stringifying; reviver runs later while parsing.

Key takeaways

• JSON.stringify packs supported data into text; JSON.parse unpacks valid JSON text.
• Replacers filter or transform before shipping; revivers rebuild selected values while receiving.
• toJSON lets an object choose its own JSON-friendly representation.
• JSON cannot hold functions, undefined, symbols, BigInt, circular references, object identity, prototypes, or Date objects as Dates.
• Recent context.source and JSON.rawJSON APIs help with exact source text, but feature-detect them.

Final definition: JSON is a strict, portable text format for simple data, with hooks for carefully changing what leaves and what comes back.

Up next: Choosing a data structure.