|
1208 | 1208 | must be repeated in the root of each schema document intended
|
1209 | 1209 | for use as a meta-schema. This is demonstrated in
|
1210 | 1210 | <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> |
1211 | 1220 | </t>
|
1212 | 1221 | </section>
|
1213 | 1222 | </section>
|
|
1308 | 1317 | </section>
|
1309 | 1318 | <section title="Example Meta-Schema With Vocabulary Declarations"
|
1310 | 1319 | 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> |
1311 | 1342 | <figure>
|
1312 | 1343 | <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. |
1321 | 1345 | </preamble>
|
1322 | 1346 | <artwork>
|
1323 | 1347 | <![CDATA[
|
1324 | 1348 | {
|
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", |
1327 | 1351 | "$recursiveAnchor": true,
|
1328 | 1352 | "$vocabulary": {
|
1329 | 1353 | "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 |
1331 | 1357 | },
|
1332 | 1358 | "allOf": [
|
1333 | 1359 | {"$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", |
1335 | 1363 | ],
|
1336 | 1364 | "patternProperties": {
|
1337 | 1365 | "^unevaluated.*$": false
|
1338 | 1366 | },
|
1339 | 1367 | "properties": {
|
1340 |
| - "$comment": "Not in vocabulary, but validated if used", |
1341 | 1368 | "localKeyword": {
|
| 1369 | + "$comment": "Not in vocabulary, but validated if used", |
1342 | 1370 | "type": "string"
|
1343 | 1371 | }
|
1344 | 1372 | }
|
1345 | 1373 | }
|
1346 | 1374 | ]]>
|
1347 | 1375 | </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> |
1357 | 1401 | </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> |
1358 | 1407 | <t>
|
1359 | 1408 | The standard meta-schemas that combine all vocabularies defined by
|
1360 | 1409 | the Core and Validation specification, and that combine all vocabularies
|
|
1363 | 1412 | meta-schemas may be found in the Validation and Hyper-Schema specifications,
|
1364 | 1413 | respectively.
|
1365 | 1414 | </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> |
1366 | 1426 | </section>
|
1367 | 1427 | </section>
|
1368 | 1428 |
|
|
1598 | 1658 | <artwork>
|
1599 | 1659 | <![CDATA[
|
1600 | 1660 | {
|
1601 |
| - "$schema": "https://json-schema.org/draft/2019-08/schema#", |
| 1661 | + "$schema": "https://json-schema.org/draft/2019-08/schema", |
1602 | 1662 | "$id": "https://example.com/original",
|
1603 | 1663 |
|
1604 | 1664 | "properties": {
|
|
1612 | 1672 | }
|
1613 | 1673 |
|
1614 | 1674 | {
|
1615 |
| - "$schema": "https://json-schema.org/draft/2019-08/schema#", |
| 1675 | + "$schema": "https://json-schema.org/draft/2019-08/schema", |
1616 | 1676 | "$id": "https://example.com/extension",
|
1617 | 1677 |
|
1618 | 1678 | "$ref": "original",
|
|
1711 | 1771 | <artwork>
|
1712 | 1772 | <![CDATA[
|
1713 | 1773 | {
|
1714 |
| - "$schema": "https://json-schema.org/draft/2019-08/schema#", |
| 1774 | + "$schema": "https://json-schema.org/draft/2019-08/schema", |
1715 | 1775 | "$id": "https://example.com/original",
|
1716 | 1776 | "$recursiveAnchor": true,
|
1717 | 1777 |
|
|
1726 | 1786 | }
|
1727 | 1787 |
|
1728 | 1788 | {
|
1729 |
| - "$schema": "https://json-schema.org/draft/2019-08/schema#", |
| 1789 | + "$schema": "https://json-schema.org/draft/2019-08/schema", |
1730 | 1790 | "$id": "https://example.com/extension",
|
1731 | 1791 | "$recursiveAnchor": true,
|
1732 | 1792 |
|
|
0 commit comments