Date and time types

isoDate

A date on a calendar in ISO 8601 format YYYY-MM-DD.

Example

A JSON example of this model.

"2025-01-01"

JSON Schema

The JSON Schema for this model.

$schema: https://json-schema.org/draft/2020-12/schema
$id: isoDate.yaml
type: string
format: date
examples:
  - 2025-01-01
description: A date on a calendar in ISO 8601 format YYYY-MM-DD

TypeSpec

The TypeSpec code for this model.

@example(isoDate.fromISO("2025-01-01"))
@Versioning.added(CommonGrants.Versions.v0_1)
scalar isoDate extends plainDate;

TypeScript

The TypeScript code for this model.

 * is rendered by `toStr` into the string format the inner schema expects. An
 * invalid `Date` is passed through unchanged so the inner validator rejects it,
 * rather than throwing a `RangeError` out of `toISOString()` and escaping
 * `safeParse`. Output is a `Date`.

isoTime

A time on a clock, without a timezone, in ISO 8601 format HH:mm:ss.

Caution

The isoTime type does not include timezone information. When representing a time in a specific timezone, use utcDateTime or offsetDateTime instead.

Example

A JSON example of this model.

"17:00:00"

JSON Schema

The JSON Schema for this model.

$schema: https://json-schema.org/draft/2020-12/schema
$id: isoTime.yaml
type: string
format: time
examples:
  - 17:00:00
description: A time on a clock, without a timezone, in ISO 8601 format HH:mm:ss

TypeSpec

The TypeSpec code for this model.

@example(isoTime.fromISO("17:00:00"))
@Versioning.added(CommonGrants.Versions.v0_1)
scalar isoTime extends plainTime;

TypeScript

The TypeScript code for this model.

  (toStr: (d: Date) => string) =>
  (val: unknown): unknown =>
    val instanceof Date && !isNaN(val.getTime()) ? toStr(val) : val;

/** Schema for UTC datetime fields (accepts an ISO string or a `Date`; outputs a `Date`) */
export const UTCDateTimeSchema = z.preprocess(
  acceptDate(d => d.toISOString()),
  z.string().datetime().transform(ensureUTC)

utcDateTime

A date and time with timezone in ISO 8601 format YYYY-MM-DDThh:mm:ssZ.

Example

A JSON example of this model.

"2024-02-28T17:00:00Z"

JSON Schema

The JSON Schema for this model.

$schema: https://json-schema.org/draft/2020-12/schema
$id: utcDateTime.yaml
type: string
format: date-time
description: A date and time with timezone in ISO 8601 format YYYY-MM-DDThh:mm:ssZ

TypeScript

The TypeScript code for this model.

 * Accept a `Date` as input by normalizing it to a string before the string

offsetDateTime

A date and time with timezone in ISO 8601 format YYYY-MM-DDThh:mm:ss±hh:mm.

Example

A JSON example of this model.

"2024-02-28T17:00:00+01:00"

JSON Schema

The JSON Schema for this model.

$schema: https://json-schema.org/draft/2020-12/schema
$id: offsetDateTime.yaml
type: string
format: date-time
description: A date and time with timezone in ISO 8601 format YYYY-MM-DDThh:mm:ss±hh:mm

TypeScript

The TypeScript code for this model.

/** Schema for ISO date format: YYYY-MM-DD (accepts a YYYY-MM-DD string or a `Date`; outputs a `Date`) */
export const ISODateSchema = z.preprocess(
  acceptDate(d => d.toISOString().slice(0, 10)),
  z

calendarYear

A calendar year in the format YYYY.

Example

A JSON example of this model.

"2025"

JSON Schema

The JSON Schema for this model.

$schema: https://json-schema.org/draft/2020-12/schema
$id: calendarYear.yaml
type: string
examples:
  - "2025"
pattern: ^[0-9]{4}$
description: A calendar year

TypeSpec

The TypeSpec code for this model.

@example("2025")
@pattern("^[0-9]{4}$")
@Versioning.added(CommonGrants.Versions.v0_2)
scalar calendarYear extends string;