in JSON Schema, $comment has a string value and guarantees that its value is not used or shown to end users in any way. In particular, its value is not collected as an annotation**.
There are three options here for JRI:
don't mention $comment at all. Extensions to JRI might end up defining different behavior which would conflict with its usage in JSON Schema (including JSON Schema within OpenAPI, AsyncAPI, etc.
include $comment as a JRI keyword with the syntax and (to the extent that they apply) semantics from JSON Schema
[what the current proposal has] Reserve $comment in the sense of ensuring that its value is not used for anything, but don't mandate its syntax or usage beyond that
I went with option 3 because I wanted to avoid conflicting behavior, but $comment was surprisingly controversial to add to JSON Schema so I figure there would be pushback for including it in JRI as a proper keyword. However, it's been noted that this approach is rather complicated and still leaves room for interoperability problems.
This issue is to discuss whether we should stick with option 3, or whether option 1 or option 2 might be better.
**title and description are annotation keywords that can be used when you want end users to see the text.
in JSON Schema,
$commenthas a string value and guarantees that its value is not used or shown to end users in any way. In particular, its value is not collected as an annotation**.There are three options here for JRI:
$commentat all. Extensions to JRI might end up defining different behavior which would conflict with its usage in JSON Schema (including JSON Schema within OpenAPI, AsyncAPI, etc.$commentas a JRI keyword with the syntax and (to the extent that they apply) semantics from JSON Schema$commentin the sense of ensuring that its value is not used for anything, but don't mandate its syntax or usage beyond thatI went with option 3 because I wanted to avoid conflicting behavior, but
$commentwas surprisingly controversial to add to JSON Schema so I figure there would be pushback for including it in JRI as a proper keyword. However, it's been noted that this approach is rather complicated and still leaves room for interoperability problems.This issue is to discuss whether we should stick with option 3, or whether option 1 or option 2 might be better.
**
titleanddescriptionare annotation keywords that can be used when you want end users to see the text.