From f3baa77124bb50b3a7000052908fe2dacf5453a8 Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Wed, 21 Mar 2018 11:23:14 -0700 Subject: [PATCH 1/8] Reorganize assertion/annotation/vocab explanations This reworks both Overview sections in preparation for moving the applicators to Core. The Core overview now covers the generic capabilities (assertion, annotation, and vocabularies), leaving the Validation overview to simply reference the concepts. Rather than noting the standard vocabularies in the top-level Core overview, they are moved in with the overview of vocabularies. Validation and basic meta-data are listed as separate vocabularies, which is consistent with how they have been described to date. Exactly how "format" and the "content*" keywords are classified into vocabularies will be finalized in future commits. The applicators are mentioned as a separate vocabulary in the core spec, although they are not moved over yet in this commit. The descriptive text about applicators which is removed from the Validation overview in this commit will be restored to the Core spec when the vocabulary is moved. There is some duplications as well as the above-mentioned ommission as a result of this change, which will be addressed in subsequent commits. --- jsonschema-core.xml | 122 ++++++++++++++++++++++----- jsonschema-validation.xml | 171 +++++--------------------------------- 2 files changed, 124 insertions(+), 169 deletions(-) diff --git a/jsonschema-core.xml b/jsonschema-core.xml index c3b63621..393304ce 100644 --- a/jsonschema-core.xml +++ b/jsonschema-core.xml @@ -123,44 +123,126 @@ data in several ways. -
+
- JSON Schema describes the structure of a JSON document (for instance, required - properties and length limitations). - Applications can use this information to validate instances (check that - constraints are met), or inform interfaces to collect user input such that the - constraints are satisfied. + 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. - Validation behaviour and keywords are specified in - a separate document. + 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 defintions 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. + parent schema objects. The information can be a simple value, or can be + calculated based on the instance contents. - Detailed annotation behavior, along with a small set of basic annotation - keywords are defined in - the validation specification. + 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 Hyper-Schema describes the hypertext structure of a JSON document. - This includes link relations from the instance to other resources, - interpretation of instances as multimedia data, and submission data required to - use an API. + JSON Schema keywords are grouped into vocabularies to encourage + modularity and re-use. Several vocabularies are provided as + standards in this and closely related documents. These vocabularies + are used with the core keywords defined as fundamental to the + "application/schema+json" media type. - Hyper-schema behaviour and keywords are specified in - a separate document. + Schema authors are encouraged to define their own vocabularies for + domain-specific concepts. A vocabulary need not be a standard to + be re-usable, although users of extension vocabularies MUST NOT + assume that any JSON Schema implementation can support the vocabulary + unless it specifically documents such support. +
+ + This vocabulary provides keywords for applying subschemas to the + instance in various ways. It is defined in this document, and + it is RECOMMENDED that all JSON Schema implementations support it. + All other vocabularies in this section are designed to be used + alongside the subschema application vocabulary. + + + Without this vocabulary or an equivalent one, JSON Schema can only + be applied to a JSON document as a whole. In most cases, schema + keywords need to be applied to specific object properties or array items. + +
+
+ + This vocabulary describes the structure of a JSON document + (for instance, required properties and length limitations). + Applications can use this information to validate instances (check that + constraints are met), or inform interfaces to collect user input + such that the constraints are satisfied. + + + Validation behaviour and keywords are specified in + a separate document. + +
+
+ + A small set of annotation keywords are defined in + the validation specification + to allow associating common kinds of meta-data with an instance. + +
+
+ + JSON Hyper-Schema produces hyperlinks as annotations available for + use with a JSON document. It supports resolving URI Templates + and describing the resource and data submission formats required + to use an API. + + + Hyper-schema behaviour and keywords are specified in + a separate document. + +
diff --git a/jsonschema-validation.xml b/jsonschema-validation.xml index 1d1d6ed9..4477c691 100644 --- a/jsonschema-validation.xml +++ b/jsonschema-validation.xml @@ -129,8 +129,7 @@
- JSON Schema validation applies schemas to locations within the instance, - and asserts constraints on the structure of the data at each location. + JSON Schema validation asserts constraints on the structure of instance data. An instance location that satisfies all asserted constraints is then annotated with any keywords that contain non-assertion information, such as descriptive metadata and usage hints. If all locations within @@ -143,139 +142,13 @@ for validators by ensuring that they do not need to maintain state across the document-wide validation process. -
- - Validation 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 whether and how subschema assertion results are - modified and/or combined. Such keywords do not assert conditions on their - own. Rather, they control how assertions are applied and evaluated. - - - The keywords in the boolean logic and - conditional sections of this specification - apply subschemas to the same location as the parent schema. The former group - defines boolean operations on the subschema assertion results, while the - latter evaluates one subschema and uses its assertion results to determine - which of two other subschemas to apply as well. - - - Several keywords determine which subschemas are applied to array items, - object property values, and object property names. They are: - "items", "additionalItems", "contains", "properties", "patternProperties", - "additionalProperties", and "propertyNames". The "contains" keyword only - requires its subschema to be valid against at least one child instance, while - the other keywords require that all subschemas are valid against all child - instances to which they apply. - -
- - Validation keywords typically operate independently, without - affecting each other's outcomes. - - - For schema author convenience, there are some exceptions among the - keywords that control subschema applicability: - - - "additionalProperties", whose behavior is defined in terms of - "properties" and "patternProperties"; and - - - "additionalItems", whose behavior is defined in terms of "items". - - - -
-
-
- - Validation is a process of checking assertions. Each assertion adds - constraints that an instance must satisfy in order to successfully validate. - - - Assertion keywords that are absent never restrict validation. - In some cases, this no-op behavior is identical to a keyword that exists with - certain values, and these values are noted where known. - - - All of the keywords in the general, - numeric, and string - sections are assertions, as well as "minItems", "maxItems", "uniqueItems", - "minProperties", "maxProperties", and "required". Additionally, "dependencies" - is shorthand for a combination of conditional and assertion keywords. - - - The "format", "contentType", and "contentEncoding" keywords can also be - implemented as assertions, although that functionality is an optional part - of this specification, and the keywords convey additional non-assertion - information. - -
- - Most validation 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 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. - -
-
-
- - In addition to assertions, this specification provides a small vocabulary - of metadata keywords that can be used to annotate the JSON instance with - useful information. The and - keywords are also useful as annotations as well as being optional assertions, - as they convey additional usage guidance for the instance data. - - - A schema that is applicable to a particular location in the instance, against - which the instance location is valid, attaches its annotations to that location - in the instance. Since many subschemas can be applicable 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. - - - Additional vocabularies SHOULD make use of this mechanism for applying - their own annotations to instances. - -
- - Annotations are collected whenever an instance is valid against - a schema object, and all of that schema object's parent schemas. - - - In particular, annotations in a subschema contained within a "not", - at any depth, including any number of intervening additional "not" - subschemas, MUST be ignored. If the instance was valid against the - "not" subschema, then by definition it is not valid against the schema - that contains the "not", so the "not" subschema's annotations are not used. - - - Similarly, annotations within a failing branch of a "oneOf", "anyOf", - "then", or "else" MUST be ignored even when the instance successfully - validates against the complete schema document. - -
-
- - Annotation keywords MUST be applied to all possible sub-instances. - Even if such application can be short-circuited when only assertion - evaluation is needed. For instance, the "contains" keyword need only - be checked for assertions until at least one array item proves valid. - However, when working with annotations, all items in the array must - be evaluated to determine all items with which the annotations should - be associated. - -
-
+ + This specification defines a set of assertion keywords, as well as a small vocabulary + of metadata keywords that can be used to annotate the JSON instance with + useful information. The and + keywords are also useful as annotations as well as being optional assertions, + as they convey additional usage guidance for the instance data. +
@@ -336,15 +209,24 @@
- The current URI for the JSON Schema Validation is + The current URI for the JSON Schema Validation meta-schema is . + This meta-schema describes the core keywords, the subschema application + vocabulary from the core specification, and all keywords + defined by this specification. All implementations of this specification + SHOULD support the subschema application vocabulary, and MUST NOT + implement behavior that contradicts that vocabulary.
Validation keywords in a schema impose requirements for successful validation of an - instance. + instance. These keywords are all assertions without any annotation behavior. + + "dependencies" has applicator behavior, but this keyword will be split + into separate assertion and applicator keywords before the next draft publication. +
@@ -899,8 +781,7 @@
The "format" keyword functions as both an annotation - () and as an assertion - (). While no special effort is required to + and as an assertion. While no special effort is required to implement it as an annotation conveying semantic meaning, implementing validation is non-trivial. @@ -1130,9 +1011,7 @@
- The content keywords function as both annotations - () and as assertions - (). + The content keywords function as both annotations and as assertions. While no special effort is required to implement them as annotations conveying how applications can interpret the data in the string, implementing validation of conformance to the media type and encoding is non-trivial. @@ -1233,13 +1112,7 @@
-
- - Schema validation is a useful mechanism for annotating instance data - with additional information. The rules for determining when and how - annotations are associated with an instance are outlined in section - . - +
These general-purpose annotation keywords provide commonly used information for documentation and user interface display purposes. They are not intended From 814dd1c902d7919697b777d9b212db01139aab8d Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Wed, 21 Mar 2018 15:53:27 -0700 Subject: [PATCH 2/8] Rework JSON Schema values definitions This adds applicators to the list of keyword types, splits the boolean schemas into their own section, and promotes the "MUST be an object or a boolean" paragraph to the containing section's introduction. --- jsonschema-core.xml | 62 ++++++++++++++++++++++++++++++--------------- 1 file changed, 41 insertions(+), 21 deletions(-) diff --git a/jsonschema-core.xml b/jsonschema-core.xml index 393304ce..8e425c78 100644 --- a/jsonschema-core.xml +++ b/jsonschema-core.xml @@ -370,14 +370,14 @@ fragment identifier syntax and semantics provided by "application/schema-instance+json". -
- - A JSON Schema MUST be an object or a boolean. - + + 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: + or schema keywords. Broadly speaking, keywords fall into one + of three categories: produce a boolean result when applied to an instance @@ -385,26 +385,21 @@ attach information to an instance for application use + + apply one or more subschemas to a particular location + in the instance, and combine or modify their results + - 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. + Keywords may fall into multiple categories, although applicators + SHOULD only produce assertion results based on their subschemas' + results. They should not define additional constraints independent + of their subschemas. - 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":{} } - - + Extension keywords, meaning those defined outside of this document + and its companions, are free to define other behaviors as well. A JSON Schema MAY contain properties which are not schema keywords. @@ -415,6 +410,31 @@ properties.
+
+ + The boolean schema values "true" and "false" are trivial schemas that + always produce themselves as assertions results, regardless of the + instance value. They never produce annotation results. + + + These boolean schemas exist to clarify schema author intent and + facilitate schema processing optimizations. They behave identically + to the following schema objects (where "not" is part of the + subschema application vocabulary defined in this document). + + + Always passes validation, as if the empty schema {} + + + Always fails validation, as if the schema { "not":{} } + + + While the empty schema object is unambiguous, there are many + possible equivalents to the "false" schema. Using the boolean + values ensures that the intent is clear to both human readers + and implementations. + +
A JSON Schema vocabulary is a set of keywords defined for a particular From ac5585eaa9fb61b40709864c8eae3c31e8bad09e Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Wed, 21 Mar 2018 15:56:03 -0700 Subject: [PATCH 3/8] Reorganize vocabularies text A bit of it moves into the vocabulary section of the Overview, while the rest moves into "Extending JSON Schema" which already covered individual keyword extensions. There will befurther work in this area before the next publication as we formalize the vocabulary concept. --- jsonschema-core.xml | 81 +++++++++++++++++++-------------------------- 1 file changed, 34 insertions(+), 47 deletions(-) diff --git a/jsonschema-core.xml b/jsonschema-core.xml index 8e425c78..8d1c67ac 100644 --- a/jsonschema-core.xml +++ b/jsonschema-core.xml @@ -182,10 +182,14 @@
-
+
- JSON Schema keywords are grouped into vocabularies to encourage - modularity and re-use. Several vocabularies are provided as + 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. + + + Several vocabularies are provided as standards in this and closely related documents. These vocabularies are used with the core keywords defined as fundamental to the "application/schema+json" media type. @@ -435,46 +439,6 @@ and implementations.
-
- - 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 @@ -577,10 +541,33 @@
- Implementations MAY define additional keywords to JSON Schema. Save - for explicit agreement, schema authors SHALL NOT expect these additional - keywords to be supported by peer implementations. Implementations SHOULD ignore - keywords they do not support. + Additional schema keywords and schema vocabularies MAY be defined + by any entity. Save for explicit agreement, schema authors SHALL NOT + expect these additional keywords and vocabularies to be supported by + implementations that do not explicitly document such support. + Implementations SHOULD ignore keywords they do not support. + + + 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. Authors of extensions to JSON Schema are encouraged to write their own From b28bd3991150411f5518d151ce7590a87dcbe847 Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Thu, 15 Mar 2018 13:30:22 -0700 Subject: [PATCH 4/8] Move applicability keywords and text to core This just moves text, with the bare minimum title, link target, and indentation changes necessary to make it fit in the core spec. The Applicability overview section becomes the intro to the applicability vocabulary, which is followed by the keywords. Further commits will rework the wording for the new arrangement and probably further re-organize the applicability overview. Note that "dependencies" is left in the validation spec, as splitting it is more complex and will be done entirely separately after the basic applicability move is complete. --- jsonschema-core.xml | 324 +++++++++++++++++++++++++++++++++++++- jsonschema-validation.xml | 266 ------------------------------- 2 files changed, 323 insertions(+), 267 deletions(-) diff --git a/jsonschema-core.xml b/jsonschema-core.xml index 8d1c67ac..10f36c1b 100644 --- a/jsonschema-core.xml +++ b/jsonschema-core.xml @@ -155,7 +155,7 @@
-
+
JSON Schema can annotate an instance with information, whenever the instance validates against the schema object containing the annotation, and all of its @@ -971,6 +971,328 @@
+
+ + Validation 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 whether and how subschema assertion results are + modified and/or combined. Such keywords do not assert conditions on their + own. Rather, they control how assertions are applied and evaluated. + + + The keywords in the boolean logic and + conditional sections of this specification + apply subschemas to the same location as the parent schema. The former group + defines boolean operations on the subschema assertion results, while the + latter evaluates one subschema and uses its assertion results to determine + which of two other subschemas to apply as well. + + + Several keywords determine which subschemas are applied to array items, + object property values, and object property names. They are: + "items", "additionalItems", "contains", "properties", "patternProperties", + "additionalProperties", and "propertyNames". The "contains" keyword only + requires its subschema to be valid against at least one child instance, while + the other keywords require that all subschemas are valid against all child + instances to which they apply. + +
+ + Validation keywords typically operate independently, without + affecting each other's outcomes. + + + For schema author convenience, there are some exceptions among the + keywords that control subschema applicability: + + + "additionalProperties", whose behavior is defined in terms of + "properties" and "patternProperties"; and + + + "additionalItems", whose behavior is defined in terms of "items". + + + +
+ +
+ +
+
+ + This keyword's value MUST be a non-empty array. + Each item of the array MUST be a valid JSON Schema. + + + An instance validates successfully against this keyword if it validates + successfully against all schemas defined by this keyword's value. + +
+ +
+ + This keyword's value MUST be a non-empty array. + Each item of the array MUST be a valid JSON Schema. + + + An instance validates successfully against this keyword if it validates + successfully against at least one schema defined by this keyword's value. + +
+ +
+ + This keyword's value MUST be a non-empty array. + Each item of the array MUST be a valid JSON Schema. + + + An instance validates successfully against this keyword if it validates + successfully against exactly one schema defined by this keyword's value. + +
+ +
+ + This keyword's value MUST be a valid JSON Schema. + + + An instance is valid against this keyword if it fails to validate + successfully against the schema defined by this keyword. + +
+
+ +
+ + These keywords work together to implement conditional + application of a subschema based on the outcome of + another subschema. + + + These keywords MUST NOT interact with each other across + subschema boundaries. In other words, an "if" in one + branch of an "allOf" MUST NOT have an impact on a "then" + or "else" in another branch. + + + There is no default behavior for any of these keywords + when they are not present. In particular, they MUST NOT + be treated as if present with an empty schema, and when + "if" is not present, both "then" and "else" MUST be + entirely ignored. + +
+ + This keyword's value MUST be a valid JSON Schema. + + + This validation outcome of this keyword's subschema + has no direct effect on the overall validation + result. Rather, it controls which of the "then" + or "else" keywords are evaluated. + + + Instances that successfully validate against this + keyword's subschema MUST also be valid against + the subschema value of the "then" keyword, if + present. + + + Instances that fail to validate against this + keyword's subschema MUST also be valid against + the subschema value of the "else" keyword, if + present. + + + If annotations + are being collected, they are collected from this + keyword's subschema in the usual way, including when + the keyword is present without either "then" or "else". + +
+
+ + This keyword's value MUST be a valid JSON Schema. + + + When "if" is present, and the instance successfully + validates against its subschema, then valiation + succeeds against this keyword if the instance also + successfully validates against this keyword's subschema. + + + This keyword has no effect when "if" is absent, or + when the instance fails to validate against its + subschema. Implementations MUST NOT evaluate + the instance against this keyword, for either validation + or annotation collection purposes, in such cases. + +
+
+ + This keyword's value MUST be a valid JSON Schema. + + + When "if" is present, and the instance fails to + validate against its subschema, then valiation + succeeds against this keyword if the instance + successfully validates against this keyword's subschema. + + + This keyword has no effect when "if" is absent, or + when the instance successfully validates against its + subschema. Implementations MUST NOT evaluate + the instance against this keyword, for either validation + or annotation collection purposes, in such cases. + +
+
+
+
+
+
+ + The value of "items" MUST be either a valid JSON Schema or an array of valid + JSON Schemas. + + + This keyword determines how child instances validate for arrays, + and does not directly validate the immediate instance itself. + + + If "items" is a schema, validation succeeds if all elements + in the array successfully validate against that schema. + + + If "items" is an array of schemas, validation succeeds if + each element of the instance validates against the schema at the + same position, if any. + + + Omitting this keyword has the same behavior as an empty schema. + +
+ +
+ + The value of "additionalItems" MUST be a valid JSON Schema. + + + This keyword determines how child instances validate for arrays, + and does not directly validate the immediate instance itself. + + + If "items" is an array of schemas, validation succeeds + if every instance element at a position greater than the size + of "items" validates against "additionalItems". + + + Otherwise, "additionalItems" MUST be ignored, as the "items" + schema (possibly the default value of an empty schema) is + applied to all elements. + + + Omitting this keyword has the same behavior as an empty schema. + +
+ +
+ + The value of this keyword MUST be a valid JSON Schema. + + + An array instance is valid against "contains" if at least one of + its elements is valid against the given schema. + +
+
+ +
+
+ + The value of "properties" MUST be an object. + Each value of this object MUST be a valid JSON Schema. + + + This keyword determines how child instances validate for objects, + and does not directly validate the immediate instance itself. + + + Validation succeeds if, for each name that appears in both + the instance and as a name within this keyword's value, the child + instance for that name successfully validates against the + corresponding schema. + + + Omitting this keyword has the same behavior as an empty object. + +
+ +
+ + The value of "patternProperties" MUST be an object. Each property name + of this object SHOULD be a valid regular expression, according to the + ECMA 262 regular expression dialect. Each property value of this object + MUST be a valid JSON Schema. + + + This keyword determines how child instances validate for objects, + and does not directly validate the immediate instance itself. + Validation of the primitive instance type against this keyword + always succeeds. + + + Validation succeeds if, for each instance name that matches any + regular expressions that appear as a property name in this keyword's value, + the child instance for that name successfully validates against each + schema that corresponds to a matching regular expression. + + + Omitting this keyword has the same behavior as an empty object. + +
+ +
+ + The value of "additionalProperties" MUST be a valid JSON Schema. + + + This keyword determines how child instances validate for objects, + and does not directly validate the immediate instance itself. + + + Validation with "additionalProperties" applies only to the child + values of instance names that do not match any names in "properties", + and do not match any regular expression in "patternProperties". + + + For all such properties, validation succeeds if the child instance + validates against the "additionalProperties" schema. + + + Omitting this keyword has the same behavior as an empty schema. + +
+ +
+ + The value of "propertyNames" MUST be a valid JSON Schema. + + + If the instance is an object, this keyword validates if every property name in + the instance validates against the provided schema. + Note the property name that the schema is testing will always be a string. + + + Omitting this keyword has the same behavior as an empty schema. + +
+
+
+
+
diff --git a/jsonschema-validation.xml b/jsonschema-validation.xml index 4477c691..ef359ad6 100644 --- a/jsonschema-validation.xml +++ b/jsonschema-validation.xml @@ -375,51 +375,6 @@
-
- - The value of "items" MUST be either a valid JSON Schema or an array of valid - JSON Schemas. - - - This keyword determines how child instances validate for arrays, - and does not directly validate the immediate instance itself. - - - If "items" is a schema, validation succeeds if all elements - in the array successfully validate against that schema. - - - If "items" is an array of schemas, validation succeeds if - each element of the instance validates against the schema at the - same position, if any. - - - Omitting this keyword has the same behavior as an empty schema. - -
- -
- - The value of "additionalItems" MUST be a valid JSON Schema. - - - This keyword determines how child instances validate for arrays, - and does not directly validate the immediate instance itself. - - - If "items" is an array of schemas, validation succeeds - if every instance element at a position greater than the size - of "items" validates against "additionalItems". - - - Otherwise, "additionalItems" MUST be ignored, as the "items" - schema (possibly the default value of an empty schema) is - applied to all elements. - - - Omitting this keyword has the same behavior as an empty schema. - -
@@ -457,16 +412,6 @@ Omitting this keyword has the same behavior as a value of false.
- -
- - The value of this keyword MUST be a valid JSON Schema. - - - An array instance is valid against "contains" if at least one of - its elements is valid against the given schema. - -
@@ -509,72 +454,6 @@
-
- - The value of "properties" MUST be an object. - Each value of this object MUST be a valid JSON Schema. - - - This keyword determines how child instances validate for objects, - and does not directly validate the immediate instance itself. - - - Validation succeeds if, for each name that appears in both - the instance and as a name within this keyword's value, the child - instance for that name successfully validates against the - corresponding schema. - - - Omitting this keyword has the same behavior as an empty object. - -
- -
- - The value of "patternProperties" MUST be an object. Each property name - of this object SHOULD be a valid regular expression, according to the - ECMA 262 regular expression dialect. Each property value of this object - MUST be a valid JSON Schema. - - - This keyword determines how child instances validate for objects, - and does not directly validate the immediate instance itself. - Validation of the primitive instance type against this keyword - always succeeds. - - - Validation succeeds if, for each instance name that matches any - regular expressions that appear as a property name in this keyword's value, - the child instance for that name successfully validates against each - schema that corresponds to a matching regular expression. - - - Omitting this keyword has the same behavior as an empty object. - -
- -
- - The value of "additionalProperties" MUST be a valid JSON Schema. - - - This keyword determines how child instances validate for objects, - and does not directly validate the immediate instance itself. - - - Validation with "additionalProperties" applies only to the child - values of instance names that do not match any names in "properties", - and do not match any regular expression in "patternProperties". - - - For all such properties, validation succeeds if the child instance - validates against the "additionalProperties" schema. - - - Omitting this keyword has the same behavior as an empty schema. - -
-
@@ -610,151 +489,6 @@ Omitting this keyword has the same behavior as an empty object.
- -
- - The value of "propertyNames" MUST be a valid JSON Schema. - - - If the instance is an object, this keyword validates if every property name in - the instance validates against the provided schema. - Note the property name that the schema is testing will always be a string. - - - Omitting this keyword has the same behavior as an empty schema. - -
-
- -
- - These keywords work together to implement conditional - application of a subschema based on the outcome of - another subschema. - - - These keywords MUST NOT interact with each other across - subschema boundaries. In other words, an "if" in one - branch of an "allOf" MUST NOT have an impact on a "then" - or "else" in another branch. - - - There is no default behavior for any of these keywords - when they are not present. In particular, they MUST NOT - be treated as if present with an empty schema, and when - "if" is not present, both "then" and "else" MUST be - entirely ignored. - -
- - This keyword's value MUST be a valid JSON Schema. - - - This validation outcome of this keyword's subschema - has no direct effect on the overall validation - result. Rather, it controls which of the "then" - or "else" keywords are evaluated. - - - Instances that successfully validate against this - keyword's subschema MUST also be valid against - the subschema value of the "then" keyword, if - present. - - - Instances that fail to validate against this - keyword's subschema MUST also be valid against - the subschema value of the "else" keyword, if - present. - - - If annotations - are being collected, they are collected from this - keyword's subschema in the usual way, including when - the keyword is present without either "then" or "else". - -
-
- - This keyword's value MUST be a valid JSON Schema. - - - When "if" is present, and the instance successfully - validates against its subschema, then valiation - succeeds against this keyword if the instance also - successfully validates against this keyword's subschema. - - - This keyword has no effect when "if" is absent, or - when the instance fails to validate against its - subschema. Implementations MUST NOT evaluate - the instance against this keyword, for either validation - or annotation collection purposes, in such cases. - -
-
- - This keyword's value MUST be a valid JSON Schema. - - - When "if" is present, and the instance fails to - validate against its subschema, then valiation - succeeds against this keyword if the instance - successfully validates against this keyword's subschema. - - - This keyword has no effect when "if" is absent, or - when the instance successfully validates against its - subschema. Implementations MUST NOT evaluate - the instance against this keyword, for either validation - or annotation collection purposes, in such cases. - -
-
- -
-
- - This keyword's value MUST be a non-empty array. - Each item of the array MUST be a valid JSON Schema. - - - An instance validates successfully against this keyword if it validates - successfully against all schemas defined by this keyword's value. - -
- -
- - This keyword's value MUST be a non-empty array. - Each item of the array MUST be a valid JSON Schema. - - - An instance validates successfully against this keyword if it validates - successfully against at least one schema defined by this keyword's value. - -
- -
- - This keyword's value MUST be a non-empty array. - Each item of the array MUST be a valid JSON Schema. - - - An instance validates successfully against this keyword if it validates - successfully against exactly one schema defined by this keyword's value. - -
- -
- - This keyword's value MUST be a valid JSON Schema. - - - An instance is valid against this keyword if it fails to validate - successfully against the schema defined by this keyword. - -
From 052ef06f78e7e7dd0a62ff15755359ef3f42ba97 Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Tue, 20 Mar 2018 15:49:23 -0700 Subject: [PATCH 5/8] Update applicator vocabulary description The prior commits just moved this text over, this commit updates the text to make sense for the new location and structure. In particular, this removes the focus on validation as the applicator vocabulary is more fundamental. --- jsonschema-core.xml | 56 +++++++++++++++++++++++++-------------------- 1 file changed, 31 insertions(+), 25 deletions(-) diff --git a/jsonschema-core.xml b/jsonschema-core.xml index 10f36c1b..7872f769 100644 --- a/jsonschema-core.xml +++ b/jsonschema-core.xml @@ -973,38 +973,27 @@
- Validation 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 whether and how subschema assertion results are - modified and/or combined. Such keywords do not assert conditions on their - own. Rather, they control how assertions are applied and evaluated. + 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. - The keywords in the boolean logic and - conditional sections of this specification - apply subschemas to the same location as the parent schema. The former group - defines boolean operations on the subschema assertion results, while the - latter evaluates one subschema and uses its assertion results to determine - which of two other subschemas to apply as well. - - - Several keywords determine which subschemas are applied to array items, - object property values, and object property names. They are: - "items", "additionalItems", "contains", "properties", "patternProperties", - "additionalProperties", and "propertyNames". The "contains" keyword only - requires its subschema to be valid against at least one child instance, while - the other keywords require that all subschemas are valid against all child - instances to which they apply. + 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 + are RECOMMENDED for use as the basis of other vocabularies.
- Validation keywords typically operate independently, without + Schema keywords typically operate independently, without affecting each other's outcomes. For schema author convenience, there are some exceptions among the - keywords that control subschema applicability: + keywords in this vocabulary: "additionalProperties", whose behavior is defined in terms of @@ -1018,8 +1007,20 @@
+ + These keywords apply subschemas to the same location in the instance + as the parent schema is being applied. They allow combining + or modifying the subschema results in various ways. +
+ + These keywords correspond to logical operators for combining or modifying + the boolean assertion results of the subschemas. They have no direct + impact on annotation collection, although they enable the same annotation + keyword to be applied to an instance location with different values. + Annotation keywords define their own rules for combining such values. +
This keyword's value MUST be a non-empty array. @@ -1118,7 +1119,7 @@ When "if" is present, and the instance successfully - validates against its subschema, then valiation + validates against its subschema, then validation succeeds against this keyword if the instance also successfully validates against this keyword's subschema. @@ -1136,7 +1137,7 @@ When "if" is present, and the instance fails to - validate against its subschema, then valiation + validate against its subschema, then validation succeeds against this keyword if the instance successfully validates against this keyword's subschema. @@ -1151,6 +1152,11 @@
+ + Each of these keywords defines a rule for applying its + subschema(s) to child instances, specifically object + properties and array items, and combining their results. +
From 8bccb31387d873916bbc81c05ec49fe12754b4e3 Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Fri, 23 Mar 2018 13:22:48 -0700 Subject: [PATCH 6/8] Update changelog and moved keywords appendix ...for the move of applicators to core. --- jsonschema-core.xml | 1 + jsonschema-validation.xml | 12 ++++++++++++ 2 files changed, 13 insertions(+) diff --git a/jsonschema-core.xml b/jsonschema-core.xml index 7872f769..b2600944 100644 --- a/jsonschema-core.xml +++ b/jsonschema-core.xml @@ -1624,6 +1624,7 @@ User-Agent: product-name/5.4.1 so-cool-json-schema/1.0.2 curl/7.43.0 Moved "definitions" from the Validation specification here as "$defs" + Moved applicator keywords from the Validation specification as their own vocabulary diff --git a/jsonschema-validation.xml b/jsonschema-validation.xml index ef359ad6..ab1b1a47 100644 --- a/jsonschema-validation.xml +++ b/jsonschema-validation.xml @@ -1056,6 +1056,17 @@ with different behavior in order to avoid invalidating schemas that still use the older name. + + All of these keywords apply subschemas to the instance and combine + their results, without asserting any conditions of their own. + Without assertion keywords, these applicators can only cause assertion + failures by using the false boolean schema, or by inverting the result + of the true boolean schema. For this reason, they are better defined + as a generic mechanism on which validation, hyper-schema, and extension + vocabularies can all be based +
@@ -1094,6 +1105,7 @@ Moved "definitions" to the core spec as "$defs" + Moved applicator keywords to the core spec From abd3eb789aef9fb6cacfeedc92e962c4b43b6a0e Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Wed, 4 Apr 2018 09:28:14 -0700 Subject: [PATCH 7/8] Fix typo, add xref to subschema vocabulary PR review feedback --- jsonschema-core.xml | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/jsonschema-core.xml b/jsonschema-core.xml index b2600944..3351596a 100644 --- a/jsonschema-core.xml +++ b/jsonschema-core.xml @@ -136,7 +136,7 @@ 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. + certain values, and keyword definitions SHOULD note such values where known. These default behaviors MUST NOT result in assertion failures.
@@ -204,7 +204,8 @@
This vocabulary provides keywords for applying subschemas to the - instance in various ways. It is defined in this document, and + instance in various ways. It is defined in section + , and it is RECOMMENDED that all JSON Schema implementations support it. All other vocabularies in this section are designed to be used alongside the subschema application vocabulary. @@ -971,7 +972,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 From 76a3efeb333df9214b3c2821322671aa5d97dc74 Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Wed, 4 Apr 2018 10:08:58 -0700 Subject: [PATCH 8/8] Update regex concerns for subschema application Move the main text into core, and just reference it from validation. --- jsonschema-core.xml | 51 ++++++++++++++++++++++++++++++++++++--- jsonschema-validation.xml | 33 +++---------------------- 2 files changed, 51 insertions(+), 33 deletions(-) diff --git a/jsonschema-core.xml b/jsonschema-core.xml index 3351596a..8fdbcc7b 100644 --- a/jsonschema-core.xml +++ b/jsonschema-core.xml @@ -540,6 +540,39 @@
+
+ + Keywords MAY use regular expressions to express constraints, or constrain + the instance value to be a regular expression. + These regular expressions SHOULD be valid according to the + ECMA 262 regular expression dialect. + + + Furthermore, given the high disparity in regular expression constructs support, + schema authors SHOULD limit themselves to the following regular expression + tokens: + + + individual Unicode characters, as defined by the JSON specification; + simple character classes ([abc]), range character classes ([a-z]); + complemented character classes ([^abc], [^a-z]); + simple quantifiers: "+" (one or more), "*" (zero or more), "?" (zero or + one), and their lazy versions ("+?", "*?", "??"); + range quantifiers: "{x}" (exactly x occurrences), "{x,y}" (at least x, at + most y, occurrences), {x,} (x occurrences or more), and their lazy + versions; + the beginning-of-input ("^") and end-of-input ("$") anchors; + simple grouping ("(...)") and alternation ("|"). + + + + Finally, implementations MUST NOT take regular expressions to be + anchored, neither at the beginning nor at the end. This means, for instance, + the pattern "es" matches "expression". + +
+
Additional schema keywords and schema vocabularies MAY be defined @@ -1489,8 +1522,9 @@ User-Agent: product-name/5.4.1 so-cool-json-schema/1.0.2 curl/7.43.0 Interoperability considerations: See Sections - and - above. + , + , and + above. Fragment identifier considerations: See Section @@ -1532,8 +1566,9 @@ User-Agent: product-name/5.4.1 so-cool-json-schema/1.0.2 curl/7.43.0 Interoperability considerations: See Sections - and - above. + , + , and + above. Fragment identifier considerations: See Section @@ -1554,6 +1589,14 @@ User-Agent: product-name/5.4.1 so-cool-json-schema/1.0.2 curl/7.43.0 &RFC6901; &RFC7159; &ldp; + + + ECMA 262 specification + + + + diff --git a/jsonschema-validation.xml b/jsonschema-validation.xml index ab1b1a47..6647a3f0 100644 --- a/jsonschema-validation.xml +++ b/jsonschema-validation.xml @@ -173,35 +173,10 @@
- Two validation keywords, "pattern" and "patternProperties", use regular - expressions to express constraints, and the "regex" value for the - "format" keyword constrains the instance value to be a regular expression. - These regular expressions SHOULD be valid according to the - ECMA 262 regular expression dialect. - - - Furthermore, given the high disparity in regular expression constructs support, - schema authors SHOULD limit themselves to the following regular expression - tokens: - - - individual Unicode characters, as defined by the JSON specification; - simple character classes ([abc]), range character classes ([a-z]); - complemented character classes ([^abc], [^a-z]); - simple quantifiers: "+" (one or more), "*" (zero or more), "?" (zero or - one), and their lazy versions ("+?", "*?", "??"); - range quantifiers: "{x}" (exactly x occurrences), "{x,y}" (at least x, at - most y, occurrences), {x,} (x occurrences or more), and their lazy - versions; - the beginning-of-input ("^") and end-of-input ("$") anchors; - simple grouping ("(...)") and alternation ("|"). - - - - Finally, implementations MUST NOT take regular expressions to be - anchored, neither at the beginning nor at the end. This means, for instance, - the pattern "es" matches "expression". + Keywords that use regular expressions, or constrain the instance value + to be a regular expression, are subject to the interoperability + considerations for regular expressions in the + JSON Schema Core specification.