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-01T00:00:00.000Z"

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.

/** A date on a calendar in ISO 8601 format YYYY-MM-DD */
@example(isoDate.fromISO("2025-01-01"))
scalar isoDate extends plainDate;

TypeScript

The TypeScript code for this model.

export const ISODateSchema = z
  .string()
  .date()
  .transform(str => new Date(str));

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.

/** A time on a clock, without a timezone, in ISO 8601 format HH:mm:ss */
@example(isoTime.fromISO("17:00:00"))
scalar isoTime extends plainTime;

TypeScript

The TypeScript code for this model.

export const ISOTimeSchema = z.preprocess(val => {
  if (typeof val === "string") {
    // Remove timezone indicator (e.g., "17:00:00.123Z" → "17:00:00.123", "17:00:00+05:00" → "17:00:00")
    // Zod's time() accepts HH:MM:SS[.fraction] but not timezone indicators
    return val.replace(/(Z|[+-]\d{2}:\d{2})$/, "");
  }
  return val;
}, z.string().time());

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.

export const UTCDateTimeSchema = z.string().datetime().transform(ensureUTC);

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.

export const OffsetDateTimeSchema = z
  .string()
  .datetime({ offset: true })
  .transform(str => new Date(str));

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.

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