What is the difference between a JSON array and a JSON object?

A JSON array ([ ]) is an ordered list of values. Values are accessed by their integer index (0, 1, 2...). A JSON object ({ }) is an unordered set of key-value pairs. Values are accessed by their string key. Use arrays when order matters or when you have a collection of similar items. Use objects when items have named properties and you need to look up values by name.

Can a JSON array contain objects?

Yes. An array of objects is the most common pattern in API responses — for example, a list of users where each user is an object. This pattern looks like: [{"id": 1, "name": "Alice"}, {"id": 2, "name": "Bob"}]. Each element of the array is an object with consistent keys.

Why is using numbered object keys (like 0, 1, 2) an anti-pattern?

Using {"0": ..., "1": ..., "2": ...} instead of an array loses all array semantics: no length property, no forEach/map/filter iteration, no guaranteed ordering, and no standard way to append items. It forces clients to write extra code to work with what should be a simple list. Always use an array [] for ordered collections.

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.