Expand the Overview section to put some context to vocabularies

Author: awwright

jsonschema-core.xml

@@ -51,7 +51,7 @@
             </address>
         </author>
 
-        <date year="2021"/>
+        <date year="2022"/>
         <workgroup>Internet Engineering Task Force</workgroup>
         <keyword>JSON</keyword>
         <keyword>Schema</keyword>
@@ -134,13 +134,63 @@
                 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.
+                Validation keywords can serve several different functions.
+                The most important types are validation, applicator, and annotation keywords.
             </t>
             <t>
-                To facilitate re-use, keywords can be organized into vocabularies. A vocabulary
+                "Validation 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.
+                Validation keywords may be used to describe a set of JSON documents.
+                Without any validation keywords, the set of all valid instances is the set of all valid JSON documents.
+                Typically, adding validation keywords creates a subset.
+            </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 a schema as part of their argument,
+                which is applied to 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 inststance,
+                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 can be achieved by listing each keyword in a different 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.
+                There are also schemas besides JSON objects:
+                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, the "schema of a 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.