Advanced JSON Structures and Design Patterns

Nested vs Flat Structures

Balanced Approach (Recommended)

{
  "id": 1,
  "name": "John",
  "address": {
    "street": "123 Main St",
    "city": "NYC"
  },
  "contact": {
    "email": "john@example.com",
    "phone": "+1234567890"
  }
}

Avoid excessive nesting (>3-4 levels).

Normalization

Denormalized (Embedded)

{
  "orders": [
    {
      "id": 1,
      "customer": {
        "id": 101,
        "name": "Alice"
      }
    }
  ]
}

Use when data is read frequently, updated rarely.

Normalized (References)

{
  "orders": [
    { "id": 1, "customerId": 101 }
  ],
  "customers": {
    "101": { "id": 101, "name": "Alice" }
  }
}

Use when data changes frequently.

API Response Patterns

Envelope Pattern

{
  "success": true,
  "data": { ... },
  "meta": {
    "total": 100,
    "page": 1
  }
}

Error Response

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid input",
    "details": [
      {
        "field": "email",
        "message": "Invalid format"
      }
    ]
  }
}

Pagination Patterns

Offset-Based

{
  "data": [...],
  "pagination": {
    "page": 2,
    "perPage": 20,
    "total": 156
  }
}

Cursor-Based

{
  "data": [...],
  "pagination": {
    "cursor": "eyJpZCI6MTAwfQ==",
    "hasMore": true
  }
}

Polymorphic Data

Discriminator Pattern

{
  "notifications": [
    {
      "type": "email",
      "recipient": "user@example.com",
      "subject": "Hello"
    },
    {
      "type": "sms",
      "phoneNumber": "+1234567890",
      "message": "Your code is 123456"
    }
  ]
}

Versioning

{
  "version": "2.0",
  "data": {
    "id": 1,
    "fullName": "John Doe"
  }
}

Event/Message Patterns

{
  "eventId": "evt_abc123",
  "eventType": "user.created",
  "timestamp": "2024-01-15T10:30:00Z",
  "version": "1.0",
  "data": {
    "userId": 123
  }
}

Best Practices

Naming Conventions

{
  "userId": 1,       // camelCase (JavaScript)
  "user_id": 1       // snake_case (Python)
}

Be consistent!

Date/Time

{
  "createdAt": "2024-01-15T10:30:00Z"  // ISO 8601
}

Money/Currency

{
  "price": {
    "amount": 2999,    // Cents
    "currency": "USD"
  }
}

HATEOAS Pattern

{
  "id": 1,
  "name": "Product",
  "links": {
    "self": "/api/products/1",
    "update": "/api/products/1",
    "delete": "/api/products/1"
  }
}

Bulk Operations

{
  "operations": [
    { "op": "create", "data": {...} },
    { "op": "update", "id": 1, "data": {...} },
    { "op": "delete", "id": 2 }
  ]
}

Sparse Fieldsets

GET /api/users?fields=id,name,email

{
  "data": [
    { "id": 1, "name": "Alice", "email": "alice@example.com" }
  ]
}

Conclusion

Good JSON structure design:

Balance nesting appropriately

Normalize based on read/write patterns

Use consistent patterns

Version your data

Follow naming conventions

Well-structured JSON makes APIs easier to use and maintain!