Skip to content

Commit 2979d0f

Browse files
handrewshandrews
committed
Control link applicability with hrefRequired
This addresses issue #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".
1 parent f26ef9c commit 2979d0f

File tree

2 files changed

+52
-24
lines changed

2 files changed

+52
-24
lines changed

‎jsonschema-hyperschema.xml

Lines changed: 49 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -172,12 +172,6 @@
172172
<postamble>
173173
This example schema defines the properties of the instance as well as link
174174
relations for the instance, with URIs incorporating values from the instance.
175-
<cref>
176-
"id" probably should not normally be a required keyword, since new instances
177-
will have an unknown "id" property until is it assigned by the server.
178-
However, this property is used in a link, and without it, multiple different
179-
instances would be given the same rel=self URI!
180-
</cref>
181175
</postamble>
182176
</figure>
183177

@@ -542,18 +536,23 @@
542536

543537
<section title="Missing values" anchor="missingValues">
544538
<t>
545-
Sometimes, the appropriate values will not be available.
546-
For example, the template might specify the use of object properties,
547-
but no such data was provided (or "hrefSchema" is not present), and the
548-
instance is an array or a string.
539+
Sometimes, the appropriate values will not be available. In many
540+
cases, the URI Template behavior of simply removing varibles that
541+
do not have a value will be appropriate. An example of this is
542+
optional query parameters, the presence or absence of which does
543+
not change the nature of the link relation type.
549544
</t>
550545

551546
<t>
552-
If any of the values required for the template are neither present in
553-
the user agent data (if relevant) nor the JSON instance, then substitute
554-
values MAY be provided from another source (such as default values).
555-
Otherwise, the link definition SHOULD be considered not to apply to the
556-
instance.
547+
However, some variables, such as an identifier used in a path component,
548+
cannot meaningfully be omitted. The resulting URI would be meaningless,
549+
or would require a different link relation type. While "hrefSchema" can
550+
express a requirement for those variables that can be supplied via input,
551+
some variables must be resolved from instance data. When that instance
552+
data is not required by the context schema, the
553+
<xref target="hrefRequired">"hrefRequired</xref> keyword may be used to
554+
indicate that when the instance data is not available, the link does
555+
not apply.
557556
</t>
558557
</section>
559558
</section>
@@ -607,7 +606,8 @@
607606
"hrefPointers": {
608607
"rootId": "/id",
609608
"parentId": "2/id"
610-
}
609+
},
610+
"hrefRequired": ["parentId"]
611611
}
612612
]
613613
}]]>
@@ -659,14 +659,8 @@
659659
</t>
660660
<t>
661661
For the root node, the relative pointer for the parent doesn't point
662-
to anything. As noted under
663-
<xref target="missingValues">missing values</xref>, such a link should
664-
simply be ignored.
665-
<cref>
666-
GitHub issue #49 tracks the question of distinguishing this situation
667-
of a missing required variable (common in path components) from
668-
missing optional variables (common in query string parameters).
669-
</cref>
662+
to anything, so <xref target="hrefRequired">"hrefRequired"</xref>
663+
prevents the link from being used with that node.
670664
</t>
671665
</section>
672666

@@ -761,6 +755,37 @@
761755
</t>
762756
</section>
763757

758+
<section title="hrefRequired" anchor="hrefRequired">
759+
<t>
760+
The value of this keyword MUST be an array, and the elements MUST be unique.
761+
Each element SHOULD match a variable in the link's URI Template, without
762+
percent-encoding. After completing the entire URI Template resolution
763+
process, if any variable that is present in this array does not have
764+
a value, the link MUST NOT be used.
765+
</t>
766+
<figure>
767+
<preamble>
768+
Here is a simplified version of the "up" link from the
769+
<xref target="hrefPointers">"hrefPointers</xref> tree example,
770+
modified to only use the parent identifier for its "href" template.
771+
While each individual node is required to have an "id" field, the
772+
"up" link uses the parent node's field, and the root node, by definition,
773+
does not have a parent node. Putting "parentId" in "hrefRequired" ensures
774+
that the "up" link is correctly unusable with the root node.
775+
</preamble>
776+
<artwork>
777+
<![CDATA[{
778+
"rel": "up",
779+
"href": "/nodes/{parentId}",
780+
"hrefPointers": {
781+
"parentId": "2/id"
782+
},
783+
"hrefRequired": ["parentId"]
784+
}]]>
785+
</artwork>
786+
</figure>
787+
</section>
788+
764789
<section title="rel" anchor="rel">
765790
<t>
766791
The value of the "rel" property indicates the name of the relation to the target

‎links.json

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,9 @@
2424
{ "$ref": "http://json-schema.org/draft-06/hyper-schema#" }
2525
]
2626
},
27+
"hrefRequired": {
28+
"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"
29+
},
2730
"rel": {
2831
"type": "string"
2932
},

0 commit comments

Comments
 (0)