halo_json_request.json

{
  "_links": {
    "self": { "href": "/foo" },
  },
  "_controls": {
    "attack": {
      "target": "/attacks",
      "method": "POST",
      "headers": {
        "Content-Type": "application/json"
      },
      "schema": { /*_json_schema_doc_here_*/ }
    }
  }
}

halo_xml_request.json

{
  "_links": {
    "self": { "href": "/" },
    "example": { "href": "/example" }
  },
  "_controls": {
    "widgetate": {
      "target": "/widget/{newID}",
      "method": "PUT",
      "headers": {
        "Content-Type": "application/xml"
      },
      "body": "<widget>\\n <name>{{name}}</name>\\n\\n <blobs>\\n {{#blobs}}\\n <blob>\\n {{#first}}\\n <first>true</first>\\n {{/first}}\\n <contents>{{contents}}</contents>\\n </blob>\\n {{/blobs}}\\n </blobs>\\n\\n {{#is_empty}}\\n <note>This is an empty widget</note>\\n {{/is_empty}}\\n</widget>\\n"
    }
  }
}

only required properties of a control object are target and method

the body string is mustache by default, would have "template_type" property to specify a different templating type

• 'target' is already a pretty well-known attr in the html world, and it generally means the 'window' to run the request through. Why not 'href' or 'action'?
• Do you really need to be able to specify all headers? or just content-type? Why not just have a 'type' attribute like link nodes in other formats, or 'enc-type' like HTML forms already have?
• I'm not a huge fan of mustache templates for XML (or any templates really), but I don't use XML on a regular basis anyway so I'll abstain from commenting on that.
• "_controls" might be a better name than "_forms". I'd have to think about that. My only reservation is probably that 'links' are a kind of 'control' as well when you think about it.

I can't believe how close this is to what I was looking for form-wise. Very nice. :) I thought people would think I was crazy with the json schema idea.

• I'm not too fussed about what we call things, so we could change target to href if people thought that was a big deal
• Yes we do need this, the headers are part of the template and use mustache like the body. This is so that servers can control all elements of the client request.
• Templates seemed like an easy way to support non-json representations. Mustache in a simple, logicless templating language with relative comprehensive programming language coverage. There are encodings challenges that need some careful thought. @tef might be able to help us figure that out.
• Again, what we call things doesn't bother me that much really. I think I chose controls because it is a little bit more descriptive and avoids conflation with a notion of a GUI "form".

Yeah, great minds and all that! ;)

If you haven't already, you should get yourself on the hal-discuss list: https://groups.google.com/group/hal-discuss

I think that by adding a "method" property and a "render" property on a link, you can completely do away with the concept of controls. The method property is obvious, but the render would be a URI to a HAL response that is a template for the request. Not human readable (use profile for that). But a link to a template. This could conceivably be ala code on demand for a javascript agent or include validators and other metadata for other types of clients. It decouples the control from the response, uses client side caching for performance, and allows it all to be done in the context of an existing link.

The headers and body and whatever else would then be controlled by the server and in a M2M world give you all you need.

You could get double duty out of render because you could use 'embedded' to indicate that link is embedded in the response. You use 'related' indicate a related resource not embedded. render would be optional and assume 'link'. Only if render was a URI, would it be a template.

And this is much lighter than embedding redundant _controls all over the place (e.g. in embedded order elements of your orders resource) or wonky top-level conventions.

JSON Hyper-Schema looks like it includes nearly everything in the _controls example above. Notably, it specifies encType and mediaType rather than arbitrary headers.