json-schema-org
Proposal: Don't allow $comment to be used in debug or error output
The spec says the following regarding the $comment keyword:
The value of this keyword MAY be used in debug or error output which is intended for developers making use of schemas.
I've noticed this before and keep forgetting to bring it up. I think this a bad idea. Comments should not be used for anything by the implementations. I'd like to remove this and strengthen the language that implementations MUST NOT use comments for anything. What do you think?
I think it's fine as is.
The value of this keyword MUST be a string. Implementations MUST NOT present this string to end users. Tools for editing schemas SHOULD support displaying and editing this keyword. The value of this keyword MAY be used in debug or error output which is intended for developers making use of schemas.
In particular, the second sentence does this for me.
Implementations MUST NOT present this string to end users.
This, to me, says that implementations can have a debug mode that handles them. The dev is not the end user, so that's fine. I suppose it then becomes the dev's responsibility to disable that mode before production.
If we take this kind of debug output away, then the only way to see these is by looking at the schema itself.
Do we see people abusing this? What is the harm? What are we really trying to prevent?
This, to me, says that implementations can have a debug mode that handles them. The dev is not the end user, so that's fine. I suppose it then becomes the dev's responsibility to disable that mode before production.
If we take this kind of debug output away, then the only way to see these is by looking at the schema itself.
But what would a debug mode do with comments? What kind of debug output are you thinking of where this would be useful? It seems to me that the only place it makes sense to look at comments is in the schema itself. What am I missing? Maybe an example could help.
Do we see people abusing this? What is the harm? What are we really trying to prevent?
These are good questions that I don't really have an answer for. I have one more. What are we trying to enable? I don't have an answer for that either. Mostly, the current text doesn't make sense to me. The most important thing to me is to change it to something that makes sense. The change I proposed accomplishes that goal, but if there's another way to change it that also makes sense, I'm ok with that too.
The only case I can think of where comments are used for anything other than schema reader notes is things like tooling directives. For example, a linter could look for a specific string in a comment to disable a linting rule for some part of the schema. For example, in our spec markdown we use comments to ignore linting rules: <!-- lint ignore rule-name -->. Eslint does something very similar in JavaScript: // eslint-diable-next-line rule-name. I was considering doing something similar for test coverage tool I created recently to ignore coverage for parts of a schema.
It would be good to discuss whether that's something we want to enable, or if we prefer people use custom keywords instead. If we don't want people using comments in that way, I don't understand what we're trying to enable by allowing them to do something with comments.
I'm going to go ahead with this. I'm going to rewrite it because it doesn't make sense to me and no one has offered an explanation. I plan to go with a fairly permissive definition restricting $comment from being able to affect validation or annotation, but allowing it to be used for things like tooling directives.