Date and Date-Time Format Validation in JSON Schema

Date and Time Validation in JSON Schema

JSON does not have a native date type, so dates are represented as strings. JSON Schema provides three format keywords for temporal values, all based on RFC 3339 (a profile of ISO 8601):

The Three Date/Time Formats

{ "format": "date" }       // "2025-01-20"
{ "format": "date-time" }  // "2025-01-20T14:30:00Z"
{ "format": "time" }       // "14:30:00Z"

• date — full calendar date: YYYY-MM-DD. No time or timezone information.
• date-time — full date with time and timezone offset: YYYY-MM-DDTHH:MM:SSZ or YYYY-MM-DDTHH:MM:SS+HH:MM. The T separator is required.
• time — time of day with timezone offset: HH:MM:SS+HH:MM or HH:MM:SSZ.

How the Example Schema Works

The schema models an event record with three temporal fields:

1. birthDate uses format: "date" — it accepts "1990-07-15" but rejects "07/15/1990" or "July 15, 1990".
2. createdAt uses format: "date-time" — the value "2025-01-20T14:30:00Z" includes a UTC timezone indicator (Z).
3. meetingTime uses format: "time" — "09:00:00+05:30" represents 9 AM in the IST timezone (UTC+5:30).

Timezone Requirements

RFC 3339 requires date-time and time values to include a timezone offset. The date format does not include timezone information. If your API needs timezone-aware dates, use date-time instead of date.

Common timezone formats:

• Z — UTC (Zulu time)
• +00:00 — explicit UTC offset
• -05:00 — US Eastern Standard Time
• +05:30 — India Standard Time

Validation Depth

Most validators check the structural format but do not verify calendar validity. For example, "2025-02-30" (February 30th, which does not exist) may pass format validation in some implementations. If you need strict calendar validation, add application-level checks.

Fractional Seconds

RFC 3339 allows fractional seconds: "2025-01-20T14:30:00.123Z". Most validators accept these, and they are useful for logging timestamps, distributed tracing, and event ordering.