Skip to main content

ADR-008 - Asset Kind Enumeration

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

Context​

The Asset type carries an asset_kind field that classifies the semantic type of a domain entity. Without explicit enumeration, implementers may use arbitrary strings, leading to inconsistent classification, failed validation, and inability to query assets by type reliably. A controlled vocabulary ensures all messages use the same classification scheme and enables downstream systems to apply type-specific logic with confidence.

Decision​

Constrain asset_kind to a finite, versioned enumeration. The initial vocabulary includes three values: PERMIT, ANCHOR, and PROJECT. These values represent the core natural resource permitting domain entities in PIES. All other domain entities are deferred to future decisions.

Rationale​

Establishing a minimal, focused enumeration reduces specification complexity and allows the core vocabulary to stabilize before expansion. PERMIT, ANCHOR, and PROJECT represent the essential entity types needed to model primary permitting workflows. Future additions will be governed through subsequent ADRs to ensure deliberate expansion rather than ad-hoc proliferation.

Assumptions​

  • PERMIT, ANCHOR, and PROJECT adequately represent the initial PIES domain scope.
  • Additional asset_kind values will be added through formal ADR or governance decisions, not ad-hoc implementation choices.
  • Validators and API implementations will enforce strict adherence to the enumeration.
  • asset_kind is case-sensitive and always uppercase.

Options Considered​

  • No enumeration (open vocabulary): Implementers choose any string. Rejected due to validation risk and inability to ensure consistency across agencies and does not comply with HL7 style design.
  • Minimal initial set (chosen): Start with PERMIT, ANCHOR, PROJECT. Allows stable foundation and defers non-essential types to later decisions.
  • Comprehensive enumeration: Define all possible asset kinds upfront. Rejected due to complexity and uncertainty about future domain scope.

Consequences​

Positive​

  • Validation is deterministic and consistent across all implementations.
  • Schema and code generation tools can rely on a stable enumeration.
  • Query engines can optimize for known asset types.
  • Specification remains focused and easier to review and govern.

Negative​

  • Implementers cannot represent new entity types until the enumeration is expanded via formal decision.
  • Transition period may see pressure to expand the vocabulary before proper governance review.
  • Code tightly couples to the enumeration; adding new kinds may require schema versioning.

References​

  • ADR-007 establishes asset_kind as the field name.
  • ADR-006 defines the structure that carries asset_kind.