Skip to main content

ADR-007 - Record to Asset Naming Alignment

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

Context​

The Asset type (defined in ADR-006) contains fields named record_id and record_kind, preserving terminology from an earlier iteration where all identifiable entities were generically called "records." As the model evolved, this naming created semantic confusion: the term "record" conflates the message envelope (kind: RECORD, GROUP, LINKAGE) with the domain entity being described (an asset like a PERMIT or PROJECT). This overlap makes it harder for implementers to distinguish between message routing concerns and asset classification concerns.

Decision​

Rename record_id to asset_id and record_kind to asset_kind across all message types, the Asset type definition, and message contracts. The asset_id field uniquely identifies a domain asset; the asset_kind field classifies what type of asset it is (semantic classification). Message kind remains the communication discriminator (RECORD, GROUP, LINKAGE).

Rationale​

Aligning field names with the conceptual model reduces cognitive overhead for implementers and eliminates the ambiguity of "record" as a term. The distinction becomes clear: kind describes the message operation type (how to route/process), while asset_kind describes the domain entity type (what the asset represents). This separation of concerns improves specification clarity and reduces implementation errors.

Assumptions​

  • All existing consumer code can tolerate a breaking schema change with versioning.
  • The rename affects only field names, not the structural composition or validation rules.
  • asset_id and asset_kind terminology will be adopted consistently across all specifications and implementation guides.

Options Considered​

  • Preserve record_id and record_kind: Maintain backward compatibility but perpetuate semantic confusion. Rejected due to ongoing cognitive burden.
  • Introduce aliases (record_id and asset_id as synonyms): Avoids breaking change but creates ambiguity and maintenance burden. Rejected.
  • Rename to asset_id and asset_kind (chosen): Clean break with clear semantics. Requires schema versioning but eliminates long-term confusion.

Consequences​

Positive​

  • Terminology aligns with the conceptual model where assets are first-class entities.
  • Clear separation between message routing (kind) and asset classification (asset_kind).
  • Reduces implementer confusion and potential bugs from conflating the two concerns.

Negative​

  • Breaking change to schema contracts; requires significant change management coordination and consumer migration.
  • All documentation, examples, and implementation code referencing record_id and record_kind must be updated.
  • Transition period where both old and new terminology may appear in migration guides.

References​

  • ADR-006 defines the structure being renamed.
  • ADR-005 establishes kind as the message envelope discriminator.