Skip to content

Control link applicability with "hrefRequired" #404

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Sep 26, 2017
Merged

Control link applicability with "hrefRequired" #404

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
2979d0f
Control link applicability with hrefRequired
handrews Sep 13, 2017
77df9df
Better meta-schema, fix typo.
handrews Sep 14, 2017
9a1d8ed
hrefRequired meta-schema should have uniqueItems
handrews Sep 19, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
73 changes: 49 additions & 24 deletions jsonschema-hyperschema.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -172,12 +172,6 @@
<postamble>
This example schema defines the properties of the instance as well as 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>

Expand Down Expand Up @@ -542,18 +536,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 variables 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>
Expand Down Expand Up @@ -607,7 +606,8 @@
"hrefPointers": {
"rootId": "/id",
"parentId": "2/id"
}
},
"hrefRequired": ["parentId"]
}
]
}]]>
Expand Down Expand Up @@ -659,14 +659,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>

Expand Down Expand Up @@ -761,6 +755,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
Expand Down
7 changes: 7 additions & 0 deletions links.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,13 @@
{ "$ref": "http://json-schema.org/draft-06/hyper-schema#" }
]
},
"hrefRequired": {
"type": "array",
"items": {
"type": "string"
},
"uniqueItems": true
},
"rel": {
"type": "string"
},
Expand Down