From 11216df70232e90c33c045f6464a5ae6f4cc007a Mon Sep 17 00:00:00 2001 From: Greg Dennis Date: Fri, 22 Nov 2024 10:25:08 +1300 Subject: [PATCH 1/6] clarify that contentSchema holds a subschema and when/how it applies --- specs/jsonschema-validation.md | 21 +++++++++++++-------- 1 file changed, 13 insertions(+), 8 deletions(-) diff --git a/specs/jsonschema-validation.md b/specs/jsonschema-validation.md index f20f64b2..819ab664 100644 --- a/specs/jsonschema-validation.md +++ b/specs/jsonschema-validation.md @@ -533,19 +533,24 @@ defined by [RFC 2046](#rfc2046). ### `contentSchema` -If the instance is a string, and if `contentMediaType` is present, this property -contains a schema which describes the structure of the string. +If the instance is a string, and if `contentMediaType` is present, this +property's subschema describes the structure of the string. This keyword MAY be used with any media type that can be mapped into JSON Schema's data model. Specifying such mappings is outside of the scope of this specification. -The value of this property MUST be a valid JSON schema. It SHOULD be ignored if -`contentMediaType` is not present. Accessing the schema through the schema -location IRI included as part of the annotation will ensure that it is correctly -processed as a subschema. Using the extracted annotation value directly is only -safe if the schema is an embedded resource with both `$schema` and an -absolute IRI `$id`. +The value of this property MUST be a valid JSON schema. The subschema is +produced as an annotation. + +Since `contentMediaType` is required to provide instruction on how to interpret +the string content, the annotation schema produced by this keyword has no +meaning if `contentMediaType` is not present. + +Accessing the schema through the schema location IRI included as part of the +annotation will ensure that it is correctly processed as a subschema. Using the +extracted annotation value directly is only safe if the subschema is an embedded +resource with both `$schema` and an absolute IRI `$id`. ### Example From 8e0466f58435ed52a52852aa37be70740d3a31e4 Mon Sep 17 00:00:00 2001 From: Greg Dennis Date: Fri, 22 Nov 2024 10:41:00 +1300 Subject: [PATCH 2/6] apply text wrap --- specs/jsonschema-validation.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/specs/jsonschema-validation.md b/specs/jsonschema-validation.md index 819ab664..23c16860 100644 --- a/specs/jsonschema-validation.md +++ b/specs/jsonschema-validation.md @@ -544,8 +544,8 @@ The value of this property MUST be a valid JSON schema. The subschema is produced as an annotation. Since `contentMediaType` is required to provide instruction on how to interpret -the string content, the annotation schema produced by this keyword has no -meaning if `contentMediaType` is not present. +string content, the annotation schema produced by this keyword has no meaning if +`contentMediaType` is not present. Accessing the schema through the schema location IRI included as part of the annotation will ensure that it is correctly processed as a subschema. Using the From 6342ec3754eed4ba4dfbf8585e71a70dba034cb6 Mon Sep 17 00:00:00 2001 From: Greg Dennis Date: Sun, 24 Nov 2024 11:48:06 +1300 Subject: [PATCH 3/6] update note about processing contentSchema subschema in context --- specs/jsonschema-validation.md | 16 ++++++++++++---- 1 file changed, 12 insertions(+), 4 deletions(-) diff --git a/specs/jsonschema-validation.md b/specs/jsonschema-validation.md index 23c16860..e8442158 100644 --- a/specs/jsonschema-validation.md +++ b/specs/jsonschema-validation.md @@ -547,10 +547,18 @@ Since `contentMediaType` is required to provide instruction on how to interpret string content, the annotation schema produced by this keyword has no meaning if `contentMediaType` is not present. -Accessing the schema through the schema location IRI included as part of the -annotation will ensure that it is correctly processed as a subschema. Using the -extracted annotation value directly is only safe if the subschema is an embedded -resource with both `$schema` and an absolute IRI `$id`. +Note that evaluating the `contentSchema` subschema in-place (i.e. as part of its +parent schema) will ensure that it is correctly processed. Independent use of +the extracted subschema (as returned in an annotation) is only safe if the +subschema is an embedded reource which defines both a `$schema` and an absolute +IRI `$id`.[^7] + +[^7] Processing a non-resource subschema in place will ensure that any +references (e.g. `$ref`) are always resolved properly. This isn't a problem when +the subschema is itself a resource. See +https://github.com/json-schema-org/json-schema-spec/issues/1381 for several +examples where processing this subschema independently can cause `$ref` +resolution failure. ### Example From a90049e01ac8c6d0f0247c0bc05583fa40cd1679 Mon Sep 17 00:00:00 2001 From: Greg Dennis Date: Thu, 28 Nov 2024 21:13:51 +1300 Subject: [PATCH 4/6] Update specs/jsonschema-validation.md Co-authored-by: Jason Desrosiers --- specs/jsonschema-validation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specs/jsonschema-validation.md b/specs/jsonschema-validation.md index e8442158..5f488977 100644 --- a/specs/jsonschema-validation.md +++ b/specs/jsonschema-validation.md @@ -534,7 +534,7 @@ defined by [RFC 2046](#rfc2046). ### `contentSchema` If the instance is a string, and if `contentMediaType` is present, this -property's subschema describes the structure of the string. +keyword's subschema describes the structure of the string. This keyword MAY be used with any media type that can be mapped into JSON Schema's data model. Specifying such mappings is outside of the scope of this From f6276dc8819c6c7d4f517e63b7ddd3ada8aa6fe9 Mon Sep 17 00:00:00 2001 From: Greg Dennis Date: Thu, 28 Nov 2024 21:18:41 +1300 Subject: [PATCH 5/6] contentSchema should not produce an annotation --- specs/jsonschema-validation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specs/jsonschema-validation.md b/specs/jsonschema-validation.md index 5f488977..4dd653d6 100644 --- a/specs/jsonschema-validation.md +++ b/specs/jsonschema-validation.md @@ -544,7 +544,7 @@ The value of this property MUST be a valid JSON schema. The subschema is produced as an annotation. Since `contentMediaType` is required to provide instruction on how to interpret -string content, the annotation schema produced by this keyword has no meaning if +string content, `contentSchema` SHOULD NOT produce an annotation if `contentMediaType` is not present. Note that evaluating the `contentSchema` subschema in-place (i.e. as part of its From 87f6201e8cf9ade76d5d7eabeb7afe1f90aab136 Mon Sep 17 00:00:00 2001 From: Greg Dennis Date: Sat, 25 Jan 2025 11:54:53 +1300 Subject: [PATCH 6/6] Update specs/jsonschema-validation.md Co-authored-by: Jason Desrosiers --- specs/jsonschema-validation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specs/jsonschema-validation.md b/specs/jsonschema-validation.md index 4dd653d6..dd36b268 100644 --- a/specs/jsonschema-validation.md +++ b/specs/jsonschema-validation.md @@ -550,7 +550,7 @@ string content, `contentSchema` SHOULD NOT produce an annotation if Note that evaluating the `contentSchema` subschema in-place (i.e. as part of its parent schema) will ensure that it is correctly processed. Independent use of the extracted subschema (as returned in an annotation) is only safe if the -subschema is an embedded reource which defines both a `$schema` and an absolute +subschema is an embedded resource which defines both a `$schema` and an absolute IRI `$id`.[^7] [^7] Processing a non-resource subschema in place will ensure that any