JSON

JSON: data written as text

JSON is a way to write data as plain text. The name is short for JavaScript Object Notation. "Notation" just means a way of writing things down.

JSON text can hold only these kinds of values:

• Strings in double quotes, like "Asha".
• Numbers, like 3 or 2.5. NaN and Infinity are not allowed.
• true and false.
• null.
• Arrays, like [1, 2].
• Plain objects, like {"name": "Asha"}. Every property name is in double quotes.

Because JSON is text, you can send it to a server or save it in a file. That is what JSON is for: sending and storing data.

JSON looks like JavaScript objects and arrays, but its rules are stricter. JSON text has:

• No comments.
• No strings in single quotes.
• No functions.
• No undefined.
• No symbols.
• No BigInt values, like 1n.
• No special value for dates.

These rules keep JSON small and simple. So almost every programming language can read JSON, not just JavaScript.

You already know objects, numbers, BigInt, and symbols from earlier lessons. This lesson shows what happens to each of them when you turn them into JSON text. Later, the Fetch & JSON lesson in Stage 7 uses the same ideas to read data from servers.

JavaScript has a built-in JSON object with two main methods:

• JSON.stringify(value) turns a JavaScript value into JSON text. "Stringify" means "make into a string".
• JSON.parse(text) reads JSON text and builds new JavaScript values from it. "Parse" means "read text and work out what it says".

JSON.parse always builds new objects and arrays. So when you turn data into JSON text and back, you get a copy. This is called a round trip. For plain data, the copy is a deep copy: nested objects are copied too. But it is not a perfect copy of every value. You'll see what gets lost later in this lesson. The Objects & references lesson explains why a new object is never the same object as the old one.

1const user = { name: "Asha", score: 3 };2const text = JSON.stringify(user);3const copy = JSON.parse(text);4console.log(text);5console.log(copy.name);

Line by line:

1. Line 1 makes an object with a name and a score.
2. Line 2 turns the object into the text {"name":"Asha","score":3}.
3. Line 3 reads that text and builds a new object, copy.
4. Line 4 prints the text.
5. Line 5 prints copy.name, which is Asha.

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);

JSON.stringify can take two more arguments:

• The second argument can change values before they are written. It is called the replacer, and the next section explains it. When you don't need it, pass null.
• The third argument adds spaces so the text is easier to read. 2 means "indent each level by two spaces". Leave it out, or pass 0, to get short text on one line.

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"
  ]
}

Pick each preset in the workbench. Compare the JSON text with what comes back. You will see that:

• A nested user comes back the same.
• A Date comes back as a string.
• undefined, functions, and symbols are left out of objects. In arrays, they become null.
• Map and Set become empty objects, {}.
• A BigInt, or a circular object (an object that points back to itself), throws a TypeError.

These results come from real JavaScript running in your browser.

1const requestBody = JSON.stringify({2  title: "Tea",3  done: false,4});5const received = JSON.parse(requestBody);6console.log(requestBody);7console.log(received.done);

A request body is the data a program sends to a server. It travels as text. So the sender calls JSON.stringify before sending (line 1). The receiver calls JSON.parse on the text it gets (line 5). Line 6 prints the text, and line 7 prints received.done, which is false.

JSON itself doesn't send or save anything. It only turns data into text and back. Other tools, like fetch, do the sending.

A replacer is the second argument to JSON.stringify. It can be a function or an array. A replacer function works like this:

• JSON.stringify calls it once for the whole value. The key is then an empty string, "".
• Then it calls it once for each property, with that property's key and value.
• Whatever the function returns is written into the JSON text.
• If it returns undefined for an object property, that property is left out.

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 can also be an array of property names, like ["name", "email"]. Then JSON.stringify writes only those properties. This works well for small, flat objects. Use a function when you need a rule, such as "remove every key called password, however deep it is".

1const user = {2  name: "Asha",3  email: "asha@example.com",4  role: "admin",5};6console.log(JSON.stringify(user, ["name", "email"]));

Line 6 passes the array ["name", "email"]. The text keeps name and email and leaves out role.

Don't count on this list alone to keep secrets out. Remove secrets on purpose, and check the data before you send it.

A reviver is the second argument to JSON.parse. It is a function. JSON.parse calls it for each value it reads, with the key and the value. Whatever the reviver returns goes into the result instead.

A common use is turning date text back into a Date object. JSON has no date type, so a date travels as text, like "2024-01-01T00:00:00.000Z". This standard way of writing a date is called an ISO string. Dates get their own lesson in the next module. Here you only need to know that JSON stores a 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 one thing: does this object have a method called toJSON? If it does, stringify calls that method and writes what it returns, instead of the object.

This is why a Date turns into a string. Every Date already has a toJSON method, Date.prototype.toJSON, and it returns the date as an ISO string.

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

Lines 4 to 6 add a toJSON method that returns the text "12.50 USD". Line 9 turns { price } into JSON. Stringify finds toJSON on price, so it writes "12.50 USD" instead of cents and currency. The printed text is {"price":"12.50 USD"}.

Classes can use toJSON the same way. For example, a Money class may keep the amount in cents, but write "12.50 USD" into JSON. Keep toJSON simple: return plain JSON data. Don't make the result depend on the current time or on variables outside the object. Then the same object always gives the same text.

JSON works well for simple data. Other values change, disappear, or cause an error when you turn them into JSON. The picture shows three of them.

The table lists all of them. Each row is one kind of value. The columns show what JSON.stringify prints, what you have after parsing it back, and why. These results were recorded from real JavaScript.

1const tags = new Set(["js", "json"]);2const text = JSON.stringify([...tags]);3const restored = JSON.parse(text);4console.log(text);5console.log(restored.length);

