JSON Dates and Times: ISO 8601 Best Practices
JSON has no date type — here is how to handle dates correctly: why ISO 8601 in UTC is the standard, timestamps vs strings, time zones, parsing back to native dates, and the pitfalls to avoid.
JSON has no date type. Numbers, strings, booleans, null, objects, arrays — that is the whole list. So every date in JSON is encoded as something else, and the encoding you choose determines whether time zones, parsing, and sorting just work or quietly break. This guide explains the standard way to represent dates in JSON and the pitfalls that cause off-by-one-day bugs.
JSON has no native date type
Because the JSON specification defines no date type, a date must be represented as a string or a number. There is no single mandated format, which is exactly why teams need a convention — and why inconsistent date handling is such a common source of bugs across services that exchange JSON.
Use ISO 8601 strings in UTC
The widely accepted standard is an ISO 8601 string in UTC, such as 2026-05-08T14:30:00Z. The Z suffix means Zulu time (UTC), removing any ambiguity about the time zone. This format sorts correctly as text, is human-readable, and is parsed natively by date libraries in every language. When in doubt, send ISO 8601 in UTC — it is the safest default for an API.
{ "createdAt": "2026-05-08T14:30:00Z" }ISO 8601 strings versus Unix timestamps
The alternative is a Unix timestamp — a number of seconds (or milliseconds) since 1970. Timestamps are compact and unambiguous and easy to do arithmetic on, but they are not human-readable and invite confusion between seconds and milliseconds. ISO 8601 strings are self-describing and readable at the cost of a few bytes. Most public APIs prefer ISO 8601 strings; high-volume internal systems sometimes prefer numeric timestamps. Pick one and document the unit.
Time zones and the off-by-one-day bug
The classic date bug comes from dropping the time zone. A bare date like 2026-05-08 with no time or zone is interpreted differently depending on the reader's locale, so a value can shift by a day when it crosses midnight in another time zone. Always include the zone (the Z for UTC, or an explicit offset like +02:00). Store and transmit in UTC, and convert to local time only at the display edge.
"2026-05-08" → read in local zone, can shift a day
"2026-05-08T00:00:00Z" → unambiguous UTCParsing dates back into your language
Since the date arrives as a string, your code must convert it back to a native date object. In JavaScript, new Date(isoString) parses ISO 8601, and the reviver argument of JSON.parse can convert date strings automatically during parsing. Python has datetime.fromisoformat, and most languages parse ISO 8601 out of the box. The round trip is reliable precisely because ISO 8601 is unambiguous.
new Date("2026-05-08T14:30:00Z");from datetime import datetime
datetime.fromisoformat("2026-05-08T14:30:00+00:00")Validating date fields
When a date field misbehaves, confirm the raw value first. A formatter makes the payload readable so you can see the exact string, and JSON Schema can enforce a date-time format on the field so malformed dates are rejected before they reach your code. Catching a bad date at the contract boundary beats debugging a time-zone shift downstream.
Frequently asked questions
How should I format dates in JSON?
Use an ISO 8601 string in UTC, such as 2026-05-08T14:30:00Z. JSON has no date type, and ISO 8601 is human-readable, sorts correctly as text, includes the time zone, and parses natively in every language.
Does JSON have a date type?
No. JSON supports only strings, numbers, booleans, null, objects, and arrays. Dates must be encoded as a string (ISO 8601 is standard) or a numeric Unix timestamp, and parsed back into a native date by your code.
Should I use ISO 8601 or a Unix timestamp in JSON?
ISO 8601 strings are self-describing, readable, and preferred by most public APIs. Unix timestamps are compact and easy for arithmetic but not human-readable and prone to seconds-versus-milliseconds confusion. Choose one and document the unit.
Why do my JSON dates shift by a day?
Usually because the time zone is missing. A bare date like 2026-05-08 is interpreted in the reader's local zone and can cross midnight elsewhere, shifting the day. Always include the zone (Z for UTC or an explicit offset) and store dates in UTC.
How do I parse a JSON date string?
Convert the string to a native date: new Date(isoString) in JavaScript, datetime.fromisoformat in Python, and built-in ISO 8601 parsers elsewhere. In JavaScript you can also use the reviver argument of JSON.parse to convert dates during parsing.
Related tools
Try these tools
JSON Formatter & Beautifier
Format, prettify, and beautify messy JSON with configurable indentation and key sorting.
JSON Validator
Validate JSON instantly with precise, human-readable error messages and line numbers.
JSON Editor
Write, edit, format, minify, and validate JSON in a fast full-screen or embedded editor.
JSON Repair & Fix
Fix invalid JSON: trailing commas, quotes, unquoted keys, and LLM markdown fences.