Skip to content

Commit 365e697

Browse files
RelequestualRelequestual
authored
Merge pull request #977 from Relequestual/Fix/936
Define compound schema documents (#936)
2 parents 78413ee + 20e1910 commit 365e697

File tree

1 file changed

+82
-12
lines changed

1 file changed

+82
-12
lines changed

‎jsonschema-core.xml

Lines changed: 82 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1159,7 +1159,7 @@
11591159
Meta-schema authoring is an advanced usage of JSON Schema, so the design of
11601160
meta-schema features emphasizes flexibility over simplicity.
11611161
</t>
1162-
<section title='The "$schema" Keyword'>
1162+
<section title='The "$schema" Keyword' anchor="keyword-schema">
11631163
<t>
11641164
The "$schema" keyword is both used as a JSON Schema feature set identifier and
11651165
as the identifier of a resource which is itself a JSON Schema, which describes the
@@ -1180,16 +1180,6 @@
11801180
It MUST NOT appear in non-resource root schema objects. If absent from
11811181
the document root schema, the resulting behavior is implementation-defined.
11821182
</t>
1183-
<t>
1184-
If multiple schema resources are present in a single document, then
1185-
schema resources which do not have a "$schema" keyword in their root
1186-
schema object MUST be processed as if "$schema" were present with the
1187-
same value as for the immediately enclosing resource.
1188-
</t>
1189-
<t>
1190-
Embedded schema resources MAY specify different "$schema" values from their
1191-
enclosing resource, as any schema that can be referenced can also be embedded.
1192-
</t>
11931183
<t>
11941184
Values for this property are defined elsewhere in this and other documents,
11951185
and by other parties.
@@ -1845,6 +1835,86 @@
18451835
</section>
18461836
</section>
18471837

1838+
<section title="Compound Documents">
1839+
<t>
1840+
A Compound Schema Document is defined as JSON document (sometimes called a "bundled" schema)
1841+
which has multiple embedded JSON Schema Resources bundled into the same document to
1842+
ease transportation.
1843+
</t>
1844+
<t>
1845+
Each embedded Schema Resource MUST be treated as an individual Schema Resource, following standard
1846+
schema loading and processing requirements, including determining vocabulary support.
1847+
</t>
1848+
<section title="Bundling">
1849+
<t>
1850+
The bundling process for creating a Compound Schema Document is defined as taking
1851+
references (such as "$ref") to an external Schema Resource and embedding the referenced
1852+
Schema Resources within the referring document. Bundling is done in such a way that
1853+
all URIs (used for referencing) in the base document and any referenced/embedded
1854+
documents do not require altering.
1855+
</t>
1856+
<t>
1857+
Each embedded JSON Schema Resource MUST identify itself with an absolute URI using the "$id" keyword,
1858+
and SHOULD make use of the "$schema" keyword to identify the dialect it is using, in the root of the
1859+
schema resource.
1860+
</t>
1861+
<t>
1862+
When the Schema Resource referenced by a by-reference applicator is bundled, the Schema Resource
1863+
MUST be located as a value of a "$defs" object at the containing schema's root.
1864+
The key of the "$defs" for the now embedded Schema Resource MAY be the "$id" of the bundled schema
1865+
or some other form of application defined unique identifer (such as a UUID). This key is not
1866+
intended to be referenced in JSON Schema, but may be used by an application to aid the
1867+
bundling process.
1868+
</t>
1869+
<t>
1870+
Bundled Schema Resource MUST NOT be bundled by replacing the schema object from which it was
1871+
referenced, or by wrapping the Schema Resource in other applicator keywords.
1872+
</t>
1873+
<t>
1874+
In order to produce identical output, references in the containing schema document to the
1875+
previously external Schema Resources MUST NOT be changed, and now resolve to a schema using the
1876+
"$id" of an embedded Schema Resource. Such identical output includes validation evaluation and URIs
1877+
or paths used in resulting annotations or errors.
1878+
</t>
1879+
<t>
1880+
While the bundling process will often be the main method for creating a Compound Schema Document,
1881+
it is also possible and expected that some will be created by hand, potentially without individual
1882+
Schema Resources existing on their own previously.
1883+
</t>
1884+
</section>
1885+
<section title="Differing and Default Dialects">
1886+
<t>
1887+
If multiple schema resources are present in a single document, then
1888+
schema resources which do not have a "$schema" keyword in their root
1889+
schema object MUST be processed as if "$schema" were present with the
1890+
same value as for the immediately enclosing resource.
1891+
</t>
1892+
<t>
1893+
Since any schema that can be referenced can also be embedded, embedded schema resources MAY
1894+
specify different "$schema" values from their enclosing resource.
1895+
</t>
1896+
</section>
1897+
<section title="Validating">
1898+
<t>
1899+
Given that a Compound Schema Document may have embedded resources which identify as using different
1900+
dialects, these documents SHOULD NOT be validated by applying a meta-schema
1901+
to the Compound Schema Document as an instance. It is RECOMMENDED that an alternate
1902+
validation process be provided in order to validate Schema Documents. Each Schema Resource
1903+
SHOULD be separately validated against its associated meta-schema.
1904+
<cref>
1905+
If you know a schema is what's being validated, you can identify if the schemas
1906+
is a Compound Schema Document or not, by way of use of "$id", which identifies an
1907+
embedded resource when used not at the document's root.
1908+
</cref>
1909+
</t>
1910+
<t>
1911+
A Compound Schema Document in which all embedded resources idenfity as using the same
1912+
dialec, or in which "$schema" is omitted and therefore defaults to that of the enclosing resource,
1913+
MAY be validated by applying the appropriate meta-schema.
1914+
</t>
1915+
</section>
1916+
</section>
1917+
18481918
<section title="Caveats">
18491919
<section title="Guarding Against Infinite Recursion">
18501920
<t>
@@ -3854,7 +3924,7 @@ https://example.com/schemas/common#/$defs/count/minimum
38543924
<t>Rename $recursive* to $dynamic*</t>
38553925
<t>$dynamicAnchor defines a fragment like $anchor</t>
38563926
<t>$dynamic* (previously $recursive) no longer use runtime base URI determination</t>
3857-
<t></t>
3927+
<t>Define Compound Schema Documents (bundle) and processing</t>
38583928
<t></t>
38593929
<t></t>
38603930
<t></t>

0 commit comments

Comments
 (0)