Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

"$comment" and JRI #9

Open
handrews opened this issue Oct 31, 2022 · 0 comments
Open

"$comment" and JRI #9

handrews opened this issue Oct 31, 2022 · 0 comments
Labels
jri Related to the JRI (JSON Referencing and Identification) proposal

Comments

@handrews
Copy link
Contributor

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:

  1. 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.
  2. include $comment as a JRI keyword with the syntax and (to the extent that they apply) semantics from JSON Schema
  3. [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.

@handrews handrews added the jri Related to the JRI (JSON Referencing and Identification) proposal label Oct 31, 2022
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
jri Related to the JRI (JSON Referencing and Identification) proposal
Projects
None yet
Development

No branches or pull requests

1 participant