Skip to content

Commit 7462c53

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 54d22c2 commit 7462c53

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
@@ -170,12 +170,6 @@
170170
<postamble>
171171
This example schema defines the properties of the instance as well as link
172172
relations for the instance, with URIs incorporating values from the instance.
173-
<cref>
174-
"id" probably should not normally be a required keyword, since new instances
175-
will have an unknown "id" property until is it assigned by the server.
176-
However, this property is used in a link, and without it, multiple different
177-
instances would be given the same rel=self URI!
178-
</cref>
179173
</postamble>
180174
</figure>
181175

@@ -540,18 +534,23 @@
540534

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

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

@@ -759,6 +753,37 @@
759753
</t>
760754
</section>
761755

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