JSON

Getting Started

Fundamental JSON concepts and syntax for beginners.

Basic Structure

Understanding JSON file structure and format.

Minimal JSON object

The simplest valid JSON structure is an empty object.

Code

1
{}

Execution

echo '{}' | jq .

Output

1
{}

JSON must contain valid data structure (object or array at root).
An empty object {} is a valid JSON document.

Valid JSON structure

A basic JSON object with key-value pairs representing a person.

Code

1
{
2
  "name": "John",
3
  "age": 30,
4
  "city": "New York"
5
}

Execution

echo '{"name":"John","age":30,"city":"New York"}' | jq .

Output

1
{
2
  "name": "John",
3
  "age": 30,
4
  "city": "New York"
5
}

Keys must be strings enclosed in double quotes.
Values can be strings, numbers, booleans, null, objects, or arrays.

JSON file format

A typical JSON file structure for configuration data.

Code

1
{
2
  "version": "1.0",
3
  "author": "Admin",
4
  "timestamp": "2025-02-28"
5
}

Execution

cat config.json | jq .

Output

1
{
2
  "version": "1.0",
3
  "author": "Admin",
4
  "timestamp": "2025-02-28"
5
}

JSON files should be saved with .json extension.
Files should contain valid JSON starting with { or [.

Data Types

JSON data types and their usage.

All JSON data types

Demonstrates all seven JSON data types.

Code

1
{
2
  "string": "Hello",
3
  "number": 42,
4
  "decimal": 3.14,
5
  "boolean_true": true,
6
  "boolean_false": false,
7
  "null_value": null,
8
  "array": [1, 2, 3],
9
  "object": {"key": "value"}
10
}

Execution

jq . data.json

Output

1
{
2
  "string": "Hello",
3
  "number": 42,
4
  "decimal": 3.14,
5
  "boolean_true": true,
6
  "boolean_false": false,
7
  "null_value": null,
8
  "array": [1, 2, 3],
9
  "object": {"key": "value"}
10
}

JSON has exactly seven data types.
Booleans are lowercase true and false (not True/False).

Type examples

Real-world example showing mixed data types in a user object.

Code

1
{
2
  "user": {
3
    "id": 123,
4
    "active": true,
5
    "score": 98.5,
6
    "notes": null,
7
    "tags": ["admin", "verified"]
8
  }
9
}

Execution

jq '.user' user.json

Output

1
{
2
  "id": 123,
3
  "active": true,
4
  "score": 98.5,
5
  "notes": null,
6
  "tags": ["admin", "verified"]
7
}

Use null to represent missing or undefined values.
Numbers don't need quotes.

Multiple types in array

Arrays can contain any combination of JSON data types.

Code

1
{
2
  "mixed": [
3
    "string",
4
    42,
5
    true,
6
    null,
7
    {"nested": "object"},
8
    [1, 2, 3]
9
  ]
10
}

Execution

jq '.mixed | length' mixed.json

Output

Arrays maintain order and can mix different types.
Be cautious with mixed-type arrays - harder to parse.

Whitespace and Comments

Handling whitespace, formatting, and comments in JSON.

Formatted JSON

Pretty-printed JSON with indentation for readability.

Code

1
{
2
  "name": "Alice",
3
  "age": 28,
4
  "email": "alice@example.com"
5
}

Execution

jq . user.json

Output

1
{
2
  "name": "Alice",
3
  "age": 28,
4
  "email": "alice@example.com"
5
}

Whitespace outside quotes is ignored in JSON.
Use consistent indentation (typically 2 or 4 spaces).

Minified JSON

Minified JSON removes all unnecessary whitespace for smaller file size.

Code

1
{"name":"Bob","age":35,"email":"bob@example.com","active":true}

Execution

jq -c . user.json

Output

{"name":"Bob","age":35,"email":"bob@example.com","active":true}

Minified JSON is harder to read but smaller for transmission.
Both formatted and minified are equivalent.

Pretty-printed with indentation

JSON with 4-space indentation standard.

Code

1
{
2
    "user": {
3
        "id": 1,
4
        "details": {
5
            "name": "Carol",
6
            "role": "admin"
7
        }
8
    }
9
}

Execution

jq . --indent 4 config.json

Output

4-space indentation applied

Most style guides recommend 2-4 spaces for indentation.
Line breaks can appear within strings using escape sequences.

Objects

Working with JSON objects and key-value pairs.

Object Syntax

Understanding JSON object structure and syntax.

Empty object

An empty object contains no key-value pairs.

Code

1
{}

Execution

echo '{}' | jq 'type'

Output

"object"

Empty objects are valid and often used as defaults.
Objects use curly braces {} as delimiters.

Simple object

A simple object with three key-value pairs.

Code

1
{
2
  "firstName": "John",
3
  "lastName": "Doe",
4
  "age": 30
5
}

Execution

jq . person.json

Output

1
{
2
  "firstName": "John",
3
  "lastName": "Doe",
4
  "age": 30
5
}

Each key is a string in double quotes.
Key-value pairs are separated by colons.
Pairs are separated by commas.

Nested object

Objects can be nested within other objects.

Code

1
{
2
  "person": {
3
    "name": "Jane",
4
    "contact": {
5
      "email": "jane@example.com",
6
      "phone": "555-1234"
7
    }
8
  }
9
}

Execution

jq '.person.contact' person.json

Output

1
{
2
  "email": "jane@example.com",
3
  "phone": "555-1234"
4
}

Objects can contain other objects as values.
Nesting can go multiple levels deep.

Object Keys

Understanding JSON object key naming and conventions.

Simple key names

Standard key names that follow common conventions.

Code

1
{
2
  "id": 1,
3
  "name": "Alice",
4
  "email": "alice@example.com",
5
  "verified": true
6
}

Execution

jq 'keys' user.json

Output

1
[
2
  "email",
3
  "id",
4
  "name",
5
  "verified"
6
]

Use camelCase or snake_case consistently.
Keep key names short and descriptive.

Keys with spaces

Keys can contain spaces if enclosed in double quotes.

Code

1
{
2
  "first name": "John",
3
  "last name": "Smith",
4
  "home address": "123 Main St"
5
}

Execution

jq '["first name"]' person.json

Output

"John"

Keys with spaces are valid but harder to access programmatically.
Use underscores or camelCase instead of spaces.

Keys with special characters

Keys can contain special characters but must be quoted.

Code

1
{
2
  "@id": "obj-123",
3
  "$type": "Person",
4
  "api-key": "abc123xyz",
5
  "time&date": "2025-02-28"
6
}

Execution

jq '.["@id"]' metadata.json

Output

"obj-123"

Special characters require bracket notation to access.
Avoid special characters in keys when possible.

Object Values

Understanding JSON object values and nesting.

Different value types

Objects can contain any valid JSON value.

Code

1
{
2
  "stringValue": "text",
3
  "numberValue": 42,
4
  "decimalValue": 3.14,
5
  "booleanValue": true,
6
  "nullValue": null,
7
  "arrayValue": [1, 2, 3],
8
  "objectValue": {"nested": true}
9
}

Execution

jq '.stringValue' data.json

Output

"text"

Values can be of any JSON type.
Use appropriate types for each value.

Nested objects as values

Objects can be deeply nested within each other.

Code

1
{
2
  "user": {
3
    "profile": {
4
      "name": "Bob",
5
      "age": 35
6
    },
7
    "settings": {
8
      "notifications": true,
9
      "theme": "dark"
10
    }
11
  }
12
}

Execution

jq '.user.settings' user.json

Output

1
{
2
  "notifications": true,
3
  "theme": "dark"
4
}

Nesting allows hierarchical data representation.
Access nested values using dot notation.

Array values in objects

Objects can contain arrays as values.

Code

1
{
2
  "user": "Carol",
3
  "hobbies": ["reading", "gaming", "cooking"],
4
  "scores": [95, 87, 92, 88],
5
  "contacts": [
6
    {"type": "email", "value": "carol@example.com"},
7
    {"type": "phone", "value": "555-5678"}
8
  ]
9
}

Execution

jq '.hobbies[0]' user.json

Output

"reading"

Arrays can be homogeneous (same type) or heterogeneous (mixed types).
Access array elements by index notation.

Arrays

Working with JSON arrays and list structures.

Array Syntax

Understanding JSON array structure and syntax.

Empty array

An empty array contains no elements.

Code

1
[]

Execution

echo '[]' | jq 'type'

Output

"array"

Empty arrays are valid and used as defaults.
Arrays use square brackets [] as delimiters.

Simple array

A simple array of strings.

Code

1
[
2
  "apple",
3
  "banana",
4
  "cherry"
5
]

Execution

jq . fruits.json

Output

1
[
2
  "apple",
3
  "banana",
4
  "cherry"
5
]

Array elements are separated by commas.
No trailing comma after last element.

Mixed types array

Arrays can contain heterogeneous types.

Code

1
[
2
  "string",
3
  42,
4
  true,
5
  null,
6
  {"key": "value"},
7
  [1, 2, 3]
8
]

Execution

jq 'length' mixed.json

Output

Mixed-type arrays are valid but harder to parse.
Prefer homogeneous arrays when possible.

Array Elements

Understanding JSON array element types and access.

Array of objects

Array containing objects.

Code

1
[
2
  {
3
    "id": 1,
4
    "name": "Alice",
5
    "role": "admin"
6
  },
7
  {
8
    "id": 2,
9
    "name": "Bob",
10
    "role": "user"
11
  }
12
]

Execution

jq '.[0].name' users.json

Output

"Alice"

Access elements by index and key: array[0].key.
Perfect for representing collections of entities.

Nested arrays

Array of arrays (2D matrix structure).

Code

1
[
2
  [1, 2, 3],
3
  [4, 5, 6],
4
  [7, 8, 9]
5
]

Execution

jq '.[1][2]' matrix.json

Output

Access nested arrays: array[row][column].
Useful for matrix or grid data.

Homogeneous array

Arrays with all elements of same type.

Code

1
{
2
  "scores": [95, 87, 92, 88, 91],
3
  "temperatures": [72.5, 68.3, 75.1, 69.8]
4
}

Execution

jq '.scores | length' data.json

Output

Homogeneous arrays are easier to process.
All elements should have consistent meaning.

Array Operations

Common operations with JSON arrays.

Accessing array elements

Access array element by zero-based index.

Code

1
{
2
  "colors": [
3
    "red",
4
    "green",
5
    "blue",
6
    "yellow"
7
  ]
8
}

Execution

jq '.colors[2]' colors.json

Output

"blue"

Index 0 is the first element.
Negative indices work in some languages.

Array length

Get the number of elements in an array.

Code

1
{
2
  "items": ["apple", "banana", "cherry", "date"]
3
}

Execution

jq '.items | length' items.json

Output

Length is commonly needed for iteration.
Empty array has length 0.

Slicing arrays

Extract subset of array elements.

Code

1
{
2
  "numbers": [10, 20, 30, 40, 50, 60]
3
}

Execution

jq '.numbers[2:5]' numbers.json

Output

Slice notation: array[start:end].
End index is exclusive.

Strings and Numbers

Working with JSON strings and numeric values.

String Format

Understanding JSON string format and syntax.

Simple strings

Basic string values enclosed in double quotes.

Code

1
{
2
  "greeting": "Hello",
3
  "sentence": "This is a complete sentence.",
4
  "empty": ""
5
}

Execution

jq '.greeting' strings.json

Output

"Hello"

Strings must use double quotes, not single quotes.
Empty strings are valid values.

Escaped characters

Strings with escape sequences for special characters.

Code

1
{
2
  "newline": "Line 1\nLine 2",
3
  "tab": "Column 1\tColumn 2",
4
  "quote": "She said \"Hello\"",
5
  "backslash": "C:\\Users\\Name"
6
}

Execution

jq '.newline' strings.json

Output

"Line 1
Line 2"

Escape sequences start with backslash.
Common escapes: \n (newline), \t (tab), \" (quote).

Unicode strings

Strings can contain Unicode characters and emojis.

Code

1
{
2
  "emoji": "Hello 👋",
3
  "chinese": "你好",
4
  "unicode": "A\u0301"
5
}

Execution

jq '.emoji' unicode.json

Output

"Hello 👋"

JSON supports full Unicode character set.
Unicode escape: \uXXXX where XXXX is hex code.

String Escapes

Understanding JSON escape sequences.

Common escape sequences

Common escape sequences in JSON strings.

Code

1
{
2
  "quote": "He said \"Hello\"",
3
  "backslash": "Path: C:\\Users\\",
4
  "newline": "First\nSecond",
5
  "tab": "Col1\tCol2",
6
  "carriage_return": "Line1\rLine2"
7
}

Execution

jq '.quote' escapes.json

Output

"He said \"Hello\""

\" escapes double quote character.
\\ escapes backslash itself.
\n for newline, \t for tab.

All escape sequences

All eight JSON escape sequences.

Code

1
{
2
  "quote": "\"",
3
  "backslash": "\\",
4
  "forward_slash": "/",
5
  "backspace": "\b",
6
  "form_feed": "\f",
7
  "newline": "\n",
8
  "carriage_return": "\r",
9
  "tab": "\t"
10
}

Execution

jq 'keys' escapes.json

Output

1
[
2
  "backslash",
3
  "backspace",
4
  "carriage_return",
5
  "form_feed",
6
  "forward_slash",
7
  "newline",
8
  "quote",
9
  "tab"
10
]

\/ is optional (usually not needed).
\b and \f are rarely used in practice.

Unicode escape sequences

Unicode escape sequences using \uXXXX notation.

Code

1
{
2
  "copyright": "\u00A9 2025",
3
  "greek": "\u03B1 (alpha)",
4
  "emoji_unicode": "\uD83D\uDC4B"
5
}

Execution

jq '.copyright' unicode.json

Output

"© 2025"

Unicode specified as 4 hex digits after \u.
Useful for non-ASCII characters.

Number Format

Understanding JSON number formatting.

Integer numbers

Integer values without decimal points.

Code

1
{
2
  "year": 2025,
3
  "count": 42,
4
  "negative": -100,
5
  "zero": 0,
6
  "large": 1000000
7
}

Execution

jq '.year' numbers.json

Output

Integers are whole numbers.
Can be positive, negative, or zero.

Decimal numbers

Decimal (floating-point) numbers.

Code

1
{
2
  "pi": 3.14159,
3
  "price": 19.99,
4
  "temperature": -5.5,
5
  "percentage": 0.95
6
}

Execution

jq '.pi' decimals.json

Output

3.14159

Include decimal point and digits after it.
Precision may vary by language.

Scientific notation

Numbers in scientific notation.

Code

1
{
2
  "avogadro": 6.02214076e+23,
3
  "tiny": 1.6e-19,
4
  "standard": 1.5e2
5
}

Execution

jq '.avogadro' scientific.json

Output

6.02214076e+23

Use e or E for exponent notation.
Useful for very large or very small numbers.

Complex Structures

Building complex JSON data structures.

Nested Objects

Working with objects nested within other objects.

Two-level nesting

Basic nested object structure.

Code

1
{
2
  "person": {
3
    "name": "Alice",
4
    "age": 30
5
  }
6
}

Execution

jq '.person.name' user.json

Output

"Alice"

Access nested values with dot notation.
Each level is another object.

Multi-level nesting

Deep nesting of multiple object levels.

Code

1
{
2
  "company": {
3
    "department": {
4
      "team": {
5
        "lead": "Bob",
6
        "size": 5
7
      }
8
    }
9
  }
10
}

Execution

jq '.company.department.team.lead' org.json

Output

"Bob"

Keep nesting depth reasonable (3-4 levels typical).
Deep nesting becomes harder to navigate.

Complex hierarchy

Complex hierarchical configuration structure.

Code

1
{
2
  "application": {
3
    "name": "MyApp",
4
    "version": "1.0",
5
    "config": {
6
      "database": {
7
        "host": "localhost",
8
        "port": 5432,
9
        "credentials": {
10
          "user": "admin",
11
          "password": "secret"
12
        }
13
      }
14
    }
15
  }
16
}

Execution

jq '.application.config.database.host' config.json

Output

"localhost"

Used for application configuration.
Represents real-world nested data.

Nested Arrays

Working with arrays nested within other structures.

Array of arrays

Two-dimensional array structure.

Code

1
{
2
  "matrix": [
3
    [1, 2, 3],
4
    [4, 5, 6],
5
    [7, 8, 9]
6
  ]
7
}

Execution

jq '.matrix[1][2]' matrix.json

Output

Access with double bracket notation.
Row column indices like [1][2].

Array of objects

Common structure for collections of entities.

Code

1
{
2
  "users": [
3
    {
4
      "id": 1,
5
      "name": "Alice",
6
      "email": "alice@example.com"
7
    },
8
    {
9
      "id": 2,
10
      "name": "Bob",
11
      "email": "bob@example.com"
12
    }
13
  ]
14
}

Execution

jq '.users[0].email' users.json

Output

"alice@example.com"

Perfect for API responses with multiple items.
Each object is a separate item.

Complex nesting

Complex nested array and object combination.

Code

1
{
2
  "departments": [
3
    {
4
      "name": "Engineering",
5
      "members": [
6
        {"name": "Alice", "roles": ["dev", "lead"]},
7
        {"name": "Bob", "roles": ["dev", "devops"]}
8
      ]
9
    },
10
    {
11
      "name": "Sales",
12
      "members": [
13
        {"name": "Carol", "roles": ["sales"]}
14
      ]
15
    }
16
  ]
17
}

Execution

jq '.departments[0].members[1].roles[0]' org.json

Output

"dev"

Represents real-world hierarchical data.
Access with combined notation.

Mixed Structures

Combining objects and arrays in real-world structures.

API response structure

Typical API response with status and nested data.

Code

1
{
2
  "status": "success",
3
  "data": {
4
    "items": [
5
      {
6
        "id": 1,
7
        "title": "Item 1",
8
        "price": 29.99
9
      },
10
      {
11
        "id": 2,
12
        "title": "Item 2",
13
        "price": 39.99
14
      }
15
    ],
16
    "pagination": {
17
      "page": 1,
18
      "total": 50
19
    }
20
  }
21
}

Execution

jq '.data.items[0].title' response.json

Output

"Item 1"

Common pattern in REST APIs.
Combines object and array nesting.

Configuration structure

Configuration combining objects and array of objects.

Code

1
{
2
  "server": {
3
    "host": "localhost",
4
    "port": 3000,
5
    "endpoints": [
6
      {
7
        "path": "/api/users",
8
        "method": "GET"
9
      },
10
      {
11
        "path": "/api/users",
12
        "method": "POST"
13
      }
14
    ]
15
  }
16
}

Execution

jq '.server.endpoints[1].path' config.json

Output

"/api/users"

Used for application configuration.
Organizes settings hierarchically.

Data model structure

Comprehensive data model with mixed nesting.

Code

1
{
2
  "user": {
3
    "id": 123,
4
    "profile": {
5
      "firstName": "John",
6
      "lastName": "Doe",
7
      "avatar": "https://example.com/avatar.jpg"
8
    },
9
    "subscriptions": [
10
      {
11
        "plan": "premium",
12
        "renewalDate": "2025-03-28"
13
      }
14
    ],
15
    "preferences": {
16
      "notifications": true,
17
      "themes": ["dark", "light"]
18
    }
19
  }
20
}

Execution

jq '.user.preferences.themes[0]' user.json

Output

"dark"

Represents complete user profile.
Combines all structure types.

Validation and Best Practices

Validating and properly formatting JSON data.

Valid JSON

Valid JSON structure and common mistakes.

Valid JSON structure

Properly formatted, valid JSON structure.

Code

1
{
2
  "name": "John",
3
  "age": 30,
4
  "email": "john@example.com",
5
  "active": true,
6
  "roles": ["admin", "user"],
7
  "metadata": null
8
}

Execution

jq . valid.json

Output

Valid JSON (output shown)

All keys are quoted strings.
All values are valid JSON types.
No trailing commas.

Invalid structure examples

Common mistakes that make JSON invalid.

Code

1
{
2
  name: "John",
3
  age: 30,
4
  active: true,
5
  roles: ["admin", "user",]
6
}

Execution

jq . invalid.json 2>&1

Output

parse error: Invalid JSON

Keys must be quoted (single or double).
Trailing commas are not allowed.
Values like true/false must be unquoted.

Common JSON errors

Multiple common JSON validation errors.

Code

1
{
2
  "valid_key": "value",
3
  'invalid_key': "value",
4
  "no_comma" "next_key",
5
  "trailing": "comma",
6
}

Execution

echo 'Show validation errors'

Output

Multiple errors detected

Single quotes not allowed for keys or strings.
Missing commas between pairs.
Trailing comma after last element.

Formatting and Style

JSON formatting, indentation, and style conventions.

Pretty-printed JSON

Well-formatted JSON with 2-space indentation.

Code

1
{
2
  "user": {
3
    "id": 1,
4
    "name": "Alice",
5
    "tags": ["admin", "verified"],
6
    "active": true
7
  }
8
}

Execution

jq . user.json

Output

1
{
2
  "user": {
3
    "id": 1,
4
    "name": "Alice",
5
    "tags": [
6
      "admin",
7
      "verified"
8
    ],
9
    "active": true
10
  }
11
}

Improves readability and debugging.
Standard in development.
2-4 spaces recommended for indentation.

Minified JSON

Minified JSON with no whitespace.

Code

1
{"user":{"id":1,"name":"Alice","tags":["admin","verified"],"active":true}}

Execution

jq -c . user.json

Output

{"user":{"id":1,"name":"Alice","tags":["admin","verified"],"active":true}}

Reduces file size for transmission.
Standard for production/APIs.
Harder to read manually.

Indentation standards

JSON with 4-space indentation standard.

Code

1
{
2
    "level": 1,
3
    "nested": {
4
        "level": 2,
5
        "items": [
6
            "first",
7
            "second"
8
        ]
9
    }
10
}

Execution

jq --indent 4 . file.json

Output

4-space indentation

Some organizations prefer 4 spaces over 2.
Consistency important within project.

Parsing and Use

Parsing JSON and using it in applications.

JavaScript JSON parsing

Parsing JSON string to JavaScript object.

Code

1
{
2
  "name": "John",
3
  "age": 30,
4
  "email": "john@example.com"
5
}

Execution

node -e "const data = JSON.parse('{\"name\": \"John\"}'); console.log(data.name);"

Output

John

JSON.parse() converts string to object.
JSON.stringify() converts object to string.

Python JSON parsing

Parsing JSON string to Python dictionary.

Code

1
{
2
  "product": "Laptop",
3
  "price": 999.99,
4
  "available": true
5
}

Execution

python3 -c "import json; data = json.loads('{\"product\": \"Laptop\"}'); print(data['product'])"

Output

Laptop

json.loads() parses JSON string.
json.load() reads from file.

Validation with schema

JSON Schema for validating data structure.

Code

1
{
2
  "type": "object",
3
  "properties": {
4
    "name": {"type": "string"},
5
    "age": {"type": "integer"},
6
    "email": {"type": "string"}
7
  },
8
  "required": ["name", "email"]
9
}

Execution

echo 'JSON Schema validation'

Output

Schema validates structure

Schema defines expected structure.
Tools validate data against schema.

JSON

Getting Started

Basic Structure

Accessibility

Best Practices

Common Errors

Keywords

Minimal JSON object

Valid JSON structure

JSON file format

Data Types

Accessibility

Best Practices

Common Errors

Keywords

All JSON data types

Type examples

Multiple types in array

Whitespace and Comments

Accessibility

Best Practices

Common Errors

Advanced Notes

Keywords

Formatted JSON

Minified JSON

Pretty-printed with indentation

Objects

Object Syntax

Accessibility

Best Practices

Common Errors

Keywords

Empty object

Simple object

Nested object

Object Keys

Accessibility

Best Practices

Common Errors

Advanced Notes

Keywords

Simple key names

Keys with spaces

Keys with special characters

Object Values

Accessibility

Best Practices

Common Errors

Keywords

Different value types

Nested objects as values

Array values in objects

Arrays

Array Syntax

Accessibility

Best Practices

Common Errors

Keywords

Empty array

Simple array

Mixed types array

Array Elements

Accessibility

Best Practices

Common Errors

Advanced Notes

Keywords

Array of objects

Nested arrays

Homogeneous array

Array Operations

Accessibility

Best Practices

Common Errors

Keywords

Accessing array elements

Array length

Slicing arrays

Strings and Numbers