Merge pull request #551 from awwright/master

Core: Improve language for schema references section

Author: handrews

jsonschema-core.xml

@@ -528,6 +528,11 @@
         </section>
 
         <section title="Base URI and Dereferencing">
+            <t>
+                To differentiate between schemas in a vast ecosystem, schemas are
+                identified by <xref target="RFC3986">URI</xref>, and can embed references to other schemas by specifying their URI.
+            </t>
+
             <section title="Initial Base URI">
                 <t>
                     <xref target="RFC3986">RFC3986 Section 5.1</xref> defines how to determine the
@@ -557,8 +562,8 @@
                 <section title="Identifying the root schema">
                     <t>
                         The root schema of a JSON Schema document SHOULD contain an "$id" keyword with
-                        a URI (containing a scheme).  This URI SHOULD either not have a fragment, or
-                        have one that is an empty string.
+                        an <xref target="RFC3986">absolute-URI</xref> (containing a scheme, but no fragment),
+                        or this absolute URI but with an empty fragment.
                         <!-- All of the standard meta-schemas use an empty fragment in their id/$id values. -->
                     </t>
                 </section>
@@ -583,18 +588,16 @@
                         without requiring JSON Pointer references to be updated.
                     </t>
                     <t>
-                        To name subschemas in a JSON Schema document,
-                        subschemas can use "$id" to give themselves a document-local identifier.
-                        This is done by setting "$id" to a URI reference consisting
-                        only of a plain name fragment (not a JSON Pointer fragment).
-                        The fragment identifier MUST begin with a letter ([A-Za-z]), followed by
-                        any number of letters, digits ([0-9]), hyphens ("-"), underscores ("_"), colons
-                        (":"), or periods (".").
+                        To specify such a subschema identifier,
+                        the "$id" keyword is set to a URI reference with a plain name fragment (not a JSON Pointer fragment).
+                        This value MUST begin with the number sign that specifies a fragment ("#"),
+                        then a letter ([A-Za-z]),
+                        followed by any number of letters, digits ([0-9]), hyphens ("-"), underscores ("_"),
+                        colons (":"), or periods (".").
                     </t>
                     <t>
-                        The effect of defining a fragment-only "$id" URI reference that neither
-                        matches the above requirements nor is a valid JSON pointer
-                        is not defined.
+                        The effect of using a fragment in "$id" that isn't blank or doesn't follow the
+                        plain name syntax is undefined.
                         <cref>
                             How should an "$id" URI reference containing a fragment with other components
                             be interpreted?  There are two cases:  when the other components match
@@ -711,11 +714,14 @@
                 </t>
                 <section title="Loading a referenced schema">
                     <t>
-                        To differentiate schemas between each other in a vast ecosystem, schemas are
-                        identified by URI. As specified above, this does not necessarily mean
-                        anything is downloaded, but instead JSON Schema implementations SHOULD
-                        already understand the schemas they will be using, including the URIs that
-                        identify them.
+                        The use of URIs to identify remote schemas does not necessarily mean anything is downloaded,
+                        but instead JSON Schema implementations SHOULD understand ahead of time which schemas they will be using,
+                        and the URIs that identify them.
+                    </t>
+                    <t>
+                        When schemas are downloaded,
+                        for example by a generic user-agent that doesn't know until runtime which schemas to download,
+                        see <xref target="hypermedia">Usage for Hypermedia</xref>.
                     </t>
                     <t>
                         Implementations SHOULD be able to associate arbitrary URIs with an arbitrary
@@ -728,7 +734,7 @@
                     <t>
                         A schema MAY (and likely will) have multiple URIs, but there is no way for a
                         URI to identify more than one schema. When multiple schemas try to identify
-                        with the same URI, validators SHOULD raise an error condition.
+                        as the same URI, validators SHOULD raise an error condition.
                     </t>
                 </section>
                 <section title="Dereferencing">
@@ -829,7 +835,7 @@
             </t>
         </section>
 
-        <section title="Usage for Hypermedia">
+        <section title="Usage for Hypermedia" anchor="hypermedia">
 
             <t>
                 JSON has been adopted widely by HTTP servers for automated APIs and robots. This
@@ -974,12 +980,12 @@ User-Agent: product-name/5.4.1 so-cool-json-schema/1.0.2 curl/7.43.0
             <t>
                 Instances and schemas are both frequently written by untrusted third parties, to be
                 deployed on public Internet servers.
-                Validators should take care that the parsing of schemas doesn't consume excessive
+                Validators should take care that the parsing and validating against schemas doesn't consume excessive
                 system resources.
                 Validators MUST NOT fall into an infinite loop.
             </t>
             <t>
-                Servers need to take care that malicious parties can't change the functionality of
+                Servers MUST ensure that malicious parties can't change the functionality of
                 existing schemas by uploading a schema with an pre-existing or very similar "$id".
             </t>
             <t>