Skip to content

Instantly share code, notes, and snippets.

Embed
What would you like to do?
halo+json in action: http://halform.herokuapp.com/
{
"_links":{
"self":{
"href":"/users"
}
},
"_forms":{
"create-user":{
"title":"Create a new widget",
"description":"Enter your widget info and submit to create a new widget",
"target":"/widgets/{id}",
"method":"POST",
"headers":{
"Content-Type":"application/json"
},
"fields":{
"name":{
"type":"Text",
"validators":[
"required"
]
},
"email":{
"type":"Text",
"validators":[
"required",
"email"
]
},
"age":{
"type":"Number"
},
"homepage":{
"type":"Text",
"dataType":"url",
"validators":[
"url"
]
},
"password":{
"type":"Password"
},
"likes":{
"type":"Checkboxes",
"options":[
"Computers",
"Combat",
"Cats"
]
},
"ninja":{
"type":"Hidden",
"value":"This is a hidden field"
},
"size":{
"type":"Select",
"options":[
"large",
"small"
]
},
"has_answer":{
"type":"Radio",
"options":[
"yes",
"no",
"wtf"
]
},
"dob":{
"type":"Date"
},
"favourite_datetime":{
"type":"DateTime"
},
"things_to_do_before_death":{
"type":"List"
}
}
}
}
}
@besquared
Copy link

besquared commented Jul 16, 2013

I want to add a few comments here as well as my own thinking.

First of all I want to advocate thinking about forms as a kind of resource separate from the resource defined in the hypermedia document in question. This is the concept proposed in http://tools.ietf.org/html/rfc6861. The outline presented there seems pretty sensible to me. Under those semantics you don't need a separate _forms key on the top level object to hold the create and editor form and you don't have to attach the name of the entity into the key as you can give it a standardized name. Instead you now either simply include 'create-form' and 'edit-form' in the _links or more likely in the _embedded section of the hypermedia document.

{
  "_links":{
    "self":{
      "href":"/users"
    }
  },
  "_embedded": {
    "create-form": {
        "href": "/users", ...
    },
    "edit-form": {
      ....
    }
  }
}

Secondly I think the goal of these forms particularly with response to HAL which is much more akin to a serialization format than a full hypermedia representation should be a lot less specific to HTML and lot more true to the resource itself. I think you start with the resource's data model and then add in optional display or html specific information. I don't have an example just yet but I'll work on something.

To be a little more specific the "type" attribute of each field shouldn't represent the UI element to be displayed but the type of data that the server reasonably expects to receive as well as potentially a set of options for that field. An additional property should be used to identify UI style hints such as checkbox, radio, select, etc. I don't know what this property should be named.

@nesterone
Copy link

nesterone commented Jul 26, 2013

Hi, All

What about to use json-schema to describe form's field?

Json-schema has a 'dafault' value which can be pre-filled by the server.

The advantages which I see is using a some common format to describe forms an json-schema seems very good for this task.

@CharlotteGore
Copy link

CharlotteGore commented Nov 4, 2013

We're actually doing a client for a hypermedia API (hal) that's got its own custom version of controls (the application makes very heavy use of forms to manipulate hypermedia documents) and it's become apparent that what we have isn't really working properly. We've experimented with just having JSON representations of forms (heavily or lightly abstracted from HTML) and these have been incredibly brittle and limiting.

Our latest thinking on what we should be doing is https://gist.github.com/CharlotteGore/7302318

For us the core of a hypermedia _controls control is just the information required for a system to basically instantly do an HTTP request without any user input required at all.

So, in our version of this spec, we have properties which contain basically key value pairs representing the form data and their initial values, a method and an action. From this an AJAX request can be generated by a machine irrespective of how what representation this might have in the client.

In addition to this, and entirely optional, we then have a separate schema that gives the machine additional information about each input. This should primarily be for validation -- we've tried to use the same 'validators' seen here -- but this metadata could conceivably be used to generate appropriate forms in a client as a handy side effect - for example a HALO Browser. In our particular use case, generating forms automatically is very important but that's because we don't currently care what these forms look like, so this seems like a 'nice to have'.

Finally we've got the order of fields as another optional piece of metadata. I think this is borrowed from JSON schema. I suppose if a server insisted on parameters appearing in a certain order then this could be justified but it seems, to be honest, you'd expect form field order to come from a view rather than the hypermedia. This probably shouldn't be part of a spec as such.

We really don't want to be putting XML templates or actual HTML forms in the hypermedia if we can avoid it. Ideally it should be trivial to generate a valid _controls control just from a server side model if possible!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment