diff --git a/jsonschema-core.xml b/jsonschema-core.xml index 557f2747..937e5f7f 100644 --- a/jsonschema-core.xml +++ b/jsonschema-core.xml @@ -123,63 +123,124 @@ data in several ways. -
+
- JSON Schema can be used to assert constraints on a JSON document, which - either passes or fails the assertions. This approach can be used to validate - conformance with the constraints, or document what is needed to satisfy them. + JSON Schema keywords fall into several general behavior categories. + Assertions validate that an instance satisfies constraints. Annotations + attach information that applications may use in any way they see fit. + Applicators apply subschemas to parts of the instance and combine + their results. - JSON Schema implementations produce a single boolean result when evaluating - an instance against schema assertions. + Evaluating an instance against a schema involves processing all of the + keywords in the schema against the appropriate locations within the instance. + Typically, applicator keywords are processed until a schema object with no + applicators (and therefore no subschemas) is reached. The appropriate + location in the instance is evaluated against the assertion and + annotation keywords in the schema object, and their results are gathered + into the parent schema according to the rules of the applicator. - An instance can only fail an assertion that is present in the schema. - In some cases, this no-op behavior is identical to a keyword that exists with - certain values, and keyword defintions SHOULD note such values where known. - These default behaviors MUST NOT result in assertion failures. + Evaluation of a parent schema object can complete once all of its + subschemas have been evaluated, although in some circumstance evaluation + may be short-circuited due to assertion results. -
+ + Extension keywords SHOULD stay within these categories, keeping in mind + that annotations in particular are extremely flexible. Complex behavior + is usually better delegated to applications on the basis of annotation + data than implemented directly as schema keywords. However, extension + keywords MAY define other behaviors for specialized purposes. + +
- Most assertions only constrain values within a certain - primitive type. When the type of the instance is not of the type - targeted by the keyword, the instance is considered to conform - to the assertion. + Applicators allow for building more complex schemas than can be accomplished + with a single schema object. Evaluation of an instance against a + schema document begins by applying + the root schema to the complete instance + document. From there, keywords known as applicators are used to determine + which additional subschemas are applied. Subschema may be applied in-place + to the current location, or to a child location. The subschemas may be all + or part of the keyword's value, or the keyword's value may identify one + or more schemas in a way defined by the keyword. - For example, the "maxLength" keyword from the companion validation - vocabulary will only restrict certain strings - (that are too long) from being valid. If the instance is a number, - boolean, null, array, or object, then it is valid against this assertion. + Applicator keywords also define how subschema boolean + assertion + results are modified and/or combined to produce the boolean result + of the applicator. Applicators may apply any boolean logic operation + to the assertion results of subschemas, but MUST NOT introduce new + assertion conditions of their own. + + + Annotation results are + combined according to the rules specified by each annotation keyword.
-
-
- - JSON Schema can annotate an instance with information, whenever the instance - validates against the schema object containing the annotation, and all of its - parent schema objects. The information can be a simple value, or can be - calculated based on the instance contents. - - - Annotations are attached to specific locations in an instance. - Since many subschemas can be applied to any single - location, annotation keywords need to specify any unusual handling of - multiple applicable occurrences of the keyword with different values. - The default behavior is simply to collect all values. - - - Unlike assertion results, annotation data can take a wide variety of forms, - which are provided to applications to use as they see fit. JSON Schema - implementations are not expected to make use of the collected information - on behalf of applications. - - - While "short-circuit" evaluation is possible for assertions, collecting - annotations requires examining all schemas that apply to an instance - location, even if they cannot change the overall assertion result. - +
+ + JSON Schema can be used to assert constraints on a JSON document, which + either passes or fails the assertions. This approach can be used to validate + conformance with the constraints, or document what is needed to satisfy them. + + + JSON Schema implementations produce a single boolean result when evaluating + an instance against schema assertions. + + + An instance can only fail an assertion that is present in the schema. + In some cases, this no-op behavior is identical to a keyword that exists with + certain values, and keyword definitions SHOULD note such values where known. + These default behaviors MUST NOT result in assertion failures. + +
+ + Most assertions only constrain values within a certain + primitive type. When the type of the instance is not of the type + targeted by the keyword, the instance is considered to conform + to the assertion. + + + For example, the "maxLength" keyword from the companion validation + vocabulary will only restrict certain strings + (that are too long) from being valid. If the instance is a number, + boolean, null, array, or object, then it is valid against this assertion. + +
+
+ +
+ + JSON Schema can annotate an instance with information, whenever the instance + validates against the schema object containing the annotation, and all of its + parent schema objects. The information can be a simple value, or can be + calculated based on the instance contents. + + + Annotations are attached to specific locations in an instance. + Since many subschemas can be applied to any single + location, annotation keywords need to specify any unusual handling of + multiple applicable occurrences of the keyword with different values. + + + The default behavior is simply to collect all values in a list in + indeterminate order. Given the extensibility of keywords, including + applicators, it is not possible to define a universally predictable + order of processing. + + + Unlike assertion results, annotation data can take a wide variety of forms, + which are provided to applications to use as they see fit. JSON Schema + implementations are not expected to make use of the collected information + on behalf of applications. + + + While "short-circuit" evaluation is possible for assertions, collecting + annotations requires examining all schemas that apply to an instance + location, even if they cannot change the overall assertion result. + +
@@ -363,7 +424,7 @@
-
+
A JSON Schema document, or simply a schema, is a JSON document used to describe an instance. @@ -439,7 +500,7 @@ and implementations.
-
+
The root schema is the schema that comprises the entire JSON document in question. @@ -973,17 +1034,7 @@
- Evaluation of an instance against a schema begins by applying the root schema - to the complete instance document. From there, various keywords are used - to determine which additional subschemas are applied to either the current - location, or a child location. These keywords also define how subschema - assertion results are modified and/or combined. Annotation results are - combined according to the rules specified by each annotation keyword. - - - Keyword that apply subschemas are called applicators, and do not assert - conditions on their own. Rather, they control how assertions are applied - and evaluated. This section defines a set of applicator keywords that + This section defines a vocabulary of applicator keywords that are RECOMMENDED for use as the basis of other vocabularies.