Revise unevaluatedProperties

Signed-off-by: Juan Cruz Viotti <[email protected]>

Author: jviotti

content/2020-12/unevaluated/unevaluatedProperties.markdown

@@ -36,11 +36,14 @@ occurences of [`properties`]({{< ref "2020-12/applicator/properties" >}}),
 [`patternProperties`]({{< ref "2020-12/applicator/patternproperties" >}}),
 [`additionalProperties`]({{< ref "2020-12/applicator/additionalproperties"
 >}}), and [`unevaluatedProperties`]({{< ref
-"2020-12/unevaluated/unevaluatedproperties" >}}) itself as long as the evaluate
-path that led to [`unevaluatedProperties`]({{< ref
-"2020-12/unevaluated/unevaluatedproperties" >}}) is a prefix of the evaluate
+"2020-12/unevaluated/unevaluatedproperties" >}}) itself, as long as the
+evaluate path that led to [`unevaluatedProperties`]({{< ref
+"2020-12/unevaluated/unevaluatedproperties" >}}) is a _prefix_ of the evaluate
 path of the others.
 
+Given its evaluation-dependent nature, this keyword is evaluated after every
+other keyword from every other vocabulary.
+
 {{<best-practice>}}
 
 There are two common use cases for this keyword, both for reducing duplication:
@@ -50,12 +53,12 @@ There are two common use cases for this keyword, both for reducing duplication:
 keywords behind conditional logic without duplicating the
 [`additionalProperties`]({{< ref "2020-12/applicator/additionalproperties"
 >}}) keyword in every possible branch. (2) Re-using 
-the [`properties`]({{< ref "2020-12/applicator/properties" >}}) and
-[`patternProperties`]({{< ref "2020-12/applicator/patternproperties" >}})
-keywords, or the [`additionalProperties`]({{< ref
-"2020-12/applicator/additionalproperties" >}}) keyword, as helpers while
-specialising the helpers with other related keywords as needed in specific
-locations without having to inline the entire helper.
+subschemas that consist of the [`properties`]({{< ref
+"2020-12/applicator/properties" >}}) and [`patternProperties`]({{< ref
+"2020-12/applicator/patternproperties" >}}) keywords, or the
+[`additionalProperties`]({{< ref "2020-12/applicator/additionalproperties" >}})
+keyword, as helpers while specialising the helpers with other related keywords
+as needed in specific locations without having to inline the entire helper.
 
 {{</best-practice>}}
 
@@ -78,230 +81,147 @@ dependencies, leading to schemas that are simpler to evaluate.
 
 ## Examples
 
-{{<schema `Schema with 'unevaluatedProperties' set to boolean true`>}}
+{{<schema `A schema that conditionally constrains object instances to define certain properties, with string additional properties in both cases`>}}
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "unevaluatedProperties": true
+  "if": { "maxProperties": 2 },
+  "then": { "properties": { "foo": true } },
+  "else": { "patternProperties": { "^@": true } },
+  "unevaluatedProperties": { "type": "string" }
 }
 {{</schema>}}
 
-{{<instance-pass `All object instances pass against the true schema`>}}
-{ "foo": "bar", "baz": 33 }
+{{<instance-pass `An object value that defines a "foo" property and other string properties is valid`>}}
+{ "foo": 1, "bar": "baz" }
 {{</instance-pass>}}
 
-{{<instance-pass `'unevaluatedProperties' does not have any effect on instances other than an object`>}}
-"John Doe"
+{{<instance-annotation>}}
+{ "keyword": "/then/properties", "instance": "", "value": [ "foo" ] }
+{ "keyword": "/unevaluatedProperties", "instance": "", "value": [ "bar" ] }
+{{</instance-annotation>}}
+
+{{<instance-pass `An object value that defines multiple properties that start with "@" and other string properties is valid`>}}
+{ "@foo": 1, "@bar": 2, "baz": "qux" }
 {{</instance-pass>}}
 
 {{<instance-annotation>}}
-{ "keyword": "/unevaluatedProperties", "instance": "", "value": [ "foo", "baz" ] }
+{ "keyword": "/else/patternProperties", "instance": "", "value": [ "@foo", "@bar" ] }
+{ "keyword": "/unevaluatedProperties", "instance": "", "value": [ "baz" ] }
 {{</instance-annotation>}}
 
