Skip to content

Commit 61a7747

Browse files
committed
Improve vocab example per gregsdennis suggestions
This incorporates most of the ideas from an earlier PR by gregsdennis, updated and enhanced by some clarifications and enhancments that were made after that PR was originally written. The example now follows the best practices from the previous section by showing separate general purpose and single-vocabulary meta-schemas, and discusses how they are used together.
1 parent c5a6078 commit 61a7747

File tree

1 file changed

+86
-26
lines changed

1 file changed

+86
-26
lines changed

jsonschema-core.xml

Lines changed: 86 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -1208,6 +1208,15 @@
12081208
must be repeated in the root of each schema document intended
12091209
for use as a meta-schema. This is demonstrated in
12101210
<xref target="example-meta-schema">the example meta-schema</xref>.
1211+
<cref>
1212+
This requirement allows implementations to find all vocabulary
1213+
requirement information in a single place for each meta-schema.
1214+
As schema extensibility means that there are endless potential
1215+
ways to combine more fine-grained meta-schemas by reference,
1216+
requiring implementations to anticipate all possibilities and
1217+
search for vocabularies in referenced meta-schemas would
1218+
be overly burdensome.
1219+
</cref>
12111220
</t>
12121221
</section>
12131222
</section>
@@ -1308,53 +1317,93 @@
13081317
</section>
13091318
<section title="Example Meta-Schema With Vocabulary Declarations"
13101319
anchor="example-meta-schema">
1320+
<t>
1321+
This meta-schema explicitly declares both the Core and Applicator vocabularies,
1322+
together with an extension vocabulary, and combines their meta-schemas with
1323+
an "allOf". The extension vocabulary's meta-schema, which describes only the
1324+
keywords in that vocabulary, is shown after the main example meta-schema.
1325+
</t>
1326+
<t>
1327+
The main example meta-schema also restricts the usage of the Applicator
1328+
vocabulary by forbidding the keywords prefixed with "unevaluated", which
1329+
are particularly complex to implement. This does not change the semantics
1330+
or set of keywords defined by the Applicator vocabulary. It just ensures
1331+
that schemas using this meta-schema that attempt to use the keywords
1332+
prefixed with "unevaluted" will fail validation against this meta-schema.
1333+
</t>
1334+
<t>
1335+
Finally, this meta-schema describes the syntax of a keyword, "localKeyword",
1336+
that is not part of any vocabulary. Presumably, the implementors and users
1337+
of this meta-schema will understand the semantics of "localKeyword".
1338+
JSON Schema does not define any mechanism for expressing keyword semantics
1339+
outside of vocabularies, making them unsuitable for use except in a
1340+
specific environment in which they are understood.
1341+
</t>
13111342
<figure>
13121343
<preamble>
1313-
This meta-schema explicitly declares both the Core and Applicator
1314-
vocabularies, and combines their meta-schemas with an "allOf".
1315-
It additionally restricts the usage of the Applicator vocabulary
1316-
by forbidding the keyword prefixed with "unevaluated". It also
1317-
describes a keyword, "localKeyword", that is not part of either
1318-
vocabulary. Note that it is its own meta-schema,
1319-
as it relies on both the Core vocabulary (as all schemas do)
1320-
and the Applicator vocabulary (for "allOf").
1344+
This meta-schema combines several vocabularies for general use.
13211345
</preamble>
13221346
<artwork>
13231347
<![CDATA[
13241348
{
1325-
"$schema": "https://json-schema.org/draft/2019-08/core-app-example#",
1326-
"$id": "https://json-schema.org/draft/2019-08/core-app-example",
1349+
"$schema": "https://json-schema.org/draft/2019-08/schema",
1350+
"$id": "https://example.com/meta/general-use-example",
13271351
"$recursiveAnchor": true,
13281352
"$vocabulary": {
13291353
"https://json-schema.org/draft/2019-08/vocab/core": true,
1330-
"https://json-schema.org/draft/2019-08/vocab/applicator": true
1354+
"https://json-schema.org/draft/2019-08/vocab/applicator": true,
1355+
"https://json-schema.org/draft/2019-08/vocab/validation": true,
1356+
"https://example.com/vocab/core-app-example": true
13311357
},
13321358
"allOf": [
13331359
{"$ref": "https://json-schema.org/draft/2019-08/meta/core"},
1334-
{"$ref": "https://json-schema.org/draft/2019-08/meta/applicator"}
1360+
{"$ref": "https://json-schema.org/draft/2019-08/meta/applicator"},
1361+
{"$ref": "https://json-schema.org/draft/2019-08/meta/validation"},
1362+
{"$ref": "https://example.com/meta/core-app-example-vocab",
13351363
],
13361364
"patternProperties": {
13371365
"^unevaluated.*$": false
13381366
},
13391367
"properties": {
1340-
"$comment": "Not in vocabulary, but validated if used",
13411368
"localKeyword": {
1369+
"$comment": "Not in vocabulary, but validated if used",
13421370
"type": "string"
13431371
}
13441372
}
13451373
}
13461374
]]>
13471375
</artwork>
1348-
<postamble>
1349-
As shown above, even though each of the referenced standard
1350-
meta-schemas declares its corresponding vocabulary, this new
1351-
meta-schema must re-declare them for itself. It would be
1352-
valid to leave the core vocabulary out of the "$vocabulary" keyword,
1353-
but it needs to be referenced through the "allOf" keyword in order
1354-
for its terms to be validated. There is no special case for
1355-
validation of core keywords.
1356-
</postamble>
1376+
</figure>
1377+
<figure>
1378+
<preamble>
1379+
This meta-schema describes only a single extension vocabulary.
1380+
</preamble>
1381+
<artwork>
1382+
<![CDATA[
1383+
{
1384+
"$schema": "https://json-schema.org/draft/2019-08/schema",
1385+
"$id": "https://example.com/meta/core-app-example-vocab",
1386+
"$recursiveAnchor": true,
1387+
"$vocabulary": {
1388+
"https://example.com/vocab/core-app-example": true,
1389+
},
1390+
"type": ["object", "boolean"],
1391+
"properties": {
1392+
"minDate": {
1393+
"type": "string",
1394+
"pattern": "\d\d\d\d-\d\d-\d\d",
1395+
"format": "date",
1396+
}
1397+
}
1398+
}
1399+
]]>
1400+
</artwork>
13571401
</figure>
1402+
<t>
1403+
As shown above, even though each of the single-vocabulary meta-schemas
1404+
referenced in the general-use meta-schema's "allOf" declares its
1405+
corresponding vocabulary, this new meta-schema must re-declare them.
1406+
</t>
13581407
<t>
13591408
The standard meta-schemas that combine all vocabularies defined by
13601409
the Core and Validation specification, and that combine all vocabularies
@@ -1363,6 +1412,17 @@
13631412
meta-schemas may be found in the Validation and Hyper-Schema specifications,
13641413
respectively.
13651414
</t>
1415+
<t>
1416+
While the general-use meta-schema can validate the syntax of "minDate",
1417+
it is the vocabulary that defines the logic behind the semantic meaning
1418+
of "minDate". Without an understanding of the semantics (in this example,
1419+
that the instance value must be a date equal to or after the date
1420+
provided as the keyword's value in the schema), an implementation can
1421+
only validate the syntactic usage. In this case, that means validating
1422+
that it is a date-formatted string (using "pattern" to ensure that it is
1423+
validated even when "format" functions purely as an annotation, as explained
1424+
in the <xref target="json-schema-validation">Validation specification</xref>.
1425+
</t>
13661426
</section>
13671427
</section>
13681428

@@ -1598,7 +1658,7 @@
15981658
<artwork>
15991659
<![CDATA[
16001660
{
1601-
"$schema": "https://json-schema.org/draft/2019-08/schema#",
1661+
"$schema": "https://json-schema.org/draft/2019-08/schema",
16021662
"$id": "https://example.com/original",
16031663
16041664
"properties": {
@@ -1612,7 +1672,7 @@
16121672
}
16131673
16141674
{
1615-
"$schema": "https://json-schema.org/draft/2019-08/schema#",
1675+
"$schema": "https://json-schema.org/draft/2019-08/schema",
16161676
"$id": "https://example.com/extension",
16171677
16181678
"$ref": "original",
@@ -1711,7 +1771,7 @@
17111771
<artwork>
17121772
<![CDATA[
17131773
{
1714-
"$schema": "https://json-schema.org/draft/2019-08/schema#",
1774+
"$schema": "https://json-schema.org/draft/2019-08/schema",
17151775
"$id": "https://example.com/original",
17161776
"$recursiveAnchor": true,
17171777
@@ -1726,7 +1786,7 @@
17261786
}
17271787
17281788
{
1729-
"$schema": "https://json-schema.org/draft/2019-08/schema#",
1789+
"$schema": "https://json-schema.org/draft/2019-08/schema",
17301790
"$id": "https://example.com/extension",
17311791
"$recursiveAnchor": true,
17321792

0 commit comments

Comments
 (0)