Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Sign up
Appearance settings

Commit b30d80b

Browse files
Merge pull request #782 from handrews/new-examp
Improve vocab example per gregsdennis suggestions
2 parents 84778d1 + fbfb852 commit b30d80b

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
@@ -1210,6 +1210,15 @@
12101210
must be repeated in the root of each schema document intended
12111211
for use as a meta-schema. This is demonstrated in
12121212
<xref target="example-meta-schema">the example meta-schema</xref>.
1213+
<cref>
1214+
This requirement allows implementations to find all vocabulary
1215+
requirement information in a single place for each meta-schema.
1216+
As schema extensibility means that there are endless potential
1217+
ways to combine more fine-grained meta-schemas by reference,
1218+
requiring implementations to anticipate all possibilities and
1219+
search for vocabularies in referenced meta-schemas would
1220+
be overly burdensome.
1221+
</cref>
12131222
</t>
12141223
</section>
12151224
</section>
@@ -1310,53 +1319,93 @@
13101319
</section>
13111320
<section title="Example Meta-Schema With Vocabulary Declarations"
13121321
anchor="example-meta-schema">
1322+
<t>
1323+
This meta-schema explicitly declares both the Core and Applicator vocabularies,
1324+
together with an extension vocabulary, and combines their meta-schemas with
1325+
an "allOf". The extension vocabulary's meta-schema, which describes only the
1326+
keywords in that vocabulary, is shown after the main example meta-schema.
1327+
</t>
1328+
<t>
1329+
The main example meta-schema also restricts the usage of the Applicator
1330+
vocabulary by forbidding the keywords prefixed with "unevaluated", which
1331+
are particularly complex to implement. This does not change the semantics
1332+
or set of keywords defined by the Applicator vocabulary. It just ensures
1333+
that schemas using this meta-schema that attempt to use the keywords
1334+
prefixed with "unevaluted" will fail validation against this meta-schema.
1335+
</t>
1336+
<t>
1337+
Finally, this meta-schema describes the syntax of a keyword, "localKeyword",
1338+
that is not part of any vocabulary. Presumably, the implementors and users
1339+
of this meta-schema will understand the semantics of "localKeyword".
1340+
JSON Schema does not define any mechanism for expressing keyword semantics
1341+
outside of vocabularies, making them unsuitable for use except in a
1342+
specific environment in which they are understood.
1343+
</t>
13131344
<figure>
13141345
<preamble>
1315-
This meta-schema explicitly declares both the Core and Applicator
1316-
vocabularies, and combines their meta-schemas with an "allOf".
1317-
It additionally restricts the usage of the Applicator vocabulary
1318-
by forbidding the keyword prefixed with "unevaluated". It also
1319-
describes a keyword, "localKeyword", that is not part of either
1320-
vocabulary. Note that it is its own meta-schema,
1321-
as it relies on both the Core vocabulary (as all schemas do)
1322-
and the Applicator vocabulary (for "allOf").
1346+
This meta-schema combines several vocabularies for general use.
13231347
</preamble>
13241348
<artwork>
13251349
<![CDATA[
13261350
{
1327-
"$schema": "https://json-schema.org/draft/2019-08/core-app-example#",
1328-
"$id": "https://json-schema.org/draft/2019-08/core-app-example",
1351+
"$schema": "https://json-schema.org/draft/2019-08/schema",
1352+
"$id": "https://example.com/meta/general-use-example",
13291353
"$recursiveAnchor": true,
13301354
"$vocabulary": {
13311355
"https://json-schema.org/draft/2019-08/vocab/core": true,
1332-
"https://json-schema.org/draft/2019-08/vocab/applicator": true
1356+
"https://json-schema.org/draft/2019-08/vocab/applicator": true,
1357+
"https://json-schema.org/draft/2019-08/vocab/validation": true,
1358+
"https://example.com/vocab/example-vocab": true
13331359
},
13341360
"allOf": [
13351361
{"$ref": "https://json-schema.org/draft/2019-08/meta/core"},
1336-
{"$ref": "https://json-schema.org/draft/2019-08/meta/applicator"}
1362+
{"$ref": "https://json-schema.org/draft/2019-08/meta/applicator"},
1363+
{"$ref": "https://json-schema.org/draft/2019-08/meta/validation"},
1364+
{"$ref": "https://example.com/meta/example-vocab",
13371365
],
13381366
"patternProperties": {
13391367
"^unevaluated.*$": false
13401368
},
13411369
"properties": {
1342-
"$comment": "Not in vocabulary, but validated if used",
13431370
"localKeyword": {
1371+
"$comment": "Not in vocabulary, but validated if used",
13441372
"type": "string"
13451373
}
13461374
}
13471375
}
13481376
]]>
13491377
</artwork>
1350-
<postamble>
1351-
As shown above, even though each of the referenced standard
1352-
meta-schemas declares its corresponding vocabulary, this new
1353-
meta-schema must re-declare them for itself. It would be
1354-
valid to leave the core vocabulary out of the "$vocabulary" keyword,
1355-
but it needs to be referenced through the "allOf" keyword in order
1356-
for its terms to be validated. There is no special case for
1357-
validation of core keywords.
1358-
</postamble>
1378+
</figure>
1379+
<figure>
1380+
<preamble>
1381+
This meta-schema describes only a single extension vocabulary.
1382+
</preamble>
1383+
<artwork>
1384+
<![CDATA[
1385+
{
1386+
"$schema": "https://json-schema.org/draft/2019-08/schema",
1387+
"$id": "https://example.com/meta/example-vocab",
1388+
"$recursiveAnchor": true,
1389+
"$vocabulary": {
1390+
"https://example.com/vocab/example-vocab": true,
1391+
},
1392+
"type": ["object", "boolean"],
1393+
"properties": {
1394+
"minDate": {
1395+
"type": "string",
1396+
"pattern": "\d\d\d\d-\d\d-\d\d",
1397+
"format": "date",
1398+
}
1399+
}
1400+
}
1401+
]]>
1402+
</artwork>
13591403
</figure>
1404+
<t>
1405+
As shown above, even though each of the single-vocabulary meta-schemas
1406+
referenced in the general-use meta-schema's "allOf" declares its
1407+
corresponding vocabulary, this new meta-schema must re-declare them.
1408+
</t>
13601409
<t>
13611410
The standard meta-schemas that combine all vocabularies defined by
13621411
the Core and Validation specification, and that combine all vocabularies
@@ -1365,6 +1414,17 @@
13651414
meta-schemas may be found in the Validation and Hyper-Schema specifications,
13661415
respectively.
13671416
</t>
1417+
<t>
1418+
While the general-use meta-schema can validate the syntax of "minDate",
1419+
it is the vocabulary that defines the logic behind the semantic meaning
1420+
of "minDate". Without an understanding of the semantics (in this example,
1421+
that the instance value must be a date equal to or after the date
1422+
provided as the keyword's value in the schema), an implementation can
1423+
only validate the syntactic usage. In this case, that means validating
1424+
that it is a date-formatted string (using "pattern" to ensure that it is
1425+
validated even when "format" functions purely as an annotation, as explained
1426+
in the <xref target="json-schema-validation">Validation specification</xref>.
1427+
</t>
13681428
</section>
13691429
</section>
13701430

@@ -1600,7 +1660,7 @@
16001660
<artwork>
16011661
<![CDATA[
16021662
{
1603-
"$schema": "https://json-schema.org/draft/2019-08/schema#",
1663+
"$schema": "https://json-schema.org/draft/2019-08/schema",
16041664
"$id": "https://example.com/original",
16051665
16061666
"properties": {
@@ -1614,7 +1674,7 @@
16141674
}
16151675
16161676
{
1617-
"$schema": "https://json-schema.org/draft/2019-08/schema#",
1677+
"$schema": "https://json-schema.org/draft/2019-08/schema",
16181678
"$id": "https://example.com/extension",
16191679
16201680
"$ref": "original",
@@ -1713,7 +1773,7 @@
17131773
<artwork>
17141774
<![CDATA[
17151775
{
1716-
"$schema": "https://json-schema.org/draft/2019-08/schema#",
1776+
"$schema": "https://json-schema.org/draft/2019-08/schema",
17171777
"$id": "https://example.com/original",
17181778
"$recursiveAnchor": true,
17191779
@@ -1728,7 +1788,7 @@
17281788
}
17291789
17301790
{
1731-
"$schema": "https://json-schema.org/draft/2019-08/schema#",
1791+
"$schema": "https://json-schema.org/draft/2019-08/schema",
17321792
"$id": "https://example.com/extension",
17331793
"$recursiveAnchor": true,
17341794

0 commit comments

Comments
(0)

AltStyle によって変換されたページ (->オリジナル) /