From 6787975adf1b9fb0e82f605c97e84c1c096a66d0 Mon Sep 17 00:00:00 2001 From: Denis Laxalde Date: Mon, 28 Aug 2017 09:37:12 +0200 Subject: [PATCH 1/9] Move "readOnly" from Hyper-Schema to Validation We move the description and schema definition of "readOnly" verbatim from the Hyper-Schema specification (and meta-schema) to the validation one, in the "Metadata keywords" section (along with "default", in particular). This addresses part of #363, which states that some keywords historically in the Hyper-Schema specification would be better in the Validation document. The main argument for moving keywords such as "readOnly" is that the Hyper-Schema document could then only focus on describing the hypermedia linking model. --- hyper-schema.json | 5 ----- jsonschema-hyperschema.xml | 17 ----------------- jsonschema-validation.xml | 17 +++++++++++++++++ schema.json | 5 +++++ 4 files changed, 22 insertions(+), 22 deletions(-) diff --git a/hyper-schema.json b/hyper-schema.json index deab4992..4de69496 100644 --- a/hyper-schema.json +++ b/hyper-schema.json @@ -127,11 +127,6 @@ "type": "string" } } - }, - "readOnly": { - "description": "If true, indicates that the value of this property is controlled by the server.", - "type": "boolean", - "default": "false" } }, "links": [ diff --git a/jsonschema-hyperschema.xml b/jsonschema-hyperschema.xml index 42d381b7..e5acc338 100644 --- a/jsonschema-hyperschema.xml +++ b/jsonschema-hyperschema.xml @@ -425,23 +425,6 @@ - -
- - If it has a value of boolean true, this keyword indicates that the value of the - instance is managed exclusively by the server or the owning authority, and - attempts by a user agent to modify the value of this property are expected to be - ignored or rejected by a server. - - - For example, this property would be used to mark a server-generated serial - number as read-only. - - - The value of this keyword MUST be a boolean. - The default value is false. - -
diff --git a/jsonschema-validation.xml b/jsonschema-validation.xml index 8c90bdb2..47fc7d84 100644 --- a/jsonschema-validation.xml +++ b/jsonschema-validation.xml @@ -740,6 +740,23 @@
+
+ + If it has a value of boolean true, this keyword indicates that the value of the + instance is managed exclusively by the server or the owning authority, and + attempts by a user agent to modify the value of this property are expected to be + ignored or rejected by a server. + + + For example, this property would be used to mark a server-generated serial + number as read-only. + + + The value of this keyword MUST be a boolean. + The default value is false. + +
+
The value of this keyword MUST be an array. diff --git a/schema.json b/schema.json index e5b848e7..36b3a62f 100644 --- a/schema.json +++ b/schema.json @@ -60,6 +60,11 @@ "type": "string" }, "default": {}, + "readOnly": { + "description": "If true, indicates that the value of this property is controlled by the server.", + "type": "boolean", + "default": "false" + }, "examples": { "type": "array", "items": {} From 9f2b7989946353f18530133dcf214c576b0242d9 Mon Sep 17 00:00:00 2001 From: Denis Laxalde Date: Mon, 28 Aug 2017 09:44:50 +0200 Subject: [PATCH 2/9] Fix the "default" value of "readOnly" in its schema definition Change from the "false" string to the `false` Boolean value. --- schema.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/schema.json b/schema.json index 36b3a62f..009e72a3 100644 --- a/schema.json +++ b/schema.json @@ -63,7 +63,7 @@ "readOnly": { "description": "If true, indicates that the value of this property is controlled by the server.", "type": "boolean", - "default": "false" + "default": false }, "examples": { "type": "array", From 203cc1cb5d4ed0f1a610696c42acb133da604468 Mon Sep 17 00:00:00 2001 From: Denis Laxalde Date: Mon, 28 Aug 2017 17:24:57 +0200 Subject: [PATCH 3/9] Only refer to "owning authority" in readOnly description --- jsonschema-validation.xml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/jsonschema-validation.xml b/jsonschema-validation.xml index 47fc7d84..57590bf6 100644 --- a/jsonschema-validation.xml +++ b/jsonschema-validation.xml @@ -743,9 +743,9 @@
If it has a value of boolean true, this keyword indicates that the value of the - instance is managed exclusively by the server or the owning authority, and - attempts by a user agent to modify the value of this property are expected to be - ignored or rejected by a server. + instance is managed exclusively by the owning authority, and attempts by a user + agent to modify the value of this property are expected to be ignored or + rejected by that owning authority. For example, this property would be used to mark a server-generated serial From 605af84ac1f363765bd3de9ddee205d0591f91e7 Mon Sep 17 00:00:00 2001 From: Denis Laxalde Date: Mon, 28 Aug 2017 17:26:50 +0200 Subject: [PATCH 4/9] Use common phrasing for default value of readOnly --- jsonschema-validation.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/jsonschema-validation.xml b/jsonschema-validation.xml index 57590bf6..45ab8490 100644 --- a/jsonschema-validation.xml +++ b/jsonschema-validation.xml @@ -753,7 +753,7 @@ The value of this keyword MUST be a boolean. - The default value is false. + Omitting this keyword has the same behavior as a value of false.
From 3af480b249afdbd09390c2c260c1e1e81c1896bb Mon Sep 17 00:00:00 2001 From: Denis Laxalde Date: Mon, 28 Aug 2017 17:28:01 +0200 Subject: [PATCH 5/9] Move type description of readOnly in its own paragraph As is done for all other keywords. --- jsonschema-validation.xml | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/jsonschema-validation.xml b/jsonschema-validation.xml index 45ab8490..7d4b1741 100644 --- a/jsonschema-validation.xml +++ b/jsonschema-validation.xml @@ -741,6 +741,9 @@
+ + The value of this keyword MUST be a boolean. + If it has a value of boolean true, this keyword indicates that the value of the instance is managed exclusively by the owning authority, and attempts by a user @@ -752,7 +755,6 @@ number as read-only. - The value of this keyword MUST be a boolean. Omitting this keyword has the same behavior as a value of false.
From c8874a76995932fdfad3339bc943654f7a3b7e73 Mon Sep 17 00:00:00 2001 From: Denis Laxalde Date: Wed, 30 Aug 2017 08:13:23 +0200 Subject: [PATCH 6/9] Remove readOnly's description in validation meta-schema The readOnly is property is actually the only one having a description; it got inherited when moved from hyper-schema meta-schema. So drop it to be consistent with the rest of the schema. Additionnally, the current description contains ambiguous "server language" which we try to avoid. --- schema.json | 1 - 1 file changed, 1 deletion(-) diff --git a/schema.json b/schema.json index 009e72a3..80635bbb 100644 --- a/schema.json +++ b/schema.json @@ -61,7 +61,6 @@ }, "default": {}, "readOnly": { - "description": "If true, indicates that the value of this property is controlled by the server.", "type": "boolean", "default": false }, From b4dc55171aab73cc1501c704c28c90dce7642a81 Mon Sep 17 00:00:00 2001 From: Denis Laxalde Date: Wed, 30 Aug 2017 10:05:50 +0200 Subject: [PATCH 7/9] Replace "user agent" by "application" in readOnly description The term "user agent" is appropriate in the scope of hypermedia, not that much elsewhere; "application" is more generic. --- jsonschema-validation.xml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/jsonschema-validation.xml b/jsonschema-validation.xml index 7d4b1741..e4cde60e 100644 --- a/jsonschema-validation.xml +++ b/jsonschema-validation.xml @@ -746,8 +746,8 @@ If it has a value of boolean true, this keyword indicates that the value of the - instance is managed exclusively by the owning authority, and attempts by a user - agent to modify the value of this property are expected to be ignored or + instance 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 owning authority. From 1d18f8fd5ee93fb5b01e609f888b5693a6efcebc Mon Sep 17 00:00:00 2001 From: Denis Laxalde Date: Wed, 30 Aug 2017 10:11:34 +0200 Subject: [PATCH 8/9] Replace "server-generated" by "database-generated" in readOnly example paragraph --- jsonschema-validation.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/jsonschema-validation.xml b/jsonschema-validation.xml index e4cde60e..ae2980aa 100644 --- a/jsonschema-validation.xml +++ b/jsonschema-validation.xml @@ -751,7 +751,7 @@ rejected by that owning authority. - For example, this property would be used to mark a server-generated serial + For example, this property would be used to mark a database-generated serial number as read-only. From 369648bb45e29722eaa50026ec6a0104f7060e4c Mon Sep 17 00:00:00 2001 From: Denis Laxalde Date: Wed, 30 Aug 2017 11:06:37 +0200 Subject: [PATCH 9/9] Mention that readOnly can be used for UI generation Echoing the document abstract. --- jsonschema-validation.xml | 3 +++ 1 file changed, 3 insertions(+) diff --git a/jsonschema-validation.xml b/jsonschema-validation.xml index ae2980aa..51b47c84 100644 --- a/jsonschema-validation.xml +++ b/jsonschema-validation.xml @@ -754,6 +754,9 @@ For example, this property would be used to mark a database-generated serial number as read-only. + + This keyword can be used to assist in user interface instance generation. + Omitting this keyword has the same behavior as a value of false.