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. Most parsers read it as midnight UTC, which is not 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.