Explanation

The format keyword in JSON Schema’s Format Annotation vocabulary serves to provide basic semantic identification of certain types of string values. Compared to older JSON Schema versions, the format keyword in the official 2020-12 dialect is purely an annotation meant to be informative and to carry semantics rather than to perform any validation.

When using format from Format Annotation, it’s recommended that you provide your validation rules alongside the format. The implementation may choose to treat format as an assertion and attempt to validate the value’s conformance to the specified semantics. However, this behavior must be explicitly enabled and is typically disabled by default. Implementations should document their level of support for such validation.

• It allows for the semantic identification of certain kinds of string values. For instance, it can indicate that a string value should be interpreted as a date, email, URI, etc.
• format is solely an annotation and does not enforce any validation. It’s meant to provide information about the expected format of the string.
• Implementations may choose to enable format as an assertion, meaning that validation fails if the value doesn’t conform to the specified format semantics. However, this is not mandatory and must be explicitly enabled.
• While users can define and use their own custom formats (e.g., “format”: “foobar”), it’s recommended to refrain from overloading the format keyword for future compatibility reasons. Instead, define custom keywords for specific validation requirements. For example in the event that you define your own “foobar” and JSON Schema subsequently chooses to define “foobar,” you may encounter difficulties.

Defined Formats

Examples

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "format": "email"
}

"john.doe@example.com"

"foo_bar"

45

{ "keyword": "/format", "instance": "", "value": "email" }

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "format": "email",
  "pattern": "^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$"
}

"john.doe@example.com"

"foo_bar"

true

{ "keyword": "/format", "instance": "", "value": "email" }