Understanding JSON Objects and Arrays

Updated · 6 min read · MetaSol Technologies

Objects and arrays are the two building blocks that give JSON its structure. Once you can read them confidently, any JSON document becomes a tree you can navigate.

Objects: named fields

An object is wrapped in braces and holds name: value pairs separated by commas.

{ "id": 7, "name": "Keyboard", "inStock": true }
  • Names (keys) are strings in double quotes.
  • Order has no meaning: {"a":1,"b":2} equals {"b":2,"a":1}.
  • Keys should be unique within one object.

Use objects for one thing with named properties: a user, an order, a settings block.

Arrays: ordered lists

An array is wrapped in brackets and holds values separated by commas.

["red", "green", "blue"]
  • Order matters: [1,2] is not [2,1].
  • Items can be any type, and types can be mixed (though mixing usually makes data harder to use).

Use arrays for many things of the same kind: line items, tags, search results.

Nesting

Real data combines the two:

{
  "order": "A-1042",
  "customer": { "name": "Amara", "email": "[email protected]" },
  "items": [
    { "sku": "KB-221", "qty": 1 },
    { "sku": "MS-014", "qty": 2 }
  ]
}

Read it as a tree: the root object has three branches, items is a list, and each item is an object of its own. The JSON Tree Viewer draws exactly this tree.

Addressing values with paths

To point at one value, write a path from the root, $:

Path Value
$.order "A-1042"
$.customer.email "[email protected]"
$.items[1].sku "MS-014"
$.items[*].qty 1, 2

This is JSONPath notation. Array indexes start at 0. Try queries live in the JSON Path Explorer.

Modelling tips

  • Prefer arrays of objects to parallel arrays. [{"name":"a","age":1}] is safer than {"names":["a"],"ages":[1]}, because the two lists can't drift out of sync.
  • Don't encode data in keys. {"user_17": {...}} is hard to query. Use [{"id": 17, ...}] instead.
  • Keep empty values explicit and consistent. Choose between omitting a field, null and [], and document the choice.
  • Avoid deep nesting when a flatter shape works. Deep trees are harder to read, query and convert to tables.