Add "$comment" as a keyword #359
Conversation
This addresses issue json-schema-org#197. The primary purpose is to reserve the keyword and ensure that implementations do NOT do anything based on its presence or contents. This improves interoperability by ensuring that comments are safe for use with any conforming system. Without this keyword, two implementations may implement it with differing semantics, potentially producing undesirable or insecure behavior. Effort has been made to ensure that existing implementations that properly ignore unknown keywords will not need to make any changes at all to be in conformance for this keyword.
I noticed while adding $comment that keywords are always quoted in section headings unless the keyword is the entire heading. This is true across all three specifications, so this trivial change brings the only outlier in line with everything else.
jsonschema-core.xml
Outdated
| specification. | ||
|
|
||
| Tools that translate other media types or programming languages | ||
| to and from application/schema+json MAY choose convert that media type or |
This ensures that comments can be used in structures such as Hyper-Schema's LDOs without every specification needing to define it separately.
|
Last call- this will get merged tomorrow at the 14 day mark barring a compelling reason to reconsider. |
|
I am not a huge fan of JSON Schema attempting to step in for JSON's shortcomings. But I won't pretend to have "compelling" reason not to add this, so I suppose I'm just a -0. |
|
@Julian yeah, I think that objection was pretty solidly covered in the issue. The implementation requirements for this are literally "don't do anything" and many schema authors view it as very helpful (based on usage in teams that I have worked with, and/or reasons given for not working with JSON Schema unless allowed to use something other than JSON). |
|
It also does not attempt to be a generic comment mechanism for JSON, nor would I support it as such. Its syntax and rationale are very specific to the structure of JSON Schema, and working with JSON Schema's extensible nature and the likelihood of problems caused by clashing extensions in this area. |
This addresses issue #197. The primary purpose is to reserve the
keyword and ensure that implementations do NOT do anything based
on its presence or contents. This improves interoperability by
ensuring that comments are safe for use with any conforming system.
Without this keyword, two implementations may implement it with
differing semantics, potentially producing undesirable or
insecure behavior.
Effort has been made to ensure that existing implementations
that properly ignore unknown keywords will not need to make
any changes at all to be in conformance for this keyword.
I noticed while adding $comment that keywords are always quoted
in section headings unless the keyword is the entire heading.
This is true across all three specifications, so the trivial
second commit brings the only outlier ($ref) in line with everything else.