From f782ee4f2858de97205d8f132de5d146a079b440 Mon Sep 17 00:00:00 2001 From: Austin Wright Date: Wed, 14 Sep 2016 02:49:07 -0700 Subject: [PATCH 01/22] Rename jsonschema-schema jsonschema-validation --- Makefile | 2 +- jsonschema-schema.xml => jsonschema-validation.xml | 0 2 files changed, 1 insertion(+), 1 deletion(-) rename jsonschema-schema.xml => jsonschema-validation.xml (100%) diff --git a/Makefile b/Makefile index 0895a74d..7fb894d7 100644 --- a/Makefile +++ b/Makefile @@ -2,7 +2,7 @@ XML2RFC=xml2rfc OUT = \ jsonschema-core.html jsonschema-core.txt \ - jsonschema-schema.html jsonschema-schema.txt \ + jsonschema-validation.html jsonschema-validation.txt \ jsonschema-hyperschema.html jsonschema-hyperschema.txt diff --git a/jsonschema-schema.xml b/jsonschema-validation.xml similarity index 100% rename from jsonschema-schema.xml rename to jsonschema-validation.xml From 90f4aab45cc2771ecf8bd3c19cbf21cbd90dd4d6 Mon Sep 17 00:00:00 2001 From: Austin Wright Date: Thu, 15 Sep 2016 01:24:26 -0700 Subject: [PATCH 02/22] Spelling fixes --- jsonschema-validation.xml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/jsonschema-validation.xml b/jsonschema-validation.xml index 28a46f4d..605a8885 100644 --- a/jsonschema-validation.xml +++ b/jsonschema-validation.xml @@ -64,7 +64,7 @@ JSON Schema (application/schema+json) has several purposes, one of which is JSON instance - validation. This document specifies a vocabulary for JSON Schema to makes assertions about + validation. This document specifies a vocabulary for JSON Schema to make assertions about valid instances. @@ -121,7 +121,7 @@
- The JSON specification allows numbers with arbritrary prevision, and JSON Schema does not add any such bounds. + The JSON specification allows numbers with arbitrary precision, and JSON Schema does not add any such bounds. This means that numeric instances processed by JSON Schema can be arbitrarily large and/or have an arbitrarily large decimal part, regardless of the ability of the underlying programming language to deal with such data. From 32523fb6c378eb87744eb0629a83876f5018a541 Mon Sep 17 00:00:00 2001 From: Austin Wright Date: Thu, 15 Sep 2016 04:17:13 -0700 Subject: [PATCH 03/22] Hyper-schema: Strengthened readings of "href" Other readings are incompatible with RFC3986 --- jsonschema-hyperschema.xml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/jsonschema-hyperschema.xml b/jsonschema-hyperschema.xml index 70b12b99..7e6fa660 100644 --- a/jsonschema-hyperschema.xml +++ b/jsonschema-hyperschema.xml @@ -416,8 +416,8 @@
The value of the "href" link description property is a template used to determine the target URI of the related resource. - The value of the instance property SHOULD be resolved as a URI-Reference per RFC 3986 and MAY be a URI reference. - The base URI to be used for relative URI resolution SHOULD be the URI used to retrieve the instance object (not the schema). + The value of the instance property MUST be resolved as a URI-reference. + The base URI to be used for relative URI resolution MUST be the URI of instance (not the schema). From a94cfeb74d716026386b089623dda52758df8483 Mon Sep 17 00:00:00 2001 From: Austin Wright Date: Thu, 15 Sep 2016 04:18:35 -0700 Subject: [PATCH 04/22] Validation: rewrote sections to avoid saying "default" --- jsonschema-validation.xml | 24 ++++++++++++++---------- 1 file changed, 14 insertions(+), 10 deletions(-) diff --git a/jsonschema-validation.xml b/jsonschema-validation.xml index 605a8885..c8bbcd7e 100644 --- a/jsonschema-validation.xml +++ b/jsonschema-validation.xml @@ -100,12 +100,12 @@ This specification uses the term "property set" to refer to the set of an object's - member names; for instance, the property set of JSON Object { "a": 1, "b": 2 } is [ - "a", "b" ]. + member names; for instance, the property set of JSON Object { "a": 1, "b": 2 } is + [ "a", "b" ]. Elements in an array value are said to be unique if no two elements of this array - are equal, as defined by the core specification. + are equal.
@@ -177,11 +177,11 @@
-
+
Validation keywords that are missing never restrict validation. - In some cases, this behavior is identical to certain values that also are no-op. - Since these values can be safely ignored or removed, they are noted where known. + In some cases, this no-op behavior is identical to a keyword that exists with certain values, + and these values are noted where known.
@@ -206,13 +206,15 @@ The value of "maximum" MUST be a number, representing an upper limit for a numeric instance. - A numeric instance described by this keyword MUST either be less than this value or possibly equal to it (see "exclusiveMaximum"). + If the instance is a number, then this keyword validates if "exclusiveMaximum" is true and instance is less than the provided value, + or else if the instance is less than or exactly equal to the provided value.
- The value of "exclusiveMaximum" MUST be a boolean, representing whether the limit in "maximum" is exclusive or not. It defaults to false. + The value of "exclusiveMaximum" MUST be a boolean, representing whether the limit in "maximum" is exclusive or not. + An undefined value is the same as false. If "exclusiveMaximum" is true, then a numeric instance MUST NOT be equal to the value specified in "maximum". @@ -225,13 +227,15 @@ The value of "minimum" MUST be a number, representing a lower limit for a numeric instance. - A numeric instance described by this keyword MUST either be more than this value or possibly equal to it (see "exclusiveMinimum"). + If the instance is a number, then this keyword validates if "exclusiveMinimum" is true and instance is greater than the provided value, + or else if the instance is greater than or exactly equal to the provided value.
- The value of "exclusiveMinimum" MUST be a boolean, representing whether the limit in "minimum" is exclusive or not. It defaults to false. + The value of "exclusiveMinimum" MUST be a boolean, representing whether the limit in "minimum" is exclusive or not. + An undefined value is the same as false. If "exclusiveMinimum" is true, then a numeric instance MUST NOT be equal to the value specified in "minimum". From b98b558a5b3dfa23d7011cb0abb03ffcc9a7643d Mon Sep 17 00:00:00 2001 From: Austin Wright Date: Thu, 15 Sep 2016 04:27:41 -0700 Subject: [PATCH 05/22] Hyper-schema: Fix outdenting problems --- jsonschema-hyperschema.xml | 30 +++++++++++++++--------------- 1 file changed, 15 insertions(+), 15 deletions(-) diff --git a/jsonschema-hyperschema.xml b/jsonschema-hyperschema.xml index 7e6fa660..975bea4e 100644 --- a/jsonschema-hyperschema.xml +++ b/jsonschema-hyperschema.xml @@ -706,10 +706,10 @@ Input Output
@@ -742,25 +742,25 @@ GET /foo/
- With a response of: + With a response of (with newlines and whitespace added):
@@ -807,8 +807,8 @@ GET /foo/ "name": "Jason", "id": 8 }, - "message": "It's easy, you just add some HTML like - this: " + "message": "It's easy, just add some HTML like + this: " }]]> From d561cce14390beb2678a33c8c52492769c26e6c9 Mon Sep 17 00:00:00 2001 From: Austin Wright Date: Thu, 15 Sep 2016 04:49:23 -0700 Subject: [PATCH 06/22] Hyper-schema: Use and other fixes to avoid overruns --- jsonschema-hyperschema.xml | 66 ++++++++++++++++---------------------- 1 file changed, 28 insertions(+), 38 deletions(-) diff --git a/jsonschema-hyperschema.xml b/jsonschema-hyperschema.xml index 975bea4e..7c1f0f2d 100644 --- a/jsonschema-hyperschema.xml +++ b/jsonschema-hyperschema.xml @@ -495,32 +495,26 @@
- -
- For example, here are some possible values for "href", followed by the results after pre-processing: - - - - - Note that in the final example, because the "+" was outside the brackets, it remained unescaped, whereas in the fourth example the "+" was escaped. - -
- + + For example, here are some possible values for "href", followed by the results after pre-processing: + Input + Output + "no change" "no change" + "(no change)" "(no change)" + "{(escape space)}" "{escape%20space}" + "{(escape+plus)}" "{escape%2Bplus}" + "{(escape*asterisk)}" "{escape%2Aasterisk}" + "{(escape(bracket)}" "{escape%28bracket}" + "{(escape))bracket)}" "{escape%29bracket}" + "{(a))b)}" "{a%29b} + "{(a (b)))}" "{a%20%28b%29} + "{()}" "{%65mpty} + "{+$*}" "{+%73elf*} + "{+($)*}" "{+%24*} + + Note that in the final example, because the "+" was outside the brackets, it remained unescaped, whereas in the fourth example the "+" was escaped. + +
@@ -692,7 +686,7 @@ Input Output To correctly resolve the URL "http://example.com/data/12345", we must take the "root" link into account. Here are some example URIs, along with the data they would resolve to: -
- - - -
+ + URI + Data + http://example.com/data/12345 {"title": "Breaking news"} + http://example.com/data/12345#/title "Breaking news" +
@@ -826,7 +816,7 @@ GET /foo/ "targetSchema": { "properties": { "message": { - "description": "Re-interpret the message text as HTML", + "description": "Re-interpret `message` as HTML", "media": { "type": "text/html" } From 90a85cca3fa1dcb1e594ad5f610914e10f3828db Mon Sep 17 00:00:00 2001 From: Austin Wright Date: Thu, 15 Sep 2016 11:53:34 -0700 Subject: [PATCH 07/22] Remove a number of excessive paragraphs --- jsonschema-core.xml | 73 +++++++++++++-------------------------------- 1 file changed, 21 insertions(+), 52 deletions(-) diff --git a/jsonschema-core.xml b/jsonschema-core.xml index 28d15b9b..2915d1da 100644 --- a/jsonschema-core.xml +++ b/jsonschema-core.xml @@ -127,56 +127,45 @@ 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 with properties which - are not schema keywords. + An empty schema is a JSON Schema with no properties, or only unknown properties.
-
+
- This example of a JSON Schema has no subschemas: + The root schema is the schema that comprises the entire JSON document in question. -
- - - -
- - JSON Schemas can also be nested, as in this example: + Some keywords take schemas themselves, allowing JSON Schemas can be nested:
- - In this example, "nested" and "alsoNested" are subschemas, and "root" is a root - schema. + In this example document, the schema titled "alsoNested" is a subschemas, + and the schema titled "root" is the root schema.
+ + JSON Schema validates and interperts data according to a data model. + JSON Schema defines six primitive types for JSON values: @@ -188,6 +177,9 @@ A JSON "string" production + + Whitespace and formatting conserns are thus outside the scope of JSON Schema. +
@@ -246,41 +238,18 @@
-
+
- It is acknowledged that an instance may be any valid JSON value as defined by . - As such, JSON Schema does not mandate that an instance be of a particular type: JSON Schema can describe any JSON value, including null. + An instance may be any valid JSON value as defined by JSON. + JSON Schema imposes no restrictions on type: JSON Schema can describe any JSON value, including, for example, null.
- JSON Schema is programming language agnostic. The only limitations are the ones - expressed by and those of the host programming - language. - -
- -
- - This specification acknowledges the role of HTTP - as the dominant protocol in use on the Internet, and the wealth of - official specifications related to it. - - - - This specification uses a subset of these specifications to recommend a set of - mechanisms, usable by this protocol, to associate JSON instances to one or more - schemas. - -
- -
- - JSON Schema does not define any semantics for the client-server interface for - any other protocols than HTTP. These semantics are application dependent, or - subject to agreement between the parties involved in the use of JSON Schema for - their own needs. + JSON Schema is programming language agnostic, and supports the full range of values described in the data model. + Be aware, however, that some languages and JSON parsers may not be able to represent in memory + the full range of values describable by JSON.
From 9608fc3ec97922c429967642a2e8ebeecda51aae Mon Sep 17 00:00:00 2001 From: Austin Wright Date: Thu, 15 Sep 2016 11:53:52 -0700 Subject: [PATCH 08/22] Fix profile= media-type parameter --- jsonschema-hyperschema.xml | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/jsonschema-hyperschema.xml b/jsonschema-hyperschema.xml index 7c1f0f2d..72b600b8 100644 --- a/jsonschema-hyperschema.xml +++ b/jsonschema-hyperschema.xml @@ -734,23 +734,24 @@ GET /foo/
With a response of (with newlines and whitespace added): -
From cbcb780fa5836694fe24685580559b2333c2fa18 Mon Sep 17 00:00:00 2001 From: Austin Wright Date: Thu, 15 Sep 2016 11:57:16 -0700 Subject: [PATCH 09/22] Fix stray punctuation --- jsonschema-core.xml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/jsonschema-core.xml b/jsonschema-core.xml index 2915d1da..23eb5ce8 100644 --- a/jsonschema-core.xml +++ b/jsonschema-core.xml @@ -157,7 +157,7 @@ - In this example document, the schema titled "alsoNested" is a subschemas, + In this example document, the schema titled "alsoNested" is a subschema, and the schema titled "root" is the root schema.
@@ -169,7 +169,7 @@ JSON Schema defines six primitive types for JSON values: - A JSON "object" production. + A JSON "object" production A JSON "array" production A JSON "true" or "false" production A JSON "number" production From e379dced695cd7f30f14a143353d805705e90084 Mon Sep 17 00:00:00 2001 From: Austin Wright Date: Thu, 15 Sep 2016 13:22:47 -0700 Subject: [PATCH 10/22] Rewrote most of "id"/dereferencing sections --- jsonschema-core.xml | 222 ++++++++++++++++++-------------------------- 1 file changed, 90 insertions(+), 132 deletions(-) diff --git a/jsonschema-core.xml b/jsonschema-core.xml index 23eb5ce8..5dc67560 100644 --- a/jsonschema-core.xml +++ b/jsonschema-core.xml @@ -5,8 +5,8 @@ - + ]> @@ -224,7 +224,9 @@ JSON Schema describes the structure of a JSON document (for instance, required properties and array length constraints). Applications can use this information to validate instances (check that constraints are met), or inform interfaces to collect user input such that the constraints are satisfied. - Validation behaviour and keywords are specified in a separate document. + + Validation behaviour and keywords are specified in a separate document. +
@@ -232,7 +234,9 @@ JSON Hyper-Schema describes the hypertext structure of a JSON document. This includes link relations from the instance to other resources, interpretation of instances as multimedia data, and submission data required to use an API. - Hyper-schema behaviour and keywords are specified in a separate document. + + Hyper-schema behaviour and keywords are specified in a separate document. +
@@ -258,7 +262,6 @@ Some programming languages and parsers use different internal representations for floating point numbers than they do for integers. - For constistency, integer JSON numbers SHOULD NOT be encoded with a fractional part. @@ -289,12 +292,10 @@ - This keyword SHOULD be located at the root of a JSON Schema. The value of this - keyword MUST be a URI and a valid JSON Reference; this URI MUST be normalized. - The resource identified by this URI MUST successfully describe the current - schema document. It is RECOMMENDED that schema authors include this keyword in their - schemas. + This keyword SHOULD be located at the root of a JSON Schema document. + The value of this keyword MUST be a URI, + a valid JSON Pointer, and this URI MUST be normalized. + The current schema MUST be valid against the meta-schema identified by this URI. @@ -320,97 +321,100 @@
+
+ + Any time a subschema is expected, a schema may instead use an object containing a "$ref" property. + The value of the $ref is a URI Reference. Resolved against the current URI base, it identifies the + URI of a schema to use. + + + The URI is not a network locator, only an identifier. A schema need not be downloadable from the address + if it is a network-addressible URL, and implementations MUST NOT assume they should perform a network + operation when they encounter a network-addressible URI. + +
+
-
+
- JSON Schema uses JSON Reference as a - mechanism for schema addressing. It extends this specification in two ways: - - - JSON Schema offers facilities to alter the base URI against which a - URI reference must resolve by the means of the "id" keyword; - it offers schemas a mechanism to declare their own URIs, placing no limits on the structure of the URI - - + RFC3986 Section 5.1 defines how to determine the default base URI of a document. - - - The initial base URI of a schema is the URI of the schema itself, or a suitable substitute URI if none is known. + Informatively, the initial base URI of a schema is the URI it was found at, or a suitable substitute URI if none is known.
-
- - The value for this keyword MUST be a string, and MUST be a valid URI-reference [RFC3986]. - This URI SHOULD be normalized, and SHOULD NOT be an empty fragment (#) or the empty string. - -
- -
- - The "id" keyword defines the URI of the schema and the base URI that other URI references within - the schema are resolved against. The "id" keyword itself is resolved against a base URI as - specified in [RFC3986]. - - - The outermost schema of a JSON Schema document SHOULD be an absolute-URI (containing a scheme, but no fragment) - or an absolute-URI with an empty fragment. - - - For example: - + + The "id" keyword defines the URI of the schema and the base URI that other URI references within + the schema are resolved against. The "id" keyword itself is resolved against a base URI as + specified in [RFC3986]. + + + The value for this keyword MUST be a string, and MUST be a valid URI-reference. + This URI SHOULD be normalized, and SHOULD NOT be an empty fragment (#) or the empty string. + + + The outermost schema of a JSON Schema document SHOULD be an absolute-URI (containing a scheme, but no fragment). + + + To identify a particular subschema in a document without needing a JSON Pointer, + subschemas can give themselves ids that can be identified by a fragment-part. + These "id" keywords with a fragment MUST begin with a letter ([A-Za-z]), to be followed by any number of + letters, digits ([0-9]), hyphens ("-"), underscores ("_"), colons (":"), and periods ("."). + + + + For example:
- + + + Subschemas at the following URI-encoded JSON + Pointers (starting from the root schema) have the following + base URIs, and are identifiable by either URI: + + + + http://example.com/root.json# + http://example.com/root.json#foo + http://example.com/other + http://example.com/other#bar + http://example.com/t/inner + urn:uuid:ee564b8a-7a87-4125-8c96-e9f123d6766f + + +
- Subschemas at the following URI-encoded JSON - Pointers (starting from the root schema) define the following - base URIs: - - - http://example.com/rootschema.json# - http://example.com/rootschema.json#foo - http://example.com/otherschema.json# - http://example.com/otherschema.json#bar - http://example.com/t/inner.json#a - urn:uuid:ee564b8a-7a87-4125-8c96-e9f123d6766f - + Schemas can be identified by any URI that has been given to them, including a JSON Pointer or + their URI given directly by "id". - -
- -
When resolving a URI to obtain a schema, tools MUST support the lookup of documents based on this URI, and the use of JSON Pointer fragments to locate particular locations within a schema document. - This is known as "canonical referencing". - - - Tools MAY also take note of the URIs schemas provide for themselves using "id", and use these values for schema dereferencing as well. - This is known as "inline referencing". + + + Tools MAY also take note of the URIs schemas provide for themselves using "id", and use these values for schema dereferencing as well. + This is known as "inline referencing". @@ -421,7 +425,7 @@ - - When an implementation encounters the "schema1" reference, it resolves it - against the current base URI, leading to URI - "http://my.site/schema1#". The way to process this URI will differ - according to the chosen dereferencing mode: - - - if canonical dereferencing is used, the implementation will - dereference this URI, and fetch the content at this URI; - if inline dereferencing is used, the implementation MAY notice that - the base URI "http://my.site/schema1#" is already defined within the - schema, and choose to use the appropriate subschema. - + When an implementation encounters the "schema1" schema, it resolves the "id" URI reference + against the current base URI, resolving to <http://example.net/schema1>. - -
- -
- When using inline dereferencing, a base URI may lead to a URI which - has a non-empty fragment part which is not a JSON Pointer, as in this - example: + When an implementation then looks inside the "schema2" schema, it encounters the "schema1" reference, + and resolves this the URI <http://example.net/schema1> which is understood as a schema defined elsewhere in the document. -
+ + An example with fragment "id" keywords: +
- - - An implementation choosing to support inline dereferencing SHOULD be able to use this kind of reference. -
- -
- -
- - Inline dereferencing can produce canonical URIs which differ from the canonical URI - of the root schema. Schema authors SHOULD ensure that implementations using - canonical dereferencing obtain the same content as implementations using inline - dereferencing. - - - - Extended JSON References using fragments which are not JSON Pointers are not dereferenceable by implementations that do not support inline dereferencing. - Schema authors should bear in mind that this support is optional before using it. -
@@ -691,19 +662,6 @@ Link: ; rel="profile", ; rel="profile" - - - JSON Reference (work in progress) - - ForgeRock US, Inc. - - - SitePen (USA) - - - - From f93c0392082f354a8cfb15ee0c4c0d938c7c24b4 Mon Sep 17 00:00:00 2001 From: Austin Wright Date: Thu, 15 Sep 2016 14:56:37 -0700 Subject: [PATCH 11/22] Switch actor in sentence --- jsonschema-core.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/jsonschema-core.xml b/jsonschema-core.xml index 5dc67560..b77f64ad 100644 --- a/jsonschema-core.xml +++ b/jsonschema-core.xml @@ -292,7 +292,7 @@ - This keyword SHOULD be located at the root of a JSON Schema document. + The root of JSON Schema documents SHOULD use this keyword. The value of this keyword MUST be a URI, a valid JSON Pointer, and this URI MUST be normalized. The current schema MUST be valid against the meta-schema identified by this URI. From f52e75c4d9db68ff8a447331a362c46b2d15b93d Mon Sep 17 00:00:00 2001 From: Austin Wright Date: Thu, 15 Sep 2016 18:26:35 -0700 Subject: [PATCH 12/22] Index the files in the repository in README --- README.md | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/README.md b/README.md index e9a978c7..5ff3bb6f 100644 --- a/README.md +++ b/README.md @@ -3,16 +3,36 @@ This repository contains the current, and historical, JSON Schema specifications. + ## Call for reviews Specifications are starting to get written. Reviews, comments and suggestions are of paramount importance to JSON Schema. It is humbly asked to you, dear reader, that you bring your contribution. + +## Contents + +Makefile - scripts to build the Internet-Draft txt/html +archive - files for other/older JSON Schema implementations +hyper-schema.json - the JSON Hyper-schema meta-schema +schema.json - the JSON Schema meta-schema +jsonschema-core.xml - sources for "core" spec +jsonschema-validation - sources for JSON Schema validation +jsonschema-hyperschema.xml - sources for hyper-schema spec + +Type "make" at a shell to build the .txt and .html spec files. + +A primer on the RFC XML format is at + + ## The website The JSON Schema web site is at http://json-schema.org/ +The source for the website is maintained in a separate repository. + + ## License The source material in this repository is licensed under the AFL or BSD license. From c77b64af8e6feb7edab13e89f38e2f7b86109270 Mon Sep 17 00:00:00 2001 From: Austin Wright Date: Fri, 16 Sep 2016 11:17:00 -0700 Subject: [PATCH 13/22] Core: Hint at how a validator API should be implemented --- jsonschema-core.xml | 35 ++++++++++++++++++++++++----------- 1 file changed, 24 insertions(+), 11 deletions(-) diff --git a/jsonschema-core.xml b/jsonschema-core.xml index b77f64ad..783efd3c 100644 --- a/jsonschema-core.xml +++ b/jsonschema-core.xml @@ -351,11 +351,11 @@ specified in [RFC3986]. - The value for this keyword MUST be a string, and MUST be a valid URI-reference. - This URI SHOULD be normalized, and SHOULD NOT be an empty fragment (#) or the empty string. + The value for this keyword MUST be a string, and MUST represent a valid URI-reference. + This URI SHOULD be normalized, and SHOULD NOT be an empty fragment <#> or an empty string ><. - The outermost schema of a JSON Schema document SHOULD be an absolute-URI (containing a scheme, but no fragment). + The root schema of a JSON Schema document SHOULD specify an absolute-URI "id" (containing a scheme, but no fragment). To identify a particular subschema in a document without needing a JSON Pointer, @@ -404,16 +404,13 @@ urn:uuid:ee564b8a-7a87-4125-8c96-e9f123d6766f -
+
Schemas can be identified by any URI that has been given to them, including a JSON Pointer or their URI given directly by "id". - When resolving a URI to obtain a schema, tools MUST support the lookup of documents based on this URI, and the use of JSON Pointer fragments to locate particular locations within a schema document. - - - Tools MAY also take note of the URIs schemas provide for themselves using "id", and use these values for schema dereferencing as well. + Tools SHOULD take note of the URIs that schemas, including subschemas, provide for themselves using "id". This is known as "inline referencing". @@ -441,12 +438,12 @@ - When an implementation encounters the "schema1" schema, it resolves the "id" URI reference + When an implementation encounters the <schema1> schema, it resolves the "id" URI reference against the current base URI, resolving to <http://example.net/schema1>. - When an implementation then looks inside the "schema2" schema, it encounters the "schema1" reference, - and resolves this the URI <http://example.net/schema1> which is understood as a schema defined elsewhere in the document. + When an implementation then looks inside the <schema2> schema, it encounters the <schema1> reference, + and resolves this the URI <http://example.net/schema1> which is understood as the schema defined elsewhere in the same document.
@@ -468,6 +465,22 @@
+
+ + To differentiate schemas between each other in a vast ecosystem, schemas are identified by URI. + As specified above, this does not necessarially mean anything is downloaded, but instead JSON Schema + implementations SHOULD provide ways to import a schema so that other schemas can reference it. + + + Implementations SHOULD be able to associate arbritrary URIs with an arbritrary schema and/or + automatically associate a schema's "id"-given URI, depending on the trust that the the validator + has in the schema. + + + A schema may have multiple URIs, but a URI must identify not more than one schema. + Validators that try to have multiple schemas associated to the same URI SHOULD raise an error condition. + +
From 5a7e53d20057f434559ee889c4062d31c0ead91a Mon Sep 17 00:00:00 2001 From: Austin Wright Date: Fri, 16 Sep 2016 11:29:07 -0700 Subject: [PATCH 14/22] Core: Add note on multiple keys in an object --- jsonschema-core.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/jsonschema-core.xml b/jsonschema-core.xml index 783efd3c..c4795340 100644 --- a/jsonschema-core.xml +++ b/jsonschema-core.xml @@ -193,7 +193,7 @@ both are strings, and are the same codepoint-for-codepoint; or both are numbers, and have the same mathematical value; or both are arrays, and have an equal value item-for-item; or - both are objects, and each property in one has exactly one property with an equal key the other, and that other property has an equal value. + both are objects, and each property in one has exactly one property with an equal key the other, and that other property has an equal value. No way is provided for a key to be used multiple times.
From 1c003d40b64318e976989da8bbd48bba10334af8 Mon Sep 17 00:00:00 2001 From: Austin Wright Date: Fri, 16 Sep 2016 11:29:29 -0700 Subject: [PATCH 15/22] Core: Remove references to past drafts This is awkward and not strictly necessary --- jsonschema-core.xml | 56 ++++++--------------------------------------- 1 file changed, 7 insertions(+), 49 deletions(-) diff --git a/jsonschema-core.xml b/jsonschema-core.xml index c4795340..c8c03f57 100644 --- a/jsonschema-core.xml +++ b/jsonschema-core.xml @@ -290,32 +290,16 @@ location of a resource which is itself a JSON Schema, which describes any schema written for this particular version. - - The root of JSON Schema documents SHOULD use this keyword. - The value of this keyword MUST be a URI, - a valid JSON Pointer, and this URI MUST be normalized. + The root schema of a JSON Schema document SHOULD use this keyword. + The value of this keyword MUST be a URI (an "absolute" URI), + and this URI MUST be normalized. The current schema MUST be valid against the meta-schema identified by this URI. - - The following values are predefined: - - - JSON Schema written - against this version. - JSON Schema hyperschema - written against this version. - JSON Schema written - against JSON Schema, draft v4. - JSON Schema hyperschema - written against JSON Schema, draft v3. - JSON Schema written - against JSON Schema, draft v3. - JSON Schema hyperschema - written against JSON Schema, draft - v3. - + Values for this property are defined in other documents and by other parties. + JSON Schema implementations SHOULD implement support for current and previous published drafts + of JSON Schema vocabularies as deemed reasonable. @@ -643,7 +627,7 @@ Link: ; rel="profile", ; rel="profile" &RFC6901; &RFC6906; &RFC7231; - JSON Schema: interactive and non interactive validation @@ -675,32 +659,6 @@ Link: ; rel="profile", ; rel="profile" - - - JSON Schema, draft 3 - - - - - SitePen (USA) - - - - - - - JSON Schema, draft 3 - - - - - SitePen (USA) - - - -
From 23ba42e129ae1d3f54bccf805cb1d1654e942c61 Mon Sep 17 00:00:00 2001 From: Austin Wright Date: Fri, 16 Sep 2016 14:37:55 -0700 Subject: [PATCH 16/22] Core: clarify a lot of language ... now that I'm more awake --- jsonschema-core.xml | 58 ++++++++++++++++----------------------------- 1 file changed, 20 insertions(+), 38 deletions(-) diff --git a/jsonschema-core.xml b/jsonschema-core.xml index c8c03f57..c0d9bffe 100644 --- a/jsonschema-core.xml +++ b/jsonschema-core.xml @@ -336,17 +336,18 @@ The value for this keyword MUST be a string, and MUST represent a valid URI-reference. - This URI SHOULD be normalized, and SHOULD NOT be an empty fragment <#> or an empty string ><. + This value SHOULD be normalized, and SHOULD NOT be an empty fragment <#> or an empty string <>. - The root schema of a JSON Schema document SHOULD specify an absolute-URI "id" (containing a scheme, but no fragment). + The root schema of a JSON Schema document SHOULD have an "id" with a valid absolute-URI (containing a scheme, but no fragment). - To identify a particular subschema in a document without needing a JSON Pointer, - subschemas can give themselves ids that can be identified by a fragment-part. - These "id" keywords with a fragment MUST begin with a letter ([A-Za-z]), to be followed by any number of - letters, digits ([0-9]), hyphens ("-"), underscores ("_"), colons (":"), and periods ("."). - + To facilitate the identification of subschemas in a JSON Schema document, + subschemas can use "id" to give themselves a URI with a custom fragment-part. + This form of "id" keyword MUST begin with a hash ("#") to identify it as a fragment URI reference, + followed by a letter ([A-Za-z]), followed by any number of + letters, digits ([0-9]), hyphens ("-"), underscores ("_"), colons (":"), or periods ("."). + For example: @@ -406,54 +407,35 @@ - When an implementation encounters the <schema1> schema, it resolves the "id" URI reference - against the current base URI, resolving to <http://example.net/schema1>. + When an implementation encounters the <#/definitions/single> schema, it resolves the "id" URI reference + against the current base URI to <http://example.net/schema1>. - When an implementation then looks inside the <schema2> schema, it encounters the <schema1> reference, - and resolves this the URI <http://example.net/schema1> which is understood as the schema defined elsewhere in the same document. + When an implementation then looks inside the <#/items> schema, it encounters the <schema1> reference, + and resolves this to <http://example.net/schema1> which is understood as the schema defined elsewhere in the same document. -
- - An example with fragment "id" keywords: - - - - -
To differentiate schemas between each other in a vast ecosystem, schemas are identified by URI. As specified above, this does not necessarially mean anything is downloaded, but instead JSON Schema - implementations SHOULD provide ways to import a schema so that other schemas can reference it. + implementations SHOULD provide ways to import a schema by URI so that other schemas can successfully reference it. Implementations SHOULD be able to associate arbritrary URIs with an arbritrary schema and/or @@ -461,7 +443,7 @@ has in the schema. - A schema may have multiple URIs, but a URI must identify not more than one schema. + A schema MAY (and likely will) have multiple URIs, but a URI has no way to identify more than one schema. Validators that try to have multiple schemas associated to the same URI SHOULD raise an error condition.
From 3cbfc8bcab58ce6c0397f205534d2a4cede76ce8 Mon Sep 17 00:00:00 2001 From: Austin Wright Date: Sat, 17 Sep 2016 00:40:13 -0700 Subject: [PATCH 17/22] Rework definition of instance/schema/data model --- jsonschema-core.xml | 110 ++++++++++++++++++++------------------------ 1 file changed, 51 insertions(+), 59 deletions(-) diff --git a/jsonschema-core.xml b/jsonschema-core.xml index c0d9bffe..d3675833 100644 --- a/jsonschema-core.xml +++ b/jsonschema-core.xml @@ -102,36 +102,73 @@
-
+
- When referring to a JSON Object, as defined by , the - terms "member" and "property" may be used interchangeably. + A JSON document is an information resource (series of octets) describable by the application/json media type. - - When referring to a JSON Array, as defined by , the terms - "element" and "item" may be used interchangeably. + In JSON Schema, the terms "JSON document", "JSON text", and "JSON value" are interchangable because of the data model it defines.
-
+
- A JSON Schema is a JSON document, and that document MUST be an object. Object - members (or properties) defined by JSON Schema (this specification, or related - specifications) are called keywords, or schema keywords. + JSON Schema interperts JSON data according to a data model. A JSON value interperted according to this data model is called an "instance". + + An instance has one of six primitive types, and a range of possible values depending on the type: + + A JSON "null" production + A "true" or "false" value, from the JSON "true" or "false" productions + An unordered set of properties mapping a string to an instance, from the JSON "object" production + An ordered list of instances, from the JSON "array" production + An arbitrary-precision, base-10 decimal number value, from the JSON "number" production + A string of Unicode code points, from the JSON "string" production + + + + Whitespace and formatting conserns are thus outside the scope of JSON Schema. + - If an instance is described by a schema, and a keyword is defined in the schema, then within this document that instance is informally said to be "described by" the keyword as well. + Since an object cannot have two properties with the same key, behavior for a JSON document that tries to define two properties (the "member" production) with the same key (the "string" production) in a single object is undefined. +
+
- A JSON Schema MAY contain properties which are not schema keywords. - Unknown keywords SHOULD be ignored. + Two JSON instances are said to be equal if and only if they are of the same type and have the same value according to the data model. Specifically, this is if: + + + both are null; or + both are true; or + both are false; or + both are strings, and are the same codepoint-for-codepoint; or + both are numbers, and have the same mathematical value; or + both are arrays, and have an equal value item-for-item; or + both are objects, and each property in one has exactly one property with an equal key the other, and that other property has an equal value. + + + + Implied in this definition is that arrays must be the same length, objects must have the same number of members, there is no way to define multiple properties with the same key, and mere formatting differences (indentation, placement of commas, trailing zeros) are insignificant.
-
+
+ + A JSON Schema document, or simply a schema, is a JSON document used to describe an instance. + A schema is itself interperted as an instance.A JSON schema MUST be an object. + + + 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 specify validate JSON Schemas and specify which vocabulary it is using. + An empty schema is a JSON Schema with no properties, or only unknown properties. @@ -162,51 +199,6 @@
-
- - JSON Schema validates and interperts data according to a data model. - - - JSON Schema defines six primitive types for JSON values: - - A JSON "object" production - A JSON "array" production - A JSON "true" or "false" production - A JSON "number" production - A JSON "null" production - A JSON "string" production - - - - Whitespace and formatting conserns are thus outside the scope of JSON Schema. - -
- -
- - Two JSON values are said to be equal if and only if: - - - both are null; or - both are true; or - both are false; or - both are strings, and are the same codepoint-for-codepoint; or - both are numbers, and have the same mathematical value; or - both are arrays, and have an equal value item-for-item; or - both are objects, and each property in one has exactly one property with an equal key the other, and that other property has an equal value. No way is provided for a key to be used multiple times. - - -
- -
- - An instance is any JSON value being described by a schema. - - - An instance may also be referred to as a "JSON instance", "JSON data", "JSON-text", or "JSON document". - -
-
From a99e8db93a1bc2db6a71c83b82cd2012cb8a76c1 Mon Sep 17 00:00:00 2001 From: Austin Wright Date: Sat, 17 Sep 2016 01:04:36 -0700 Subject: [PATCH 18/22] Core: Typo fixes --- jsonschema-core.xml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/jsonschema-core.xml b/jsonschema-core.xml index d3675833..b9da7c0c 100644 --- a/jsonschema-core.xml +++ b/jsonschema-core.xml @@ -157,7 +157,7 @@
A JSON Schema document, or simply a schema, is a JSON document used to describe an instance. - A schema is itself interperted as an instance.A JSON schema MUST be an object. + A schema is itself interperted as an instance. A JSON schema MUST be an object. 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. @@ -167,7 +167,7 @@ Unknown keywords SHOULD be ignored. - A schema that itself describes a schema is called a meta-schema. Meta-schemas are used to specify validate JSON Schemas and specify which vocabulary it is using. + 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. From a7929f1ccc79fff30b35aee856624a253101c250 Mon Sep 17 00:00:00 2001 From: Austin Wright Date: Sat, 17 Sep 2016 07:24:36 -0700 Subject: [PATCH 19/22] Core: s/inline reference/internal reference/ --- jsonschema-core.xml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/jsonschema-core.xml b/jsonschema-core.xml index b9da7c0c..4693d781 100644 --- a/jsonschema-core.xml +++ b/jsonschema-core.xml @@ -381,14 +381,14 @@ urn:uuid:ee564b8a-7a87-4125-8c96-e9f123d6766f -
+
Schemas can be identified by any URI that has been given to them, including a JSON Pointer or their URI given directly by "id". Tools SHOULD take note of the URIs that schemas, including subschemas, provide for themselves using "id". - This is known as "inline referencing". + This is known as "Internal referencing". From 8c9b183a14c3485d8b3611d428c7ee1ff746c690 Mon Sep 17 00:00:00 2001 From: Austin Wright Date: Sat, 17 Sep 2016 07:25:08 -0700 Subject: [PATCH 20/22] Core: fix typo --- jsonschema-core.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/jsonschema-core.xml b/jsonschema-core.xml index 4693d781..0263f114 100644 --- a/jsonschema-core.xml +++ b/jsonschema-core.xml @@ -495,7 +495,7 @@ Link: ; rel="describedby"
Instances MAY specify a "profile" as described in The 'profile' Link Relation. - When used as a media-type parameter, HTTP servers gain the ability to perform Content-Type Negotiation based on profile. The media-type paramater MUST be a whitespace-separated list of URIs (i.e. relative references are invalid). + When used as a media-type parameter, HTTP servers gain the ability to perform Content-Type Negotiation based on profile. The media-type parameter MUST be a whitespace-separated list of URIs (i.e. relative references are invalid). The profile URI is opaque and SHOULD NOT automatically be dereferenced. If the implementation does not understand the semantics of the provided profile, the implementation can instead follow the "describedby" links, if any, which may provide information on how to handle the profile. From ef6d322a01a34743a2e25205b0d2d127171c1196 Mon Sep 17 00:00:00 2001 From: Austin Wright Date: Sat, 17 Sep 2016 07:25:23 -0700 Subject: [PATCH 21/22] Core: move HTTP section into Hypermedia section --- jsonschema-core.xml | 48 ++++++++++++++++++++++----------------------- 1 file changed, 24 insertions(+), 24 deletions(-) diff --git a/jsonschema-core.xml b/jsonschema-core.xml index 0263f114..cf66d8d3 100644 --- a/jsonschema-core.xml +++ b/jsonschema-core.xml @@ -442,29 +442,7 @@
-
- - When used for hypermedia systems over a network, HTTP is frequently the protocol of choice for distributing schemas. Misbehaved clients can pose problems for server maintainers if they pull a schema over the network more frequently than necessary, when it's instead possible to cache a schema for a long period of time. - - - HTTP servers SHOULD set long-lived caching headers on JSON Schemas. HTTP clients SHOULD observe caching headers and not re-request documents within their freshness period. - - - Clients SHOULD set or prepend a User-Agent header specific to the JSON Schema implementation or software product. Since symbols are listed in decreasing order of significance, the JSON Schema library name/version goes first, then the more generic HTTP library name (if any). For example: -
- - - -
- - - Clients SHOULD be able to make requests with a "From" header so that server operators can contact the owner of a potentially misbehaving script. - -
- -
+
One of the largest adoptors of JSON has been HTTP servers for automated APIs and robots. @@ -543,7 +521,29 @@ Link: ; rel="profile", ; rel="profile"
-
+
+ + When used for hypermedia systems over a network, HTTP is frequently the protocol of choice for distributing schemas. Misbehaved clients can pose problems for server maintainers if they pull a schema over the network more frequently than necessary, when it's instead possible to cache a schema for a long period of time. + + + HTTP servers SHOULD set long-lived caching headers on JSON Schemas. HTTP clients SHOULD observe caching headers and not re-request documents within their freshness period. + + + Clients SHOULD set or prepend a User-Agent header specific to the JSON Schema implementation or software product. Since symbols are listed in decreasing order of significance, the JSON Schema library name/version goes first, then the more generic HTTP library name (if any). For example: +
+ + + +
+ + + Clients SHOULD be able to make requests with a "From" header so that server operators can contact the owner of a potentially misbehaving script. + +
+ +
From e73a65023ae9042ceca52ba33d00dff9c4576dd6 Mon Sep 17 00:00:00 2001 From: Austin Wright Date: Sat, 17 Sep 2016 07:30:29 -0700 Subject: [PATCH 22/22] Core: add shared cache suggestion --- jsonschema-core.xml | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/jsonschema-core.xml b/jsonschema-core.xml index cf66d8d3..442adc19 100644 --- a/jsonschema-core.xml +++ b/jsonschema-core.xml @@ -526,7 +526,9 @@ Link: ; rel="profile", ; rel="profile" When used for hypermedia systems over a network, HTTP is frequently the protocol of choice for distributing schemas. Misbehaved clients can pose problems for server maintainers if they pull a schema over the network more frequently than necessary, when it's instead possible to cache a schema for a long period of time. - HTTP servers SHOULD set long-lived caching headers on JSON Schemas. HTTP clients SHOULD observe caching headers and not re-request documents within their freshness period. + HTTP servers SHOULD set long-lived caching headers on JSON Schemas. + HTTP clients SHOULD observe caching headers and not re-request documents within their freshness period. + Distributed systems SHOULD make use of a shared cache and/or caching proxy. Clients SHOULD set or prepend a User-Agent header specific to the JSON Schema implementation or software product. Since symbols are listed in decreasing order of significance, the JSON Schema library name/version goes first, then the more generic HTTP library name (if any). For example: