"$comment" keyword

[handrews]

[EDIT: I changed it from "comment" to "$comment" as explained in a later... um... comment]

JSON lacks comments. Comments in complex schemas are good. The "description" keyword, as a general annotation feature that is noted as being usable in interface display is not suitable for schema author-to-schema author comments.

Let's reserve "$comment" as a keyword.

Implementations MUST NOT use "$comment" in any sort of end user data presentation.

Implementations MAY choose to use the value of "$comment" in debugging messages. Similar, schema editing tools MAY make use of or encourage the use of the comment keyword.

Implementations MAY opt to not store the comment field and its value in memory as an optimization.

There is no restriction on the comment's value. While a string is the most obvious sort of comment, schema authors may decide to format comments in any way they wish. Implementations that use comments for debugging or other purposes SHOULD support strings. Schema authors inventing more complex comment forms MUST NOT assume that peer implementations will be able to understand those forms.

"$comment" would also be legal within a "$ref" object, and an implementation would still be able to use it for debugging. All other keywords would still be in the "MUST be ignored" category should they appear in a "$ref" object.

[EDIT: originally this suggested the validation spec but as noted below it really belongs in core if we have it at all]

As an obvious use case, the reviews around "jsonReference" and "notJsonReference" in the meta-schema would have been much easier if a comment field is allowed.

[erosb]

I'm not sure if it is a necessary feature. I can just hardly imagine any usecase where "description" is unsuitable for debugging and I need an other programmer-friendly "comment" too.

[handrews]

Explaining complex usage of allOf/anyOf/oneOf/not/dependencies is very useful for schema maintainers, but should not be used as a description of anything user-visible.

[erosb]

Ah-ha, now it is more understandable.

Well it an optional feature and not too complex to implement, so I don't mind it.

[handrews]

Well it an optional feature and not too complex to implement, so I don't mind it.

Yeah, the idea here is really just to reserve the keyword so that it is not co-opted by extensions.

[handrews]

Should probably actually be "$comment" in the core spec, just as comments are part of the core syntax of programming languages rather than some sort of library or extension. If a media type supports comments, that should be in the media type definition.

That will also make clear that it has nothing to do with validation or hypermedia.

[handrews]

Here is an example of how comment could be used, direct from all of the confusion that these changes for "$ref" in the meta-schema have caused in #168, #188, #194, and json-schema-org/json-schema-org.github.io#57:

{
    "$schema": "http://json-schema.org/draft/schema#",
    "id": "http://json-schema.org/draft/schema#",
    "title": "Core schema meta-schema",
    "definitions": {
        "jsonReference": {
            "type": "object",
            "properties": {
                "$ref": {
                    "type": "string",
                    "format": "uriref"
                }
            },
            "required": [ "$ref" ],
            "$comment": "We do not set '\"additionalProperties\": false' because the spec says that other properties MUST be ignored.  It does not forbid their existence."
        },
        "notJsonReference": {
            "not": {
                "required": [ "$ref" ]
            },
            "$comment": "This gets used to ensure that it is never ambiguous whether an object is or is not a JSON Reference."
        },
       "schema": {...}
    },
    "$comment": "This oneOf ensures that everything is either considered a JSON Reference, or a schema, but never both.  This is necessary because $ref requires that all other keywords are ignored, but does not forbid their existence.",
    "oneOf": [
        {
            "$comment": "Including the notJsonReference definition here ensures that if $ref is present, it will validate as a JSON Reference (the other branch of the enclosing oneOf) or it will not validate at all.  This is what we want, as only schemas withouth $ref can be treated as regular schema objects.",
            "allOf": [
                { "$ref": "#/definitions/schema" },
                { "$ref": "#/definitions/notJsonReference" }
            ]
        },
        { "$ref": "#/definitions/jsonReference" }
    ],
    "default": {}
}

[epoberezkin]

@handrews At the moment only keywords that affect validation start with $. description and title don't have it. Comment also doesn't affect validation - why does it need $ in front of it?

[handrews]

@handrews At the moment only keywords that affect validation start with $. description and title don't have it. Comment also doesn't affect validation - why does it need $ in front of it?

@epoberezkin that's not correct. Only core keywords have $. Validation does not. This is not a meta-data keyword that is part of a vocabulary that is for consumers of schemas. We already have that with description. This is for notes by and for schema maintainers about technical issues with the schema itself. You would not put that stuff about "oneOf" in a description, as description is supposed to be part of the data that an implementation uses (as help text, for instance).

So $comment is like /* .. */ in C-derived languages, or '#' in Perl, Python, etc. It's something that a debugger can use, but a production compiler just strips it out.

[handrews]

A comment feature is only useful if it is independent of all vocabularies, hence putting it in core, hence making it $comment with the $ prefix.

[epoberezkin]

@handrews I agree only core keywords have $. But all core keywords affect validation now. And you suggest introducing another core keyword that has no effect on validation. I'd rather comment be in the category where there are other keywords not affecting validation...

[handrews]

@epoberezkin how do core keywords directly affect validation?

$schema sets the meta-schema, e.g. the vocabulary. That vocabulary may not even be a validation vocabulary.

id/$id identifies and changes the base URI. No impact on validation, it's purely about how to resolve URIs, whatever those URIs do.

$ref allows a schema located elsewhere to be re-used. Depending on how you look at it, it either logically includes the referenced schema, which then behaves however it would have behaved if written in line (so validates if it is a validation schema, but if it's not a validation schema it has no validation effect). Or it simply has the result of the schema to which it refers. Which again, is a validation result if that is a validation schema, but if it is a schema using a non-validation vocabulary, $ref doesn't suddenly add validation to that non-validation vocabulary.

$ref is either an inclusion or a proxy (as we've discussed ad nauseum elsewhere), but it doesn't care what it is including or proxying.

[epoberezkin]

as we've discussed ad nauseum

lol