Composable Models

Composable models build complex data structures from discrete, optional sub-objects rather than requiring rigid, fully-populated schemas.

Core Concept

Instead of a flat structure with many nullable fields, composable models group related fields into sub-objects that can be included or omitted based on what's relevant:

{
  // Core fields (always present)
  "id": "123",
  "createdAt": "2025-06-08T14:22:00Z",
  
  // Include only relevant sub-objects
  "address": { ... },      // Include if street address exists
  "coordinates": { ... },  // Include if GPS coordinates exist
  "fiberAccessDetails": {  // Include if fiber infrastructure exists
    "serviceability": { ... } // Fiber service availability
  }
}

Benefits

• Flexibility - Include only data relevant to each resource
• Clarity - Each sub-object has a single, clear purpose
• Extensibility - Add new sub-objects without breaking existing implementations
• Efficiency - Reduce payload size by omitting irrelevant data

Example: OAF-100 Location Model

The Location model demonstrates effective use of composable design:

Always Required

• Core fields: id, createdAt, updatedAt
• Geography object: country, region, locality, postalCode

Conditionally Required

At least one of:

• address object - Street-level location details
• coordinates object - GPS positioning

Optional Extensions

• fiberAccessDetails - Fiber infrastructure details including serviceability
• customFields - Operator-specific data

This design allows appropriate representation whether the location is an urban street address, rural GPS coordinates, or a combination of both.

Best Practices

1. Group related fields - Don't scatter related data across the root object
2. Make sub-objects independent - Avoid dependencies between optional objects
3. Document requirements clearly - Specify which combinations are valid
4. Keep objects focused - Each sub-object should serve one purpose