Format Validation

Overview

The format keyword is used to convey semantic information for values that are accurately described by authoritative resources such as RFCs or external specifications. While structural validation ensures correct data types and structures, format validation provides semantic validation for specific data formats.

The format keyword functions as both an assertion (validation) and an annotation (metadata). Implementations SHOULD provide assertion behavior for format values defined in this specification.

Usage

Value: String The value of this keyword MUST be a string. While this keyword can validate any type, each distinct format value generally only validates a specific set of instance types.

{
  "type": "string",
  "format": "email"
}

If the type of the instance to validate is not in the expected set for a format, validation for this keyword SHOULD succeed (not fail).

Implementation Requirements

Implementations:

SHOULD provide validation for each format attribute defined in this document
Are encouraged to provide validation for formats listed in the Format Registry
MAY support custom format values, but such support MUST be configurable and disabled by default
SHOULD use a common parsing library or well-known regular expression for each format
SHOULD clearly document any limitations regarding format validation
MUST refuse to process any schema containing a format value they don’t support

Validation is limited to syntactic checking. Implementations SHOULD NOT attempt to send an email, connect to a URL, or otherwise check the existence of an entity identified by a format instance.

Dates and Times

These format values apply to string instances and are based on RFC 9557 and RFC 3339.

`date-time`

A date-time representation including timezone. Standard: RFC 9557 “date-time-ext” rule

{
  "type": "string",
  "format": "date-time"
}

Valid Examples

2026-03-03T15:30:00Z
2026-03-03T15:30:00+05:30
2026-03-03T15:30:00.123Z
2026-03-03T15:30:00-08:00

This format SHOULD allow and validate published leap seconds per RFC 3339, section 5.7.

`date`

A full date without time or timezone. Standard: RFC 3339 “full-date” rule

{
  "type": "string",
  "format": "date"
}

Valid Example: 2026-03-03

`time`

A time of day with timezone, independent of any specific date. Standard: RFC 3339 “full-time” rule

{
  "type": "string",
  "format": "time"
}

Valid Examples

15:30:00Z
15:30:00+05:30
15:30:00.123Z

The time format MUST NOT include leap seconds. Leap seconds only apply to specific dates, and time represents a time value independent of any date.

`duration`

A duration of time. Standard: RFC 3339 Appendix A “duration” rule (from ISO 8601)

{
  "type": "string",
  "format": "duration"
}

Valid Examples

P1Y - 1 year
P3M - 3 months
P1DT12H - 1 day and 12 hours
PT30M - 30 minutes
P1Y2M3DT4H5M6S - 1 year, 2 months, 3 days, 4 hours, 5 minutes, 6 seconds

Email Addresses

`email`

A valid Internet email address. Standard: RFC 5321, section 4.1.2 “Mailbox” rule

{
  "type": "string",
  "format": "email"
}

Valid Examples

Hostnames

`hostname`

A valid Internet hostname. Standard: RFC 1123, section 2.1

{
  "type": "string",
  "format": "hostname"
}

Valid Examples

example.com
api.company.co.uk
my-server-01.internal

IP Addresses

`ipv4`

An IPv4 address in dotted-quad notation. Standard: RFC 2673, section 3.2 “dotted-quad” syntax

{
  "type": "string",
  "format": "ipv4"
}

Valid Examples

192.168.1.1
10.0.0.1
172.16.0.1
8.8.8.8

`ipv6`

An IPv6 address. Standard: RFC 4291, section 2.2

{
  "type": "string",
  "format": "ipv6"
}

Valid Examples

2001:0db8:85a3:0000:0000:8a2e:0370:7334
2001:db8:85a3::8a2e:370:7334 (compressed)
::1 (loopback)
fe80::1 (link-local)

Resource Identifiers

`uri`

A valid Internationalized Resource Identifier (IRI). Standard: RFC 3987

{
  "type": "string",
  "format": "uri"
}

Valid Examples

https://example.com/path
ftp://files.example.org/file.txt
mailto:[email protected]

All valid URIs are also valid IRIs.

`uri-reference`

A URI reference (either a URI or a relative reference). Standard: RFC 3986

{
  "type": "string",
  "format": "uri-reference"
}

Valid Examples

https://example.com/path (absolute URI)
/path/to/resource (relative reference)
../other/resource (relative reference)
#section (fragment-only reference)

`iri`

A valid IRI (Internationalized Resource Identifier). Standard: RFC 3987

{
  "type": "string",
  "format": "iri"
}

`iri-reference`

An IRI reference (either an IRI or a relative reference). Standard: RFC 3987

{
  "type": "string",
  "format": "iri-reference"
}

`uuid`

A Universally Unique Identifier. Standard: RFC 4122

