Merge pull request json-schema-org#372 from handrews/clarity

Minor readability / clarity fixes
handrews · Aug 31, 2017 · a560f8b · a560f8b
2 parents 3b17738 + ec5c9cd
commit a560f8b
Show file tree

Hide file tree

Showing 2 changed files with 17 additions and 7 deletions.
diff --git a/jsonschema-core.xml b/jsonschema-core.xml
@@ -431,10 +431,12 @@
 
             <section title='The "$id" keyword' anchor="id-keyword">
                 <t>
-                    The "$id" keyword defines a URI for the schema,
-                    and the base URI that other URI references within the schema are resolved against.
-                    The "$id" keyword itself is resolved against the base URI that the object as a
-                    whole appears in.
+                    The "$id" keyword defines a URI for the schema, and the base URI that
+                    other URI references within the schema are resolved against.
+                    A subschema's "$id" is resolved against the base URI of its parent schema.
+                    If no parent sets an explicit base with "$id", the base URI is that of the
+                    entire document, as determined per
+                    <xref target="RFC3986">RFC 3986 section 5</xref>.
                 </t>
                 <t>
                     If present, the value for this keyword MUST be a string, and MUST represent a
@@ -468,7 +470,7 @@
                     Pointer references are updated.
                 </t>
                 <t>
-                    The effect of defining a URI fragment "$id" that neither
+                    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.
                 </t>

diff --git a/jsonschema-hyperschema.xml b/jsonschema-hyperschema.xml
@@ -211,6 +211,10 @@
             </figure>
 
             <section title="Interaction with validation">
+                <t>
+                    Hyper-schema keywords can be applied when the instance is valid against
+                    the schema that includes those keywords.
+                </t>
                 <t>
                     Hyper-schemas MUST NOT be applied to an instance if the instance fails to
                     validate against the validation keywords within or containing the hyper-schema.
@@ -464,6 +468,10 @@
                         hint may be added in a future draft (see issue #73 in the GitHub repository).
                     </cref>
                 </t>
+                <t>
+                    An operation is a specific use of a link described by an LDO, after any
+                    template variables have been resolved.
+                </t>
                 <t>
                     There are several ways that a client can use data with a link:
                     <list>
@@ -474,8 +482,8 @@
                             inherent relation to the target resource's representation</t>
                     </list>
                     The three ways to use client-supplied data are each addressed by a separate
-                    schema keyword within the link description object.  Link operations
-                    ignore schemas that are not relevant to their semantics.
+                    schema keyword within the link description object.  When performing operations,
+                    clients SHOULD ignore schemas that are not relevant to their semantics.
                 </t>
                 <t>
                     Link Description Objects do not directly indicate what operations, such