{
"_links" : { … },
"name" : "…",
"other-values" : [
{ … }, …
],
"_templates" : {
"default" : {
"properties" : {
"department" : {
"suggest" : {
"resource" : {
"href" : "/departments{?q}",
"templated" : true
},
// alternative to
"values" : [
{ "title" : "Some department", "id" : 4711, "_links" : { … } },
{ "title" : "Some other department", "id", : 4712, "_links" : { … } }
],
// alternative to
"embedded" : "other-values" | "$.other-values",
// in any case…
"prompt-ref" : "title",
"value-ref" : "id" | "$._links.self",
"selected-ref" : "id" | "$._links.self"
}
}
}
}
}
}
- One of
values
,resource
,embedded
as defined below.values
-- The presence of thevalues
attribute indicates that clients are supposed to choose from the values described in that array. They can either be scalar values or documents. If they are documents,prompt-ref
andvalue-ref
(see below) allow extracting properties from the objects for display and submission purposes.resource
-- The presence of theresource
attribute indicates that the values to choose from are available from the nested HAL link object. Clients follow the link expanding the URI template and treat the result as if it were listed asvalues
directly.embedded
-- The presence of theembedded
indicates that the collection of values to choose from is available in the original HAL document. The attribute value is either a field reference or JSON Path expression.
prompt-ref
-- (optional) selects a prompt from the elements of the values to choose from. Is interpreted as JSON Path if it starts with$
.value-ref
-- (optional) names the field to be submitted as value for the property. Is interpreted as JSON Path if it starts with$
. If the property is not set and the values are objects, we use theself
link contained in object.selected-ref
-- (optional) names the field of the original document that the value obtained fromvalue-ref
is supposed to be compared to determine whether a value is supposed to be considered selected. If the attribute is not defined, none of the values to choose from is supposed to be selected.
i'd like to see how JSONPath would be used here and whether we need to indicate the diff between field and path-to-field. imagine a form for allowing people to select one or more JSONPath values to store in the database!
If a prompt-ref
/value-ref
starts with a $
, clients are supposed to interpret those as JSON Path expression to be applied to the individual objects listed in values
or retrieved by following the resource
link.
If the values were a list of JSON Path expressions, prompt-ref
and value-ref
would just be omitted and the values would be used as is.
If they were documents, the JSON Path expression would be evaluated against the document:
{
"values" : [
{ "someExp" : "$.some.jsonpath.expression" },
…
],
"value-ref" : "$.someExp"
}
In this case, the client would resolve $.someExp
against the provided document and end up with $.some.jsonpath.expression
to be submitted eventually.
In this particular case, a plain someExp
used for value-ref
is essentially a shortcut for $.someExp
.
i suspect we need to sort out where embedded data "lives" (HAL doc, HAL-FORMS doc)
I was assuming the HAL document. The more I think about it, the harder it is for me to find a good example for when this might make sense. I'd even be fine we start without it, if noone else comes up with a good example.
think we need to indicate if the href value is templated (templated="true" seems the right approach)
Applied by switching to resource
for that case and requiring that to be a HAL link.
do clients then sort for display?
I'd assume clients can sort whatever they eventually resolve the prompt to the way they want (sorting alphabetically seems like a decent suggestion).
finally, why is there a _links element in your values example above?
Because essentially the documents in values
can be (should be?) valid HAL documents.
If they're representations of resources, a natural way to identify them is via their URI.
And resorting to identifiers makes a good default when sending values to the server, no?
The selected criteria
See selected-ref
.