Skip to content

Commit 5f305b8

Browse files
handrewshandrews
authored
Merge pull request #488 from handrews/define-vocab
Define "vocabularies" and other related terms.
2 parents 5b86e14 + c523b66 commit 5f305b8

File tree

1 file changed

+96
-34
lines changed

1 file changed

+96
-34
lines changed

‎jsonschema-core.xml

Lines changed: 96 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -190,7 +190,8 @@
190190
<t>
191191
Whitespace and formatting concerns, including different lexical
192192
representations of numbers that are equal within the data model, are thus
193-
outside the scope of JSON Schema. JSON Schema vocabularies that wish
193+
outside the scope of JSON Schema. JSON Schema
194+
<xref target="vocabulary">vocabularies</xref> that wish
194195
to work with such differences in lexical representations SHOULD define
195196
keywords to precisely interpret formatted strings within the data model
196197
rather than relying on having the original JSON representation Unicode
@@ -201,6 +202,13 @@
201202
JSON document that tries to define two properties (the "member" production) with
202203
the same key (the "string" production) in a single object is undefined.
203204
</t>
205+
<t>
206+
Note that JSON Schema vocabularies are free to define their own extended
207+
type system. This should not be confused with the core data model types
208+
defined here. As an example, "integer" is a reasonable type for a
209+
vocabulary to define as a value for a keyword, but the data model
210+
makes no distinction between integers and other numbers.
211+
</t>
204212
</section>
205213

206214
<section title="Instance media types">
@@ -261,41 +269,95 @@
261269
fragment identifier syntax and semantics provided by
262270
"application/schema-instance+json".
263271
</t>
264-
<t>
265-
A JSON Schema MUST be an object or a boolean.
266-
</t>
267-
<t>
268-
JSON Schema vocabularies can include assertions, which return a boolean result
269-
when applied to an instance. The boolean schema values "true" and "false"
270-
are trivial assertions that always return themselves regardless of the
271-
instance value. As an example, in terms of the validation vocabulary,
272-
boolean schemas are equivalent to the following behaviors:
273-
<list style="hanging">
274-
<t hangText="true">Always passes validation, as if the empty schema {}</t>
275-
<t hangText="false">Always fails validation, as if the schema { "not":{} }</t>
276-
</list>
277-
</t>
278-
<t>
279-
Properties that are used to describe the instance are called keywords, or schema
280-
keywords.
281-
The meaning of properties is specified by the vocabulary that the schema is using.
282-
</t>
283-
<t>
284-
A JSON Schema MAY contain properties which are not schema keywords.
285-
Unknown keywords SHOULD be ignored.
286-
</t>
287-
<t>
288-
A schema that itself describes a schema is called a meta-schema.
289-
Meta-schemas are used to validate JSON Schemas and specify which vocabulary it
290-
is using.
291-
</t>
292-
<t>
293-
An empty schema is a JSON Schema with no properties, or only unknown properties.
294-
</t>
295-
272+
<section title="JSON Schema values and keywords">
273+
<t>
274+
A JSON Schema MUST be an object or a boolean.
275+
</t>
276+
<t>
277+
Object properties that are applied to the instance are called keywords,
278+
or schema keywords. Broadly speaking, keywords fall into one or both
279+
of two categories:
280+
<list style="hanging">
281+
<t hangText="assertions">
282+
produce a boolean result when applied to an instance
283+
</t>
284+
<t hangText="annotations">
285+
attach information to an instance for application use
286+
</t>
287+
</list>
288+
</t>
289+
<t>
290+
Keywords may fall into either or both categories. Extension keywords,
291+
meaning those defined outside of this document and its companions,
292+
are free to define other behaviors as well.
293+
</t>
294+
<t>
295+
The boolean schema values "true" and "false" are trivial assertions that
296+
always return themselves regardless of the instance value. As an example,
297+
in terms of the validation vocabulary, boolean schemas are equivalent to
298+
the following behaviors:
299+
<list style="hanging">
300+
<t hangText="true">
301+
Always passes validation, as if the empty schema {}
302+
</t>
303+
<t hangText="false">
304+
Always fails validation, as if the schema { "not":{} }
305+
</t>
306+
</list>
307+
</t>
308+
<t>
309+
A JSON Schema MAY contain properties which are not schema keywords.
310+
Unknown keywords SHOULD be ignored.
311+
</t>
312+
<t>
313+
An empty schema is a JSON Schema with no properties, or only unknown
314+
properties.
315+
</t>
316+
</section>
317+
<section title="JSON Schema vocabularies" anchor="vocabulary">
318+
<t>
319+
A JSON Schema vocabulary is a set of keywords defined for a particular
320+
purpose. The vocabulary specifies the meaning of its keywords as
321+
assertions, annotations, and/or any vocabulary-defined keyword category.
322+
The two companion standards to this document each define a vocabulary:
323+
One for instance validation, and one for hypermedia annotations.
324+
Vocabularies are the primary mechanism for extensibility within
325+
the JSON Schema media type.
326+
</t>
327+
<t>
328+
Vocabularies may be defined by any entity. Vocabulary authors SHOULD
329+
take care to avoid keyword name collisions if the vocabulary is intended
330+
for broad use, and potentially combined with other vocabularies. JSON
331+
Schema does not provide any formal namespacing system, but also does
332+
not constrain keyword names, allowing for any number of namespacing
333+
approaches.
334+
</t>
335+
<t>
336+
Vocabularies may build on each other, such as by defining the behavior
337+
of their keywords with respect to the behavior of keywords from another
338+
vocabulary, or by using a keyword from another vocabulary with
339+
a restricted or expanded set of acceptable values. Not all such
340+
vocabulary re-use will result in a new vocabulary that is compatible
341+
with the vocabulary on which it is built. Vocabulary authors SHOULD
342+
clearly document what level of compatibility, if any, is expected.
343+
</t>
344+
<t>
345+
A schema that itself describes a schema is called a meta-schema.
346+
Meta-schemas are used to validate JSON Schemas and specify which vocabulary
347+
it is using.
348+
<cref>
349+
Currently, only a single meta-schema may be specified per schema,
350+
meaning that in order to use multiple vocabularies, a meta-schema
351+
must be written that encompasses all of them. The hyper-schema
352+
meta-schema is an example of this, as it encompasses the validation
353+
vocabulary as well as the hypermedia vocabulary.
354+
</cref>
355+
</t>
356+
</section>
296357
<section title="Root schema and subschemas">
297358
<t>
298-
The root schema is the schema that comprises the entire JSON document in question.
359+
The root schema is the schema that comprises the entire JSON document
360+
in question.
299361
</t>
300362
<t>
301363
Some keywords take schemas themselves, allowing JSON Schemas to be nested:

0 commit comments

Comments
 (0)