Specification of the shaf-form media type profile

shaf-form.md

The shaf-form media type profile

This profile describes how a set of descriptors should be interpreted to turn a generic media type into a form (similar to HTML forms). For example, the HAL media type (application/hal+json) does not specify any semantics about forms, however we can add semantics about forms to a HAL document but providing a profile.

shaf-form descriptors

• method: The HTTP method used for submitting the form.
• href: The target uri that the form should be submitted to.
• name: A string used to indentify the form.
• title: A string used as title/label when showing the form in a user interface.
• type: The media type that must be set in the CONTENT-TYPE header when submiting the form.
• submit: A string used as label for the CallToAction (e.g. the submit button text).
• fields: An array of field descriptors. See below.

field descriptors

• name: A string that should be used as key for the field.
• type: A string specifying the possible values accepted by the field.
• title: A string used to present this field. If not present name may be used instead.
• required: A boolean specifying that the field must be given a value before the form is submitted.
• value: A prefilled value. Should be shown in a user interface and sent back on submission unless changed.
• hidden: A boolean specifying that the field should not be shown in a user interface.

Example:

Given the following form:

    "create-form": {
      "method": "POST",
      "name": "create-post",
      "title": "Create Post",
      "href": "/posts",
      "type": "application/json",
      "_links": {
        "self": {
          "href": "http://localhost:3000/posts/form"
        }
      },
      "fields": [
        {
          "name": "title",
          "type": "string",
        },
        {
          "name": "message",
          "type": "string",
        }
      ]
    },

A client should then present a user interface with the possiblity to fill in two fields accepting string values (if applicable the interface should be titled "Create Post"). The entered values should be mapped to the keys title resp. message. (The client may of course fill in the details itself whenever possible). When the form is to be submitted, the client constructs a json string with the keys and values and makes a POST request to http://localhost:3000/posts/form with the header Content-Type header set to application/json and the json string as body.

Using Curl, the form above could be submitted using:

curl -H "Content-Type: application/json" \
     -X POST \
     -d '{"title": "hello", "message": "world"}' \
     localhost:3000/posts