From ecb9fcb1ec4b7ec8f69535c8cac5a2610945db65 Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Mon, 21 Aug 2017 16:43:17 -0700 Subject: [PATCH 1/3] Add "$comment" as a keyword. This addresses issue #197. The primary purpose is to reserve the keyword and ensure that implementations do NOT do anything based on its presence or contents. This improves interoperability by ensuring that comments are safe for use with any conforming system. Without this keyword, two implementations may implement it with differing semantics, potentially producing undesirable or insecure behavior. Effort has been made to ensure that existing implementations that properly ignore unknown keywords will not need to make any changes at all to be in conformance for this keyword. --- jsonschema-core.xml | 36 ++++++++++++++++++++++++++++++++++++ schema.json | 3 +++ 2 files changed, 39 insertions(+) diff --git a/jsonschema-core.xml b/jsonschema-core.xml index 1517ccc2..27b09e88 100644 --- a/jsonschema-core.xml +++ b/jsonschema-core.xml @@ -573,6 +573,32 @@ +
+ + This keyword is reserved for comments from schema authors to readers or + maintainers of the schema. + + The value of this keyword MUST be a string. Implementations MUST NOT present this + string to end users. Tools for editing schemas SHOULD support displaying and + editing this keyword. The value of this keyword MAY be used in debug or error + output which is intended for developers making use of schemas. + + Tools that translate other media types or programming languages + to and from application/schema+json MAY choose convert that media type or + programming language's native comments to or from "$comment" values. + The behavior of such translation when both native comments and "$comment" + properties are present is implementation-dependent. + + Implementations SHOULD treat "$comment" identically to an unknown extension + keyword. They MAY strip "$comment" values at any point during processing. + In particular, this allows for shortening schemas when the size of deployed + schemas is a concern. + + Implementations MUST NOT take any other action based on the presence, absence, + or contents of "$comment" properties. + +
+
@@ -723,6 +749,16 @@ User-Agent: product-name/5.4.1 so-cool-json-schema/1.0.2 curl/7.43.0 Individual JSON Schema vocabularies are liable to also have their own security considerations. Consult the respective specifications for more information. + + Schema authors should take care with "$comment" contents, as a malicious + implementation can display them to end-users in violation of a spec, or + fail to strip them if such behavior is expected. + + + A malicous schema author could place executable code or other dangerous + material within a "$comment". Implementations MUST NOT parse or otherwise + take action based on "$comment" contents. +
diff --git a/schema.json b/schema.json index 621cc510..8fa29c99 100644 --- a/schema.json +++ b/schema.json @@ -50,6 +50,9 @@ "type": "string", "format": "uri-reference" }, + "$comment": { + "type": "string" + }, "title": { "type": "string" }, From 865db54564d1078817e50d794ec5f5b9aaaaf489 Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Mon, 21 Aug 2017 16:54:53 -0700 Subject: [PATCH 2/3] Fix "$ref" quoting in section header. I noticed while adding $comment that keywords are always quoted in section headings unless the keyword is the entire heading. This is true across all three specifications, so this trivial change brings the only outlier in line with everything else. --- jsonschema-core.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/jsonschema-core.xml b/jsonschema-core.xml index 27b09e88..f652543d 100644 --- a/jsonschema-core.xml +++ b/jsonschema-core.xml @@ -390,7 +390,7 @@
-
+
The "$ref" keyword is used to reference a schema, and provides the ability to validate recursive structures through self-reference. From 93d312f1d6f4a6e1b5c6752e10aac72ecc1b37e6 Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Mon, 21 Aug 2017 17:26:44 -0700 Subject: [PATCH 3/3] Clarify $comment usage in vocabularies. This ensures that comments can be used in structures such as Hyper-Schema's LDOs without every specification needing to define it separately. --- hyper-schema.json | 3 +++ jsonschema-core.xml | 8 +++++++- 2 files changed, 10 insertions(+), 1 deletion(-) diff --git a/hyper-schema.json b/hyper-schema.json index 84249f01..3e23b689 100644 --- a/hyper-schema.json +++ b/hyper-schema.json @@ -49,6 +49,9 @@ "submissionSchema": { "description": "Schema describing the data to submit along with the request", "allOf": [ { "$ref": "#" } ] + }, + "$comment": { + "type": "string" } } } diff --git a/jsonschema-core.xml b/jsonschema-core.xml index f652543d..84cee92b 100644 --- a/jsonschema-core.xml +++ b/jsonschema-core.xml @@ -583,8 +583,14 @@ editing this keyword. The value of this keyword MAY be used in debug or error output which is intended for developers making use of schemas. + Schema vocabularies SHOULD allow "$comment" within any object containing + vocabulary keywords. Implementations MAY assume "$comment" is allowed + unless the vocabulary specifically forbids it. Vocabularies MUST NOT + specify any effect of "$comment" beyond what is described in this + specification. + Tools that translate other media types or programming languages - to and from application/schema+json MAY choose convert that media type or + to and from application/schema+json MAY choose to convert that media type or programming language's native comments to or from "$comment" values. The behavior of such translation when both native comments and "$comment" properties are present is implementation-dependent.