search

ldexterldesign / BUY-SELL

💵 A schema (made from https://json-schema.org + https://schema.org) to help me record/reference when buying/selling things (and perhaps you too?)
0 stars 0 forks source link

Transfer $comment to description (annotation) #7

Closed ldexterldesign closed 3 years ago

ldexterldesign commented 4 years ago

The $comment keyword is strictly intended for adding comments to the JSON schema source. 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, (which is quite likely your future self), but should not be used to communicate to users of the schema.

"eligibleRegion": {
    "$comment": "Do use ISO 3166-1 alpha-3 three-letter country codes http://en.wikipedia.org/wiki/ISO_3166-1_alpha-3",
    "examples": [
        "mlt",
        "gbr"
    ],
    "items": {
        "type": "string"
    },
    "s:additionalType": "http://schema.org/Text",
    "s:sameAs": "http://schema.org/eligibleRegion",
    "type": "array"
}

"totalPriceUnit": {
    "$comment": "totalPrice / unitPriceSpecification.referenceQuantity",
    "type": "number"
}

Both of these $comments are instructions to users so should not be $comments according to spec'. Transfer to description annotations.