A few suggestions

[evert]

I'm just looking to implement this. I have a few different thoughts and suggestions.

Happy to open separate issues for these too.

1. Add title to forms. title is useful for generating user interfaces. e.g.: "Create customers".
2. Rename "displayText" to "title" or "label" in fields. "title" is more consistent with HAL link titles, and "label" is more consistent with HTML5.
3. Speaking of HTML5, have you considered to just use all the HTML5 attributes verbatim? It's a great standard, and you'd make it super easy to turn hal-forms into html forms. Why reinvent the wheel?

The last one is a bit more drastic.

I noticed that hal-forms have a _links object to define the target. This made me think: is it a good idea that there's a second _links object, and what is specifically it's meaning?

If a link is a relationship between two documents, this gets a bit confusing because the form is not really it's own resource/document?

Thinking about this more, it made me feel that the best model might actually be to limit the amount of forms per resource to exactly one, so the "target" link can just appear in the top-level _links object.

This sounds limiting, but there's already a mechanism to get multiple resources appear in 1: using _embedded. I would suggest to avoid duplicating the functionality that _embedded already provides and keep resources small and focused.

[pezra]

These are interesting ideas. I'd support the addition of an optional title to forms.

The others i am more skeptical of. I prefer label to displayText but the benefit is not worth introducing a breaking change. The HTML5 input types list is large. Perhaps larger than necessary for APIs? It would also introduce breaking changes which i'm not sure is worth it.

Regarding the target link, I don' t love that the target url is in an _links section that will never contain anything else. I would very much prefer the target url be specified as href (allowing a form to be an extension of a link object) or a target_href. However, either of those would be a breaking change. I am not sure the benefit is worth the cost.

I strongly oppose the idea that of having just one form per representation. It would be possible to implement a form system on top of _embedded (A form rel with different names for each form. The bodies could look exactly like the current form object.) However, that is not the approach this spec takes. Adopting that approach would require breaking changes and i doubt the benefit is worth the cost.

If you haven't noticed i think breaking changes are the mortal sin for APIs. 😄 I'm ok with almost anything else. However, I am not the author or maintainer of this spec so that is just one guy on the internet's opinion.

@evert, If you want pursue these ideas i'd suggest submitting a PR. @jareddellitt, et al, are really good about refining and merging PRs.

[pezra]

One option for avoiding most of the breaking changes would be to make supporting the current approach a "SHOULD". It adds complexity to clients that want to fully support the spec but it does provide a way to improve the spec over time. Having a pattern for improving the spec in dramatic ways is probably a good thing.

[evert]

Hi @pezra ,

The reason I felt comfortable voicing these ideas is because the status of this specification is draft and the version is 0.0.2. Generally this signals that drastic changes are still accepted.

[travi]

i think avoidance of the html5 attributes was actually intentional, so that this spec was not too closely tied to only web applications.

personally, i still lean in that direction so that controls of non-web consumers are not unintentionally made more difficult by assuming that the html5 controls exist in similar ways on other platforms.

also, keep in mind that we wouldn't want to have an api that is overly prescriptive of rendering for things like value-groups when the choice between even the web options of radio-buttons, checkboxes, selection-box, etc may depend on how the consumer intends to present the experience to their users.