Skip to content
devsmiths

What Is JSON? A Practical Introduction

JSON is the most common data-interchange format on the web. This guide explains its value types, syntax, and the gotchas that trip people up.

JSON — JavaScript Object Notation — is a text-based format for representing structured data. It is the default lingua franca of HTTP APIs, the on-disk format for most modern config files, and the wire format for logs, queues, and a long tail of developer tooling. If you write software in 2026, you almost certainly read and write JSON every day.

This guide covers what JSON is, the six value types it supports, the syntax rules you must follow, and the differences between JSON and the JavaScript object literals it superficially resembles.

Where JSON came from

JSON was extracted from JavaScript by Douglas Crockford in the early 2000s as a minimal serialization format. It is standardized in two places that agree on the syntax: ECMA-404 (the JSON Data Interchange Syntax) and RFC 8259 (the IETF's JSON specification). Both define the same grammar — a small, closed set of tokens and structures with no ambiguity.

The deliberate minimalism is the point. JSON has no schema, no comments, no references, no dates, and no binary type. What it does have is a grammar small enough that every mainstream language ships a parser for it in the standard library.

The six JSON value types

Every JSON document is a single value. A value is one of:

  1. string — Unicode text wrapped in double quotes: "hello".
  2. number — a decimal number: 42, -3.14, 1.2e10. No NaN or Infinity.
  3. boolean — true or false.
  4. null — the literal null.
  5. object — an unordered collection of string-keyed pairs: {"name": "Ada", "age": 36}.
  6. array — an ordered list of values: [1, 2, 3].

Objects and arrays can nest arbitrarily, which is what makes JSON capable of representing complex documents.

Objects vs arrays

The two container types serve different purposes. An object maps names to values — use it when the fields have meaning:

{
  "id": "user_123",
  "email": "ada@example.com",
  "active": true
}

An array is an ordered sequence — use it when only position matters:

["red", "green", "blue"]

In practice you compose them. An API response listing users is almost always an array of objects:

[
  { "id": "user_1", "email": "ada@example.com" },
  { "id": "user_2", "email": "alan@example.com" }
]

JSON object keys are always strings and the spec says they should be unique within an object. Parsers that accept duplicates typically keep the last value, but you should never rely on that — produce documents with unique keys.

JSON vs JavaScript object literals

JSON looks like JavaScript, but it is a strict subset and the differences matter. The following is a valid JS object literal but invalid JSON:

{
  name: 'Ada',        // unquoted key, single quotes
  tags: ['a', 'b',],  // trailing comma
  born: new Date(),   // function call
  bio: undefined,     // undefined is not a JSON value
}

The same data in valid JSON:

{
  "name": "Ada",
  "tags": ["a", "b"],
  "born": "1815-12-10T00:00:00Z",
  "bio": null
}

Three rules cover most of the difference: keys must be quoted strings, strings use double quotes, and trailing commas are not allowed. There is no undefined in JSON — use null, or omit the key entirely.

If you have a payload that mixes JSON with JS-isms, the JSON Repair tool can normalize it.

Where JSON is used

  • HTTP APIs — almost every REST API speaks JSON. Content-Type: application/json.
  • Config files — package.json, tsconfig.json, composer.json, and many more.
  • Structured logs — one JSON object per line (NDJSON) is the standard for log shippers.
  • Document stores — MongoDB, DynamoDB, CouchDB store JSON-shaped documents.
  • Web messaging — postMessage, WebSockets, and Server-Sent Events all carry JSON.

Reading and writing JSON

Every mainstream language has a standard-library parser. The shape of the API is the same: serialize a value to a string, parse a string to a value.

JavaScript:

const obj = JSON.parse('{"a":1,"b":[2,3]}');
const text = JSON.stringify(obj, null, 2);

Python:

import json
obj = json.loads('{"a":1,"b":[2,3]}')
text = json.dumps(obj, indent=2)

Go:

import "encoding/json"

var obj map[string]any
json.Unmarshal([]byte(`{"a":1,"b":[2,3]}`), &obj)
out, _ := json.MarshalIndent(obj, "", "  ")

Common gotchas

  • Trailing commas — invalid in JSON, even though most code formatters add them in JS.
  • Comments — JSON has no // or /* */. JSON5 and JSONC do, but they are not JSON.
  • Single quotes — strings and keys must use double quotes.
  • NaN and Infinity — not valid JSON numbers. Use null or a sentinel string.
  • Large numbers — JSON numbers are decimal text, but JavaScript parsers convert them to 64-bit floats, losing precision past 2^53. For monetary or ID values, serialize as strings.
  • Dates — there is no date type. Convention is ISO 8601 strings ("2026-05-13").
  • Encoding — JSON is Unicode, typically UTF-8. A leading byte-order mark will break strict parsers.

If a document looks fine but won't parse, the JSON Validator usually pinpoints the offending byte.

Next steps