The parts of an ISO 8601 timestamp
2025-11-16T14:00:00.000Z reads as: date, T separator, time to milliseconds, and Z for UTC. Replace Z with +08:00 and the same string describes a different instant — 14:00 in Shanghai rather than 14:00 UTC.
2025-11-16— date only. Interpreted as midnight UTC by most parsers, which is not the same as local midnight.2025-11-16T14:00:00Z— UTC, second precision.2025-11-16T14:00:00.123Z— UTC, millisecond precision.2025-11-16T22:00:00+08:00— same instant as the previous line.2025-11-16T14:00:00— no offset; parsing depends on the implementation, which is why RFC 3339 requires one.
Why date-only strings cause off-by-one bugs
new Date("2025-11-16") is treated as UTC midnight by the ECMAScript spec, while some libraries treat it as local midnight. In UTC+8, that is an eight-hour difference; in UTC-5, the rendered date can be the previous day. Always include a time and an offset when the instant matters.
Formatting rules worth remembering
- Use
Tbetween date and time, andZor a numeric offset at the end. - Fractional seconds use a dot, not a comma:
.123, not,123. - Week dates (
2025-W46-1) and ordinal dates (2025-320) exist but are rarely accepted by APIs. - ISO 8601 allows
24:00:00for midnight at the end of a day; many parsers reject it.
For JSON APIs, RFC 3339 is the profile of ISO 8601 to follow: it requires an offset and allows fractional seconds.