Skip to main content

ADR-005 - Top-Level Message Kinds as Contracts

  • Status: Accepted
  • Decision Date: 2026-03-24
  • Deciders: PIES Design Team
  • Category: Specification, Messaging, Ontology

Context​

PIES currently treats all objects as Records, but the evolving data model (per ADR-004) recognizes that Groups (collections of related assets), Linkages (relationships between assets), and Records themselves are conceptually distinct message kinds with different semantics and operations. Additionally, all messages are rooted to Assets (the resources they reference or describe). Without explicitly defining these message kinds and their relationship to Assets, the specification becomes ambiguous about what types of messages are valid, how they should be validated, and what operations consumers can expect to perform on each type.

Decision​

Define Records, Groups, and Linkages as distinct top-level message kinds within PIES. Each message kind is rooted to one or more Assets (per ADR-006), which anchor and identify the resources being described or related. Each message kind carries its own API contract specifying how systems should submit, retrieve, validate, and query that message type.

Rationale​

Making message kinds explicit at the specification level ensures that API implementers, validators, and consumers share a common understanding of what types of messages are in scope. Each message kind may have different validation rules, required fields, and operational semantics. By treating them as distinct contracts rather than variants of a single type, we enable clear, independent evolution of each type's specification and reduce the cognitive burden on implementers who must otherwise infer the intended semantics.

Assumptions​

  • The three message kinds (Records, Groups, Linkages) are sufficient to represent the PIES domain.
  • Each message kind has semantically distinct operations or constraints that justify separate treatment.
  • Assets provide a consistent rooting mechanism across all message kinds.
  • Validators and API implementations can reasonably accept a contract where different message kinds are handled distinctly.

Options Considered​

  • Single generic message type: Define everything as a Record with a discriminator field.
    • Simpler specification but conflates semantics and creates ambiguity about which operations apply to which type.
  • Distinct message kinds (chosen): Three separate contracts (Records, Groups, Linkages), each rooted to Assets, with clear semantics.
    • More documentation but clearer contracts and tighter validation.
  • Hierarchical type system: Base Message type with Record, Group, Linkage as subtypes.
    • Adds abstraction but may obscure the distinct operational semantics.

Consequences​

Positive​

  • Specification clearly defines what types of messages are valid and supported.
  • Validators can enforce type-specific rules and schemas based on message kind.
  • API implementers understand that different message kinds may require different handling and rooting to Assets.
  • Clear separation of concerns makes evolution of each message type independent.

Negative​

  • Specification becomes more complex with three separate message contracts instead of one.
  • Consumers must understand the distinctions between message kinds and how they relate to Assets.
  • Query and bulk operation semantics across multiple kinds require additional specification work.

References​

  • ADR-004 establishes the conceptual need for Groups and Linkages as top levels.
  • PADS-646 Outcomes discussion on message types and API contracts.