From 8a76beab264256ab715a8007cff15e8a6f2534bb Mon Sep 17 00:00:00 2001 From: Austin Wright Date: Fri, 16 Dec 2022 18:13:16 -0700 Subject: [PATCH] Split Overview into Validation, Annotation, and Vocabularies This better describes the specific uses that JSON Schema supports. The vocabulary-related prose is moved down into the relevant section. --- jsonschema-core.xml | 105 ++++++++++++++++++++++++++++---------------- 1 file changed, 67 insertions(+), 38 deletions(-) diff --git a/jsonschema-core.xml b/jsonschema-core.xml index fabcfedc..0ba5626f 100644 --- a/jsonschema-core.xml +++ b/jsonschema-core.xml @@ -125,57 +125,50 @@ -
+ +
- This document proposes a new media type "application/schema+json" to identify a JSON - Schema for describing JSON data. - It also proposes a further optional media type, "application/schema-instance+json", - to provide additional integration features. - JSON Schemas are themselves JSON documents. - This, and related specifications, define keywords allowing authors to describe JSON - data in several ways. + A JSON Schema describes a validator (also known as a "recognizer" or "acceptor") that classifies a provided JSON document as "accepted" or "rejected." + It supports "structural validation" (context-free grammars), and certain more complicated conditions. + However validation always follows JSON semantics, so two documents that are value-equal, but vary only by indentation, whitespace, character escapes, and property ordering, will validate with the same result. - JSON Schema uses keywords to assert constraints on JSON instances or annotate those - instances with additional information. Additional keywords are used to apply - assertions and annotations to more complex JSON data structures, or based on - some sort of condition. + With respect to a given schema, a document accepted by that schema is called an "instance." + A JSON Schema may be used to specify sets of JSON documents, by referring to the set of all instances of that schema. - To facilitate re-use, keywords can be organized into vocabularies. A vocabulary - consists of a list of keywords, together with their syntax and semantics. - A dialect is defined as a set of vocabularies and their required support - identified in a meta-schema. + A condition for accepting a document is called an "assertion". + Assertions add constraints that instances must conform to. + Given a schema and an instance, the schema "accepts" an instance whenever all the assertions are met, + and the schema "rejects" when any of the assertions fail. + In a schema without any assertion keywords, all JSON documents are accepted. - JSON Schema can be extended either by defining additional vocabularies, - or less formally by defining additional keywords outside of any vocabulary. - Unrecognized individual keywords simply have their values collected as annotations, - while the behavior with respect to an unrecognized vocabulary can be controlled - when declaring which vocabularies are in use. + Assertions are encoded into a JSON Schema using "keywords," described below. +
+ +
- This document defines a core vocabulary that MUST be supported by any - implementation, and cannot be disabled. Its keywords are each prefixed - with a "$" character to emphasize their required nature. This vocabulary - is essential to the functioning of the "application/schema+json" media - type, and is used to bootstrap the loading of other vocabularies. + A JSON Schema also describes an "annotator", a way to read an instance and return a set of "annotations." + Annotations can be any metadata describing that instance. - Additionally, this document defines a RECOMMENDED vocabulary of keywords - for applying subschemas conditionally, and for applying subschemas to - the contents of objects and arrays. Either this vocabulary or one very - much like it is required to write schemas for non-trivial JSON instances, - whether those schemas are intended for assertion validation, annotation, - or both. While not part of the required core vocabulary, for maximum - interoperability this additional vocabulary is included in this document - and its use is strongly encouraged. + For example, you can document the meaning of a property, + suggest a default value for new instances, + generate a list of hyperlinks from the instance, + or declare relationships between data. + Applications may make use of annotations to query for arbitrary information; + for example, to extract a list of names from a document with a known structure. + Annotations may also describe values within the instance in a standard way; + for example, extracting a common type of hyperlink from many different types of documents, using a different schema for type. - Further vocabularies for purposes such as structural validation or - hypermedia annotation are defined in other documents. These other - documents each define a dialect collecting the standard sets of - vocabularies needed to write schemas for that document's purpose. + Like assertions, the rules governing annotations are encoded in a JSON Schema using keywords. + Annotations are only produced from instances (documents accepted by the schema), + and may only be meaningful with instances known by the application to be meaningful. + That is, if you generate an arbitrary instance with nonsense data, + the resulting annotations will not necessarily be true, even though the input is valid.
@@ -384,6 +377,42 @@
+ + To facilitate re-use, keywords can be organized into vocabularies. A vocabulary + consists of a list of keywords, together with their syntax and semantics. + A dialect is defined as a set of vocabularies and their required support + identified in a meta-schema. + + + JSON Schema can be extended either by defining additional vocabularies, + or less formally by defining additional keywords outside of any vocabulary. + Unrecognized individual keywords simply have their values collected as annotations, + while the behavior with respect to an unrecognized vocabulary can be controlled + when declaring which vocabularies are in use. + + + This document defines a core vocabulary that MUST be supported by any + implementation, and cannot be disabled. Its keywords are each prefixed + with a "$" character to emphasize their required nature. This vocabulary + is essential to the functioning of the "application/schema+json" media + type, and is used to bootstrap the loading of other vocabularies. + + + Additionally, this document defines a RECOMMENDED vocabulary of keywords + for applying subschemas conditionally, and for applying subschemas to + the contents of objects and arrays. Either this vocabulary or one very + much like it is required to write schemas for non-trivial JSON instances, + whether those schemas are intended for assertion validation, annotation, + or both. While not part of the required core vocabulary, for maximum + interoperability this additional vocabulary is included in this document + and its use is strongly encouraged. + + + Further vocabularies for purposes such as structural validation or + hypermedia annotation are defined in other documents. These other + documents each define a dialect collecting the standard sets of + vocabularies needed to write schemas for that document's purpose. + A schema vocabulary, or simply a vocabulary, is a set of keywords, their syntax, and their semantics. A vocabulary is generally organized