You've seen JSON in config files, API responses, and database records. It's everywhere in modern development — and for good reason. But if you've never stopped to think about what it actually is or how it works, this guide will give you a solid foundation.

{
  "name": "Jane Doe",
  "age": 28,
  "skills": ["JavaScript", "Python"],
  "active": true
}

That right there is JSON. Clean, readable, and understood by virtually every programming language. Let's break down exactly what's going on.

What is JSON?

JSON stands for JavaScript Object Notation. It's a lightweight, text-based format for representing structured data. Despite the JavaScript in the name, JSON is language-agnostic — Python, Ruby, Java, PHP, and Go all have built-in support for reading and writing it.

JSON is built on two fundamental structures:

  • Objects: key-value pairs wrapped in curly braces { }
  • Arrays: ordered lists of values wrapped in square brackets [ ]

Everything in JSON is composed of these two building blocks. That simplicity is a big part of why JSON won out over alternatives like XML.

How JSON Works: Data Types and Syntax

JSON supports exactly six data types. No more, no less.

  • String: text in double quotes — "hello"
  • Number: integer or decimal — 42, 3.14
  • Boolean: true or false (always lowercase)
  • Null: represents the absence of a value — null
  • Object: a collection of key-value pairs — { "key": "value" }
  • Array: an ordered list — [1, 2, 3]

You can nest objects and arrays freely to represent complex data hierarchies.

A couple of common gotchas to watch out for:

  • No comments allowed — JSON has no comment syntax. // this and /* this */ will break parsing.
  • No trailing commas — ["a", "b",] is invalid JSON, even though JavaScript allows it in arrays and objects.
  • Keys must be strings — and they must use double quotes, not single quotes.

JSON in the Real World

REST API Responses

When you call a REST API, the response body is almost always JSON. In JavaScript, you parse it with .json():

const res = await fetch('https://api.example.com/users/1');
const user = await res.json();
console.log(user.name); // "Jane Doe"

package.json

Every Node.js project has a package.json at its root. It's just a JSON file that describes your project — its name, version, scripts, and dependencies.

{
  "name": "my-app",
  "version": "1.0.0",
  "scripts": {
    "dev": "vite"
  },
  "dependencies": {
    "react": "^18.0.0"
  }
}

localStorage

Browsers only store strings in localStorage, so when you want to persist an object, you serialize it to JSON first and parse it back when you need it:

// Save
localStorage.setItem('user', JSON.stringify({ id: 1, name: 'Jane' }));

// Load
const user = JSON.parse(localStorage.getItem('user'));

Frequently Asked Questions

JSON vs XML — which should I use?
For most modern web APIs, JSON is the better choice. It's less verbose, easier to read, and natively supported in JavaScript. XML still appears in older enterprise systems and some specific contexts like SVG and RSS, but if you're starting fresh, go with JSON.
Can I add comments to JSON?
Not in standard JSON. The spec (RFC 8259) intentionally excludes comments to keep the format simple and parser-friendly. If you need comments in a config file, consider YAML or JSON5 instead. Some tools like VS Code also support JSONC (JSON with comments) for their own config files.
Is a JSON object the same as a JavaScript object?
They look similar but they're not the same thing. A JavaScript object is a runtime data structure; JSON is a text format. JSON keys must be double-quoted strings, and JSON doesn't support functions, undefined, or Date objects. Use JSON.stringify() to convert a JS object to JSON text, and JSON.parse() to go the other way.

Summary

  • JSON is a text-based data format built on two structures: objects ({}) and arrays ([])
  • It supports six data types: string, number, boolean, null, object, and array
  • No comments, no trailing commas, keys must be double-quoted strings
  • Used everywhere: REST APIs, config files, databases, localStorage

Need to work with JSON right now? These tools have you covered: