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 Hint: Use the jsonschema metaschema and jsonschema lint commands to catch keywords set to invalid values
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 Hint: Use the jsonschema validate command to collect annotations from the command-line
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 JSON Schema 2020-12 Validation Section 7.3.1
"date" Time JSON Schema 2020-12 Validation Section 7.3.1
"time" Time JSON Schema 2020-12 Validation Section 7.3.1
"duration" Time JSON Schema 2020-12 Validation Section 7.3.1
"email" Emails JSON Schema 2020-12 Validation Section 7.3.2
"idn-email" Emails JSON Schema 2020-12 Validation Section 7.3.2
"hostname" Hostnames JSON Schema 2020-12 Validation Section 7.3.3
"idn-hostname" Hostnames JSON Schema 2020-12 Validation Section 7.3.3
"ipv4" IP Addresses JSON Schema 2020-12 Validation Section 7.3.4
"ipv6" IP Addresses JSON Schema 2020-12 Validation Section 7.3.4
"uri" Resource Identifiers JSON Schema 2020-12 Validation Section 7.3.5
"uri-reference" Resource Identifiers JSON Schema 2020-12 Validation Section 7.3.5
"iri" Resource Identifiers JSON Schema 2020-12 Validation Section 7.3.5
"iri-reference" Resource Identifiers JSON Schema 2020-12 Validation Section 7.3.5
"uuid" Resource Identifiers JSON Schema 2020-12 Validation Section 7.3.5
"uri-template" Resource Identifiers JSON Schema 2020-12 Validation Section 7.3.6
"json-pointer" JSON Pointer JSON Schema 2020-12 Validation Section 7.3.7
"relative-json-pointer" JSON Pointer JSON Schema 2020-12 Validation Section 7.3.7
"regex" Regular Expressions JSON Schema 2020-12 Validation 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