-* Here, no properties are defined in the above schema. Consequently, all properties in an object instance are considered unevaluated, and the `unevaluatedProperties` subschema applies to them. Since the subschema here is a boolean true, an instance with unevaluated properties, regardless of their value, is considered valid.
-
-{{<schema `Schema with 'unevaluatedProperties' set to boolean false`>}}
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "unevaluatedProperties": false
-}
-{{</schema>}}
+{{<instance-fail `An object value that defines a "foo" property and other non-string properties is invalid`>}}
+{ "foo": 1, "bar": 2 }
+{{</instance-fail>}}
 
-{{<instance-fail `All object instances fail against the false schema`>}}
-{ "foo": "bar" }
+{{<instance-fail `An object value that defines multiple properties that start with "@" and other non-string properties is invalid`>}}
+{ "@foo": 1, "@bar": 2, "baz": 3 }
 {{</instance-fail>}}
 
-{{<instance-pass `'unevaluatedProperties' does not have any effect on instances other than an object`>}}
-[ "John", 46, false ]
+{{<instance-pass `An empty object value is valid`>}}
+{}
 {{</instance-pass>}}
 
-{{<schema `Schema with 'unevaluatedProperties', 'properties', and 'patternProperties', with unevaluatedProperties set to boolean false`>}}
+{{<instance-pass `A non-object value is valid`>}}
+"Hello World"
+{{</instance-pass>}}
+
+{{<schema `A schema that constraints object instances to only allow extension keywords that start with "@" using a helper`>}}
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "properties": {
-    "foo": { "type": "string" }
-  },
-  "patternProperties": {
-    "^b": { "type": "number" }
-  },
-  "unevaluatedProperties": false
+  "properties": { "foo": true },
+  "$ref": "#/$defs/allow-extensions",
+  "unevaluatedProperties": false,
+  "$defs": {
+    "allow-extensions": {
+      "patternProperties": { "^@": true }
+    }
+  }
 }
 {{</schema>}}
 
-{{<instance-fail `An instance with unevaluated properties is invalid`>}}
-{ "foo": "foo", "bar": 36, "fooBar": false }
-{{</instance-fail>}}
-
-{{<instance-pass `An instance with no unevaluated properties is valid`>}}
-{ "foo": "foo", "bar": 36 }
+{{<instance-pass `An object value that only defines a "foo" property is valid`>}}
+{ "foo": 1 }
 {{</instance-pass>}}
 
 {{<instance-annotation>}}
 { "keyword": "/properties", "instance": "", "value": [ "foo" ] }
-{ "keyword": "/patternProperties", "instance": "", "value": [ "bar" ] }
 {{</instance-annotation>}}
 
-* For the first instance, the annotation result of `properties` is [ "foo" ], and the annotation result of `patternProperties` is [ "bar" ]. However, the 'fooBar' property remains unevaluated, so the `unevaluatedProperties` subschema applies to it. This subschema fails (as any instance against a false schema is always invalid), leading to the failure of the entire schema.
-* For the second instance, the annotation result of `properties` is [ "foo" ], and the annotation result of `patternProperties` is [ "bar" ]. No properties remain unevaluated; hence, the instance is considered valid.
-
-{{<schema `Schema with 'unevaluatedProperties', 'properties', and 'patternProperties', with unevaluatedProperties set to an object subschema`>}}
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "properties": {
-    "foo": { "type": "string" }
-  },
-  "patternProperties": {
-    "^b": { "type": "number" }
-  },
-  "unevaluatedProperties": { "type": "boolean" }
-}
-{{</schema>}}
-
-{{<instance-pass `An instance with no unevaluated properties is valid`>}}
-{ "foo": "foo", "bar": 36 }
+{{<instance-pass `An object value that only defines a "foo" property and other properties that start with "@" is valid`>}}
+{ "foo": 1, "@bar": 2, "@baz": 3 }
 {{</instance-pass>}}
 
 {{<instance-annotation>}}
 { "keyword": "/properties", "instance": "", "value": [ "foo" ] }
