Merge pull request #1564 from json-schema-org/gregsdennis/contentSchema

clarify that contentSchema holds a subschema and when/how it applies

Author: gregsdennis

specs/jsonschema-validation.md

@@ -548,19 +548,32 @@ defined by [RFC 2046](https://www.rfc-editor.org/info/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