FORMATS.org

Comparison of Hypermedia Message Formats

Form Controls / Actions

Format	href	name/id	title/caption	method	media-type	fields	schema	string template	structured template
HTML5	action=””			method=””	enctype=””	yes
halo	“href”	json key		“method”	“content-type”		“schema”	“template”
siren	“href”	“name”	“title”	“method”	“type”	“fields”
mason	“href”	json key	“title”	“method”	depends on type		“schemaUrl”		“template”
Collection+JSON	“href” (query)/current resource		“prompt”
Hydra	current resource	“@type”		“method”		“expects”: {“supportedProperty”}
Format	Name	Title	Type	Value
Siren	“name”		“type”	“value”
Collection+JSON	“name”	“prompt”		“value”
Hydra	“property”		“range”

HTML

W3C: HTML5 Forms

halo+json

Gist: A sketch of application/halo+json and application/halo+xml

{
  "_controls": {
    "widgetate": {
      "href": "/widget/{newID}",
      "method": "PUT",
      "content-type": "application/xml",
      "schema": null,
      "template": "<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"
    }
  }
}

Siren

Siren Home page

{
  "actions": [
    {
      "name": "add-item",
      "title": "Add Item",
      "method": "POST",
      "href": "http://api.x.io/orders/42/items",
      "type": "application/x-www-form-urlencoded",
      "fields": [
        { "name": "orderNumber", "type": "hidden", "value": "42" },
        { "name": "productCode", "type": "text" },
        { "name": "quantity", "type": "number" }
      ]
    }
  ]
}

Mason

{
  "@actions": {
    "is:delete-issue": {
      "type": "void",
      "href": "...",
      "method": "DELETE",
      "title": "Delete issue"
    }
  }
}

{
  "@actions": {
    // JSON action with schema reference
    "is:project-create": {
      "type": "json",
      "href": "...",
      "title": "Create new project",
      "schemaUrl": "..."
    },
    // JSON action with default template
    "is:update-project": {
      "type": "json",
      "href": "...",
      "title": "Update project details",
      "template": {
        "Code": "SHOP",
        "Title": "Webshop",
        "Description": "All issues related to the webshop."
      }
    }
  }
}

https://github.com/JornWildt/Mason/blob/master/Documentation/Mason-draft-1.md#actions

Collection+JSON

CJ does not have a form-like representation. It does allow resources to contain a “template”, which is really a list of form fields, and a client can use HTTP methods against the same endpoint to perform CRUD operations. In addition CJ provides “queries” for basic GET based operations.

{
  "template" :
  {
    "data" :
    [
      {"prompt" : STRING, "name" : STRING, "value" : VALUE},
      {"prompt" : STRING, "name" : STRING, "value" : VALUE},
      ...
      {"prompt" : STRING, "name" : STRING, "value" : VALUE}
    ]
  }
}

{
  "queries" :
  [
    {
      "href" : "http://example.org/search",
      "rel" : "search",
      "prompt" : "Enter search string",
      "data" :
      [
        {"name" : "search", "value" : ""}
      ]
    }
  ]
}

JSON-LD + Hydra

Example taken from this blog post

JSON-LD itself does not have form like controls, only linking. Hydra introduces an “operation” property for this purpose.

{
  "@context": [
    "http://www.w3.org/ns/hydra/core",
    {
      "@vocab": "https://schema.org/",
      "image": { "@type": "@id" },
      "friends": { "@type": "@id" }
    }
  ],
  "@id": "https://api.example.com/player/1234567890/friends",
  "operation": {
    "@type": "BefriendAction",
    "method": "POST",
    "expects": {
      "@id": "http://schema.org/Person",
      "supportedProperty": [
        { "property": "name", "range": "Text" },
        { "property": "alternateName", "range": "Text" },
        { "property": "image", "range": "URL" }
      ]
    }
  }
}