What Is JSON and How Does It Work

You open an API response and see a wall of curly braces, square brackets, and colons. That's JSON. A plain-text format that became the de facto standard for data exchange on the web — not by committee decree, but because developers needed something more readable than XML and more structured than CSV.

What JSON is

JSON stands for JavaScript Object Notation. The name is misleading: it's not JavaScript-specific. Every modern language — Python, Go, PHP, Java, Rust — handles JSON natively or with a small library.

It's a text format. Open any JSON response in Notepad and you can read it. No special bytes, no binary headers. What you see is what's there.

The spec lives in RFC 8259 and json.org. The entire specification fits on one page — which is a big part of why it won.

Basic syntax

JSON is built on two structures: objects (key-value pairs) and arrays (ordered lists).

An object:

{
  "name": "Rafael",
  "age": 31,
  "active": true
}

An array:

["New York", "London", "São Paulo"]

Arrays and objects nest freely:

{
  "user": "rafael",
  "cities": ["New York", "London"],
  "profile": {
    "plan": "pro",
    "trial": false
  }
}

Data types

JSON has exactly six types. No dates, no functions, no classes. Six:

Things that catch people off guard:

• Strings need double quotes. Single quotes are invalid JSON.
• Object keys are always strings: { "id": 1 }, never { id: 1 }.
• There's no Date type. Dates become strings — typically ISO 8601: "2024-03-15T10:00:00Z".
• There's no undefined. If a field doesn't exist, it simply isn't in the JSON — or it's null.
• No trailing commas. { "a": 1, } is invalid. This trips up developers coming from modern JavaScript.

Where JSON shows up

Anywhere two systems need to exchange data:

REST APIs: login request bodies, user list responses, validation error messages with field and reason — all JSON.

Config files: package.json, tsconfig.json, composer.json, .eslintrc, VS Code extension configs. Most of the JavaScript ecosystem uses JSON as its config format.

LocalStorage and cookies: browser data is almost always serialized to JSON before storage and deserialized on read.

Logs and events: observability tools like Datadog, Elastic, and Loki expect structured JSON logs. Much easier to filter and query than plain text.

Databases: PostgreSQL has a native jsonb type with indexing. MongoDB stores documents in BSON (Binary JSON). Most modern relational databases support JSON columns.

Reading and writing JSON in code

In JavaScript and TypeScript:

// Parse: JSON string → object
const data = JSON.parse('{"name":"Rafael","age":31}');
console.log(data.name); // Rafael

// Stringify: object → JSON string
const json = JSON.stringify({ name: "Rafael", active: true });
// '{"name":"Rafael","active":true}'

// With indentation (useful for debug)
console.log(JSON.stringify(data, null, 2));

In Python:

import json

# Parse
data = json.loads('{"name": "Rafael", "age": 31}')
print(data["name"])  # Rafael

# Serialize
text = json.dumps({"name": "Rafael", "active": True})

In Go:

import "encoding/json"

type User struct {
    Name string `json:"name"`
    Age  int    `json:"age"`
}

var u User
json.Unmarshal([]byte(`{"name":"Rafael","age":31}`), &u)

The pattern is the same across languages: a parse function (input: string, output: native structure) and a serialize function (input: native structure, output: string).

Common errors that break parsing

JSON is strict. One mistake and the entire parse fails:

// INVALID — trailing comma after last field
{
  "name": "Rafael",
  "age": 31,
}

// INVALID — single quotes
{
  'name': 'Rafael'
}

// INVALID — comment (JSON has no comments)
{
  "name": "Rafael" // primary user
}

// INVALID — unquoted key
{
  name: "Rafael"
}

These four are the most common failures. They all show up in hand-written JSON — especially trailing commas, because every modern code editor accepts them as valid JavaScript, but JSON doesn't.

When I get broken JSON from an external API or legacy system, I use the JSON Formatter to locate the exact error and line number. The native parser just says "unexpected token", which isn't helpful when the payload has 300 lines.

JSON vs the alternatives

XML: more verbose, harder to read, supports comments and namespaces. Still dominant in SOAP systems and older enterprise integrations. If you have no choice, fine — but if you do, JSON is simpler.

YAML: more human-readable (no curly braces), supports comments, good for config. The problem is a complicated spec full of edge cases — YAML has a history of deserialization vulnerabilities and surprising behaviors (the famous country: NO that becomes false because NO is a boolean in YAML). Great for files humans edit directly (Docker Compose, GitHub Actions), bad for data exchange between systems.

CSV: simple and compact for tabular data. Zero support for types or nested structures. When the data is a flat table, CSV still makes sense. When there's hierarchy, it falls apart.

Protocol Buffers / MessagePack: binary formats, much more efficient in size and parse speed. Worth it when performance matters more than readability. Require a schema.

JSON is the middle ground: readable, no mandatory schema, supported everywhere. Not the most efficient, not the most expressive — the most practical.

Frequently asked questions

Does JSON support comments?

No. The official spec doesn't include them. This is particularly frustrating in config files where comments would be useful. TypeScript's tsconfig.json uses an extension called JSONC (JSON with Comments) that allows // and /* */, but that's not standard JSON — regular parsers reject it.

If you need comments in config files, consider TOML or YAML. For APIs, document outside the payload.

Can a number field be sometimes integer, sometimes decimal?

In JSON there's no distinction between 42 and 42.0 — both are number. The distinction lives in the parsing language: JavaScript reads both as number, Go can map to int or float64 depending on the struct field type. The JSON itself doesn't differentiate.

One practical concern: very large integers (above 2⁵³ in JavaScript) lose precision when parsed as number. For large IDs or millisecond timestamps, it's common to receive the number as a string in JSON specifically to avoid this.

Does JSON support binary data like images?

Not directly. If you need to include binary data in JSON, the standard approach is Base64 encoding — include the encoded string as a JSON string field. The trade-off is +33% payload size plus encoding/decoding overhead. For large files, a separate upload endpoint with just the URL in the JSON is usually the better call.

What's the difference between null and a missing field?

In JSON these are distinct. { "price": null } means the field exists and its value is explicitly null. An object without the price field means the information wasn't provided. For APIs, the semantics matter: a PATCH with "price": null might mean "remove this value", while omitting the field might mean "don't change it". Document what your API expects.

Simple format, but precision still matters

The format itself has fewer than ten rules. What gets complicated is everything outside the format: no schema, no types beyond the basic six, no versioning. Two systems can exchange JSON perfectly and still behave differently because each side interprets null or decimal numbers differently.

For simple data between controlled systems, JSON works fine with no additional structure. For public APIs, internal contracts between teams, or financial data, defining a schema is worth it — JSON Schema is the standard for that, but that's a topic for another post.