Skip to main content

ADR-010 - Schema Composition Pattern for Grouping Assets

  • Status: Accepted
  • Decision Date: 2026-07-27
  • Deciders: PIES Design Team
  • Category: Data Model, Schema

Context​

Grouping assets requires common baseline structural properties. Without a formalized composition pattern, these baseline attributes risk being duplicated across multiple asset_kind definitions, creating maintenance burden and semantic inconsistency. A centralized structural resource type ensures consistent container behavior while avoiding bloat in individual asset definitions.

Decision​

Define a shared abstract Collection data resource type which will be embedded within a JSON Schema Draft-07 allOf composition. Grouping asset kinds inherit this resource type to enforce common baseline properties without requiring a secondary asset_type discriminator field in the payload. Each grouping asset kind composes its specific properties with the Collection resource type.

Rationale​

Schema composition via allOf centralizes common resource attributes into a single, versioned schema. This approach decouples baseline structural requirements from asset-specific properties, reduces duplication, and simplifies schema maintenance. The abstract Collection resource type acts as a contract that all grouping assets must satisfy, while allowing asset-specific extensions without modifying the shared baseline.

Assumptions​

  • JSON Schema Draft-07 allOf semantics are suitable for this composition pattern.
  • Collection resource types omit additionalProperties: false to avoid isolated evaluation conflicts in composed schemas.
  • All grouping asset kinds share a common set of baseline structural requirements.
  • The Collection resource type remains stable; changes to it constitute breaking schema changes.

Options Considered​

  • No composition, duplicate properties: Each grouping asset kind defines its own baseline attributes. Simpler initially, but creates maintenance burden and inconsistency. Rejected.
  • Separate asset_type discriminator field: Grouping assets carry an additional field to indicate container semantics. Clearer but adds payload complexity and creates a secondary classification system. Rejected.
  • Composed Collection resource type (chosen): Single abstract resource type via allOf. Centralizes baseline requirements, simplifies schema inheritance, reduces duplication.

Consequences​

Positive​

  • Common container attributes are defined once and inherited consistently across grouping asset kinds.
  • Schema maintenance is simplified; changes to Collection propagate automatically.
  • Asset-specific properties remain isolated and easy to evolve independently.
  • Payload remains flat; no secondary discriminator field adds clarity.

Negative​

  • Schema inheritance via allOf increases cognitive complexity for schema authors and consumers.
  • Composite schemas require careful tooling and documentation to remain maintainable.
  • JSON Schema Draft-07 composition semantics force all schema definitions to remain open-ended.
  • Changes to the Collection baseline become breaking changes affecting all inheriting asset kinds.

References​

  • ADR-008 defines which asset kinds are grouping containers.
  • ADR-007 establishes asset_kind as the asset classification field.