Aglet

Triage API date and time format drift

A timestamp can remain valid text while changing the instant or ordering the client sees. Freeze one record whose display, expiry, or sort changed. Record raw value, field meaning, parser timezone, normalized value, and client revision, then separate formatting from semantic change.

Establish what is happening

  1. Capture the raw timestamp

    Record endpoint, field name, raw timestamp, declared meaning, response version, and environment without sensitive record content. Note precision, offset, and whether the client displayed, stored, or compared it differently. Preserve precision and offset in the record.

  2. Compare one known instant

    Use two representations of the same instant plus an intentionally different instant. Compare parser output, timezone, precision, sort position, expiry decision, and display. A string comparison can look stable while the normalized instant changes.

  3. Bound affected comparisons

    Group changes by field, endpoint, parser version, timezone, operation, and user-visible outcome. Separate missing offset, precision loss, timezone shift, and local-time conversion. Preserve records whose ordering or expiry changed for review.

What to carry forward

Triage ends with raw and normalized values, first comparison boundary, affected operation cohort, and explicit time assumptions. Stop before changing timezone rules globally. Route parser, contract, and consumer questions separately. Keep raw and normalized timestamps together. Keep the original representation available.

Technical background: Project documentation on GitHub.

Keep the decision with the work.

Use a Work Item in Aglet to record the problem, the evidence you have, and the next decision. Add an owner and priority, then keep updates in the discussion so the next person can follow the reasoning.

Create an account See the product workflow