JSON Schema Annotation and Documentation Extension

[seagreen]

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?

[handrews]

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?
• UI Schema ( [Proposal] JSON UI Schema #67 ): There's an overlap between things that are used for documentation and things that are used in UIs, but they aren't quite the same. I like the idea of having vocabularies with distinct goals, but again perhaps some things fit in both places? Or maybe UI just builds further on documentation/metadata like hyper-schema builds on validation?

[handrews]

This is part of a larger discussion I just started on the google group https://groups.google.com/forum/#!topic/json-schema/cG4HAyerqQk

[handrews]

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.

[handrews]

@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]

I can go into a lot more detail, but my basic idea is:

• Annotation keywords are those that:

  • Have a user (not a schema maintainer) as the audience
  • Do not directly impact validation, hyper-schema execution, etc.
  • May be used differently in different contexts

• Pulling them into their own vocabulary lets us:

  • Define all generally useful annotations in one place
  • Describe what information each holds, but not how the information is used
  • Reference them in each vocabulary that has a specific use for them

• Vocabularies can put various levels of constraint (MAY, SHOULD, MUST) on usage

  • The hyper-schema vocabulary might define:
    • If a request schema gives a "default", the server should treat a missing value the same as if the default was present
    • Likewise for clients and a "default" in a response schema
    • "title" is used as it is for RFC 5988's "title" link attribute
  • A UI generation vocabulary may define:
    • That the "default" be used to pre-populate UI input fields
    • That "title" should be suitable for use as an input label
    • That "description" should be suitable for use as a tooltip

• Larger 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).

  • Having the annotation fields defined on their own gives everything more flexibility in specifying how they are used
  • Being clear that the annotation spec defines only what the information is and not how it must be used will help implementors avoid assumptions about what documentation and annotation necessarily mean.

Thoughts?

[handrews]

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.