A Set holds unique values, but it doesn't keep them as normal properties. So JSON.stringify can't see them. Line 2 copies the values into an array with [...tags]. Arrays work in JSON, so the text is ["js","json"]. Line 5 prints 2, the length of the parsed array.

1const order = { id: 12345678901234567890n };2const text = JSON.stringify(order, (_key, value) =>3  typeof value === "bigint" ? value.toString() : value,4);5const copy = JSON.parse(text);6console.log(text);7console.log(typeof copy.id);

Lines 2 to 4 pass a replacer. When a value is a BigInt, the replacer returns it as a string. So the JSON text holds the digits in quotes, and line 7 prints string. The receiver can check that string and then call BigInt(copy.id) to get the BigInt back.

Don't turn a large ID into a normal number. A normal number can't hold that many digits exactly, so the ID would change.

So a JSON round trip is only a limited way to copy data. It works for plain data. For other values, structuredClone is a better tool. It is a built-in function that also copies Dates, Maps, Sets, and more. The BigInt lesson explains why 1n is a different type from 1. Numbers explains why very large numbers lose their last digits.

Newer JavaScript engines add two tools for big numbers in JSON. An engine is the part of a browser, or of Node, that runs JavaScript.

First, the problem. JSON text can hold a number with many digits, like 12345678901234567890. But a normal JavaScript number keeps only about 16 digits exactly. So JSON.parse rounds the number before your code ever sees it.

The first tool is a third argument for the reviver, called context. For a simple value like a number or a string, context.source is the exact text of that value in the JSON. So the reviver can read the original digits and build a BigInt from 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 gives the rounded number 12345678901234567000. With context.source, the reviver reads the original digits and makes 12345678901234567890n.

The second tool, JSON.rawJSON, is for writing JSON. JSON.rawJSON("12345678901234567890") makes a special value that holds the exact text you gave it. When JSON.stringify meets that value, it writes the text as it is. So JSON.stringify({ id: JSON.rawJSON("12345678901234567890") }) keeps every digit. Only pass text you trust, and it must be valid JSON.

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

Line 1 makes the raw value. Line 2 turns { id } into JSON, and line 3 prints {"id":12345678901234567890}.

Not every browser has these tools yet, so check before you use them. This is called feature detection:

• typeof JSON.rawJSON === "function" tells you whether JSON.rawJSON exists.
• JSON.isRawJSON(value) tells you whether a value was made by JSON.rawJSON.
• For context.source, parse a tiny piece of JSON with a reviver and see whether context.source arrives.

Run these checks in the browser, after the page has loaded. The server that builds the page may support different features. Sending big IDs as strings still works everywhere, so it is the simplest safe choice.

Where you will use this

You use JSON whenever data leaves your program or comes into it. For example, when you:

• Save settings in the browser.
• Save data in a file.
• Send data to a server.
• Read the data a server sends back.
• Write a log without secrets in it.
• Keep sample data for tests.

In Stage 7, the Fetch & JSON lesson uses fetch with response.json(). response.json() follows the same JSON rules you learn here.

Browser storage keeps only text. localStorage is a small store in the browser. It keeps strings, even after the page is closed. To save settings there:

• localStorage.setItem("settings", JSON.stringify(settings)) saves the settings as one string.
• JSON.parse(localStorage.getItem("settings") ?? "{}") reads them back. getItem gives null when nothing is saved, so ?? "{}" uses the text of an empty object instead.

The saved text may be broken, or saved by an older version of your page. So be ready for JSON.parse to throw, and show a friendly message if it does.

When you send JSON to a server, keep it short: leave out the third argument. Also tell the server the text is JSON, by setting the request's content type to application/json. Indented JSON is better for files and logs that people read.

The table lists common jobs. Each row shows the job, the tool to use, and one thing to watch out for.

Common misconceptions

• "JSON is any JavaScript object written as text." No. JSON has stricter rules: double quotes only, no comments, and no comma after the last item.
• "JSON.parse gives me back my original objects." No. It builds new, plain objects and arrays. Methods and classes are gone, unless you rebuild them with a reviver.
• "Dates stay Dates in JSON." No. They become strings, because of Date.prototype.toJSON.
• "A Map turns into JSON like an object." No. A Map doesn't keep its entries as normal properties, so it becomes {}. Turn it into an array or object first.
• "Big numbers are always safe in JSON." No. JSON text can hold many digits, but a JavaScript number keeps only about 16 exactly. Send big numbers as strings, or use context.source and BigInt where it works.
• "The replacer and the reviver run at the same time." No. The replacer runs while JSON.stringify writes the text. The reviver runs later, while JSON.parse reads it.
• "JSON.parse runs the text as JavaScript code." No. It only reads data. It never runs functions or code. You still need to check the keys and values you get before you use them.
• "JSON.stringify always gives a string." No. If the whole value is undefined, it returns undefined. Check the result before you save it or send it.
• "If JSON.parse works, the data is safe to use." No. It only proves the text follows the JSON rules. Also check the shape, the allowed values, and the size before you use the data in your app.

The table compares the two functions you can pass in. Each row is one of them.

Key takeaways

• JSON.stringify turns plain data into JSON text. JSON.parse reads JSON text and builds new values.
• A replacer changes or removes values while the text is written. A reviver changes values while the text is read.
• toJSON lets an object choose what it looks like in JSON.
• JSON can't hold functions, undefined, symbols, BigInt, circular objects, classes, or Dates as Dates. A parsed object is always a new object.
• context.source and JSON.rawJSON keep exact digits in newer engines. Check that they exist before you use them.

Final definition: JSON is a strict text format for simple data that almost every program can read. A replacer and a reviver let you change what goes out and what comes back.

Up next: Choosing a data structure.