JSON Arrays vs Objects: When to Use Each

Every JSON document is built from exactly two container types: arrays and objects. The syntax difference takes one sentence to explain. The modelling difference — knowing which one a given piece of data should be — is what separates an API that clients enjoy from one that generates support tickets.

This post is about the choice, not the syntax. If you need the underlying rules first, The Complete Guide to JSON covers the grammar and the six data types.

The mechanical difference

An array is an ordered list in square brackets. Elements are accessed by zero-based numeric index. Order is part of the data — ["a", "b"] and ["b", "a"] are different documents. Duplicates are fine.

An object is an unordered set of key-value pairs in curly braces. Values are accessed by key name. Keys must be unique in practice and must be double-quoted strings. Order is explicitly not part of the data, even though most parsers happen to preserve insertion order.

{
  "orderId": "A-8842",
  "status": "shipped",
  "items": [
    { "sku": "TSH-01", "qty": 2, "price": 19.99 },
    { "sku": "MUG-07", "qty": 1, "price": 8.50 }
  ],
  "shippedAt": "2026-08-07T09:14:00Z"
}

The order itself is an object: it has a fixed set of named fields that mean different things. items is an array: an arbitrary number of things of the same kind, where the sequence might matter for display. Each item is an object again. That pattern — objects for records, arrays for collections of records — covers most real payloads.

The decision rule

Ask two questions.

Are these things the same kind of thing? If yes, and there can be zero, one, or many of them, use an array. Products, log entries, users, tags, coordinates. If the fields mean different things — name, email, createdAt — use an object.

Does the order carry information? Arrays preserve it, objects do not. Search results ranked by relevance, steps in a workflow, timeseries points, a playlist — all arrays, because reordering them destroys meaning. A user's profile fields have no meaningful order, so an object is correct.

The failure mode you want to avoid is the numeric-keyed object:

{ "0": "apple", "1": "banana", "2": "cherry" }

This is a list wearing an object costume. It usually appears when a language serialises a sparse array or a PHP array, and it forces every consumer to sort string keys numerically to recover the order. If it is a list, make it an array.

When an object beats an array for a collection

There is one legitimate exception, and it is a good one: keying a collection by ID.

{
  "users": {
    "usr_8Kq2": { "name": "Ada", "role": "admin" },
    "usr_31Bd": { "name": "Grace", "role": "editor" }
  }
}

Compare with the array form, where each object carries its own id field. The keyed version wins when consumers mostly do lookups: users["usr_8Kq2"] is a direct hash access, whereas the array requires scanning or building an index client-side. It also makes duplicate IDs structurally impossible, and it produces cleaner diffs — adding a user changes one line rather than shifting indices.

The array wins when order matters, when you paginate or stream, when the collection is large enough that you want to process it incrementally, or when the same entity can legitimately appear twice. Normalised client-side stores (Redux, Apollo's cache) use keyed objects internally for exactly the lookup reason, and it is common to send an array over the wire and normalise on arrival.

Top-level shape: always an object

Returning a bare array from an API endpoint is a decision you cannot undo.

["a", "b", "c"]

That is valid JSON and it works fine — until you need to add a total count, a next-page cursor, a deprecation warning, or a partial-failure list. Any of those requires changing the top-level type, which breaks every existing client at once.

Wrap it instead:

{
  "data": [ { "id": 1 }, { "id": 2 } ],
  "page": { "next": "cur_9f2a", "total": 4821 }
}

Now metadata is additive. New optional fields at the top level are backwards compatible, because a client reading data ignores everything it does not know about. There was also a historical security argument — a top-level array was exploitable via JSON hijacking in older browsers — which no longer applies to modern engines but did shape the convention.

The same instinct applies to single values. An endpoint that returns 42 or "ok" is technically valid JSON under RFC 8259, and it is still worth wrapping in an object so the response has somewhere to grow.

Consistency beats cleverness

Two rules save more client-side code than any structural choice.

Never let a field change type. A field that is an object when there is one result and an array when there are several is the most user-hostile shape in API design. Consumers have to type-check on every access. Always return an array, even when it has zero or one element — an empty array is a perfectly good "nothing here".

Prefer explicit null to a missing key. If deletedAt is absent when the record is live and present when it is deleted, a consumer cannot distinguish "not deleted" from "the API did not send this field this time". Sending "deletedAt": null makes the contract self-describing. Omit keys only when absence is genuinely meaningful, such as a sparse patch payload.

Keep arrays homogeneous. [1, "two", null, {"three": 3}] is legal JSON and terrible data. Consumers should be able to write one loop body, not a type switch.

Nesting: how deep is too deep

The spec puts no limit on nesting. Parsers do, usually a few hundred to a few thousand levels, to avoid blowing the stack — and deeply nested untrusted input is a real denial-of-service vector, which is why you should cap depth when parsing anything from outside your system.

The practical limit arrives much earlier. Past three or four levels, a payload becomes hard to reason about, hard to type, and expensive to traverse defensively — data.user.profile.settings.notifications.email needs a null check at every step. When you hit that, the usual fixes are to flatten related fields into the parent, split the response into separate endpoints, or normalise into ID-keyed collections and let the client join.

Reading deep structures in raw text does not scale. A JSON Tree Viewer renders the document as a collapsible tree so you can fold branches you do not care about, and it makes array-versus-object mistakes immediately obvious — a numeric-keyed object looks visibly different from a real array. Pair it with a JSON Formatter when you just need indentation, and both run entirely in your browser, so you can inspect a production response containing real customer data without uploading it anywhere.

Structure decides what you can do next

The array-versus-object choice has downstream consequences that are easy to miss when you are designing a payload.

Querying. Extracting data with JSONPath is straightforward over arrays of uniform objects — $.items[*].sku gets you every SKU in one expression. Over an ID-keyed object you need a wildcard on the keys instead, and filters get more awkward. If a collection is going to be queried and filtered a lot, an array of uniform objects is the friendlier shape; JSONPath queries covers the syntax, and a JSONPath Query Tester lets you check an expression against your own document before you write code around it.

Tabular export. An array of flat objects converts to CSV or a spreadsheet almost mechanically — one row per element, one column per key. Nested objects and arrays inside those elements are where conversion gets lossy and you have to choose a flattening strategy, which is the whole subject of converting JSON to CSV without losing nested data.

If you know a payload will end up in a spreadsheet or a data warehouse, an array of flat, uniform objects at the top of the data field is the shape that makes everything downstream easy. Design for the consumer, not for whatever your ORM happened to serialise.