Expand the Overview section to put some context to vocabularies

Author: awwright

jsonschema-core.xml

@@ -135,13 +135,67 @@
                 data in several ways.
             </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.
+                A JSON Schema document is comprised of a set of keywords,
+                which are specified as properties in a JSON object.
+                The name of the keyword is used as the property name,
+                and any arguments to the keyword are provided as the value.
+                Keywords can be classified by their functions.
+                The most important classes are assertion, annotation, and applicator keywords.
             </t>
             <t>
-                To facilitate re-use, keywords can be organized into vocabularies. A vocabulary
+                "Assertion keywords" form the basis of JSON Schema.
+                Given a schema and an instance, the instance is "valid" if all of the keywords in
+                the schema are valid against the instance.
+                Assertion keywords may be used to describe a set of JSON documents.
+                Without any assertion keywords, the set of all valid instances is the set of all valid JSON documents.
+                Typically, adding assertion keywords reduces the set of valid JSON documents.
+                Keywords are defined to not be redundant with other keywords:
+                For example, the "minimum" keyword only shrinks the valid set of numbers, but not strings or other
+                types&#x2014;this is what the "type" keyword does.
+            </t>
+            <t>
+                When an instance validates against a schema, "annotation keywords" may provide "annotations":
+                metadata that describes the instance.
+                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.
+            </t>
+            <t>
+                "Applicator keywords" are keywords that accept sub-schemas as part of their argument,
+                which are validated against the instance in some fashion.
+                Applicator keywords may use or modify the validation result of their sub-schemas,
+                for example, to be valid conditional on which sub-schemas are valid
+                (e.g. the "if", "then", "oneOf", or "anyOf" keywords).
+                They may also validate a schema against values within the instance,
+                for example, a specific property within the object (the "properties" keyword).
+                The "$ref" keyword is a special applicator keyword that takes a reference to a schema,
+                instead of a literal schema. This allows schemas to be defined recursively.
+            </t>
+            <t>
+                Applicator keywords typically also return the annotations from their valid schemas.
+                Since only annotations from valid schemas can be returned,
+                applicator keywords may be used to specify annotations that conditionally appear,
+                depending on the validation result of other keywords.
+            </t>
+            <t>
+                Since keywords are listed in an object by their name,
+                they may be used at most once per schema and sub-schema.
+                However, the effect of multiple keywords may be achieved by listing each keyword in its own sub-schema,
+                inside an applicator keyword designed for this purpose, such as the "allOf" keyword.
+                Additionally, many keywords can often be reduced to a single keyword;
+                for example, when using "minimum", only the highest value of many will be effective.
+                Schemas may also be a boolean value:
+                The booleans true/false represent a schema that's always valid/invalid, respectively.
+            </t>
+            <t>
+                JSON Schema documents can themselves be described by a schema.
+                In this context, this "schema of the schema" is called the meta-schema.
+                In addition to a core vocabulary and a default validation vocabulary,
+                JSON Schema supports some amount of customization by providing a custom meta-schema.
+            </t>
+            <t>
+                To facilitate re-use, the meta-schema organizes keywords 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.