diff --git a/specs/jsonschema-validation.md b/specs/jsonschema-validation.md index f20f64b2..dd36b268 100644 --- a/specs/jsonschema-validation.md +++ b/specs/jsonschema-validation.md @@ -533,19 +533,32 @@ 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 +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 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 +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 +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 resource 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