Define compound schema documents (#936)

jsonschema-core.xml

@@ -1159,7 +1159,7 @@
                     Meta-schema authoring is an advanced usage of JSON Schema, so the design of
                     meta-schema features emphasizes flexibility over simplicity.
                 </t>
-                <section title='The "$schema" Keyword'>
+                <section title='The "$schema" Keyword' anchor="keyword-schema">
                     <t>
                         The "$schema" keyword is both used as a JSON Schema feature set identifier and
                         as the identifier of a resource which is itself a JSON Schema, which describes the
@@ -1180,16 +1180,6 @@
                         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
-                        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,
                         and by other parties.
@@ -1845,6 +1835,86 @@
                 </section>
             </section>
 
+            <section title="Compound Documents">
+                <t>
+                    A Compound Schema Document is defined as JSON document (sometimes called a "bundled" schema)
+                    which has multiple embedded JSON Schema Resources bundled into the same document to
+                    ease transportation.
+                </t>
+                <t>
+                    Each embedded Schema Resource MUST be treated as an individual Schema Resource, following standard
+                    schema loading and processing requirements, including determining vocabulary support.
+                </t>
+                <section title="Bundling">
+                    <t>
+                        The bundling process for creating a Compound Schema Document is defined as taking
+                        references (such as "$ref") to an external Schema Resource and embedding the referenced
+                        Schema Resources within the referring document. Bundling is done in such a way that
+                        all URIs (used for referencing) in the base document and any referenced/embedded
+                        documents do not require altering.
+                    </t>
+                    <t>
+                        Each embedded JSON Schema Resource MUST identify itself with an absolute URI using the "$id" keyword,
+                        and SHOULD make use of the "$schema" keyword to identify the dialect it is using, in the root of the
+                        schema resource.
+                    </t>
+                    <t>
+                        When the Schema Resource referenced by a by-reference applicator is bundled, the Schema Resource
+                        MUST be located as a value of a "$defs" object at the containing schema's root.
+                        The key of the "$defs" for the now embedded Schema Resource MAY be the "$id" of the bundled schema
+                        or some other form of application defined unique identifer (such as a UUID). This key is not
+                        intended to be referenced in JSON Schema, but may be used by an application to aid the
+                        bundling process.
+                    </t>
+                    <t>
+                        Bundled Schema Resource MUST NOT be bundled by replacing the schema object from which it was
+                        referenced, or by wrapping the Schema Resource in other applicator keywords.
+                    </t>
+                    <t>
+                        In order to produce identical output, references in the containing schema document to the
+                        previously external Schema Resources MUST NOT be changed, and now resolve to a schema using the
+                        "$id" of an embedded Schema Resource. Such identical output includes validation evaluation and URIs
+                        or paths used in resulting annotations or errors.
+                    </t>
+                    <t>
+                        While the bundling process will often be the main method for creating a Compound Schema Document,
+                        it is also possible and expected that some will be created by hand, potentially without individual
+                        Schema Resources existing on their own previously.
+                    </t>
+                </section>
+                <section title="Differing and Default Dialects">
+                    <t>
+                        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>
+                        Since any schema that can be referenced can also be embedded, embedded schema resources MAY
+                        specify different "$schema" values from their enclosing resource.
+                    </t>
+                </section>
+                <section title="Validating">
+                    <t>
+                        Given that a Compound Schema Document may have embedded resources which identify as using different
+                        dialects, these documents SHOULD NOT be validated by applying a meta-schema
+                        to the Compound Schema Document as an instance. It is RECOMMENDED that an alternate
+                        validation process be provided in order to validate Schema Documents. Each Schema Resource
+                        SHOULD be separately validated against its associated meta-schema.
+                        <cref>
+                            If you know a schema is what's being validated, you can identify if the schemas
+                            is a Compound Schema Document or not, by way of use of "$id", which identifies an
+                            embedded resource when used not at the document's root.
+                        </cref>
+                    </t>
+                    <t>
+                        A Compound Schema Document in which all embedded resources idenfity as using the same
+                        dialec, or in which "$schema" is omitted and therefore defaults to that of the enclosing resource,
+                        MAY be validated by applying the appropriate meta-schema.
+                    </t>
+                </section>
+            </section>
+
             <section title="Caveats">
                 <section title="Guarding Against Infinite Recursion">
                     <t>
@@ -3854,7 +3924,7 @@ https://example.com/schemas/common#/$defs/count/minimum
                             <t>Rename $recursive* to $dynamic*</t>
                             <t>$dynamicAnchor defines a fragment like $anchor</t>
                             <t>$dynamic* (previously $recursive) no longer use runtime base URI determination</t>
-                            <t></t>
+                            <t>Define Compound Schema Documents (bundle) and processing</t>
                             <t></t>
                             <t></t>
                             <t></t>