Skip to main content

ADR-003 - Event Date and DateTime Representation

  • Status: Accepted
  • Decision Date: 2025-05-15
  • Deciders: PIES Design Team
  • Category: Data Model, Specification

Context​

PIES events must represent temporal information (process start dates, decision dates, completion times) across diverse use cases spanning reporting, auditing, and operational workflows. Without a standardized temporal representation, implementations risk incompatibility, timezone confusion, and inability to reason about event ordering in distributed systems. Events also carry semantic ambiguity: some represent a single moment in time, others represent a bounded interval, and others may represent ongoing events. Mixing date and datetime specificity within the same event structure creates validation complexity and implementation errors.

Decision​

Adopt RFC 3339 as the canonical temporal representation for all events in PIES. Define two distinct event structure variants: one for date-only events (reporting, day-level granularity) and one for datetime events (auditing, sub-second precision). Prohibit mixing date and datetime properties within a single event. Enforce UTC-only representation for all datetime values by appending the "Z" timezone designator. Provide explicit implementation guidance for choosing specificity based on use case intent.

Structure​

An Event shall contain exactly one of the following mutually exclusive patterns:

  1. Date Pattern: start_date (required), end_date (optional). Format: YYYY-MM-DD with leading zero padding.
    • Instant event: start_date equals end_date.
    • Bounded interval: start_date and end_date both present, end_date greater than start_date.
  2. DateTime Pattern: start_datetime (required), end_datetime (optional). Format: YYYY-MM-DDTHH:mm:ss[.sssssss]Z with UTC timezone.
    • Instant event: start_datetime equals end_datetime.
    • Bounded interval: start_datetime and end_datetime both present, end_datetime greater than start_datetime.

An event with only a start value (omitted end) represents a single point-in-time moment and shall be interpreted "at face value" as the specific moment of occurrence. Interpretation of the event meaning must not infer mutable state such as "still ongoing" from the omitted end property.

Rationale​

RFC 3339 is a standardized, widely implemented subset of ISO 8601 that eliminates timezone ambiguity by requiring explicit designators. Separating date and datetime patterns avoids the cognitive and validation burden of optional fields that users must reason about. Requiring UTC-only datetime values eliminates timezone conversion errors and establishes a single canonical representation across all provider systems. Specificity guidance (date for reporting, datetime for auditing) aligns temporal representation with semantic intent rather than forcing all consumers to infer purpose from payload structure or attribute names.

Allowing optional end properties enables flexible expression of instant events (start equals end), bounded intervals (both start and end present), and open-ended events (end omitted). This flexibility trades off against increased parsing and interpretation complexity. Consumers must be prepared to handle missing end values and interpret them according to resource-specific semantics and operational context.

Prohibiting ongoing events (where end is omitted and implicitly means "current or ongoing") ensures that asynchronous message consumers do not need to interpret missing end values as mutable state. All temporal information in PIES is immutable at the message level. Events with only a start value are interpreted as point-in-time facts describing a single moment of occurrence, not as state assertions about ongoing processes.

Assumptions​

  • All provider systems can generate and parse RFC 3339 date and datetime strings.
  • UTC is an acceptable canonical timezone for all use cases. No providers require local timezone preservation.
  • The distinction between date and datetime intent can be determined at message design time, not runtime.
  • Systems can operate without inferring ongoing event state from omitted end properties.
  • Sub-second precision in datetime values (up to 7 decimal places) is permissible for PIES use cases.

Options Considered​

  • Unix/Epoch timestamp: Compact, system-friendly, standard in many APIs. Timezone-agnostic by definition. Rejected because human readability and RFC standardization are important for governance and audit trails. Timestamps also require auxiliary schema to distinguish date-only from full datetime intent.
  • ISO 8601 with timezone flexibility: Allows local timezone representation (e.g., 2024-12-01T10:00:00-07:00). Provides timezone context but increases validation complexity and creates multiple valid representations of the same moment. Rejected due to ecosystem standardization preference and the administrative burden of tracking sender timezones.
  • Single unified temporal field with optional precision: One field that accepts both date and datetime based on length. Simpler API but harder to validate and document. Rejected because oneOf schema pattern is clearer and better supported by JSON Schema validators.
  • RFC 3339 with UTC-only enforcement (chosen): Standardized, human-readable, strict timezone discipline. Eliminates ambiguity and provides clear validation rules. Requires explicit UTC awareness from providers but ensures correctness.

Consequences​

Positive​

  • RFC 3339 is standardized, widely implemented, and recognized across government and industry systems.
  • Separating date and datetime patterns makes validation deterministic and schema tooling straightforward.
  • UTC-only datetime values eliminate timezone conversion errors and establish a single source of truth for temporal facts.
  • Specificity guidance helps implementers choose the appropriate level of detail based on use case, reducing data bloat and implementation confusion.
  • Optional end properties allow flexible expression of instant, bounded, and open-ended events without requiring artificial end values or workarounds.
  • Prohibiting ongoing events forces event producers to provide complete temporal facts, improving data quality and consumer correctness.

Negative​

  • Events requiring sub-day granularity must use datetime, increasing payload size compared to date-only representation.
  • Providers must coordinate on UTC representation, requiring awareness of their local timezone offset and explicit UTC conversion.
  • Systems representing historical events with only year or year-month granularity must round to the nearest supported precision (day or second).
  • Conversion between date and datetime formats is lossy. Dropping time from datetime loses precision and cannot be reliably reversed.
  • Implementers unfamiliar with RFC 3339 may struggle with sub-second precision, timezone designators, or the Z suffix.
  • Omitted end properties introduce interpretation ambiguity. Consumer systems must define and document how to interpret missing end values in their operational context.

References​

None at this time. Future ADRs on temporal queries, retention policies, or audit log retention may reference this decision.