Improve the documentation for required

Signed-off-by: Juan Cruz Viotti <jv@jviotti.com>

Author: jviotti

content/2020-12/validation/required.markdown

@@ -24,110 +24,85 @@ related:
     keyword: minProperties
 ---
 
-The `required` keyword is used to specify which properties must be present within an object instance.
+The `required` keyword restricts object instances to define the given set of properties.
+
+{{<common-pitfall>}} The presence of this keyword does not depend on the
+presence of the [`properties`]({{< ref "2020-12/applicator/properties" >}})
+keyword. The `required` keyword mandates that certain properties are present
+(independently of their value), while the [`properties`]({{< ref
+"2020-12/applicator/properties" >}}) keyword describes the value of such
+properties when present.{{</common-pitfall>}}
+
+{{<constraint-warning `object`>}}
 
 ## Examples
 
-{{<schema `Schema with the 'required' keyword`>}}
+{{<schema `A schema that constrains object instances to define certain properties`>}}
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "type": "object",
-  "required": [ "foo" ]
+  "required": [ "foo", "bar", "baz" ]
 }
 {{</schema>}}
 
-{{<instance-pass `An instance with all the required properties is valid`>}}
-{ "foo": "bar" }
+{{<instance-pass `An object value that defines the required properties to any values is valid`>}}
+{ "foo": 1, "bar": 2, "baz": 3 }
 {{</instance-pass>}}
 
-{{<instance-fail `An instance with missing required properties is invalid`>}}
-{ "bar": false }
+{{<instance-pass `An object value that defines a superset of the required properties is valid`>}}
+{ "foo": 1, "bar": 2, "baz": 3, "extra": true }
+{{</instance-pass>}}
+
+{{<instance-fail `An object value that only defines a subset of the required properties is invalid`>}}
+{ "foo": 1, "bar": 2, "extra": true }
 {{</instance-fail>}}
 
-{{<instance-pass `An instance with all the required properties is valid`>}}
-{ "foo": [ "bar" ], "baz": 13 }
+{{<instance-fail `An empty object is invalid`>}}
+{}
+{{</instance-fail>}}
+
+{{<instance-pass `A non-object value is valid`>}}
+"Hello World"
 {{</instance-pass>}}
-* _It is important to note that when the required properties are not defined in the `properties`, then the only requirement to make the instance valid is to have those properties present in the instance irrespective of their value's datatype._
 
-{{<schema `Schema with the 'required' keyword`>}}
+{{<schema `A schema that constrains object instances to define certain properties and to describe their value`>}}
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "type": "object",
+  "required": [ "name", "age" ],
   "properties": {
     "name": { "type": "string" },
     "age": { "type": "integer" }
-  },
-  "required": [ "name", "age" ]
+  }
 }
 {{</schema>}}
 
-{{<instance-pass `An instance with all the required properties is valid`>}}
-{ "name": "John", "age": 65 }
+{{<instance-pass `An object value that defines the required properties and matches their definition is valid`>}}
+{ "name": "John Doe", "age": 30 }
 {{</instance-pass>}}
 
-{{<instance-fail `An instance with missing required properties is invalid`>}}
-{ "name": "Doe" }
-{{</instance-fail>}}
+{{<instance-annotation>}}
+{ "keyword": "/properties", "instance": "", "value": [ "name", "age" ] }
+{{</instance-annotation>}}
 
-{{<instance-fail `The value of 'age' property must be an integer`>}}
-{ "name": "John Doe", "age": "48" }
-{{</instance-fail>}}
+{{<instance-pass `An object value that defines a superset of the required properties and matches their definition is valid`>}}
+{ "name": "John Doe", "age": 30, "extra": true }
+{{</instance-pass>}}
 
-{{<schema `Schema with the 'required' keyword in nested subschemas`>}}
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "type": "object",
-  "properties": {
-    "name": { "type": "string" },
-    "address": {
-      "type": "object",
-      "properties": {
-        "city": { "type": "string" },
-        "country": { "type": "string" }
-      },
-      "required": [ "city", "country" ]
-    }
-  },
-  "required": [ "address" ]
-}
-{{</schema>}}
+{{<instance-annotation>}}
+{ "keyword": "/properties", "instance": "", "value": [ "name", "age" ] }
+{{</instance-annotation>}}
 
-{{<instance-pass `An instance with all the required properties is valid`>}}
-{
-  "name": "John",
-  "address": {
-    "city": "New York",
-    "country": "USA"
-  }
-}
-{{</instance-pass>}}
+{{<instance-fail `An object value that only defines a subset of the required properties and matches their definition is invalid`>}}
+{ "name": "John Doe" }
+{{</instance-fail>}}
 
-{{<instance-fail `'name' property is missing in the root object`>}}
-{
-  "address": {
-    "city": "Hyderabad",
-    "country": "India"
-  }
-}
+{{<instance-fail `An object value that defines the required properties but does not match their definition is invalid`>}}
+{ "name": 123, "age": "foo" }
 {{</instance-fail>}}
 
-{{<instance-fail `'country' property is missing in the nested object`>}}
-{
-  "name": "Doe",
-  "address": {
-    "city": "Dallas"
-  }
-}
+{{<instance-fail `An empty object is invalid`>}}
+{}
 {{</instance-fail>}}
 
-{{<schema>}}
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "type": "object",
-  "properties": {
-    "name": { "type": "string" }
-  },
-  "required": [ "name", "age", "name" ]
-}
-// Schema with duplicate items in the required list is invalid.
-{{</schema>}}
+{{<instance-pass `A non-object value is valid`>}}
+"Hello World"
+{{</instance-pass>}}