halo+json in action: http://halform.herokuapp.com/

example.halo.json

{
  "_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"
        }
      }
    }
  }
}

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!