Skip to content

"$comment" and JRI #9

Open
Open
@handrews

Description

@handrews

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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    jriRelated to the JRI (JSON Referencing and Identification) proposal

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions