List vs Object Document Patterns

APIs and config files choose different top-level shapes. Recognizing patterns helps you read documentation faster and design consistent endpoints.

Root array

Valid JSON can be an array at the top level:

[
  {"id": 1, "name": "Alpha"},
  {"id": 2, "name": "Beta"}
]

Common for small static lists or batch exports. Many REST APIs prefer an object wrapper instead so metadata has a home.

Envelope object

Wrap list data plus metadata:

{
  "data": [
    {"id": 1, "name": "Alpha"}
  ],
  "meta": { "total": 42, "page": 1 }
}

Names vary (data, items, results, records). The idea is the same: payload + context in one object.

Pagination fields

Repeated patterns:

{
  "items": [],
  "nextCursor": "abc123",
  "hasMore": true
}

or offset style with page, pageSize, totalCount. Clients should not assume field names—read each API’s spec.

Object-only documents

Configuration is usually a single object:

{
  "theme": "dark",
  "features": { "beta": false }
}

No array at root; nested objects group settings.

Choosing a shape

Prefer object root when	Root array OK when
You need pagination or errors alongside data	Fixed small catalog
Versioning or links objects appear	Internal tools, fixtures
Multiple resource types share one endpoint	Simple public data feeds

Consistency within your own API matters more than copying another product’s field names.