format : String
format
StringDefine 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 |
| 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 Annotation |
| Specification | https://json-schema.org/draft/2020-12/json-schema-validation.html#section-7.2.1 |
| Metaschema | https://json-schema.org/draft/2020-12/meta/format-annotation |
| Official Tests | draft2020-12/format.json |
| 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 communicates that string instances are of the given
logical type by producing an annotation value.
Common Pitfall
By default, this keyword does not perform validation. If
validation is desired, the best practice is to combine this keyword with the
pattern keyword. This guarantees
interoperable and unambiguous behavior across JSON Schema implementations.
Another option is to produce a custom dialect that opts-in to the Format Assertion vocabulary. However, this vocabulary is considered optional by the official JSON Schema Test Suite. As a consequence, not many implementations support it.
Best Practice
While technically allowed by the JSON Schema specification, extending this keyword with custom formats is considered to be an anti-pattern that can introduce interoperability issues and undefined behavior. As a best practice, stick to standardised formats. If needed, introduce a new keyword for custom string logical types.
Digging Deeper
This keyword and its validation guarantees are a common source of confusion of the JSON Schema specification across versions.
Since the introduction of this keyword, the JSON Schema specifications clarified that validation was not mandatory. However, the majority of older Schema implementations did support validation, leading schema-writers to rely on it. At the same time, a second problem emerged: implementations often didn’t agree on the strictness of validation, mainly on complex logical types like e-mail addresses, leading to various interoperability issues.
In JSON Schema 2020-12, the specification introduces two mutually incompatible vocabularies to clarify whether the keyword acts as an annotation or as an assertion. Confusingly enough, it also allows implementations to perform validation even when the annotation variant is in use, but only as a setting that is disabled by default.
To avoid the gray areas of this keyword, we recommend only treating it as an
annotation, never enabling validation support at the implementation level (even
if supported), and performing validation using the pattern keyword.
The supported formats are the following.
Examples
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"format": "email"
}"john.doe@example.com"{ "keyword": "/format", "instance": "", "value": "email" }"foo-bar"{ "keyword": "/format", "instance": "", "value": "email" }45