{
  "type": "string",
  "format": "uuid"
}

Valid Example: f81d4fae-7dec-11d0-a765-00a0c91e6bf6

The uuid format is for plain UUIDs, not UUIDs in URNs. For UUIDs as URNs (e.g., urn:uuid:...), use the uri format with a pattern regular expression of ^urn:uuid:.

`uri-template`

A URI Template of any level. Standard: RFC 6570

{
  "type": "string",
  "format": "uri-template"
}

Valid Examples

https://api.example.com/users/{id}
https://example.com/search{?q,page}
https://api.example.com/{version}/items{/id}

URI Templates may be used for IRIs; there is no separate IRI Template specification.

JSON Pointers

`json-pointer`

A JSON Pointer string. Standard: RFC 6901, section 5

{
  "type": "string",
  "format": "json-pointer"
}

Valid Examples

/foo/bar
/items/0
/properties/name
“ (empty string - references the whole document)

`relative-json-pointer`

A Relative JSON Pointer. Standard: draft-handrews-relative-json-pointer-01

{
  "type": "string",
  "format": "relative-json-pointer"
}

Valid Examples

0
1/name
0#

To allow for both absolute and relative JSON Pointers, use anyOf or oneOf:

{
  "anyOf": [
    { "format": "json-pointer" },
    { "format": "relative-json-pointer" }
  ]
}

Regular Expressions

`regex`

A valid regular expression. Standard: ECMA-262

{
  "type": "string",
  "format": "regex"
}

Valid Examples

^[a-z]+$
\\d{3}-\\d{3}-\\d{4}
[A-Z][a-z]*

Implementations that validate formats MUST accept at least the subset of ECMA-262 defined in the JSON Schema Core specification, and SHOULD accept all valid ECMA-262 expressions.

Format Registry

JSON Schema maintains a registry of formats defined by other specifications and organizations. As of the publication of this specification, the format registry can be found at:

https://github.com/json-schema-org/json-schema-spec/blob/main/specs/registries/format.json

Implementations SHOULD support the formats listed in this registry as if they were defined by this document.

Custom Formats

Implementations MAY support custom format values, but:

Such support MUST be configurable
Custom formats MUST be disabled by default
Save for agreement between parties, schema authors SHALL NOT expect a peer implementation to support custom format values

Example with Custom Format

{
  "type": "string",
  "format": "custom-sku",
  "description": "Custom format - requires specific implementation support"
}

Complete Examples

{
  "type": "object",
  "properties": {
    "email": {
      "type": "string",
      "format": "email"
    },
    "website": {
      "type": "string",
      "format": "uri"
    },
    "dateOfBirth": {
      "type": "string",
      "format": "date"
    },
    "registeredAt": {
      "type": "string",
      "format": "date-time"
    },
    "ipAddress": {
      "type": "string",
      "format": "ipv4"
    }
  }
}

Structural Validation - Type and structural constraints
Content Validation - String-encoded data

Overview

Core Specification

Validation Specification

Advanced Concepts

Development Process

Overview

Usage

Implementation Requirements

Dates and Times

`date-time`

`date`

`time`

`duration`

Email Addresses

`email`

Hostnames

`hostname`

IP Addresses

`ipv4`

`ipv6`

Resource Identifiers

`uri`

`uri-reference`

`iri`

`iri-reference`

`uuid`

`uri-template`

JSON Pointers

`json-pointer`

`relative-json-pointer`

Regular Expressions

`regex`

Format Registry

Custom Formats

Complete Examples

Build docs developers (and LLMs) love

Overview

Core Specification

Validation Specification

Advanced Concepts

Development Process

​Overview

​Usage

​Implementation Requirements

​Dates and Times

​date-time

​date

​time

​duration

​Email Addresses

​email

​Hostnames

​hostname

​IP Addresses

​ipv4

​ipv6

​Resource Identifiers

​uri

​uri-reference

​iri

​iri-reference

​uuid

​uri-template

​JSON Pointers

​json-pointer

​relative-json-pointer

​Regular Expressions

​regex

​Format Registry

​Custom Formats

​Complete Examples

​Related Topics

Build docs developers (and LLMs) love

Overview

Usage

Implementation Requirements

Dates and Times

`date-time`

`date`

`time`

`duration`

Email Addresses

`email`

Hostnames

`hostname`

IP Addresses

`ipv4`

`ipv6`

Resource Identifiers

`uri`

`uri-reference`

`iri`

`iri-reference`

`uuid`

`uri-template`

JSON Pointers

`json-pointer`

`relative-json-pointer`

Regular Expressions

`regex`

Format Registry

Custom Formats

Complete Examples

Related Topics