Merge pull request #914 from handrews/schema-res

$schema can change across embedded resources

Author: Relequestual

jsonschema-core.xml

@@ -450,6 +450,10 @@
                         is its top-level schema object, which would also be a document root schema
                         if the resource were to be extracted to a standalone JSON Schema document.
                     </t>
+                    <t>
+                        Whether multiple schema resources are embedded or linked with a reference,
+                        they are processed in the same way, with the same available behaviors.
+                    </t>
                 </section>
             </section>
 
@@ -631,7 +635,7 @@
                 </t>
                 <t>
                     Note that some keywords, such as "$schema", apply to the lexical
-                    scope of the entire schema document, and therefore MUST only
+                    scope of the entire schema resource, and therefore MUST only
                     appear in a schema resource's root schema.
                 </t>
                 <t>
@@ -1163,37 +1167,20 @@
                         media type "application/schema+json".
                     </t>
                     <t>
-                        The "$schema" keyword SHOULD be used in a resource root schema.
-                        It MUST NOT appear in resource subschemas.  If absent from the root schema, the
-                        resulting behavior is implementation-defined.
+                        The "$schema" keyword SHOULD be used in the document root schema object,
+                        and MAY be used in the root schema objects of embedded schema resources.
+                        It MUST NOT appear in non-resource root schema objects.  If absent from
+                        the document root schema, the resulting behavior is implementation-defined.
                     </t>
                     <t>
-                        If multiple schema resources are present in a single document, then all
-                        schema resources SHOULD Have the same value for "$schema".  The result of
-                        differing values for "$schema" within the same schema document is
-                        implementation-defined.
-                        <cref>
-                            Using multiple "$schema" keywords in the same document would imply that the
-                            feature set and therefore behavior can change within a document.  This would
-                            necessitate resolving a number of implementation concerns that have not yet
-                            been clearly defined.  So, while the pattern of using "$schema" only in root
-                            schemas is likely to remain the best practice for schema authoring,
-                            implementation behavior is subject to be revised or liberalized in
-                            future drafts.
-                        </cref>
-                        <cref>
-                            The exception made for embedded schema resources is to
-                            allow bundling multiple schema resources into a single schema document
-                            without needing to change their contents, as described later in this
-                            specification.
-                        </cref>
-                        <!--
-                            In particular, the process of validating an instance, including validating a
-                            schema as an instance against its meta-schema, only allows for a single set
-                            of rules across the entire instance document.  There is no equivalent of
-                            changing the meta-schema partway through the validation for non-schema
-                            instances.
-                        -->
+                        If multiple schema resources are present in a single document, then
+                        schema resources which do not have a "$schema" keyword in their root
+                        schema object MUST be processed as if "$schema" were present with the
+                        same value as for the immediately enclosing resource.
+                    </t>
+                    <t>
+                        Embedded schema resources MAY specify different "$schema" values from their
+                        enclosing resource, as any schema that can be referenced can also be embedded.
                     </t>
                     <t>
                         Values for this property are defined elsewhere in this and other documents,
@@ -3789,7 +3776,7 @@ https://example.com/schemas/common#/$defs/count/minimum
                 <list style="hanging">
                     <t hangText="draft-handrews-json-schema-03">
                         <list style="symbols">
-                            <t></t>
+                            <t>"$schema" MAY change for embedded resources</t>
                             <t>Array-value "items" functionality is now "prefixItems"</t>
                             <t>"items" subsumes the old function of "additionalItems"</t>
                             <t>"contains" and "unevaluatedItems" interactions now specified</t>