Description
There's a potentially infinite amount of things we might want to know about each JSON Schema that don't have to do with how it actually validates data. For instance the title and description of a schema already have their own keywords, but these don't have any effect on validation.
I suggest we break self-describing schema info off into it's own extension to JSON Schema. For Draft 4 this wouldn't have been worth the trouble, but as we make self-describing keywords more sophisticated (for example with internationalization) it will become more important.
The concrete need for this is so that programs that already have a way to store metadata can use the structural validation parts of the JSON Schema specification without pulling in a redundant metadata specification.
First discussed here. I'm definitely open to changing the title of this issue -- perhaps "JSON Schema Documentation Extension" would be a better fit?
Activity
handrews commentedon Nov 8, 2016
I think I18N/L10N make a particularly compelling reason to split this off.
There are two regions of overlap worth special consideration:
default
: I use this at runtime in the same context as using validation, even when I am not looking at other meta-data keywords at all. Should this just be in both vocabularies with the same definition?handrews commentedon Nov 17, 2016
This is part of a larger discussion I just started on the google group https://groups.google.com/forum/#!topic/json-schema/cG4HAyerqQk
default
specification (6.2) needs fleshing out #204handrews commentedon Dec 25, 2016
As seen in #125, #204, and json-schema-org/JSON-Schema-Test-Suite#139, the presence of
default
in the validation spec makes many people (including myself years ago) assume that it takes a more active and mandatory role in validation than it actually does. Separating the annotation and validation keywords would reduce confusion.contentLang
property #114[-]JSON Schema Metadata Extension[/-][+]JSON Schema Annotation and Documentation Extension[/+]handrews commentedon Dec 28, 2016
@seagreen I saw your note that you wouldn't mind changing the title so I did :-) I kept your Documentation but added Annotation as I will explain in the next comment where I'm going to outline an initial proposal. Feel free to change it again if you don't like what I picked. I just wanted to get rid of "metadata" because to some extent, schemas are by definition metadata- they are data about some instance data. And from another point of view, things like titles are actually data.
handrews commentedon Dec 29, 2016
I can go into a lot more detail, but my basic idea is:
Annotation keywords are those that:
Pulling them into their own vocabulary lets us:
Vocabularies can put various levels of constraint (MAY, SHOULD, MUST) on usage
"default"
, the server should treat a missing value the same as if the default was present"default"
in a response schema"title"
is used as it is for RFC 5988's "title" link attribute"default"
be used to pre-populate UI input fields"title"
should be suitable for use as an input label"description"
should be suitable for use as a tooltipLarger documentation guidance can be given as part of a vocabulary (for instance hyper-schema) or as a supplemental project (such as a more all-encompassing service definition project).
Thoughts?
handrews commentedon Jan 5, 2017
See also #217 for a proposal of a hyper-schema specific default (
"messageDefault"
). This came from the larger discussion of"default"
in #204, where some support was expressed for vocabulary-specific terms rather than a single"default"
with multiple possible uses.11 remaining items