Skip to content

added some verbiage to the vocabularies example for clarity #756

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 8 commits into from
Closed

added some verbiage to the vocabularies example for clarity #756

Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
689947f
added some verbiage to the vocabularies example for clarity
gregsdennis Jun 30, 2019
bbb0c0a
moved 'preamble' for vocab example to just text to support list
gregsdennis Jun 30, 2019
0f4ad19
clarified the distinction between semantic and syntatic validation
gregsdennis Jun 30, 2019
351b5d1
use 'startDate' instead of 'pastDate'
gregsdennis Jun 30, 2019
e00832b
a bit more clarity
gregsdennis Jun 30, 2019
68e3140
lowercased a 'must' since it's informative
gregsdennis Jul 1, 2019
a5a0343
Make handling of unkown vocabs clearer
Relequestual Jul 3, 2019
bf1f8e6
Moved cref inside t tag
Relequestual Jul 9, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
87 changes: 71 additions & 16 deletions jsonschema-core.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -920,7 +920,7 @@
the relevant protocol's successful "no content" message, such as
an HTTP 204 status.
<cref>
Vocabulary documents may be added shortly, or in the next draft.
Vocabulary documents may be added in forthcoming drafts.
For now, identifying the keyword set is deemed sufficient as that,
along with meta-schema validation, is how the current "vocabularies"
work today.
Expand All @@ -931,13 +931,22 @@
If the value is true, then implementations that do not recognize
the vocabulary MUST refuse to process any schemas that declare
this meta-schema with "$schema". If the value is false, implementations
that do not recognize the vocabulary MAY choose to proceed with processing
that do not recognize the vocabulary SHOULD proceed with processing
such schemas.
</t>
<t>
When processing a schema that uses unrecognized vocabularies, keywords
declared by those vocabularies are treated like any other unrecognized
Processing a schema with an unrecognized vocabulary (where the value of
the associated vocabulary key is "false") SHOULD result in keywords
declared by that vocabulary (if known) being treated like any other unrecognized
keyword, and ignored.
<cref>
Opted for SHOULD here, because it's not possible to know what keywords
WERE included in the unkown vocabulary. If another known
vocabulary uses one of the same keywords as the unkown vocabulary, this
shouldn't result in THAT keyword being ignored. (And it's unlikely that it
is possble to tell this anyway. Unless it's a known but unsupported vocabulary,
however I think here the phrase "known" is equivilent to "supported.)
</cref>
</t>
<t>
The "$vocabulary" keyword SHOULD be used in the root schema of any schema
Expand Down Expand Up @@ -1074,17 +1083,32 @@
</section>
<section title="Example Meta-Schema With Vocabulary Declarations"
anchor="example-meta-schema">
<t>
This meta-schema explicitly declares both the Core and Applicator
vocabularies with its own vocabulary and combines the
Core and Applicator meta-schemas with an "allOf". It does not
need to include itself in the "allOf" since it is its own
meta-schema. It additionally applies three modifications to the
combination of these vocabularies:
<list>
<t>
It restricts the usage of the Applicator vocabulary
by forbidding the keywords prefixed with "unevaluated".
</t>
<t>
It describes a keyword, "startDate", that is defined by
its own vocabulary.
</t>
<t>
It describes a keyword, "localKeyword", that is not
part of any vocabulary.
</t>
</list>
Note that it is its own meta-schema, as it relies on both the Core
vocabulary (as all schemas do) and the Applicator vocabulary (for
"allOf", "properties", and "patternProperties").
</t>
<figure>
<preamble>
This meta-schema explicitly declares both the Core and Applicator
vocabularies, and combines their meta-schemas with an "allOf".
It additionally restricts the usage of the Applicator vocabulary
by forbidding the keyword prefixed with "unevaluated". It also
describes a keyword, "localKeyword", that is not part of either
vocabulary. Note that it is its own meta-schema,
as it relies on both the Core vocabulary (as all schemas do)
and the Applicator vocabulary (for "allOf").
</preamble>
<artwork>
<![CDATA[
{
Expand All @@ -1093,7 +1117,8 @@
"$recursiveAnchor": true,
"$vocabulary": {
"https://json-schema.org/draft/2019-04/vocab/core": true,
"https://json-schema.org/draft/2019-04/vocab/applicator": true
"https://json-schema.org/draft/2019-04/vocab/applicator": true,
"https://json-schema.org/draft/2019-04/vocab/core-app-example": true
},
"allOf": [
{"$ref": "https://json-schema.org/draft/2019-04/meta/core"},
Expand All @@ -1103,8 +1128,13 @@
"^unevaluated.*$": false
},
"properties": {
"$comment": "Not in vocabulary, but validated if used",
"startDate": {
"$comment": "Defined by vocabulary"
"type": "string",
"format": "date"
},
"localKeyword": {
"$comment": "Not in vocabulary, but validated if used",
"type": "string"
}
}
Expand All @@ -1121,6 +1151,31 @@
validation of core keywords.
</postamble>
</figure>
<t>
"localKeyword" and "startDate" are now valid for any schema that
declares this meta-schema for their "$schema". Note that defining
it in this way does not imply the new keywords are valid within an
instance to be validated by such a schema.
</t>
<t>
Although the meta-schema can validate the syntax of "startDate"
within a schema, it is the vocabulary that defines the logic behind
the semantic meaning of "startDate". Without an understanding of
the semantics (that the instance value should represent a date after that
given in the schema), an implementation can only validate the syntactic
usage of "startDate" (that it is a date-formatted string). This is why
a schema must refuse to validate a schema which uses a meta-schema
that declares a required unknown vocabulary.
</t>
<t>
In order for an implementation to understand the keywords defined by
vocabulary, it may be necessary for the user to augment the
implementation by writing a plug-in or other extension that the
implementation can use to execute the new validation logic. The
mechanisms by which an implementation supports this are not covered
by this specification, however it is RECOMMENDED that implementations
provide such support.
</t>
<t>
The standard meta-schemas that combine all vocabularies defined by
the Core and Validation specification, and that combine all vocabularies
Expand Down