Skip to content

Commit 0359124

Browse files
handrewshandrews
committed
Add "$vocabulary" and the vocabularies concept
This defines the $vocabulary keyword and explains how it fits into schema and meta-schema processing. Vocabulary-specific meta-schemas to be added in a subsequent commit.
1 parent e84494c commit 0359124

File tree

1 file changed

+217
-2
lines changed

1 file changed

+217
-2
lines changed

‎jsonschema-core.xml

+217-2
Original file line numberDiff line numberDiff line change
@@ -801,6 +801,44 @@
801801
</section>
802802

803803
<section title="Meta-Schemas and Vocabularies">
804+
<t>
805+
Two concepts, meta-schemas and vocabularies, are used to inform an implementation
806+
how to interpret a schema. A schema S declares its meta-schema M with the "$schema"
807+
keyword, and meta-schemas declare vocabularies with the "$vocabulary" keyword.
808+
The vocabularies declared in M are those that are expected to be used in S.
809+
The meta-schema M may itself use a different set of vocabularies, which are
810+
declared in its own meta-schema, M'.
811+
</t>
812+
<t>
813+
The role of the meta-schema is to constrain the structure of conforming schemas,
814+
as well as simplify the process of composing multiple vocabularies into a usable
815+
feature set. Schema authoring is obviously expected to be a common activity, so
816+
schema authors need only understand how to reference a single meta-schema.
817+
</t>
818+
<t>
819+
Meta-schema authoring is an advanced usage of JSON Schema, so the design of
820+
meta-schema features emphasizes flexibility over simplicity.
821+
</t>
822+
<t>
823+
The role of a vocabulary is to declare which keywords (including sub-keywords
824+
such as those in JSON Hyper-Schema's Link Description Object) are in use,
825+
and with which semantics. The semantics are indicated by the document
826+
that publicizes the vocabulary URI. At this time, there is no machine-readable
827+
description of keywords other than validation rules, which appear in the
828+
meta-schema.
829+
</t>
830+
<t>
831+
Meta-schemas are separate from vocabularies to allow for the same sets of
832+
vocabularies to be combined in different ways, and for meta-schema authors
833+
to impose additional constraints such as forbidding certain keywords, or
834+
performing unusually strict syntactical validation, as might be done
835+
during a development and testing cycle.
836+
</t>
837+
<t>
838+
A schema is considered to be processed as meta-schema if it was
839+
identified as such in a schema's "$schema". Implementations MAY
840+
also offer alternate ways to process schemas using meta-schema rules.
841+
</t>
804842
<section title='The "$schema" Keyword'>
805843
<t>
806844
The "$schema" keyword is both used as a JSON Schema feature set identifier and
@@ -823,7 +861,7 @@
823861
<t>
824862
<cref>
825863
Using multiple "$schema" keywords in the same document would imply that the
826-
vocabulary and therefore behavior can change within a document. This would
864+
feature set and therefore behavior can change within a document. This would
827865
necessitate resolving a number of implementation concerns that have not yet
828866
been clearly defined. So, while the pattern of using "$schema" only in root
829867
schemas is likely to remain the best practice for schema authoring,
@@ -844,6 +882,175 @@
844882
published drafts of JSON Schema vocabularies as deemed reasonable.
845883
</t>
846884
</section>
885+
<section title='The "$vocabulary" Keyword'>
886+
<t>
887+
The "$vocabulary" keyword is used within meta-schemas to declare
888+
the sets of keywords that schemas described by the meta-schema are
889+
expected to use.
890+
</t>
891+
<t>
892+
The value of this keyword MUST be an object. The property names in the
893+
object MUST be URIs, (containing a scheme) and this URI MUST be normalized.
894+
The URI MAY be a URL, but the nature of the retrievable resources is
895+
currently undefined, and reserved for future use. Vocabulary authors
896+
SHOULD NOT serve a document at that URL. A server MAY respond with
897+
the relevant protocol's successful "no content" message, such as
898+
an HTTP 204 status.
899+
<cref>
900+
Vocabulary documents may be added shortly, or in the next draft.
901+
For now, identifying the keyword set is deemed sufficient as that,
902+
along with meta-schema validation, is how the current "vocabularies"
903+
work today.
904+
</cref>
905+
</t>
906+
<t>
907+
The values of the object properties MUST be booleans.
908+
If the value is true, then implementations that do not recognize
909+
the vocabulary MUST refuse to process any schemas that declare
910+
this meta-schema with "$schema". If the value is false, implementations
911+
that do not recognize the vocabulary MAY choose to proceed with processing
912+
such schemas.
913+
</t>
914+
<t>
915+
When processing a schema that uses unrecognized vocabularies, keywords
916+
declared by those vocabularies are treated like any other unrecognized
917+
keyword, and ignored.
918+
</t>
919+
<t>
920+
The "$vocabulary" keyword SHOULD be used in the root schema of any schema
921+
document intended for use as a meta-schema. It MUST NOT appear in subschemas.
922+
</t>
923+
<t>
924+
The "$vocabulary" keyword MUST be ignored in a schema documents that
925+
is not being processed as a meta-schema. This allows validating
926+
a meta-schema M against its own meta-schema M' without requiring
927+
the validator to understand the vocabularies declared by M.
928+
</t>
929+
<t>
930+
Note that the processing restrictions on "$vocabulary" mean that
931+
meta-schemas that reference other meta-schemas, for example to
932+
provide a meta-schema that extends or composes other meta-schemas,
933+
do not automatically declare the vocabularies of those other
934+
meta-schemas. All such declarations must be repeated in the root
935+
of each schema document intended for use as a meta-schema.
936+
</t>
937+
<section title="Best Practices for Vocabulary and Meta-Schema Authors">
938+
<t>
939+
Meta-schema authors SHOULD NOT use "$vocabulary" to combine multiple
940+
vocabularies that define conflicting syntax or semantics for the same
941+
keyword. As semantic conflicts are not generally detectable through
942+
schema validation, implementations are not expected to detect such
943+
conflicts. If conflicting vocabularies are declared, the resulting
944+
behavior is undefined.
945+
</t>
946+
<t>
947+
Vocabulary authors SHOULD provide a meta-schema that validates the
948+
expected usage of the vocabulary's keywords. Such meta-schemas
949+
SHOULD NOT forbid additional keywords, and MUST NOT forbid
950+
the "$id", "$schema", or "$vocabulary" keywords in the root schema.
951+
</t>
952+
<t>
953+
It is RECOMMENDED that meta-schema authors reference each vocabulary's
954+
meta-schema using the <xref target="allOf">"allOf"</xref> keyword,
955+
although other mechanisms for constructing the meta-schema may be
956+
appropriate for certain use cases.
957+
</t>
958+
<t>
959+
Meta-schemas MAY impose additional constraints, including describing
960+
keywords not present in any vocabulary, beyond what the meta-schemas
961+
associated with the declared vocabularies describe. This allows for
962+
restricting usage to a subset of a vocabulary, and for validating
963+
locally defined keywords not intended for re-use.
964+
</t>
965+
<t>
966+
Meta-schemas intended for local use, with no need to test for
967+
vocabulary support in arbitrary implementations, can safely omit
968+
"$vocabulary" entirely.
969+
</t>
970+
</section>
971+
<section title="The JSON Schema Core Vocabulary">
972+
<t>
973+
Keywords declared in in this specification that begin with "$" make up
974+
the JSON Schema Core vocabulary. These keywords are either required in
975+
order process any schema or meta-schema, including those split across
976+
multiple documents, or exist to reserve keywords for purposes that
977+
require guaranteed interoperability.
978+
</t>
979+
<t>
980+
The Core vocabulary MUST be considered mandatory at all times, in order
981+
to bootstrap the processing of further vocabularies. Meta-schema
982+
authors MAY explicitly list the Core vocabulary, but do not need
983+
to do so. If present, the Core vocabulary entry MUST have a value
984+
of true indicating that it is required. The behavior of a value
985+
of false is undefined.
986+
</t>
987+
<t>
988+
The current URI for the Core vocabulary is:
989+
<eref target="https://json-schema.org/draft-08/vocabularies/core"/>.
990+
</t>
991+
<t>
992+
The current URI for the corresponding meta-schema is:
993+
<eref target="https://json-schema.org/draft-08/core">.
994+
</t>
995+
</section>
996+
<section title="Example Meta-Schema With Vocabulary Declarations">
997+
<figure>
998+
<preamble>
999+
This meta-schema explicitly declares both the Core and Applicator
1000+
vocabularies, and combines their meta-schemas with an "allOf".
1001+
It additional restricts the usage of the Applicator vocabulary
1002+
by forbidding the keyword prefixed with "unevaluated". It also
1003+
describes a keyword, "localKeyord", that is not part of either
1004+
vocabulary. Note that it is its own meta-schema,
1005+
as it relies on both the Core vocabulary (as all schemas do)
1006+
and the Applicator vocabulary (for "allOf"0.
1007+
</preamble>
1008+
<artwork>
1009+
<![CDATA[
1010+
{
1011+
"$schema": "https://json-schema.org/draft-08/core-app-example#",
1012+
"$id": "https://json-schema.org/draft-08/core-app-example",
1013+
"$recursiveAnchor": true,
1014+
"$vocabulary": {
1015+
"https://json-schema.org/draft-08/vocabularies/core": true,
1016+
"https://json-schema.org/draft-08/vocabularies/applicator": true
1017+
}.
1018+
"allOf": [
1019+
{"$ref": "https://json-schema.org/draft-08/core"},
1020+
{"$ref": "https://json-schema.org/draft-08/applicator"}
1021+
],
1022+
"patternProperties": {
1023+
"^unevaluated.*$": false
1024+
},
1025+
"properties": {
1026+
"$comment": "Not in vocabulary, but validated if used",
1027+
"localKeyword": {
1028+
"type": "string"
1029+
}
1030+
}
1031+
}
1032+
]]>
1033+
</artwork>
1034+
<postamble>
1035+
As shown above, even though each of the referenced standard
1036+
meta-schemas declares its corresponding vocabulary, this new
1037+
meta-schema must re-declare them for itself. It would be
1038+
valid to leave the core vocabulary out of the "$vocabulary" keyword,
1039+
but it MUST be referenced through the "allOf" keyword in order
1040+
for its terms to be validated. There is no special case for
1041+
validation of core keywords.
1042+
</postamble>
1043+
</figure>
1044+
<t>
1045+
The standard meta-schemas that combine all vocabularies defined by
1046+
the Core and Validation specification, and that combine all vocabularies
1047+
defined by those specifications as well as the Hyper-Schema specification,
1048+
demonstrate additional complex combinations. These URIs for these
1049+
meta-schemas may be found in the Validation and Hyper-Schema specifications,
1050+
respectively.
1051+
</t>
1052+
</section>
1053+
</section>
8471054
</section>
8481055

8491056
<section title="Base URI and Dereferencing">
@@ -1601,6 +1808,14 @@
16011808
This section defines a vocabulary of applicator keywords that
16021809
are RECOMMENDED for use as the basis of other vocabularies.
16031810
</t>
1811+
<t>
1812+
The current URI for this vocabulary, known as the Applicator vocabulary, is:
1813+
<eref target="https://json-schema.org/draft-08/vocabularies/applicator"/>.
1814+
</t>
1815+
<t>
1816+
The current URI for the corresponding meta-schema is:
1817+
<eref target="https://json-schema.org/draft-08/applicator">.
1818+
</t>
16041819
<section title="Keyword Independence">
16051820
<t>
16061821
Schema keywords typically operate independently, without
@@ -1636,7 +1851,7 @@
16361851
keyword to be applied to an instance location with different values.
16371852
Annotation keywords define their own rules for combining such values.
16381853
</t>
1639-
<section title="allOf">
1854+
<section title="allOf" anchor="allOf">
16401855
<t>
16411856
This keyword's value MUST be a non-empty array.
16421857
Each item of the array MUST be a valid JSON Schema.

0 commit comments

Comments
 (0)