Merge pull request #1 from Acubed/aaa-uri-fix

s/resolution scope/base URI/

Author: awwright

jsonschema-core.xml

@@ -176,6 +176,7 @@
             <section title="JSON Schema primitive types">
                 <t>
                     JSON Schema defines seven primitive types for JSON values:
+                    <!-- TODO integer and number are both the same syntax, integer is just a subset -->
                     <list style="hanging">
                         <t hangText="array">A JSON array.</t>
                         <t hangText="boolean">A JSON boolean.</t>
@@ -221,7 +222,7 @@
                 </t>
 
                 <t>
-                    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".
                 </t>
             </section>
 
@@ -333,6 +334,7 @@
 
         <section title='The "$schema" keyword'>
             <section title="Purpose">
+                <!-- TODO a custom $schema keyword might also be used to enforce minimum required functionality of a validator -->
                 <t>
                     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 @@
                 <t>
                     This keyword SHOULD be located at the root of a JSON Schema. The value of this
                     keyword MUST be a <xref target="RFC3986">URI</xref> and a valid <xref
-                    target="json-reference">JSON Reference</xref>; 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</xref>; 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.
                 </t>
 
@@ -375,62 +377,52 @@
 
         </section>
 
-        <section title="URI resolution scopes and dereferencing">
+        <section title="Base URI and dereferencing">
             <section title="Definition">
                 <t>
                     JSON Schema uses <xref target="json-reference">JSON Reference</xref> as a
                     mechanism for schema addressing. It extends this specification in two ways:
 
                     <list>
                         <t>JSON Schema offers facilities to alter the base URI against which a
-                        reference must resolve by the means of the "id" keyword;</t>
+                        URI reference must resolve by the means of the "id" keyword;</t>
                         <t>it offers schemas a mechanism to declare their own URIs, placing no limits on the structure of the URI</t>
                     </list>
 
                 </t>
 
                 <t>
-                    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.
+                    <!-- TODO: RFC3986 defines exactly how to do this -->
+                    The initial base URI of a schema is the URI of the schema itself, or a suitable substitute URI if none is known.
                 </t>
             </section>
 
-            <section title='URI resolution scope alteration with the "id" keyword'>
-
+            <section title='Base URI alteration with the "id" keyword'>
                 <section title="Valid values">
                     <t>
-                        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 [RFC3986].
                         This URI SHOULD be normalized, and SHOULD NOT be an empty fragment (#) or the empty string.
                     </t>
                  </section>
 
                 <section title="Usage">
                     <t>
-                        The "id" keyword is used to alter the resolution scope.
-                        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 "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].
                     </t>
-
                     <t>
-                        When using "id" to alter resolution scopes, schema authors SHOULD ensure
-                        that resolution scopes are 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.
                     </t>
-
                     <t>
-                        This schema will be taken as an example:
+                        For example:
                     </t>
-
-                    <!--
-                        FIXME: http again as a scheme, maybe another one? It can be any scheme after
-                        all
-                    -->
                     <figure>
                         <artwork>
 <![CDATA[
 {
-    "id": "http://x.y.z/rootschema.json#",
+    "id": "http://example.com/rootschema.json#",
     "schema1": {
         "id": "#foo"
     },
@@ -444,7 +436,7 @@
         }
     },
     "schema3": {
-        "id": "some://where.else/completely#"
+        "id": "urn:uuid:ee564b8a-7a87-4125-8c96-e9f123d6766f"
     }
 }
 ]]>
@@ -454,15 +446,15 @@
                     <t>
                         Subschemas at the following URI-encoded <xref target="json-pointer">JSON
                         Pointer</xref>s (starting from the root schema) define the following
-                        resolution scopes:
-
+                        base URIs:
+    
                         <list style="hanging">
-                            <t hangText="# (document root)">http://x.y.z/rootschema.json#</t>
-                            <t hangText="#/schema1">http://x.y.z/rootschema.json#foo</t>
-                            <t hangText="#/schema2">http://x.y.z/otherschema.json#</t>
-                            <t hangText="#/schema2/nested">http://x.y.z/otherschema.json#bar</t>
-                            <t hangText="#/schema2/alsonested">http://x.y.z/t/inner.json#a</t>
-                            <t hangText="#/schema3">some://where.else/completely#</t>
+                            <t hangText="# (document root)">http://example.com/rootschema.json#</t>
+                            <t hangText="#/schema1">http://example.com/rootschema.json#foo</t>
+                            <t hangText="#/schema2">http://example.com/otherschema.json#</t>
+                            <t hangText="#/schema2/nested">http://example.com/otherschema.json#bar</t>
+                            <t hangText="#/schema2/alsonested">http://example.com/t/inner.json#a</t>
+                            <t hangText="#/schema3">urn:uuid:ee564b8a-7a87-4125-8c96-e9f123d6766f</t>
                         </list>
                     </t>
 
@@ -504,15 +496,15 @@
 
                     <t>
                         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:
 
                         <list>
                             <t>if canonical dereferencing is used, the implementation will
                             dereference this URI, and fetch the content at this URI;</t>
                             <t>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.</t>
                         </list>
                     </t>
@@ -521,7 +513,7 @@
 
                 <section title="Inline dereferencing and fragments">
                     <t>
-                        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:
                     </t>
@@ -576,6 +568,7 @@
             </t>
 
             <section title='Correlation by means of the "Link" header'>
+                <!-- HTTP linking is referenced by specs that have nothing to do with HTTP, so this isn't always the case -->
                 <t>
                     It is RECOMMENDED that instances be associated with JSON Schemas using the link relation "describedby", as defined by <xref target="RFC5988">RFC 5988, section 5.3</xref>.
                 </t>

jsonschema-hyperschema.xml

@@ -386,7 +386,7 @@
             <section title="pathStart">
                 <t>
                     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 <xref target="json-schema-core">JSON Schema core specification</xref>), using the rules from <xref target="RFC3986">RFC 3986, Sec 5</xref>.
+                    The value of the "pathStart" property MUST be resolved relative to the current URI base (as defined in the <xref target="json-schema-core">JSON Schema core specification</xref>), using the rules from <xref target="RFC3986">RFC 3986, Sec 5</xref>.
                 </t>
 
                 <t>
@@ -416,7 +416,7 @@
             <section title="href" anchor="href">
                 <t>
                     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 <xref target="RFC3986">RFC 3986</xref> and MAY be a relative reference to a URI.
+                    The value of the instance property SHOULD be resolved as a URI-Reference per <xref target="RFC3986">RFC 3986</xref> 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).
                 </t>