Objects and Arrays

Most real JSON documents combine objects and arrays to represent entities and collections. Designing clear shapes makes APIs and configs easier to consume.

Objects as records

An object often models one thing—a user, an order, a settings block:

{
  "userId": "u_42",
  "email": "[email protected]",
  "preferences": {
    "theme": "dark",
    "notifications": true
  }
}

Nested objects group related fields without flattening names like preferences_theme.

Arrays as lists

Arrays model ordered collections: tags, line items, search results:

{
  "tags": ["json", "api", "tutorial"],
  "items": [
    { "sku": "A1", "qty": 2 },
    { "sku": "B3", "qty": 1 }
  ]
}

Key naming conventions

JSON keys are case-sensitive. Common styles:

• camelCase — firstName (typical in JavaScript APIs)
• snake_case — first_name (common in Python/Ruby backends)
• kebab-case — rare inside keys because - is minus; often avoided

Pick one style per API and stay consistent.

Empty structures

Both are valid and mean different things:

{ "list": [] }
{ "list": {} }

[] is an empty array; {} is an empty object. Do not interchange them unless your schema allows both.

Depth and readability

Deep nesting (a.b.c.d.e) mirrors data but hurts readability. Many teams flatten with clear key names or paginate large arrays. When reading unfamiliar JSON, start at the top level, expand one object or array at a time, and note repeating patterns—that is how most API payloads are designed.