If you have spent any time building software in the last decade, you have almost certainly encountered JSON. I use it every single day, whether I am debugging API responses, writing configuration files, or passing data between a frontend and a backend. In this guide, I want to walk you through everything you need to know about JSON: from the basics of its syntax all the way through validation with JSON Schema and converting it to other formats.

What Is JSON and Why Did It Win?

JSON stands for JavaScript Object Notation. Douglas Crockford popularized it in the early 2000s as a lightweight alternative to XML for data interchange. The idea was simple: take the object literal syntax that JavaScript developers already knew and use it as a universal data format.

Before JSON took off, XML was the dominant format for web services. SOAP APIs sent XML back and forth with verbose tags, namespaces, and schemas. A simple user record in XML might look like this:

<user>
  <name>Alice</name>
  <age>30</age>
  <active>true</active>
</user>

The same data in JSON is noticeably shorter and easier to read:

{
  "name": "Alice",
  "age": 30,
  "active": true
}

JSON won because it is less verbose, maps directly to native data structures in most languages, and is easier for humans to read. Today it powers REST APIs, NoSQL databases like MongoDB, package manifests like package.json, and configuration files across the ecosystem. If you need to quickly format or validate a JSON document, try our JSON Formatter and Validator.

JSON Syntax Rules

JSON supports six data types, and understanding them is fundamental to working with the format effectively.

Objects

An object is an unordered collection of key-value pairs wrapped in curly braces. Keys must be strings (in double quotes), and each key-value pair is separated by a comma:

{
  "firstName": "Bob",
  "lastName": "Smith",
  "role": "developer"
}

Arrays

An array is an ordered list of values wrapped in square brackets:

["JavaScript", "Python", "Rust", "Go"]

Strings, Numbers, Booleans, and Null

Strings must use double quotes. Numbers can be integers or floating-point (no leading zeros, no hex). Booleans are true or false (lowercase only). And null represents an empty or missing value.

Nesting

The real power of JSON comes from nesting these types inside each other. Here is a more realistic example:

{
  "user": {
    "id": 42,
    "name": "Alice",
    "emails": ["[email protected]", "[email protected]"],
    "address": {
      "city": "Portland",
      "state": "OR",
      "zip": "97201"
    },
    "verified": true,
    "deletedAt": null
  }
}

Common Mistakes That Trip People Up

I have debugged countless "invalid JSON" errors over the years, and the same mistakes come up again and again. Here are the ones I see most often:

Trailing commas. JavaScript lets you put a comma after the last item in an array or object. JSON does not. This is probably the single most common source of parse errors:

// INVALID - trailing comma
{
  "name": "Alice",
  "age": 30,
}

Single quotes. JSON requires double quotes for strings and keys. Single quotes will cause a parse failure immediately:

// INVALID - single quotes
{'name': 'Alice'}

Comments. JSON does not support comments of any kind. No //, no /* */. If you need comments in a configuration file, consider using JSONC (JSON with Comments, supported by VS Code) or switch to YAML. You can convert between these formats using our JSON to YAML converter.

Unquoted keys. In JavaScript, you can write { name: "Alice" }. In JSON, that key must be in double quotes: { "name": "Alice" }.

Working with JSON in JavaScript

JavaScript gives you two core methods for working with JSON: JSON.parse() and JSON.stringify().

Parsing JSON

The JSON.parse() method takes a JSON string and returns a JavaScript value. Always wrap it in a try-catch block, because malformed input will throw a SyntaxError:

const raw = '{"name": "Alice", "age": 30}';

try {
  const user = JSON.parse(raw);
  console.log(user.name); // "Alice"
} catch (error) {
  console.error("Failed to parse JSON:", error.message);
}

Stringifying JavaScript Objects

The JSON.stringify() method converts a JavaScript value to a JSON string. It accepts optional arguments for filtering properties and controlling indentation:

const data = { name: "Alice", age: 30, active: true };

// Compact output
JSON.stringify(data);
// '{"name":"Alice","age":30,"active":true}'

// Pretty-printed with 2-space indent
JSON.stringify(data, null, 2);
// {
//   "name": "Alice",
//   "age": 30,
//   "active": true
// }

