JSON Arrays — Lists, Collections & Nested Patterns

What is a JSON Array?

An array is an ordered list of values enclosed in square brackets[]. Items are separated by commas, and can be any valid JSON type.

Array basicsjson

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

Array Patterns

1. Homogeneous Arrays (Same Type)

The most common and recommended pattern — all items share the same type:

Homogeneous arraysjson

1{
2  "tags": ["javascript", "react", "nextjs"],
3  "scores": [98, 87, 92, 100],
4  "flags": [true, false, true, true]
5}

2. Array of Objects

The dominant pattern in APIs. Each object in the array represents one entity:

Array of user objectsjson

1{
2  "users": [
3    {
4      "id": 1,
5      "name": "Alice",
6      "role": "admin"
7    },
8    {
9      "id": 2,
10      "name": "Bob",
11      "role": "editor"
12    },
13    {
14      "id": 3,
15      "name": "Charlie",
16      "role": "viewer"
17    }
18  ]
19}

3. Nested Arrays (Matrices)

Arrays can contain other arrays, useful for grids, tables, and multi-dimensional data:

Tic-tac-toe board as nested arraysjson

1{
2  "board": [
3    ["X", "O", "X"],
4    ["O", "X", "O"],
5    ["O", "X", "X"]
6  ]
7}

4. Tuple-Like Arrays

Mixed-type arrays where position determines meaning (like coordinates):

GeoJSON coordinate pairjson

1{
2  "location": {
3    "type": "Point",
4    "coordinates": [-73.9857, 40.7484]
5  }
6}

Array Structure Visualization

Common Array Patterns in JSON

Real-World API Patterns

Paginated List Response

GET /api/products — Paginated responsejson

1{
2  "items": [
3    { "id": "prod_01", "name": "Keyboard", "price": 79.99 },
4    { "id": "prod_02", "name": "Mouse", "price": 49.99 },
5    { "id": "prod_03", "name": "Monitor", "price": 399.99 }
6  ],
7  "total": 156,
8  "page": 1,
9  "pageSize": 3,
10  "hasMore": true
11}

GraphQL-Style Response

GraphQL edges patternjson

1{
2  "data": {
3    "posts": {
4      "edges": [
5        { "node": { "id": "1", "title": "Hello World" }, "cursor": "abc" },
6        { "node": { "id": "2", "title": "Second Post" }, "cursor": "def" }
7      ],
8      "pageInfo": {
9        "hasNextPage": true,
10        "endCursor": "def"
11      }
12    }
13  }
14}

Best Practices

Prefer homogeneous arrays

Keep all items the same type for predictable parsing.

Use empty arrays, not null

Return [] instead of null for empty collections.

Consistent object shapes

Every object in an array should have the same keys.

Wrap in an object

Use {"items": [...]} instead of bare arrays for extensibility.

Paginate large arrays

Never return unbounded arrays — add pagination metadata.

Avoid deep nesting

Flatten nested arrays where possible for easier querying.

Array vs Object: When to Use Which

Scenario	Use Array	Use Object
List of items	✓ [item1, item2]
Key-value lookup		✓ { "key": "value" }
Ordered data	✓ maintains order	⚠ order not guaranteed
Collection of entities	✓ array of objects
Configuration map		✓ named settings
Coordinates	✓ [lat, lng]	✓ { "lat": 40, "lng": -74 }

Try It Yourself

Build a JSON document representing a shopping cart with an array of items. Each item should have a name, quantity, price, and whether it’s a gift.

Try It Yourself

Add more items or modify the cart structure

Frequently Asked Questions

Can JSON arrays contain different types?

Yes. JSON arrays can mix strings, numbers, booleans, null, objects, and nested arrays. However, for type safety, most APIs use homogeneous arrays (same type for all items).

Are JSON arrays zero-indexed?

JSON itself does not define indexing — arrays are just ordered lists. However, when parsed in JavaScript, Python, Java, etc., the first element is at index 0.

Is there a maximum array size in JSON?

No spec limit exists. Practical limits depend on available memory and parser implementation. Very large arrays should be paginated or streamed.

Can a JSON document be just an array?

Yes. [1, 2, 3] is a valid JSON document with an array as the root value. However, wrapping in an object ({"items": [1,2,3]}) is preferred for extensibility.

How do I represent an empty list in JSON?

Use an empty array: []. This is preferred over null because it preserves the type information (the field is a list, it just has no items).

Try These Tools

JSON Pretty Print & Viewer

Visualize arrays and nested structures in a tree view

Open tool

JSON Validator

Catch trailing commas and bracket mismatches instantly

Open tool

Continue Learning

JSON Objects — Deep Dive

Learn about the other structural type in JSON

Working with Nested JSON

Flatten deeply nested arrays and objects

JSON Parsing & Serialization

Parse JSON arrays in JavaScript, Python, and more

Large JSON Files

Stream and process large JSON arrays efficiently