Link Relation Types

Links express a relation between the resource they appear on (the link context), and the link target. The link relation type (RFC8288 Sec 3.3) determines the kind of relation between the link context and the link target.

Next to the standard link relation types, which are to be interpreted with their standardized meaning, ContentGrid defines following extension link relation types:

Link relation type	Description
`https://contentgrid.cloud/rels/contentgrid/relation`	Refers to a ContentGrid relation of the entity-item. The link’s `name` attribute is the relation name
`https://contentgrid.cloud/rels/contentgrid/content`	Refers to the binary content of a content attribute. The link’s `name` attribute is the content attribute name
`https://contentgrid.cloud/rels/contentgrid/entity`	Refers to a ContentGrid entity (from a root resource entities-root and profile-root). The link’s `name` attribute is the entity name

CURIEs

CURIEs (Compact URIs) are a shorthand notation for extension link relation types.

They are used as defined in the HAL specification. The curies link relation provides expansion templates.

Before comparing a link relation, a CURIE must be expanded into the full URI.

Formal definition of CURIE expansion

Since the HAL specification does not formally specify how CURIEs should be expanded, a definition is given here.

A safe_curie or a curie MAY be used as an extension link relation type. They MUST be expanded to a URI to obtain the formal extension link relation type and SHOULD NOT be used as-is.
A CURIE consists of a prefix and a reference, separated by a colon (:). In the context of HAL; the CURIE MUST have a prefix, and the reference MUST also be an NCName.
```
safe_curie := '[' curie ']'
curie := prefix ':' reference
prefix := NCName
reference := NCName
```
The curies links:
1. MUST have a name link attribute, which is the CURIE prefix.
2. MUST be a URI template, which MUST end in a variable named rel. (e.g.: http://example.com/relations/{rel}) The CURIE is expanded by expanding the URI template with the rel variable set to the CURIE reference.
Expansion of a CURIE to a URI begins at the HAL Resource object that contains the particular link relation
1. If a curies link relation is present with its name attribute equal the CURIE prefix, this link relation is used for expanding the CURIE to an URL
2. Else, the parent HAL Resource object is consulted using the same algorithm.
3. If the top-level HAL Resource object was reached without finding a link relation for the CURIE, expansion has failed. An error SHOULD be reported, and the link relation MUST be ignored for all purposes.

A HAL resource using CURIEs

{
  [...]
  "_links": {
    "self": {
      "href": "https://example.com/users/123"
    },
    "cg:content": [
      {
        "name": "profile_picture",
        "href": "https://example.com/users/123/picture"
      }
    ],
    "https://contentgrid.cloud/rels/contentgrid/relation": [
      {
        "name": "friends",
        "href": "https://example.com/users/123/friends"
      }
    ],
    "[example:curied-link]": {
      "href": "https://example.com/dahl-curry"
    },
    "unregistered:curie": {
      "href": "https://example.com/unregistered-curie"
    },
    "curies": [
      {
        "name": "cg",
        "href": "https://contentgrid.cloud/rels/contentgrid/{rel}",
        "template": true
      },
      {
        "name": "example",
        "href": "https://example.com/relations/{rel}",
        "template": true
      }
    ]
  }
}

This is equivalent to the following resource when CURIEs are expanded:

{
  [...]
  "_links": {
    "self": {
      "href": "https://example.com/users/123"
    },
    "https://contentgrid.cloud/rels/contentgrid/content": [
      {
        "name": "profile_picture",
        "href": "https://example.com/users/123/picture"
      }
    ],
    "https://contentgrid.cloud/rels/contentgrid/relation": [
      {
        "name": "friends",
        "href": "https://example.com/users/123/friends"
      }
    ],
    "https://example.com/relations/curied-link": {
      "href": "https://example.com/dahl-curry"
    }
  }
}

IANA-registered link relation types and URI-based extension link relatinos are passed through as-is.
CURIEs and Safe CURIEs are expanded based on the URI templates of the curies links
CURIEs using unknown prefixes are completely ignored