Skip to content

Commit

Permalink
Split Overview into Validation, Annotation, and Vocabularies
Browse files Browse the repository at this point in the history 
This better describes the specific uses that JSON Schema supports.
The vocabulary-related prose is moved down into the relevant section.
  • Loading branch information
@awwright
awwright committed Dec 17, 2022
1 parent d29e9c4 commit 8a76bea
Showing 1 changed file with 67 additions and 38 deletions.
105 changes: 67 additions & 38 deletions jsonschema-core.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -125,57 +125,50 @@
</t>
</section>

<section title="Overview">
<!-- JSON Schema is designed for two broad use cases, which should each get their own section. -->
<section title="Validation">
<t>
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.
</t>
<t>
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.
</t>
<t>
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.
</t>
<t>
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.
</t>
</section>

<section title="Annotation">
<t>
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.
</t>
<t>
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.
</t>
<t>
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.
</t>
</section>

Expand Down Expand Up @@ -384,6 +377,42 @@
</t>
</section>
<section title="Schema Vocabularies">
<t>
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.
</t>
<t>
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.
</t>
<t>
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.
</t>
<t>
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.
</t>
<t>
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.
</t>
<t>
A schema vocabulary, or simply a vocabulary, is a set of keywords,
their syntax, and their semantics. A vocabulary is generally organized
Expand Down

0 comments on commit 8a76bea

Please sign in to comment.