HAL is a simple format that gives a consistent and easy way to hyperlink between resources in your API.

Definitions

Definition Title Type Description
linkArray HAL Link Array array An array of linkObjects of the same link relation
linkObject HAL Link Object object An object with link information
embedded HAL Embedded Resource object An embedded HAL resource
embeddedArray HAL Embedded Array array An array of embedded resources with the same link relation

Schema

{
  "type": "object",
  "properties": {
    "_links": {
      "$ref": "#/definitions/links"
    },
    "_embedded": {
      "$ref": "#/definitions/embedded"
    }
  },
  "definitions": {
    "links": {
      "title": "HAL Links",
      "description": "Object of links with the rels as the keys",
      "type": "object",
      "additionalProperties": {
        "oneOf": [
          {
            "$ref": "#/definitions/linkObject"
          },
          {
            "$ref": "#/definitions/linkArray"
          }
        ]
      }
    },
    "linkArray": {
      "title": "HAL Link Array",
      "description": "An array of linkObjects of the same link relation",
      "type": "array",
      "items": {
        "$ref": "#/definitions/linkObject"
      }
    },
    "linkObject": {
      "title": "HAL Link Object",
      "description": "An object with link information",
      "type": "object",
      "properties": {
        "name": {
          "$ref": "http://hyperschema.org/core/base#/definitions/name"
        },
        "href": {
          "anyOf": [
            {
              "$ref": "http://hyperschema.org/core/link#/definitions/href"
            },
            {
              "$ref": "http://hyperschema.org/core/link#/definitions/hrefTemplated"
            }
          ]
        },
        "templated": {
          "$ref": "http://hyperschema.org/core/link#/definitions/isTemplated"
        },
        "type": {
          "$ref": "http://hyperschema.org/core/base#/definitions/mediaType"
        },
        "deprecation": {
          "$ref": "http://hyperschema.org/core/link#/definitions/isDeprecated"
        }
      },
      "required": [
        "href"
      ]
    },
    "embedded": {
      "title": "HAL Embedded Resource",
      "description": "An embedded HAL resource",
      "type": "object",
      "additionalProperties": {
        "oneOf": [
          {
            "$ref": "#"
          },
          {
            "$ref": "#/definitions/embeddedArray"
          }
        ]
      }
    },
    "embeddedArray": {
      "title": "HAL Embedded Array",
      "description": "An array of embedded resources with the same link relation",
      "type": "array",
      "items": {
        "$ref": "#"
      }
    }
  }
}

Example Message

{
  "_links": {
    "self": {
      "href": "/orders"
    },
    "curies": [
      {
        "name": "ea",
        "href": "http://example.com/docs/rels/{rel}",
        "templated": true
      }
    ],
    "next": {
      "href": "/orders?page=2"
    },
    "ea:find": {
      "href": "/orders{?id}",
      "templated": true
    },
    "ea:admin": [
      {
        "href": "/admins/2",
        "title": "Fred"
      },
      {
        "href": "/admins/5",
        "title": "Kate"
      }
    ]
  },
  "currentlyProcessing": 14,
  "shippedToday": 20,
  "_embedded": {
    "ea:order": [
      {
        "_links": {
          "self": {
            "href": "/orders/123"
          },
          "ea:basket": {
            "href": "/baskets/98712"
          },
          "ea:customer": {
            "href": "/customers/7809"
          }
        },
        "total": 30,
        "currency": "USD",
        "status": "shipped"
      },
      {
        "_links": {
          "self": {
            "href": "/orders/124"
          },
          "ea:basket": {
            "href": "/baskets/97213"
          },
          "ea:customer": {
            "href": "/customers/12369"
          }
        },
        "total": 20,
        "currency": "USD",
        "status": "processing"
      }
    ]
  }
}