format : String

format

String

Define and assert semantic information about a string instance.

Value This keyword must be set to a string, preferrably one that is standardized by JSON Schema to ensure interoperability
Kind Annotation Assertion
Applies To String
Dialect 2020-12
Changed In Draft 3 Draft 4 Draft 6 Draft 7 2019-09
Introduced In Draft 1
Vocabulary Format Assertion
Specification https://json-schema.org/draft/2020-12/json-schema-validation.html#section-7.2.2
Metaschema https://json-schema.org/draft/2020-12/meta/format-assertion
Official Tests
Default None
Annotation String The format name set by this keyword
Affected By None
Affects None
Also See

Explanation

The format keyword of the “format-assertion” vocabulary allows for basic semantic identification of certain kinds of string values that are commonly used. It provides a way to specify logical formats for string types, such as dates, email addresses, URIs, etc. However, it’s important to note that this vocabulary is not used by default in the official 2020-12 dialect of JSON Schema. If you want to utilize it, you would need to define your own custom dialect that includes this vocabulary.

While the format keyword theoretically provides interoperable logical string type validation, many existing implementations may not support this vocabulary. Therefore, it’s recommended to use the format keyword from the Format Annotation vocabulary (which is available out of the box) alongside any custom validation within the schema.

Defined Formats

Format Category Specification
"date-time" Time https://json-schema.org/draft/2020-12/json-schema-validation.html#section-7.3.1
"date" Time https://json-schema.org/draft/2020-12/json-schema-validation.html#section-7.3.1
"time" Time https://json-schema.org/draft/2020-12/json-schema-validation.html#section-7.3.1
"duration" Time https://json-schema.org/draft/2020-12/json-schema-validation.html#section-7.3.1
"email" Emails https://json-schema.org/draft/2020-12/json-schema-validation.html#section-7.3.2
"idn-email" Emails https://json-schema.org/draft/2020-12/json-schema-validation.html#section-7.3.2
"hostname" Hostnames https://json-schema.org/draft/2020-12/json-schema-validation.html#section-7.3.3
"idn-hostname" Hostnames https://json-schema.org/draft/2020-12/json-schema-validation.html#section-7.3.3
"ipv4" IP Addresses https://json-schema.org/draft/2020-12/json-schema-validation.html#section-7.3.4
"ipv6" IP Addresses https://json-schema.org/draft/2020-12/json-schema-validation.html#section-7.3.4
"uri" Resource Identifiers https://json-schema.org/draft/2020-12/json-schema-validation.html#section-7.3.5
"uri-reference" Resource Identifiers https://json-schema.org/draft/2020-12/json-schema-validation.html#section-7.3.5
"iri" Resource Identifiers https://json-schema.org/draft/2020-12/json-schema-validation.html#section-7.3.5
"iri-reference" Resource Identifiers https://json-schema.org/draft/2020-12/json-schema-validation.html#section-7.3.5
"uuid" Resource Identifiers https://json-schema.org/draft/2020-12/json-schema-validation.html#section-7.3.5
"uri-template" Resource Identifiers https://json-schema.org/draft/2020-12/json-schema-validation.html#section-7.3.6
"json-pointer" JSON Pointer https://json-schema.org/draft/2020-12/json-schema-validation.html#section-7.3.7
"relative-json-pointer" JSON Pointer https://json-schema.org/draft/2020-12/json-schema-validation.html#section-7.3.7
"regex" Regular Expressions https://json-schema.org/draft/2020-12/json-schema-validation.html#section-7.3.8

Examples

Custom meta-schema including the 'Format Assertion' vocabulary Schema
{
  "$schema": "https://example.com/custom-meta-schema",
  "$id": "https://example.com/custom-meta-schema",
  "$vocabulary": {
    "https://json-schema.org/draft/2020-12/vocab/core": true,
    "https://json-schema.org/draft/2020-12/vocab/format-assertion": true
  },
  "allOf": [
    { "$ref": "https://json-schema.org/draft/2020-12/meta/core" },
    { "$ref": "https://json-schema.org/draft/2020-12/meta/format-assertion" }
  ]
}
Schema with '$schema' set to custom meta-schema Schema
{
  "$schema": "https://example.com/custom-meta-schema",
  "$id": "https://example.com/schema",
  "format": "email"
}
Valid A string instance with correct email format is valid Instance
"john.doe@example.com"
Invalid A string instance with incorrect email format is also valid Instance
"foo_bar"
Valid 'format' keyword is irrelevant for instances with values other than strings Instance
45
Annotations
{ "keyword": "/format", "instance": "", "value": "email" }