JSON Arrays Explained

A JSON array is an ordered sequence of zero or more values enclosed in square brackets []. Elements are separated by commas, and each element can be any valid JSON type — string, number, boolean, null, object, or another array. Arrays preserve insertion order, making them suitable for lists, sequences, and collections where position matters.

Basic syntax:

["apple", "banana", "cherry"]
[1, 2, 3, 4, 5]
[true, false, true]
[{"id": 1, "name": "Alice"}, {"id": 2, "name": "Bob"}]

Mixed-type arrays:

JSON allows arrays to contain elements of different types:

[1, "hello", true, null, {"key": "value"}, [1, 2, 3]]

While this is syntactically valid, mixing types within a single array is generally discouraged in practice because it makes the data harder to process with statically typed languages and harder to validate with JSON Schema. Most well-designed APIs use homogeneous arrays where all elements share the same structure.

Empty arrays vs. null:

An empty array [] means "there is a collection, but it currently has no items." This is semantically different from null, which means "there is no collection at all." For example, {"tags": []} means the item has been processed but no tags were applied, while {"tags": null} might mean tags have not been evaluated yet. Choose between the two deliberately and document your convention.

Nested arrays:

Arrays can contain other arrays, creating multi-dimensional structures:

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

This pattern is useful for matrices, grid data, or grouped collections. However, deeply nested arrays can become difficult to navigate and parse. If you find yourself nesting more than 2-3 levels deep, consider restructuring with named objects instead.

Common mistakes developers make:

A frequent mistake is adding a trailing comma after the last element: [1, 2, 3,]. This is valid in JavaScript but invalid in JSON. Another mistake is confusing arrays with objects when modeling data — use arrays for ordered, indexed collections and objects for named, keyed properties. Developers also sometimes use arrays when order does not matter, which can cause issues if the consumer relies on the implicit ordering. Additionally, very large arrays (tens of thousands of elements) can cause performance issues in some parsers and should be paginated in API responses.

Best practices:

Keep array elements homogeneous (same type and structure). Use descriptive parent keys ("items", "results", "users") rather than generic names. For large collections, implement pagination rather than returning everything in a single array. Validate array contents with JSON Schema using the items keyword to enforce element types.