Revise the readOnly keyword

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

Author: jviotti

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

@@ -28,82 +28,102 @@ related:
     keyword: deprecated
 ---
 
-The `readOnly` keyword is used to indicate that the value of a particular property is managed exclusively by the owning authority, and attempts by an application to modify the value of this property are expected to be ignored or rejected by that authority. It essentially means that the instance value should not be modified.
+The `readOnly` keyword, when set to `true`, signifies that an instance value
+(such as a specific object property) cannot be modified or removed, whatever
+that means in the context of the system. For example, form generators may rely
+on this keyword to mark the corresponding input as read only. This keyword does
+not affect validation, but the evaluator will collect its value as an
+annotation.
 
-It's important to note that this keyword doesn't imply the schema itself is writable; schemas must be treated as immutable. Instead, the keyword specifies instances where read/write operation semantics are use case specific.
+{{<best-practice>}}
 
-* `readOnly` does not affect data validation but serves as an informative annotation.
+Avoid setting this keyword to the default value `false`. If an instance value
+is not considered to be read only, 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.
 
-## Examples
+Also avoid simultaneously setting this keyword and the [`writeOnly`]({{< ref
+"2020-12/meta-data/writeonly" >}}) keyword to `true` for the same instance
+location, resulting in ambiguous semantics.
 
-{{<schema `Schema with 'readOnly' keyword`>}}
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "readOnly": true,
-  "type": "number"
-}
-{{</schema>}}
+{{</best-practice>}}
 
-{{<instance-pass `An instance with a numeric value is valid`>}}
-45
-{{</instance-pass>}}
+{{<common-pitfall>}}
 
-{{<instance-annotation>}}
-{ "keyword": "/readOnly", "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 read only under certain
+conditions determined by a dynamic operator like [`anyOf`]({{< ref
+"2020-12/applicator/anyof" >}}).
+
+{{</common-pitfall>}}
+
+{{<metaschema-check-type `boolean`>}}
+
+## Examples
 
-{{<schema `Schema with logical operators`>}}
+{{<schema `A schema that statically marks the id optional object property as read only`>}}
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "if": {
-    "properties": {
-      "immutable": { "const": true }
-    }
-  },
-  "then": {
-    "readOnly": true
-  },
-  "else": {
-    "readOnly": false
+  "properties": {
+    "id": { "readOnly": true },
+    "value": { "type": "integer" }
   }
 }
 {{</schema>}}
 
-{{<instance-pass>}}
-{ "immutable": false }
+{{<instance-pass `An object value that defines the read only property is valid but an annotation is emitted`>}}
+{ "id": 1234, "value": 5 }
 {{</instance-pass>}}
 
 {{<instance-annotation>}}
-{ "keyword": "/else/readOnly", "instance": "", "value": false }
+{ "keyword": "/properties/id/readOnly", "instance": "/id", "value": true }
 {{</instance-annotation>}}
 
-{{<instance-pass>}}
-{ "immutable": true }
+{{<instance-pass `An object value that does not define the read only property is valid and no annotation is emitted`>}}
+{ "value": 5 }
 {{</instance-pass>}}
 
-{{<instance-annotation>}}
-{ "keyword": "/then/readOnly", "instance": "", "value": true }
-{{</instance-annotation>}}
+{{<instance-fail `An object value that does not match the schema is invalid and no annotations are emitted`>}}
+{ "id": 1234, "value": null }
+{{</instance-fail>}}
 
-{{<schema `Schema with multiple annotations for the same instance`>}}
+{{<schema `A schema that dynamically marks the id optional object property as read only based on the presence of the data property`>}}
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "readOnly": true,
-  "$ref": "#/$defs/name",
-  "$defs": {
-    "name": {
-      "readOnly": true,
-      "type": "string"
+  "properties": {
+    "id": true,
+    "value": { "type": "integer" }
+  },
+  "dependentSchemas": {
+    "value": {
+      "properties": { "id": { "readOnly": true } }
     }
   }
 }
 {{</schema>}}
 
-{{<instance-pass>}}
-"John Doe"
+{{<instance-pass `An object value that defines both properties is valid but an annotation is emitted`>}}
+{ "id": 1234, "value": 5 }
 {{</instance-pass>}}
 
 {{<instance-annotation>}}
-{ "keyword": "/readOnly", "instance": "", "value": true }
-{ "keyword": "/$ref/readOnly", "instance": "", "value": true }
+{ "keyword": "/dependentSchemas/value/properties/id/readOnly", "instance": "/id", "value": true }
 {{</instance-annotation>}}
+
+{{<instance-pass `An object value that only defines the value property is valid and no annotation is emitted`>}}
+{ "value": 5 }
+{{</instance-pass>}}
+
+{{<instance-pass `An object value that only defines the id property is valid and no annotation is emitted`>}}
+{ "id": 1234 }
+{{</instance-pass>}}
+
+{{<instance-fail `An object value that does not match the schema is invalid and no annotations are emitted`>}}
+{ "value": null }
+{{</instance-fail>}}