default : Any
default
AnyThis keyword can be used to supply a default JSON value associated with a particular schema.
| Value |
This keyword must be set to a JSON value, preferrably that successfully validates against the corresponding subschema
Hint: Use the jsonschema metaschema and jsonschema lint commands to catch keywords set to invalid values
|
|---|---|
| Kind | Annotation |
| Applies To | Any |
| Base Dialect | 2020-12 |
| Changed In | None |
| Introduced In | Draft 1 |
| Vocabulary | Meta Data |
| Specification | https://json-schema.org/draft/2020-12/json-schema-validation.html#section-9.2 |
| Metaschema | https://json-schema.org/draft/2020-12/meta/meta-data |
| Official Tests | draft2020-12/default.json |
| Default | None |
| Annotation |
Any
The default value 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 default keyword declares a default instance value for a schema or any of
its subschemas, typically to support specialised tooling like documentation and
form generators. This keyword does not affect validation, but the evaluator
will collect its value as an annotation.
Common Pitfall
The standard evaluation process will not automatically use these values to fill in missing parts of the instance. Furthermore, the JSON Schema specification does not provide any guidance on how this keyword should be used.
Consult the documentation of any JSON Schema tooling you rely on to check if and how it makes use of this keyword.
Best Practice
Meta-schema validation will not check that the default values you declare are actually valid against their respective schemas, as JSON Schema does not offer a mechanism for meta-schemas to declare that instances validate against parts of the same instance being evaluated. As a consequence, it is not rare for schemas to declare invalid default values that go undetected for a long time.
It is recommended to use the jsonschema lint
command, as this linter performs further checks to detect many corner cases,
including this one.
Digging Deeper
You might be tempted to evaluate a schema against an instance and rely on
default annotations to feed back the missing values back to it. However,
there is a known limitation that prevents this approach: in JSON Schema,
annotations are collected when a subschema is evaluated, which means that the
default value annotation is only emitted when the corresponding instance
location is present (and thus a default value is not required).
There is a
discussion to
introduce new variants of this keyword (propertyDefaults and itemDefaults)
to properly support this use case.
Examples
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"default": {},
"properties": {
"language": { "default": "en" },
"notifications": { "default": true }
}
}{ "language": "es", "notifications": false }{ "keyword": "/default", "instance": "", "value": {} }
{ "keyword": "/properties/language/default", "instance": "/language", "value": "en" }
{ "keyword": "/properties/notifications/default", "instance": "/notifications", "value": true }{}{ "keyword": "/default", "instance": "", "value": {} }"Hello World"{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"email": {
"default": "johndoe@acme.com",
"$ref": "#/$defs/email-address"
}
},
"$defs": {
"email-address": {
"type": "string",
"format": "email",
"default": "example@example.org"
}
}
}{ "email": "jane@foo.com" }{ "keyword": "/properties/email/default", "instance": "/email", "value": "johndoe@acme.com" }
{ "keyword": "/$defs/email-address/default", "instance": "/email", "value": "example@example.org" }{}{ "email": 1 }