Understanding JSON objects, arrays and nested data

Two containers, unlimited combinations

JSON gives you two collection types and four scalar types. Every JSON document — no matter how complex — is a tree of these:

• Objects ({}): unordered key/value pairs, keys must be strings.
• Arrays ([]): ordered lists of any values.
• Scalars: strings, numbers, booleans (true/false), and null.

Model those well and downstream code is easy. Model them poorly and every consumer suffers.

Objects: named fields

Reach for an object when each value has a distinct role. Keys are always double-quoted strings, order isn't semantic, and values can be any JSON type — including other objects or arrays.

Arrays: ordered lists

Reach for an array when position matters or elements are homogeneous. Order is semantic — preserve it. Empty arrays are valid.

Nested data

Real APIs mix both freely. Two nesting rules of thumb:

1. Don't nest for the sake of nesting. Every level costs client ergonomics. 2. Group data that always travels together. address as an object beats five loose address_* fields.

Common modeling mistakes

• Object with numeric string keys ({"0": ..., "1": ...}) — that's an array wearing an object costume.
• Array of key/value pairs when a map fits — if lookups are always by key, an object beats it.
• Wrapping single values in one-element arrays — unless the field is genuinely a list, drop the wrapper.

Exploring nested JSON

Deep documents are hard to read as text. Our Tree Viewer collapses branches, shows types, and lets you copy the JSON path ($.orders[0].items[1]) of any node.

Converting between shapes

• Object-of-arrays ↔ array-of-objects: JSON to CSV for spreadsheets.
• Nested JSON → flat XML: JSON to XML.
• Schema-first design: sketch in YAML and convert to JSON.

Related reading

• What is JSON?
• JSON best practices
• How APIs use JSON