Siren is a hypermedia specification for representing entities, offering structures to communicate information about entities, actions for executing state transitions, and links for client navigation.

Definitions

Definition Title Type Description
entities Siren Entity Array array Array of Siren entities
actions Siren Actions Array array Array of Siren actions
action Siren Action object Siren Action
fields Siren Fields Array array Array of Siren fields
field Siren Field object Siren Field

Schema

{
  "properties": {
    "class": {
      "$ref": "http://hyperschema.org/core/base#/definitions/classes"
    },
    "properties": {
      "$ref": "http://hyperschema.org/core/properties#/definitions/propertyObject"
    },
    "entities": {
      "$ref": "#/definitions/entities"
    },
    "actions": {
      "$ref": "#/definitions/actions"
    },
    "links": {
      "$ref": "#/definitions/links"
    }
  },
  "definitions": {
    "entities": {
      "title": "Siren Entity Array",
      "description": "Array of Siren entities",
      "type": "array",
      "items": {
        "$ref": "#"
      }
    },
    "actions": {
      "title": "Siren Actions Array",
      "description": "Array of Siren actions",
      "type": "array",
      "items": {
        "$ref": "#/definitions/action"
      }
    },
    "action": {
      "title": "Siren Action",
      "description": "Siren Action",
      "type": "object",
      "properties": {
        "name": {
          "$ref": "http://hyperschema.org/core/base#/definitions/name"
        },
        "title": {
          "$ref": "http://hyperschema.org/core/base#/definitions/title"
        },
        "method": {
          "$ref": "http://hyperschema.org/protocols/http#/definitions/method"
        },
        "href": {
          "$ref": "http://hyperschema.org/core/link#/definitions/href"
        },
        "type": {
          "$ref": "http://hyperschema.org/core/base#/definitions/mediaType"
        },
        "fields": {
          "$ref": "#/definitions/fields"
        }
      }
    },
    "fields": {
      "title": "Siren Fields Array",
      "description": "Array of Siren fields",
      "type": "array",
      "items": {
        "$ref": "#/definitions/field"
      }
    },
    "field": {
      "title": "Siren Field",
      "description": "Siren Field",
      "type": "object",
      "properties": {
        "name": {
          "$ref": "http://hyperschema.org/core/fields#/definitions/name"
        },
        "type": {
          "$ref": "http://hyperschema.org/mediatypes/html#/definitions/type"
        },
        "value": {
          "$ref": "http://hyperschema.org/core/fields#/definitions/value"
        }
      }
    },
    "links": {
      "title": "Siren Links Array",
      "description": "Array of Siren links",
      "type": "array",
      "items": {
        "$ref": "#/definitions/link"
      }
    },
    "link": {
      "title": "Siren Link",
      "description": "Siren Link",
      "type": "object",
      "properties": {
        "rel": {
          "$ref": "http://hyperschema.org/core/link#/definitions/rels"
        },
        "href": {
          "$ref": "http://hyperschema.org/core/link#/definitions/href"
        }
      }
    }
  }
}

Example Message

{
  "class": [
    "order"
  ],
  "properties": {
    "orderNumber": 42,
    "itemCount": 3,
    "status": "pending"
  },
  "entities": [
    {
      "class": [
        "items",
        "collection"
      ],
      "rel": [
        "http://x.io/rels/order-items"
      ],
      "href": "http://api.x.io/orders/42/items"
    },
    {
      "class": [
        "info",
        "customer"
      ],
      "rel": [
        "http://x.io/rels/customer"
      ],
      "properties": {
        "customerId": "pj123",
        "name": "Peter Joseph"
      },
      "links": [
        {
          "rel": [
            "self"
          ],
          "href": "http://api.x.io/customers/pj123"
        }
      ]
    }
  ],
  "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"
        }
      ]
    }
  ],
  "links": [
    {
      "rel": [
        "self"
      ],
      "href": "http://api.x.io/orders/42"
    },
    {
      "rel": [
        "previous"
      ],
      "href": "http://api.x.io/orders/41"
    },
    {
      "rel": [
        "next"
      ],
      "href": "http://api.x.io/orders/43"
    }
  ]
}