-{ "keyword": "/patternProperties", "instance": "", "value": [ "bar" ] }
+{ "keyword": "/$defs/allow-extensions/patternProperties", "instance": "", "value": [ "@bar", "@baz" ] }
 {{</instance-annotation>}}
 
-{{<instance-pass `An instance with unevaluated properties that conform to the 'unevaluatedProperties' subschema is valid`>}}
-{ "foo": "foo", "bar": 36, "fooBar": false }
+{{<instance-pass `An object value that only defines properties that start with "@" is valid`>}}
+{ "@foo": 1, "@bar": 2, "@baz": 3 }
 {{</instance-pass>}}
 
 {{<instance-annotation>}}
-{ "keyword": "/properties", "instance": "", "value": [ "foo" ] }
-{ "keyword": "/patternProperties", "instance": "", "value": [ "bar" ] }
-{ "keyword": "/unevaluatedProperties", "instance": "", "value": [ "fooBar" ] }
+{ "keyword": "/$defs/allow-extensions/patternProperties", "instance": "", "value": [ "@foo", "@bar", "@baz" ] }
 {{</instance-annotation>}}
 
-{{<instance-fail `An instance with unevaluated properties that do not conform to the 'unevaluatedProperties' subschema is invalid`>}}
-{ "foo": "foo", "bar": 36, "fooBar": "string" }
+{{<instance-fail `An object value that only defines a "foo" property and other properties that do not start with "@" is invalid`>}}
+{ "foo": 1, "bar": 2 }
 {{</instance-fail>}}
-* For the first instance, there are no unevaluated properties.
-* For the second instance, 'fooBar' is unevaluated, and the `unevaluatedProperties` subschema applies to it. 'fooBar' conforms to this subschema, and hence the instance is valid. The annotations produced by applicators are: `properties` → [ "foo" ], `patternProperties` → [ "bar" ], and `unevaluatedProperties` → [ "fooBar" ].
 
-{{<schema `Schema with 'unevaluatedProperties' and 'allOf' keyword`>}}
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "properties": {
-    "foo": { "type": "string" }
-  },
-  "allOf": [
-    {
-      "patternProperties": {
-        "^b": { "type": "number" }
-      }
-    }
-  ],
-  "unevaluatedProperties": { "type": "boolean" }
-}
-{{</schema>}}
-
-{{<instance-pass `An instance with unevaluated properties that conform to the 'unevaluatedProperties' subschema is valid`>}}
-{ "foo": "foo", "bar": 36, "fooBar": false }
+{{<instance-pass `An empty object value is valid`>}}
+{}
 {{</instance-pass>}}
 
-{{<instance-annotation>}}
-{ "keyword": "/properties", "instance": "", "value": [ "foo" ] }
-{ "keyword": "/allOf/0/patternProperties", "instance": "", "value": [ "foo" ] }
-{ "keyword": "/unevaluatedProperties", "instance": "", "value": [ "fooBar" ] }
-{{</instance-annotation>}}
-
-{{<instance-fail `An instance with unevaluated properties that do not conform to the 'unevaluatedProperties' subschema is invalid`>}}
-{ "foo": "foo", "bar": 36, "fooBar": "string" }
-{{</instance-fail>}}
-For the above two instances, the annotation result of `properties` is [ "foo" ], and the annotation result of nested `patternProperties` is [ "bar" ]. The `unevaluatedProperties` recognizes the annotations from `properties` as well as `patternProperties` (as it can see through adjacent and nested applicators as only the produced annotations matter, not the schema structure) and ensures that 'fooBar' remains unevaluated and its subschema applies to 'fooBar'.
-* The first instance passes as it conforms to the unevaluated subschema.
-* The second instance fails as it does not conform to the unevaluated subschema.
+{{<instance-pass `A non-object value is valid`>}}
+"Hello World"
+{{</instance-pass>}}
 
-{{<schema `Schema with 'unevaluatedProperties' and 'allOf' keyword`>}}
+{{<schema `A schema that constraints object instances to not define any properties, as both object keywords are cousins`>}}
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "properties": {
-    "foo": { "type": "string" }
-  },
   "allOf": [
-    {
-      "additionalProperties": true
-    }
-  ],
-  "unevaluatedProperties": false
+    { "properties": { "foo": true } },
+    { "unevaluatedProperties": false }
+  ]
 }
 {{</schema>}}
 