JSON Schema: Validating Your Data

As your JSON documents grow in complexity, you need a way to ensure they follow a specific structure. That is where JSON Schema comes in. JSON Schema is a vocabulary that lets you annotate and validate JSON documents. Think of it as TypeScript for your data files.

Here is a simple schema that validates a user object:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "name": { "type": "string", "minLength": 1 },
    "age": { "type": "integer", "minimum": 0 },
    "email": { "type": "string", "format": "email" }
  },
  "required": ["name", "email"]
}

JSON Schema has gone through several draft versions. Draft-07 is still widely used in production, but Draft 2020-12 is the latest stable specification. The core concepts remain the same across drafts: you define the expected type, constraints, required fields, and nested structures.

You can generate and validate JSON Schema documents using our JSON Schema Validator.

Converting JSON to Other Formats

JSON is fantastic as a data interchange format, but it is not always the right choice for every situation. Here are the conversions I find myself doing most often.

JSON to CSV

When you need to open data in Excel or Google Sheets, CSV is the way to go. Flat JSON arrays convert cleanly, but nested objects require flattening. For example, this JSON:

[
  { "name": "Alice", "age": 30, "city": "Portland" },
  { "name": "Bob", "age": 25, "city": "Seattle" }
]

becomes this CSV:

name,age,city
Alice,30,Portland
Bob,25,Seattle

Our JSON to CSV converter handles nested objects by flattening keys with dot notation, so address.city becomes a column header.

JSON to YAML

YAML is the preferred format for DevOps configuration files: Docker Compose, Kubernetes manifests, GitHub Actions workflows, and Ansible playbooks all use YAML. The same data in YAML is more concise and supports comments:

name: Alice
age: 30
emails:
  - [email protected]
  - [email protected]

Convert between the two formats instantly with our JSON to YAML converter.

JSON to TypeScript

If you work with TypeScript, you know the value of having proper type definitions for your API responses. Instead of manually writing interfaces, you can generate them from a sample JSON response. Our JSON to TypeScript converter takes a JSON object and produces TypeScript interfaces automatically.

JSON to XML

Some legacy systems and SOAP APIs still require XML. If you need to bridge the gap between a modern JSON API and an older XML-based system, our JSON to XML converter handles the translation for you.

Pro Tips for Working with JSON

Over the years, I have picked up several techniques that save me time and prevent bugs. Here are the ones I think every developer should know.

Pretty-Printing with a Custom Indent

The third argument to JSON.stringify() controls indentation. You can pass a number (spaces) or even a string (like a tab character):

// Tab-indented output
JSON.stringify(data, null, "\t");

// From the command line (Node.js)
// node -e "console.log(JSON.stringify(require('./data.json'), null, 2))"

Deep Cloning Objects

The old trick of JSON.parse(JSON.stringify(obj)) creates a deep clone, but it drops undefined, functions, and Date objects. Modern JavaScript provides a better alternative:

// Old approach (lossy)
const clone = JSON.parse(JSON.stringify(original));

// Modern approach (preserves more types)
const clone = structuredClone(original);

Use structuredClone() when you can. Fall back to the JSON round-trip method only when you specifically want to strip non-serializable values.

JSON Lines (NDJSON)

When you are dealing with large datasets or streaming data, JSON Lines (also called NDJSON) is a great format. Each line is a valid JSON value, and you process them one at a time without loading the entire file into memory:

{"id": 1, "event": "click", "timestamp": 1712678400}
{"id": 2, "event": "scroll", "timestamp": 1712678401}
{"id": 3, "event": "submit", "timestamp": 1712678402}

This format is widely used in logging pipelines, data engineering, and tools like jq.

Wrapping Up

JSON is one of those technologies that is so fundamental it is easy to take for granted. But understanding its rules, knowing where the common pitfalls are, and having the right tools at hand can save you hours of debugging time. Whether you are parsing API responses, validating configuration files, or converting data between formats, I hope this guide has given you a solid foundation.

Here is a quick summary of the BoltQuickTools resources mentioned in this article:

All of these tools run entirely in your browser. Your data never leaves your device, and there is nothing to install or sign up for.