Control link applicability with hrefRequired

handrews · handrews · commit 040082cfe5a0 · 2017-09-12T19:04:17.000-07:00
This addresses issue json-schema-org#49. Add a keyword, "hrefRequired", that prevents a link from being used if a variable named in that keyword's array cannot be resolved to a value by any available mechanism. Remove outdated language about non-object instances causing problems, as this is addressed by "hrefPointers".
diff --git a/hyper-schema.json b/hyper-schema.json
@@ -28,6 +28,9 @@
                     "description": "a schema for validating user input to the URI template, where the input is in the form of a JSON object with property names matching variable names in \"href\"",
                     "allOf": [ {"$ref": "#"} ]
                 },
+                "hrefRequired": {
+                    "description": "an array of URI template variables names from \"href\" which must be filled out with some value, either from the instance or user input"
+                },
                 "rel": {
                     "description": "relation to the target resource of the link",
                     "type": "string"
diff --git a/jsonschema-hyperschema.xml b/jsonschema-hyperschema.xml
@@ -183,12 +183,6 @@
                     binary data treated as a PNG image.
                     It also defines link relations for the instance, with URIs incorporating values
                     from the instance.
-                    <cref>
-                        "id" probably should not normally be a required keyword, since new instances
-                        will have an unknown "id" property until is it assigned by the server.
-                        However, this property is used in a link, and without it, multiple different
-                        instances would be given the same rel=self URI!
-                    </cref>
                 </postamble>
             </figure>
 
@@ -644,18 +638,23 @@
 
                     <section title="Missing values" anchor="missingValues">
                         <t>
-                            Sometimes, the appropriate values will not be available.
-                            For example, the template might specify the use of object properties,
-                            but no such data was provided (or "hrefSchema" is not present), and the
-                            instance is an array or a string.
+                            Sometimes, the appropriate values will not be available.  In many
+                            cases, the URI Template behavior of simply removing varibles that
+                            do not have a value will be appropriate.  An example of this is
+                            optional query parameters, the presence or absence of which does
+                            not change the nature of the link relation type.
                         </t>
 
                         <t>
-                            If any of the values required for the template are neither present in
-                            the user agent data (if relevant) nor the JSON instance, then substitute
-                            values MAY be provided from another source (such as default values).
-                            Otherwise, the link definition SHOULD be considered not to apply to the
-                            instance.
+                            However, some variables, such as an identifier used in a path component,
+                            cannot meaningfully be omitted.  The resulting URI would be meaningless,
+                            or would require a different link relation type.  While "hrefSchema" can
+                            express a requirement for those variables that can be supplied via input,
+                            some variables must be resolved from instance data.  When that instance
+                            data is not required by the context schema, the
+                            <xref target="hrefRequired">"hrefRequired</xref> keyword may be used to
+                            indicate that when the instance data is not available, the link does
+                            not apply.
                         </t>
                     </section>
                 </section>
@@ -709,7 +708,8 @@
             "hrefPointers": {
                 "rootId": "/id",
                 "parentId": "2/id"
-            }
+            },
+            "hrefRequired": ["parentId"]
         }
     ]
 }]]>
@@ -761,14 +761,8 @@
                 </t>
                 <t>
                     For the root node, the relative pointer for the parent doesn't point
-                    to anything.  As noted under
-                    <xref target="missingValues">missing values</xref>, such a link should
-                    simply be ignored.
-                    <cref>
-                        GitHub issue #49 tracks the question of distinguishing this situation
-                        of a missing required variable (common in path components) from
-                        missing optional variables (common in query string parameters).
-                    </cref>
+                    to anything, so <xref target="hrefRequired">"hrefRequired"</xref>
+                    prevents the link from being used with that node.
                 </t>
             </section>
 
@@ -863,6 +857,37 @@
                 </t>
             </section>
 
+            <section title="hrefRequired" anchor="hrefRequired">
+                <t>
+                    The value of this keyword MUST be an array, and the elements MUST be unique.
+                    Each element SHOULD match a variable in the link's URI Template, without
+                    percent-encoding.  After completing the entire URI Template resolution
+                    process, if any variable that is present in this array does not have
+                    a value, the link MUST NOT be used.
+                </t>
+                <figure>
+                    <preamble>
+                        Here is a simplified version of the "up" link from the
+                        <xref target="hrefPointers">"hrefPointers</xref> tree example,
+                        modified to only use the parent identifier for its "href" template.
+                        While each individual node is required to have an "id" field, the
+                        "up" link uses the parent node's field, and the root node, by definition,
+                        does not have a parent node.  Putting "parentId" in "hrefRequired" ensures
+                        that the "up" link is correctly unusable with the root node.
+                    </preamble>
+                    <artwork>
+<![CDATA[{
+    "rel": "up",
+    "href": "/nodes/{parentId}",
+    "hrefPointers": {
+        "parentId": "2/id"
+    },
+    "hrefRequired": ["parentId"]
+}]]>
+                    </artwork>
+                </figure>
+            </section>
+
             <section title="rel" anchor="rel">
                 <t>
                     The value of the "rel" property indicates the name of the relation to the target
diff --git a/links.json b/links.json
@@ -17,6 +17,9 @@
             "description": "a schema for validating user input to the URI template, where the input is in the form of a JSON object with property names matching variable names in \"href\"",
             "allOf": [ {"$ref": "#"} ]
         },
+        "hrefRequired": {
+            "description": "an array of URI template variables names from \"href\" which must be filled out with some value, either from the instance or user input"
+        },
         "rel": {
             "description": "relation to the target resource of the link",
             "type": "string"