-{{<instance-pass `An instance with no unevaluated properties is valid`>}}
-{ "foo": "foo" }
-{{</instance-pass>}}
+{{<instance-fail `An object value that only defines a "foo" property is invalid as the schema prohibits unevaluated properties`>}}
+{ "foo": 1 }
+{{</instance-fail>}}
 
-{{<instance-annotation>}}
-{ "keyword": "/properties", "instance": "", "value": [ "foo" ] },
-{ "keyword": "/allOf/0/additionalProperties", "instance": "", "value": [ "foo" ] }
-{{</instance-annotation>}}
+{{<instance-fail `An object value that defines any other property is invalid as the schema prohibits unevaluated properties`>}}
+{ "bar": 2 }
+{{</instance-fail>}}
 
-{{<instance-pass `An instance with no unevaluated properties is valid`>}}
-{ "foo": "foo", "bar": "bar" }
+{{<instance-pass `An empty object value is valid`>}}
+{}
 {{</instance-pass>}}
 
-{{<instance-annotation>}}
-{ "keyword": "/properties", "instance": "", "value": [ "foo" ] }
-{ "keyword": "/allOf/0/additionalProperties", "instance": "", "value": [ "foo", "bar" ] }
-{{</instance-annotation>}}
-
-* In the first case, there are no unevaluated properties.
-* In the second case, the nested `{ additionalProperties: true }` evaluated all the remaining properties. So there's nothing left unevaluated.
+{{<instance-pass `A non-object value is valid`>}}
+"Hello World"
+{{</instance-pass>}}
 
-{{<schema `Schema with 'unevaluatedProperties' and '#ref' keyword`>}}
+{{<schema `A schema that constraints object instances to define arbitrary properties`>}}
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "properties": {
-      "foo": { "type": "string" }
-  },
-  "$ref": "#/$defs/bar",
-  "unevaluatedProperties": false,
-  "$defs": {
-    "bar": {
-      "properties": {
-        "bar": { "type": "string" }
-      }
-    }
-  }
+  "allOf": [ { "unevaluatedProperties": true } ],
+  "unevaluatedProperties": false
 }
 {{</schema>}}
 
-{{<instance-pass `An instance with no unevaluated properties is valid`>}}
-{ "foo": "foo", "bar": "bar" }
+{{<instance-pass `An object value that defines any property is valid as the nested applicator takes precedence`>}}
+{ "foo": 1, "bar": 2, "baz": 3 }
 {{</instance-pass>}}
 
 {{<instance-annotation>}}
-{ "keyword": "/properties", "instance": "", "value": [ "foo" ] }
-{ "keyword": "/$ref/properties", "instance": "", "value": [ "bar" ] }
+{ "keyword": "/allOf/0/unevaluatedProperties", "instance": "", "value": [ "foo", "bar", "baz" ] }
 {{</instance-annotation>}}
 
-{{<instance-fail `An instance with unevaluated properties is invalid`>}}
-{ "foo": "foo", "bar": "bar", "baz": "baz" }
-{{</instance-fail>}}
-
-{{<schema `Schema with nested 'unevaluatedProperties' keyword`>}}
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "properties": {
-    "foo": { "type": "string" }
-  },
-  "allOf": [
-    {
-      "unevaluatedProperties": true
-    }
-  ],
-  "unevaluatedProperties": false
-}
-{{</schema>}}
-
-{{<instance-pass `No properties remain unevaluated for the top-level 'unevaluatedProperties'`>}}
-{ "foo": "foo", "bar": 101 }
+{{<instance-pass `An empty object value is valid`>}}
+{}
 {{</instance-pass>}}
 
-{{<instance-annotation>}}
-{ "keyword": "/properties", "instance": "", "value": [ "foo" ] }
-{ "keyword": "/allOf/0/unevaluatedProperties", "instance": "", "value": [ "foo", "bar" ] }
-{{</instance-annotation>}}
+{{<instance-pass `A non-object value is valid`>}}
+"Hello World"
+{{</instance-pass>}}