T
json format data web development

JSON Explained: From Basics to Advanced Usage

A deep dive into JSON — its history, syntax, use cases in modern web development, common pitfalls, and best practices for working with structured data.

2026-04-09 Use This Tool

What Is JSON?

JSON (JavaScript Object Notation) is a lightweight, text-based data interchange format that is easy for both humans to read and write, and for machines to parse and generate. Despite being derived from JavaScript syntax, JSON is language-independent — virtually every modern programming language has libraries to parse and produce it.

JSON was introduced by Douglas Crockford in the early 2000s as a simpler alternative to XML for data exchange on the web. Today, it is the dominant format for REST APIs, configuration files, databases like MongoDB, and much more.

JSON Syntax: The Complete Picture

A JSON value is one of:

  • Object: { "key": value, ... } — an unordered collection of key-value pairs
  • Array: [ value, ... ] — an ordered list of values
  • String: "hello world" — must use double quotes
  • Number: 42, 3.14, -7, 1.5e10 — no distinction between int and float
  • Boolean: true or false
  • Null: null
{
  "name": "Alice",
  "age": 30,
  "isActive": true,
  "scores": [95, 87, 100],
  "address": {
    "city": "London",
    "postcode": "SW1A 1AA"
  },
  "notes": null
}

Common Syntax Mistakes

Mistake Incorrect Correct
Trailing comma { "a": 1, } { "a": 1 }
Single quotes { 'key': 'val' } { "key": "val" }
Unquoted key { key: "val" } { "key": "val" }
Comments { // comment } (not supported)
Undefined { "a": undefined } Use null or omit the key

A Brief History

  • 2001: Douglas Crockford begins promoting JSON as a stateless server-to-browser communication protocol
  • 2006: IETF publishes RFC 4627, the first formal JSON specification
  • 2013: ECMA International formalizes JSON as ECMA-404
  • 2017: RFC 8259 supersedes all previous RFCs and becomes the definitive standard

Before JSON, XML dominated API communication. JSON's brevity and natural fit with JavaScript objects made it a runaway success in the Web 2.0 era — a trend that has only accelerated.

Where JSON Is Used

REST APIs

Almost every REST API today returns JSON. A request to a weather API might look like:

{
  "location": "Tokyo",
  "temperature": 22.4,
  "unit": "celsius",
  "conditions": ["cloudy", "humid"],
  "forecast": [
    { "day": "Monday", "high": 24, "low": 18 },
    { "day": "Tuesday", "high": 21, "low": 16 }
  ]
}

Configuration Files

Tools like ESLint (.eslintrc.json), TypeScript (tsconfig.json), and npm (package.json) all use JSON for configuration.

NoSQL Databases

MongoDB stores documents in BSON (Binary JSON). CouchDB, Firebase Firestore, and DynamoDB all use JSON-like document models.

Local Storage and Cookies

Browsers' localStorage only stores strings, so developers often JSON.stringify() objects before storing and JSON.parse() them on retrieval.

Logging & Observability

Structured logging in JSON makes it trivial to query logs with tools like Elasticsearch, Datadog, or Loki.

JSON Parsing in Practice

JavaScript / TypeScript

// Parse string to object
const data = JSON.parse('{"name":"Alice","age":30}');
console.log(data.name); // "Alice"

// Serialize object to string
const json = JSON.stringify({ name: "Alice", age: 30 }, null, 2);

The optional null, 2 argument to JSON.stringify adds pretty-printing with 2-space indentation — invaluable for debugging.

Python

import json

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

# Serialize
text = json.dumps({"name": "Alice", "age": 30}, indent=2)

Go

import (
    "encoding/json"
    "fmt"
)

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

func main() {
    var p Person
    json.Unmarshal([]byte(`{"name":"Alice","age":30}`), &p)
    fmt.Println(p.Name)
}

Advanced Topics

JSON Schema

JSON Schema is a vocabulary for validating the structure of JSON data. It allows you to define required fields, value types, patterns, and constraints:

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

JSON Pointer (RFC 6901)

JSON Pointer provides a string syntax for identifying a specific value within a JSON document:

  • /name → the name field
  • /scores/0 → first element of the scores array

JSON Patch (RFC 6902)

JSON Patch defines a format for expressing a sequence of operations to apply to a JSON document — useful for incremental updates in APIs.

Performance Considerations

  • Size: JSON is text-based and verbose. For high-throughput systems, consider MessagePack or Protocol Buffers as binary alternatives.
  • Parsing speed: Modern JSON parsers (like simdjson) can parse gigabytes per second, but for most web apps, JSON parsing is not a bottleneck.
  • Deeply nested structures: Very deep nesting can cause stack overflow errors in recursive parsers. Keep structures reasonably flat where possible.

JSON vs XML vs YAML

Feature JSON XML YAML
Readability Good Verbose Excellent
Comments ❌ ✅ ✅
Binary support ❌ (needs base64) ❌ ❌
Schema validation JSON Schema XSD ❌ (limited)
Best for APIs, config, storage Documents, legacy Config files

Best Practices

  1. Validate on input: Never trust incoming JSON — always validate against a schema or check for expected fields.
  2. Use null intentionally: Distinguish between "field is missing" and "field is explicitly null."
  3. Avoid deeply nested structures: Flat data is easier to work with. Use IDs to link related objects.
  4. Consistent key naming: Pick a convention (camelCase, snake_case) and stick to it across your API.
  5. Dates as ISO 8601 strings: JSON has no date type. Use "2025-04-09T00:00:00Z" format for interoperability.
  6. Minify for production, pretty-print for debugging: Use compact JSON in API responses to reduce bandwidth; pretty-print locally.

Summary

JSON has become the universal language of data exchange on the web for good reason: it is simple, readable, and supported everywhere. Understanding its syntax, limitations, and best practices will make you a more effective developer — whether you are building APIs, writing configuration files, or processing data pipelines.

Back to Blog JSON Formatter →