description : String
description
StringAn explanation about the purpose of the instance described by the schema.
| Value |
This keyword must be set to a string
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.1 |
| Metaschema | https://json-schema.org/draft/2020-12/meta/meta-data |
| Official Tests | None |
| Default | None |
| Annotation |
String
The description 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 description keyword is a placeholder for a longer human-readable string
summary of what a schema or any of its subschemas are about. This keyword does
not affect validation, but the evaluator will collect its value as an
annotation.
Best Practice
We heavily recommend to declare this keyword at the top level of every schema,
as a human-readable longer description of what the schema is about.
Note that this keyword is meant to be to be used in conjunction with the
title keyword. The idea is to
augment the short summary with a longer description, and not to avoid the
concise summary altogether.
Common Pitfall
Tooling makers must be careful when statically traversing schemas in search of occurences of this keyword. It is possible for schemas to make use of this keyword behind conditional operators, references, or any other type of keyword that makes it hard or even impossible to correctly locate these values without fully evaluating the schema against an instance. The only bullet proof method is through annotation collection.
Examples
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"title": "Even Number",
"description": "This schema describes an even number",
"type": "number",
"multipleOf": 2
}10{ "keyword": "/title", "instance": "", "value": "Even number" }
{ "keyword": "/description", "instance": "", "value": "This schema describes an even number" }7{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"title": "Number",
"type": "number",
"if": { "multipleOf": 2 },
"then": { "description": "This is an even number" },
"else": { "description": "This is an odd number" }
}10{ "keyword": "/title", "instance": "", "value": "Number" }
{ "keyword": "/then/description", "instance": "", "value": "This is an even number" }7{ "keyword": "/title", "instance": "", "value": "Number" }
{ "keyword": "/else/description", "instance": "", "value": "This is an odd number" }"Hello World"