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