From 2c975f6edd8bb541eecb12dc65005f367fcf8510 Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Tue, 14 Nov 2017 13:12:33 -0800 Subject: [PATCH 1/4] Add a note about type in data model vs vocabs People routinely file a "bug" that the validation type "integer" is not listed in the core spec. Explain why that is on purpose. --- jsonschema-core.xml | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/jsonschema-core.xml b/jsonschema-core.xml index f75b45c8..2d8cb9ad 100644 --- a/jsonschema-core.xml +++ b/jsonschema-core.xml @@ -201,6 +201,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. + + 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. +
From 982910270d1fdedbdf4a41a26997acfcdc473ac8 Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Tue, 14 Nov 2017 13:16:32 -0800 Subject: [PATCH 2/4] Indent and rewrap in prep for new sections. These will go into subscections, so they need to be indented further and in some cases re-wrapped. There are no content changes in this commit, only formatting. --- jsonschema-core.xml | 71 +++++++++++++++++++++++++-------------------- 1 file changed, 39 insertions(+), 32 deletions(-) diff --git a/jsonschema-core.xml b/jsonschema-core.xml index 2d8cb9ad..21a514b2 100644 --- a/jsonschema-core.xml +++ b/jsonschema-core.xml @@ -268,41 +268,48 @@ fragment identifier syntax and semantics provided by "application/schema-instance+json". - - A JSON Schema MUST be an object or a boolean. - - - 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: - - Always passes validation, as if the empty schema {} - Always fails validation, as if the schema { "not":{} } - - - - 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. - - - A JSON Schema MAY contain properties which are not schema keywords. - Unknown keywords SHOULD be ignored. - - - 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. - - - An empty schema is a JSON Schema with no properties, or only unknown properties. - + + A JSON Schema MUST be an object or a boolean. + + + 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: + + + Always passes validation, as if the empty schema {} + + + Always fails validation, as if the schema { "not":{} } + + + + + 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. + + + A JSON Schema MAY contain properties which are not schema keywords. + Unknown keywords SHOULD be ignored. + + + 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. + + + An empty schema is a JSON Schema with no properties, or only unknown + properties. +
- 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. Some keywords take schemas themselves, allowing JSON Schemas to be nested: From 9ab1fdbc5dc1082a749cefe79496b5278bb8913f Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Tue, 14 Nov 2017 13:38:02 -0800 Subject: [PATCH 3/4] Keyword and vocabulary sections in core Actually add the sections and rework the contents to make sense in this order. Define more terms that were being used without clear definition before. --- jsonschema-core.xml | 79 ++++++++++++++++++++++++++++++++++++--------- 1 file changed, 63 insertions(+), 16 deletions(-) diff --git a/jsonschema-core.xml b/jsonschema-core.xml index 21a514b2..42c6cbff 100644 --- a/jsonschema-core.xml +++ b/jsonschema-core.xml @@ -268,15 +268,33 @@ fragment identifier syntax and semantics provided by "application/schema-instance+json". +
A JSON Schema MUST be an object or a boolean. - 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: + 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: + + + produce a boolean result when applied to an instance + + + attach information to an instance for application use + + + + + 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. + + + 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: Always passes validation, as if the empty schema {} @@ -286,26 +304,55 @@ - - 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. - A JSON Schema MAY contain properties which are not schema keywords. Unknown keywords SHOULD be ignored. + + An empty schema is a JSON Schema with no properties, or only unknown + properties. + +
+
+ + 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. + + + 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. + + + 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. + 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. + + 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. + - - An empty schema is a JSON Schema with no properties, or only unknown - properties. - - +
The root schema is the schema that comprises the entire JSON document From c523b660a672840968150af8a1fc251204be5e52 Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Tue, 14 Nov 2017 13:38:56 -0800 Subject: [PATCH 4/4] Add data model reference to vocabularies --- jsonschema-core.xml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/jsonschema-core.xml b/jsonschema-core.xml index 42c6cbff..c872f8fd 100644 --- a/jsonschema-core.xml +++ b/jsonschema-core.xml @@ -190,7 +190,8 @@ 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 + vocabularies 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