Revise the deprecated keyword

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

Author: jviotti

content/2020-12/meta-data/deprecated.markdown

@@ -28,89 +28,96 @@ related:
     keyword: writeOnly
 ---
 
-The `deprecated` keyword is used to indicate that a particular property should not be used and may be removed in the future. It provides a warning to users or applications that certain parts of the schema or are no longer recommended for use.
+The `deprecated` keyword, when set to `true`, signifies that an instance value
+(such as a specific property) should not be used and may be removed in the
+future. This keyword does not affect validation, but the evaluator will collect
+its value as an annotation.
 
-* `deprecated` does not affect data validation but serves as an informative annotation.
-* A true value suggests that applications should avoid using the deprecated property, and the property might be removed in future versions of the schema.
+{{<best-practice>}}
 
-## Examples
+Avoid setting this keyword to the default value `false`. If an instance value
+is not considered to be deprecated, the best practice is to omit the use of
+this keyword altogether. This prevents unnecessarily generating and collecting
+an annotation that does not carry any additional meaning.
 
-{{<schema `Schema with 'deprecated' keyword`>}}
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "deprecated": true,
-  "type": "number"
-}
-{{</schema>}}
+{{</best-practice>}}
 
-{{<instance-pass `An instance with a numeric value is valid`>}}
-45
-{{</instance-pass>}}
+{{<common-pitfall>}}
 
-{{<instance-annotation>}}
-{ "keyword": "/deprecated", "instance": "", "value": true }
-{{</instance-annotation>}}
+Tooling makers must be careful when statically traversing schemas in search of
+occurences of this keyword. It is possible for schemas to make use of this
+keyword behind conditional operators, references, or any other type of keyword
+that makes it hard or even impossible to correctly locate these values without
+fully evaluating the schema against an instance. The only bullet proof method
+is through annotation collection.
+
+For example, an instance property might only be deprecated under certain
+conditions determined by a dynamic operator like [`anyOf`]({{< ref
+"2020-12/applicator/anyof" >}}).
+
+{{</common-pitfall>}}
+
+{{<metaschema-check-type `boolean`>}}
 
-{{<schema `Schema with logical operators`>}}
+## Examples
+
+{{<schema `A schema that statically marks the city optional object property as deprecated`>}}
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "properties": {
-    "foo": { "type": "boolean" },
-    "bar": { "type": "string" }
-  },
-  "if": {
-    "properties": {
-      "foo": { "const": true }
-    }
-  },
-  "then": {
-    "properties": {
-      "bar": { "deprecated": true }
-    }
-  },
-  "else": {
-    "properties": {
-      "bar": { "deprecated": false }
-    }
+    "country": { "type": "string" },
+    "city": { "type": "string", "deprecated": true }
   }
 }
 {{</schema>}}
 
-{{<instance-pass>}}
-{ "foo": false, "bar": "bar" }
+{{<instance-pass `An object value that defines the deprecated property is valid but an annotation is emitted`>}}
+{ "country": "United Kingdom", "city": "London" }
 {{</instance-pass>}}
 
 {{<instance-annotation>}}
-{ "keyword": "/else/properties/bar/deprecated", "instance": "/bar", "value": false }
+{ "keyword": "/properties/city/deprecated", "instance": "/city", "value": true }
 {{</instance-annotation>}}
 
-{{<instance-pass>}}
-{ "foo": true, "bar": "bar" }
+{{<instance-pass `An object value that does not define the deprecated property is valid and no annotation is emitted`>}}
+{ "country": "United Kingdom" }
 {{</instance-pass>}}
 
-{{<instance-annotation>}}
-{ "keyword": "/then/properties/bar/deprecated", "instance": "/bar", "value": true }
-{{</instance-annotation>}}
+{{<instance-fail `An object value that does not match the schema is invalid and no annotations are emitted`>}}
+{ "city": 1 }
+{{</instance-fail>}}
 
-{{<schema `Schema with multiple annotations for the same instance`>}}
+{{<schema `A schema that dynamically marks the city optional object property as deprecated based on the presence of the country property`>}}
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "deprecated": true,
-  "$ref": "#/$defs/name",
-  "$defs": {
-    "name": {
-      "deprecated": true,
-      "type": "string"
+  "properties": {
+    "country": { "type": "string" },
+    "city": { "type": "string" }
+  },
+  "dependentSchemas": {
+    "country": {
+      "properties": { "city": { "deprecated": true } }
     }
   }
 }
 {{</schema>}}
 
-{{<instance-pass>}}
-"John Doe"
+{{<instance-pass `An object value that defines both properties is valid but an annotation is emitted`>}}
+{ "country": "United Kingdom", "city": "London" }
 {{</instance-pass>}}
 
 {{<instance-annotation>}}
-{ "keyword": "/deprecated", "instance": "", "value": true }
-{ "keyword": "/$ref/deprecated", "instance": "", "value": true }
+{ "keyword": "/dependentSchemas/country/properties/city/deprecated", "instance": "/city", "value": true }
 {{</instance-annotation>}}
+
+{{<instance-pass `An object value that only defines the city property is valid and no annotation is emitted`>}}
+{ "city": "London" }
+{{</instance-pass>}}
+
+{{<instance-pass `An object value that only defines the country property is valid and no annotation is emitted`>}}
+{ "country": "United Kingdom" }
+{{</instance-pass>}}
+
+{{<instance-fail `An object value that does not match the schema is invalid and no annotations are emitted`>}}
+{ "city": 1 }
+{{</instance-fail>}}