openadr3.vtn.time — energy.grid-coordination/clj-oa3-vtn 0.12.1

Time helpers for the VTN.

The VTN's internal canon is java.time.ZonedDateTime for any datetime value (createdDateTime, modificationDateTime, intervalPeriod.start) and java.time.Duration for any duration value (intervalPeriod.duration). All zone-sensitive arithmetic happens on ZonedDateTime so DST is handled correctly by the IANA rules.

At the wire boundary (HTTP response, MQTT publish, DDB :data attribute, and the DDB :eventStart GSI key) datetimes are serialised to canonical UTC Z form via zdt->utc-z. The OA3 spec strongly conventionalises Z form, and the GSI relies on lex-orderable sort keys, so canonicalising the wire keeps both consistent.

Inbound parsing accepts arbitrary RFC 3339 offsets (Z, +00:00, -07:00, …) and the VTN-RI's non-standard space-separated form.

duration->iso clj

(duration->iso d)

Format a Duration as its ISO 8601 string (PT1H, PT15M, …).

now-utc-z clj

(now-utc-z)

Current instant as a canonical UTC Z ISO 8601 string. Convenience wrapper.

now-zdt clj

(now-zdt)

Current instant as a UTC ZonedDateTime.

parse-duration clj

(parse-duration s)

Parse an ISO 8601 duration string to a java.time.Duration.

parse-duration-maybe clj

(parse-duration-maybe s)

Parse to Duration if s is a non-blank string; pass through nil and already-parsed Duration values.

parse-zdt clj

(parse-zdt s)

Parse an RFC 3339 datetime string to a ZonedDateTime.

Accepts arbitrary offsets per RFC 3339 (Z, +00:00, -07:00, …). The returned ZonedDateTime is zoned to the wire offset (no IANA name is recoverable from the wire).

Also accepts the VTN-RI's non-standard space-separated form (2026-03-08 19:22:06, no offset) by inserting T and assuming UTC.

parse-zdt-maybe clj

(parse-zdt-maybe s)

Parse to ZonedDateTime if s is a non-blank string; pass through nil and already-parsed ZonedDateTime values.

plus-days clj

(plus-days zdt n)

Add n calendar days to a ZonedDateTime, respecting the zone's DST rules.

zdt->utc-z clj

(zdt->utc-z zdt)

Format a ZonedDateTime as canonical UTC Z ISO 8601 (2026-05-03T07:00:00Z). Normalises to UTC regardless of the zone the value carries — this is the wire form for OA3 and the canonical form for the DDB :eventStart GSI.