format : String
format
StringDefine semantic information about a string instance.
| Value |
This keyword must be set to a string, preferably 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 | Draft 7 |
| Changed In | Draft 3 Draft 4 Draft 6 |
| Introduced In | Draft 1 |
| Vocabulary | Validation |
| Specification | https://json-schema.org/draft-07/draft-handrews-json-schema-validation-01#rfc.section.7 |
| Metaschema | http://json-schema.org/draft-07/schema# |
| Official Tests | draft7/format.json |
| Default | None |
| Annotation | None |
| Affected By | None |
| Affects | None |
The format keyword communicates
that string instances are of the given logical type.
Common Pitfall
By default, this keyword does not perform validation, as
validating formats is considered optional by the official JSON Schema Test
Suite. As a consequence, not many implementations support it. 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.
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.
To avoid the gray areas of this keyword, we recommend only treating it as
semantic metadata, 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": "http://json-schema.org/draft-07/schema#",
"format": "email"
}"john.doe@example.com""foo-bar"45