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

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.