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
Base 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

The format keyword restricts string instances to the given logical type and produces an annotation value.

However, this vocabulary is not used by default in the JSON Schema 2020-12 dialect. To use it, a custom dialect that includes this vocabulary is required. As a consequence, not many JSON Schema implementations support it. In most cases, it is advised to stick to the Format-Annotation variant of this keyword.

The supported formats are the following:

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

Remember that JSON Schema is a constraint-driven language. Therefore, non-string instances successfully validate against this keyword. If needed, make use of the type keyword to constraint the accepted type accordingly.

Examples

A custom dialect meta-schema that opts-in to the Format Assertion vocabulary Schema 
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://example.com/my-dialect",
  "$dynamicAnchor": "meta",
  "$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" }
  ]
}
A schema that validates string instances as e-mail addresses Schema 
{
  "$schema": "https://example.com/custom-meta-schema",
  "format": "email"
}
Valid A string value that represents a valid e-mail address is valid Instance 
"john.doe@example.com"
Annotations 
{ "keyword": "/format", "instance": "", "value": "email" }
Invalid A string value that represents an invalid e-mail address is invalid Instance 
"foo-bar"
Valid Any non-string value is valid but no annotation is produced Instance 
45