{"action":"opened","issue":{"url":"https://api.github.com/repos/json-schema-org/json-schema-spec/issues/197","repository_url":"https://api.github.com/repos/json-schema-org/json-schema-spec","labels_url":"https://api.github.com/repos/json-schema-org/json-schema-spec/issues/197/labels{/name}","comments_url":"https://api.github.com/repos/json-schema-org/json-schema-spec/issues/197/comments","events_url":"https://api.github.com/repos/json-schema-org/json-schema-spec/issues/197/events","html_url":"https://github.com/json-schema-org/json-schema-spec/issues/197","id":195717291,"number":197,"title":"\"comment\" keyword","user":{"login":"handrews","id":2358015,"avatar_url":"https://avatars.githubusercontent.com/u/2358015?v=3","gravatar_id":"","url":"https://api.github.com/users/handrews","html_url":"https://github.com/handrews","followers_url":"https://api.github.com/users/handrews/followers","following_url":"https://api.github.com/users/handrews/following{/other_user}","gists_url":"https://api.github.com/users/handrews/gists{/gist_id}","starred_url":"https://api.github.com/users/handrews/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/handrews/subscriptions","organizations_url":"https://api.github.com/users/handrews/orgs","repos_url":"https://api.github.com/users/handrews/repos","events_url":"https://api.github.com/users/handrews/events{/privacy}","received_events_url":"https://api.github.com/users/handrews/received_events","type":"User","site_admin":false},"labels":[],"state":"open","locked":false,"assignee":null,"assignees":[],"milestone":null,"comments":0,"created_at":"2016-12-15T04:58:13Z","updated_at":"2016-12-15T04:58:13Z","closed_at":null,"body":"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.\r\n\r\nLet's reserve `\"comment\"` as a keyword.\r\n\r\nImplementations MUST NOT use `\"comment\"` in any sort of end user data presentation.\r\n\r\nImplementations 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.\r\n\r\nImplementations MAY opt to not store the comment field and its value in memory as an optimization.\r\n\r\nThere 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.\r\n\r\n`\"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.\r\n\r\nPresumably this would go in the validation spec as it is not necessary in order to make `application/schema+json` a viable media type.\r\n\r\nAs 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."}}
{"actor":{"display_login":"handrews"}}