From 83a7a1b13b501f755b3524930c6ea9a1b1c918ed Mon Sep 17 00:00:00 2001 From: Austin Wright Date: Tue, 23 Jun 2015 22:57:26 -0700 Subject: [PATCH 1/2] s/resolution scope/base URI/ --- jsonschema-core.xml | 42 ++++++++++++++++++++------------------ jsonschema-hyperschema.xml | 4 ++-- 2 files changed, 24 insertions(+), 22 deletions(-) diff --git a/jsonschema-core.xml b/jsonschema-core.xml index 1e8c50d7..5ab27f18 100644 --- a/jsonschema-core.xml +++ b/jsonschema-core.xml @@ -176,6 +176,7 @@
JSON Schema defines seven primitive types for JSON values: + A JSON array. A JSON boolean. @@ -221,7 +222,7 @@ - An instance may also be referred to as "JSON instance", or "JSON data". + An instance may also be referred to as a "JSON instance", "JSON data", or "JSON document".
@@ -333,6 +334,7 @@
+ The "$schema" keyword is both used as a JSON Schema version identifier and the location of a resource which is itself a JSON Schema, which describes any schema @@ -342,9 +344,9 @@ 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 both absolute - and normalized. The resource located at this URI MUST successfully describe - itself. It is RECOMMENDED that schema authors include this keyword in their + target="json-reference">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. @@ -375,7 +377,7 @@
-
+
JSON Schema uses JSON Reference as a @@ -383,39 +385,38 @@ JSON Schema offers facilities to alter the base URI against which a - reference must resolve by the means of the "id" keyword; + 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 - Altering the URI within a schema is called defining a new resolution scope. - The initial resolution scope of a schema is the URI of the schema itself, or a suitable substitute URI if none is known. + + The initial base URI of a schema is the URI of the schema itself, or a suitable substitute URI if none is known.
-
+
- The value for this keyword MUST be a string, and MUST be a valid URI (relative or absolute). + 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 "id" keyword is used to alter the resolution scope. + The "id" keyword is used to give the document a URI and set its base URI for resolving URI references against. When an id is encountered, an implementation MUST resolve this id against - the most immediate parent scope. The resolved URI will be the new resolution - scope for this subschema and all its children, until another "id" is - encountered. + the parent environment base URI. The resolved URI will be the new base URI for + the rest of the schema and all child schemas, until another "id" is encountered. - When using "id" to alter resolution scopes, schema authors SHOULD ensure - that resolution scopes are unique within the schema. + When using "id" to alter the base URI, schema authors SHOULD ensure + that the URI is unique within the schema. @@ -454,7 +455,7 @@ Subschemas at the following URI-encoded JSON Pointers (starting from the root schema) define the following - resolution scopes: + base URIs: http://x.y.z/rootschema.json# @@ -504,7 +505,7 @@ When an implementation encounters the "schema1" reference, it resolves it - against the most immediate parent scope, leading to URI + 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: @@ -512,7 +513,7 @@ 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 - URI scope "http://my.site/schema1#" is already defined within the + the base URI "http://my.site/schema1#" is already defined within the schema, and choose to use the appropriate subschema. @@ -521,7 +522,7 @@
- When using inline dereferencing, a resolution scope may lead to a URI which + 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: @@ -576,6 +577,7 @@
+ It is RECOMMENDED that instances be associated with JSON Schemas using the link relation "describedby", as defined by RFC 5988, section 5.3. diff --git a/jsonschema-hyperschema.xml b/jsonschema-hyperschema.xml index b91b07c8..549005e6 100644 --- a/jsonschema-hyperschema.xml +++ b/jsonschema-hyperschema.xml @@ -386,7 +386,7 @@
This property is a URI that defines what the instance's URI MUST start with in order to validate. - The value of the "pathStart" property MUST be resolved relative to the closest URI Resolution Scope (as defined in the JSON Schema core specification), using the rules from RFC 3986, Sec 5. + The value of the "pathStart" property MUST be resolved relative to the current URI base (as defined in the JSON Schema core specification), using the rules from RFC 3986, Sec 5. @@ -416,7 +416,7 @@
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 relative reference to a URI. + 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). From 851daec1af20e26e01967ce39fcc0ba87c7a995b Mon Sep 17 00:00:00 2001 From: Austin Wright Date: Wed, 19 Aug 2015 11:33:49 -0700 Subject: [PATCH 2/2] Update/clean up wording for "id" section --- jsonschema-core.xml | 38 +++++++++++++++----------------------- 1 file changed, 15 insertions(+), 23 deletions(-) diff --git a/jsonschema-core.xml b/jsonschema-core.xml index 5ab27f18..ee95a2b4 100644 --- a/jsonschema-core.xml +++ b/jsonschema-core.xml @@ -401,37 +401,29 @@
- The value for this keyword MUST be a string, and MUST be a valid URI reference. + 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 is used to give the document a URI and set its base URI for resolving URI references against. - When an id is encountered, an implementation MUST resolve this id against - the parent environment base URI. The resolved URI will be the new base URI for - the rest of the schema and all child schemas, until another "id" is encountered. + 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]. - - When using "id" to alter the base URI, schema authors SHOULD ensure - that the URI is unique within the schema. + 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. - - This schema will be taken as an example: + For example: - -
@@ -458,12 +450,12 @@ base URIs: - http://x.y.z/rootschema.json# - http://x.y.z/rootschema.json#foo - http://x.y.z/otherschema.json# - http://x.y.z/otherschema.json#bar - http://x.y.z/t/inner.json#a - some://where.else/completely# + 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