json-schema-org / json-schema-org/referencing

"$comment" and JRI

Open
#9 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

jri
Dominant language
Makefile
Stars
9
Forks
1
PR merge metrics
No merged PRs in 30d

Description

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.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Review the three proposed treatments of $comment in the issue and the linked referencing pull-request discussion. Compare their interoperability implications for JRI and JSON Schema, then document a maintainer-approved decision; the issue is done when one option is selected and the proposal reflects it.

Written by the indexing model from the issue text.

Assessment

Tech stack
json
Domain
backend-api-design
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.