hal-forms-suggestions.md

Suggestions for HAL FORMS

{
  "_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 the values 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 and value-ref (see below) allow extracting properties from the objects for display and submission purposes.
  • resource -- The presence of the resource 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 as values directly.
  • embedded -- The presence of the embedded 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 the self link contained in object.
• selected-ref -- (optional) names the field of the original document that the value obtained from value-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.

Questions that were to be answered

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.