Skip to content

Define "vocabularies" and other related terms. #488

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

Merged
merged 4 commits into from
Nov 16, 2017
Merged

Define "vocabularies" and other related terms. #488

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
2c975f6
Add a note about type in data model vs vocabs
handrews Nov 14, 2017
9829102
Indent and rewrap in prep for new sections.
handrews Nov 14, 2017
9ab1fdb
Keyword and vocabulary sections in core
handrews Nov 14, 2017
c523b66
Add data model reference to vocabularies
handrews Nov 14, 2017
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
130 changes: 96 additions & 34 deletions jsonschema-core.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -190,7 +190,8 @@
<t>
Whitespace and formatting concerns, including different lexical
representations of numbers that are equal within the data model, are thus
outside the scope of JSON Schema. JSON Schema vocabularies that wish
outside the scope of JSON Schema. JSON Schema
<xref target="vocabulary">vocabularies</xref> that wish
to work with such differences in lexical representations SHOULD define
keywords to precisely interpret formatted strings within the data model
rather than relying on having the original JSON representation Unicode
Expand All @@ -201,6 +202,13 @@
JSON document that tries to define two properties (the "member" production) with
the same key (the "string" production) in a single object is undefined.
</t>
<t>
Note that JSON Schema vocabularies are free to define their own extended
type system. This should not be confused with the core data model types
defined here. As an example, "integer" is a reasonable type for a
vocabulary to define as a value for a keyword, but the data model
makes no distinction between integers and other numbers.
</t>
</section>

<section title="Instance media types">
Expand Down Expand Up @@ -261,41 +269,95 @@
fragment identifier syntax and semantics provided by
"application/schema-instance+json".
</t>
<t>
A JSON Schema MUST be an object or a boolean.
</t>
<t>
JSON Schema vocabularies can include assertions, which return a boolean result
when applied to an instance. The boolean schema values "true" and "false"
are trivial assertions that always return themselves regardless of the
instance value. As an example, in terms of the validation vocabulary,
boolean schemas are equivalent to the following behaviors:
<list style="hanging">
<t hangText="true">Always passes validation, as if the empty schema {}</t>
<t hangText="false">Always fails validation, as if the schema { "not":{} }</t>
</list>
</t>
<t>
Properties that are used to describe the instance are called keywords, or schema
keywords.
The meaning of properties is specified by the vocabulary that the schema is using.
</t>
<t>
A JSON Schema MAY contain properties which are not schema keywords.
Unknown keywords SHOULD be ignored.
</t>
<t>
A schema that itself describes a schema is called a meta-schema.
Meta-schemas are used to validate JSON Schemas and specify which vocabulary it
is using.
</t>
<t>
An empty schema is a JSON Schema with no properties, or only unknown properties.
</t>

<section title="JSON Schema values and keywords">
<t>
A JSON Schema MUST be an object or a boolean.
</t>
<t>
Object properties that are applied to the instance are called keywords,
or schema keywords. Broadly speaking, keywords fall into one or both
of two categories:
<list style="hanging">
<t hangText="assertions">
produce a boolean result when applied to an instance
</t>
<t hangText="annotations">
attach information to an instance for application use
</t>
</list>
</t>
<t>
Keywords may fall into either or both categories. Extension keywords,
meaning those defined outside of this document and its companions,
are free to define other behaviors as well.
</t>
<t>
The boolean schema values "true" and "false" are trivial assertions that
always return themselves regardless of the instance value. As an example,
in terms of the validation vocabulary, boolean schemas are equivalent to
the following behaviors:
<list style="hanging">
<t hangText="true">
Always passes validation, as if the empty schema {}
</t>
<t hangText="false">
Always fails validation, as if the schema { "not":{} }
</t>
</list>
</t>
<t>
A JSON Schema MAY contain properties which are not schema keywords.
Unknown keywords SHOULD be ignored.
</t>
<t>
An empty schema is a JSON Schema with no properties, or only unknown
properties.
</t>
</section>
<section title="JSON Schema vocabularies" anchor="vocabulary">
<t>
A JSON Schema vocabulary is a set of keywords defined for a particular
purpose. The vocabulary specifies the meaning of its keywords as
assertions, annotations, and/or any vocabulary-defined keyword category.
The two companion standards to this document each define a vocabulary:
One for instance validation, and one for hypermedia annotations.
Vocabularies are the primary mechanism for extensibility within
the JSON Schema media type.
</t>
<t>
Vocabularies may be defined by any entity. Vocabulary authors SHOULD
take care to avoid keyword name collisions if the vocabulary is intended
for broad use, and potentially combined with other vocabularies. JSON
Schema does not provide any formal namespacing system, but also does
not constrain keyword names, allowing for any number of namespacing
approaches.
</t>
<t>
Vocabularies may build on each other, such as by defining the behavior
of their keywords with respect to the behavior of keywords from another
vocabulary, or by using a keyword from another vocabulary with
a restricted or expanded set of acceptable values. Not all such
vocabulary re-use will result in a new vocabulary that is compatible
with the vocabulary on which it is built. Vocabulary authors SHOULD
clearly document what level of compatibility, if any, is expected.
</t>
<t>
A schema that itself describes a schema is called a meta-schema.
Meta-schemas are used to validate JSON Schemas and specify which vocabulary
it is using.
<cref>
Currently, only a single meta-schema may be specified per schema,
meaning that in order to use multiple vocabularies, a meta-schema
must be written that encompasses all of them. The hyper-schema
meta-schema is an example of this, as it encompasses the validation
vocabulary as well as the hypermedia vocabulary.
</cref>
</t>
</section>
<section title="Root schema and subschemas">
<t>
The root schema is the schema that comprises the entire JSON document in question.
The root schema is the schema that comprises the entire JSON document
in question.
</t>
<t>
Some keywords take schemas themselves, allowing JSON Schemas to be nested:
Expand Down