Skip to main content

ADR-011 - Payload vs Containment Separation

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

Context​

Graph-based data models risk conflating two distinct concerns: the definition of nodes (entities with properties) and the definition of edges (relationships between entities). In PIES, this manifests as a temptation to embed containment arrays or relationship metadata directly within asset payloads. This coupling increases payload size, creates circular dependencies, and makes it ambiguous whether updates to a node trigger topology changes.

Decision​

Enforce strict separation between payload content and containment operations. RECORD messages shall carry pure node property state and never include arrays of related assets or containment metadata.

GROUP and LINKAGE messages represent invertible perspectives on relationships:

  • GROUP: Contains an asset_set array of co-related assets bound to a top-level asset. All attributes (top-level asset reference, asset_set, and all derived properties) are mandatory.
  • LINKAGE: Contains an asset_group attribute identifying the binding point, plus references to linked assets. The main asset, linked asset, and asset_group are all mandatory and provider-declared.

These two structures are isometric and bijective. Each can be mathematically derived from the other without data loss.

Rationale​

Separating node definition (RECORD) from topology operations (GROUP/LINKAGE) creates a clear, unambiguous contract: RECORD is "what the asset is", while GROUP/LINKAGE is "what this asset relates to or contains." This separation prevents payload bloat, eliminates circular definitions, and allows independent evolution of node schemas and relationship semantics. Asset consumers can reason about each message kind's responsibility without implicit topology side effects.

The invertible design of GROUP and LINKAGE (per ADR-004) means implementers and consumers can query relationships from either perspective without redundant storage or transformation complexity. Viewing the relation as a collection of co-related assets (GROUP) or as a set of pairwise linkages bound to a common point (LINKAGE) should be isometrically equivalent.

Assumptions​

  • All node property state flows through RECORD messages; GROUP and LINKAGE messages do not carry node properties.
  • In GROUP messages: the top-level asset, asset_set array, and all structural attributes are mandatory.
  • In LINKAGE messages: the main asset, linked asset, and asset_group binding point are all mandatory and provider-declared.
  • Both GROUP and LINKAGE are complete, self-contained messages; neither should be optional or omitted for correctness.
  • GROUP and LINKAGE messages are fully invertible per ADR-004 (isometric, bijective design).

Options Considered​

  • Embedded containment: Node payloads include arrays of related assets. Simpler for single-message operations but creates bloat, circular references, and ambiguity. Rejected.
  • Payload-only with secondary metadata field: RECORD carries a _relations or similar field. Still couples payload to topology. Rejected.
  • Strict separation with distinct GROUP/LINKAGE structures (chosen): RECORD for nodes, GROUP with asset_set for co-related collections, LINKAGE with asset_group for pairwise bindings. Invertible design maintains mathematical equivalence while allowing consumers to query from either perspective.

Consequences​

Positive​

  • Clear responsibility model: RECORD defines the entity; GROUP/LINKAGE define the relationships.
  • Payloads remain lean and focused on node properties.
  • Topology updates are explicit and traceable (separate messages).
  • Node definitions can evolve independently of relationship semantics.
  • No circular dependencies or ambiguous update semantics.

Negative​

  • Representing a complete entity with all its relationships requires multiple message types.
  • Queries involving relationships must understand and compose multiple message kinds.
  • Providers must carefully declare all required fields (main asset, linked assets, asset_group in LINKAGE, while top-level asset and asset_set in GROUP).
  • Initial ingestion of an entity may require several message submissions rather than one.
  • The invertible relationship between GROUP and LINKAGE adds conceptual complexity for implementers unfamiliar with isometric data design.

References​

  • ADR-004 establishes isometric Group/Linkage duality.
  • ADR-005 defines RECORD, GROUP, and LINKAGE as distinct message kinds.
  • ADR-006 defines the Asset structure elements used in asset_set.