JSON object vs array: differences and which belongs at the root

Short answer

A JSON object groups name/value pairs inside {}. A JSON array preserves an ordered sequence of values inside []. Either can be the root of a valid JSON document, but they are not interchangeable: the receiving API or process determines which one matches its contract.

The structural difference

An object identifies each value by a name:

{
  "id": 42,
  "name": "Ada"
}

An array identifies elements by position:

[
  { "id": 42, "name": "Ada" },
  { "id": 43, "name": "Linus" }
]

Names in an object should be unique, and their visible order should not carry meaning. Array order is part of the sequence, and the same value may occur more than once.

Which structure should be at the root

Use an object when the document represents one entity or a response with named fields. Use an array when the root directly represents an ordered collection of equivalent items. If a response needs both a list and metadata, an object often expresses the contract more clearly:

{
  "results": [{ "id": 42 }, { "id": 43 }],
  "total": 2,
  "next": null
}

Do not wrap an array merely because an old library expects it, and do not remove a wrapper if the contract defines pagination, version, or status fields.

Valid JSON does not mean valid for an API

The JSON validator accepts {} and [], as well as other JSON values at the root. An API can still reject an array because it expected an object with a results property. That is a contract error, not a syntax error.

Check separately that the text parses, the root has the expected type, required properties exist, and each array item follows the agreed structure. A syntax validator cannot infer an undocumented application schema.

Consequences when converting to CSV

A table usually corresponds to an array of objects with comparable columns. The JSON to CSV converter also accepts one object as one row, but it does not arbitrarily turn arrays of numbers or mixed values into a table because there is no universal choice of columns.

Before converting, decide what one row represents. If objects contain different fields, decide whether missing columns should be empty or whether the input needs normalization first.

Frequent mistakes

• Reading data.name when data is an array.
• Treating object property order as an API contract.
• Confusing an empty object {} with an empty list [].
• Accepting a valid root without checking the expected schema.
• Flattening a heterogeneous array into a table and losing relationships.

RFC 8259 defines an object as a collection of name/value pairs and an array as an ordered sequence. Choose the root from the meaning of the data, not only from which form passes a parser.