diff --git a/jsonschema-core.xml b/jsonschema-core.xml
index f75b45c8..c872f8fd 100644
--- a/jsonschema-core.xml
+++ b/jsonschema-core.xml
@@ -190,7 +190,8 @@
Whitespace and formatting concerns, including different lexical
representations of numbers that are equal within the data model, are thus
- outside the scope of JSON Schema. JSON Schema vocabularies that wish
+ outside the scope of JSON Schema. JSON Schema
+ vocabularies that wish
to work with such differences in lexical representations SHOULD define
keywords to precisely interpret formatted strings within the data model
rather than relying on having the original JSON representation Unicode
@@ -201,6 +202,13 @@
JSON document that tries to define two properties (the "member" production) with
the same key (the "string" production) in a single object is undefined.
+
+ Note that JSON Schema vocabularies are free to define their own extended
+ type system. This should not be confused with the core data model types
+ defined here. As an example, "integer" is a reasonable type for a
+ vocabulary to define as a value for a keyword, but the data model
+ makes no distinction between integers and other numbers.
+
@@ -261,41 +269,95 @@
fragment identifier syntax and semantics provided by
"application/schema-instance+json".
-
- A JSON Schema MUST be an object or a boolean.
-
-
- JSON Schema vocabularies can include assertions, which return a boolean result
- when applied to an instance. The boolean schema values "true" and "false"
- are trivial assertions that always return themselves regardless of the
- instance value. As an example, in terms of the validation vocabulary,
- boolean schemas are equivalent to the following behaviors:
-
- Always passes validation, as if the empty schema {}
- Always fails validation, as if the schema { "not":{} }
-
-
-
- Properties that are used to describe the instance are called keywords, or schema
- keywords.
- The meaning of properties is specified by the vocabulary that the schema is using.
-
-
- A JSON Schema MAY contain properties which are not schema keywords.
- Unknown keywords SHOULD be ignored.
-
-
- A schema that itself describes a schema is called a meta-schema.
- Meta-schemas are used to validate JSON Schemas and specify which vocabulary it
- is using.
-
-
- An empty schema is a JSON Schema with no properties, or only unknown properties.
-
-
+
+
+ A JSON Schema MUST be an object or a boolean.
+
+
+ Object properties that are applied to the instance are called keywords,
+ or schema keywords. Broadly speaking, keywords fall into one or both
+ of two categories:
+
+
+ produce a boolean result when applied to an instance
+
+
+ attach information to an instance for application use
+
+
+
+
+ Keywords may fall into either or both categories. Extension keywords,
+ meaning those defined outside of this document and its companions,
+ are free to define other behaviors as well.
+
+
+ The boolean schema values "true" and "false" are trivial assertions that
+ always return themselves regardless of the instance value. As an example,
+ in terms of the validation vocabulary, boolean schemas are equivalent to
+ the following behaviors:
+
+
+ Always passes validation, as if the empty schema {}
+
+
+ Always fails validation, as if the schema { "not":{} }
+
+
+
+
+ A JSON Schema MAY contain properties which are not schema keywords.
+ Unknown keywords SHOULD be ignored.
+
+
+ An empty schema is a JSON Schema with no properties, or only unknown
+ properties.
+
+
+
+
+ A JSON Schema vocabulary is a set of keywords defined for a particular
+ purpose. The vocabulary specifies the meaning of its keywords as
+ assertions, annotations, and/or any vocabulary-defined keyword category.
+ The two companion standards to this document each define a vocabulary:
+ One for instance validation, and one for hypermedia annotations.
+ Vocabularies are the primary mechanism for extensibility within
+ the JSON Schema media type.
+
+
+ Vocabularies may be defined by any entity. Vocabulary authors SHOULD
+ take care to avoid keyword name collisions if the vocabulary is intended
+ for broad use, and potentially combined with other vocabularies. JSON
+ Schema does not provide any formal namespacing system, but also does
+ not constrain keyword names, allowing for any number of namespacing
+ approaches.
+
+
+ Vocabularies may build on each other, such as by defining the behavior
+ of their keywords with respect to the behavior of keywords from another
+ vocabulary, or by using a keyword from another vocabulary with
+ a restricted or expanded set of acceptable values. Not all such
+ vocabulary re-use will result in a new vocabulary that is compatible
+ with the vocabulary on which it is built. Vocabulary authors SHOULD
+ clearly document what level of compatibility, if any, is expected.
+
+
+ A schema that itself describes a schema is called a meta-schema.
+ Meta-schemas are used to validate JSON Schemas and specify which vocabulary
+ it is using.
+
+ Currently, only a single meta-schema may be specified per schema,
+ meaning that in order to use multiple vocabularies, a meta-schema
+ must be written that encompasses all of them. The hyper-schema
+ meta-schema is an example of this, as it encompasses the validation
+ vocabulary as well as the hypermedia vocabulary.
+
+
+
- The root schema is the schema that comprises the entire JSON document in question.
+ The root schema is the schema that comprises the entire JSON document
+ in question.
Some keywords take schemas themselves, allowing JSON Schemas to be nested: