search

ga4gh / gks-core

Common classes and schemas used by all GKS specifications (ie. VR, VA, etc..)
Apache License 2.0
2 stars 0 forks source link

Resolve misuse of `$comment` #71

Open korikuzma opened 1 month ago

korikuzma commented 1 month ago

@ahwagner @larrybabb there are two comments in Statement as seen here. Which one should we go with?

From the JSON Schema documentation:

The $comment keyword is strictly intended for adding comments to a schema. Its value must always be a string. Unlike the annotations title, description, and examples, JSON schema implementations aren't allowed to attach any meaning or behavior to it whatsoever, and may even strip them at any time. Therefore, they are useful for leaving notes to future editors of a JSON schema, but should not be used to communicate to users of the schema.

It seems we should be going back and reviewing the use of $comment in this repo. For now, I think we should just leave these as-is, unless it breaks something.

RST rebuild with MSP b13 is a good catch, LGTM

Originally posted by @ahwagner in https://github.com/ga4gh/gks-common/pull/70#pullrequestreview-2311512778

larrybabb commented 1 week ago

@mbrush we need to discuss how $comment is intended to be used in json schema files and whether or not we are applying it consistently. I think @ahwagner, you and I need to walk through this so that we can find the appropriate application for the content you are adding in these fields. @ahwagner raised a few concerns in a recent review.