Skip to main content

ADR-001 - Transaction Identifier Strategy

  • Status: Accepted
  • Decision Date: 2025-04-01
  • Deciders: PIES Design Team
  • Category: Data Model, Messaging

Context​

PIES messages require unique transaction identifiers to support asynchronous, distributed message processing. While UUIDv4 provides strong uniqueness guarantees, it sacrifices sortability and carries no inherent temporal semantics. Additionally, the abbreviated field name tx_id creates ambiguity when reading schemas and implementation code. As the platform matures, temporal ordering and clarity in field naming become critical for operational observability, querying, and integration with audit systems that expect monotonically sortable identifiers.

Decision​

Adopt UUIDv7 (as specified in RFC 9562) for all transaction identifiers in PIES messages. Name the field transaction_id across all message contracts, schemas, and implementation documentation. The transaction_id field shall be mandatory on all message kinds and contain a valid UUIDv7 string in canonical form.

Rationale​

UUIDv7 combines the temporal properties of Unix timestamps with cryptographic uniqueness, eliminating the need for separate timestamp fields and enabling direct sorting by creation order across distributed systems. This reduces complexity in database indexes, log aggregation, and audit trails. Naming to transaction_id improves code readability and self-documentation, particularly for new implementers unfamiliar with abbreviated field conventions. The explicit naming aligns with PIES design principles favoring clarity over brevity.

Assumptions​

  • All providers can generate UUIDv7 identifiers using standard libraries.
  • Database and logging systems can store and index UUIDv7 values efficiently.
  • Distributed clocks across all provider systems are reasonably synchronized (clock skew tolerance is built into UUIDv7 design).
  • The canonical UUIDv7 string representation (eight hex digits, hyphen, four hex digits, hyphen, four hex digits, hyphen, four hex digits, hyphen, twelve hex digits) is acceptable as the message format.

Options Considered​

  • UUIDv4: Strong uniqueness, no temporal ordering. Sorting requires separate timestamp fields and becomes expensive at scale. Rejected due to operational complexity and loss of inherent temporal metadata.
  • Unix timestamp as primary identifier: Provides ordering and temporal semantics. Collisions under high throughput require secondary uniqueness mechanisms. Rejected as insufficient for distributed transactionality.
  • ULID: Sortable, compressible (128-bit), human-readable format. Provides temporal ordering and uniqueness. Rejected due to narrower adoption across ecosystems and libraries compared to UUIDv7, which has broader RFC standardization and implementation support across agencies and platforms.
  • UUIDv7 with explicit transaction_id field (chosen): Sortable, temporally aware, globally unique. Canonical naming removes ambiguity. Integrates cleanly with audit systems and observability platforms.

Consequences​

Positive​

  • Transaction identifiers are naturally sortable by creation time without secondary timestamp fields.
  • Database indexes on transaction_id provide both uniqueness and temporal locality.
  • UUIDv7 structure embeds temporal semantics, enabling efficient log aggregation and retention queries.
  • Explicit field name transaction_id reduces implementation errors and improves code maintainability.
  • Aligns with industry best practices for distributed system identifiers (e.g., microservices, event sourcing).

Negative​

  • Breaking change to all message schemas. Implementations referencing tx_id must migrate to accept transaction_id instead.
  • Providers must implement UUIDv7 generation. Non-standard libraries may lack support or introduce compatibility risks.
  • Clock synchronization across distributed systems becomes a runtime dependency. Severe clock skew can lead to non-monotonic ordering.
  • The string representation of UUIDv7 is 36 characters, slightly increasing payload size compared to compact binary formats.

References​

None at this time. Future ADRs on message versioning or temporal queries may reference this decision.