JSON Array vs Object – When to Use Each

JSON has two composite data types: arrays ([]) and objects ({}). Choosing the right one for each part of your data structure makes your API more predictable and easier to consume.

What a JSON array is

A JSON array is an ordered list of values enclosed in square brackets. Values can be of any JSON type (strings, numbers, booleans, null, objects, or other arrays), but in practice arrays usually contain items of the same type.

[
  "admin",
  "editor",
  "viewer"
]

// Array of objects — the most common API pattern:
[
  { "id": 1, "name": "Alice", "role": "admin" },
  { "id": 2, "name": "Bob",   "role": "editor" }
]

Arrays are accessed by integer index (0-based). The order of elements is preserved and significant.

What a JSON object is

A JSON object is an unordered set of key-value pairs enclosed in curly braces. Keys must be strings (double-quoted). Values can be any JSON type.

{
  "id": 42,
  "name": "Alice",
  "email": "alice@example.com",
  "active": true,
  "roles": ["admin", "editor"],
  "address": {
    "city": "London",
    "country": "UK"
  }
}

Object values are accessed by key name. Order is technically not guaranteed by the JSON spec, though most parsers preserve insertion order.

When to use an array

• Ordered collections: A list of search results, paginated items, log entries where sequence matters
• Collections of same-type items: A list of user objects, a list of product IDs, a list of error messages
• When you iterate: If you're going to forEach, map, or filter over it, it should be an array
• When count matters: Arrays have a length property; objects don't without extra work

When to use an object

• Named properties: An entity with distinct fields (user, product, config settings)
• Key-based lookup: A map from user ID to user data, a dictionary of error codes to messages
• Configuration: Settings where each key has a specific meaning (host, port, timeout)
• API responses with metadata: A top-level object wrapping a data array and a pagination object

The numbered-key anti-pattern

A common mistake is using an object with numbered string keys to represent a list:

// Anti-pattern — don't do this
{
  "0": { "id": 1, "name": "Alice" },
  "1": { "id": 2, "name": "Bob" },
  "2": { "id": 3, "name": "Carol" }
}

// Correct — use an array
[
  { "id": 1, "name": "Alice" },
  { "id": 2, "name": "Bob" },
  { "id": 3, "name": "Carol" }
]

The numbered-key version forces every consumer to convert it to an array before they can iterate, count items, or use array methods. There's no good reason to use this pattern — it's almost always a serialization bug from code that converted a zero-indexed array to an object.

Array of objects — the most common API pattern

Most REST API responses use the array-of-objects pattern for collections. Each object in the array represents one record, and every object has the same set of keys:

{
  "users": [
    { "id": 1, "name": "Alice", "email": "alice@example.com", "active": true },
    { "id": 2, "name": "Bob",   "email": "bob@example.com",   "active": false },
    { "id": 3, "name": "Carol", "email": "carol@example.com", "active": true }
  ],
  "total": 3
}

The outer structure is an object (it has named fields: users and total). The users value is an array of objects. This is the standard pattern that every HTTP client library knows how to handle.

Object as a lookup map

Objects are ideal when you need to look up items by a unique key — for example, a map of country codes to country names, or error codes to messages:

{
  "US": "United States",
  "GB": "United Kingdom",
  "DE": "Germany",
  "JP": "Japan"
}

// Error code map:
{
  "E001": "Invalid input format",
  "E002": "Authentication failed",
  "E003": "Resource not found"
}

Object lookup by key is O(1). Searching an array of objects for a matching key is O(n). When your primary access pattern is "give me the item with this ID", an object map is more efficient than an array.

Inspect your JSON structure

Use the JSON Formatter tree view to visually inspect the structure of any JSON document. The tree makes it immediately clear which parts are arrays (shown with indices) and which are objects (shown with key names), so you can spot accidentally numbered-key objects or other structural issues at a glance.