$comment : String
$comment
StringThis keyword reserves a location for comments from schema authors to readers or maintainers of the schema.
| Value |
This keyword must be set to a string
Hint: Use the jsonschema metaschema command to catch keywords set to invalid values
|
|---|---|
| Kind | Reserved Location |
| Applies To | Any |
| Base Dialect | 2020-12 |
| Changed In | None |
| Introduced In | Draft 7 |
| Vocabulary | Core |
| Specification | https://json-schema.org/draft/2020-12/json-schema-core.html#section-8.3 |
| Metaschema | https://json-schema.org/draft/2020-12/meta/core |
| Official Tests | None |
| Default | None |
| Annotation | None |
| Affected By | None |
| Affects | None |
The $comment keyword is a standardised placeholder for explanatory string
schema comments. This keyword is completely ignored by the evaluation process
and it is possible to strip instances of this keyword when distributing your
schemas for the purpose of space-efficiency. This keyword is commonly used to
declare TODO
comments
in various parts of a schema.
Common Pitfall
Compared to other similar keywords from the Meta Data vocabulary, this keyword does not produce an annotation. Furthermore, the specification explicitly prohibits any JSON Schema tooling from inferring meaning from this keyword or elevating its contents to the end user in any way.
Digging Deeper
The JSON data format does not support any form of comments at the grammar level. While this is a common point of contention, comment support (or any other improvement) will be never added. The ECMA 404 JSON standard declares that: “it is not expected that the JSON grammar will ever change”. If this keyword is not enough, there are various other data formats that operate on the JSON data model that have comment support, like YAML and JSON5. However, JSON remains by far the preferred data format within the community, both when authoring schemas and over the wire.
Examples
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$comment": "This is an internal note about the schema that is ignored by the evaluation process",
"properties": {
"name": {
"$comment": "TODO: Add `pattern` to better validate names",
"type": "string"
}
}
}{ "name": "John Doe" }