Multi-link link relations

HAL resources are JSON documents with a number of properties and a _links section with link relations to other resources. There are two types of link relations:

  1. single-link link relations

  2. multi-link link relations

Single-link link rel

A single-link link relation has exactly one link behind it. A good example is the aa:time-based link relation in an aa:asset resource. It’s used to query the time-based Metadata for an asset. There’s one link to get that, not multiple ones. A single-link link relation like aa:time-based has a JSON object as value with the link definition. Example:

{
  "_links": {
    "aa:time-based": {
      "href": "https://host/..."
    }
  }
}

Multi-link link rel

A multi-link link relation can have multiple links behind it. A good example is the loc:item link relation in an loc:collection resource. It’s used to query the items in the collection of a folder. There can be zero, one, or multiple entries. If there are zero entries, then the result will not contain the loc:item link rel at all. If there are one or more entries, the link relation also contains one or multiple entries. In any case, the value is always a JSON array of JSON objects, even if there’s only one entry.

Example of a multi-link link rel with one link:

{
  "_links": {
    "loc:item": [
      {
        "href": "https://host/..."
      }
    ]
  }
}

Example of a multi-link link rel with one link:

{
  "_links": {
    "loc:item": [
      {
        "href": "https://host/..."
      },
      {
        "href": "https://host/..."
      },
      {
        "href": "https://host/..."
      }
    ]
  }
}

Usage

If a link rel is a single-link or multi-link link rel depends on the resource in which it is used. Example:

  • aa:asset is a single-link link rel when it appears in an aa:attributes resource. Here, the link rel is used to navigate to the asset that owns this aa:attributes resource.