Links Object Clarification Needed

When reading the definition of the links object (, the documentation seems to suggest that only 2 link names are permitted (self and related) since it says you may define more later, but it isn’t explicit
as to how custom links may be defined. If we understand the spec correctly, this means “self” and “related” are
the only links we can specify. Each link may refer to exactly one URL and one URL only. Is this the right interpretation?

Right now, yes, that’s correct. But very shortly, custom links will be allowed with a full mapping to RFC 5988. See here and check out some of the linked issues for the backstory.

@ethanresnick Is this still true at the moment? Asking because the JSON Schema doc linked from the FAQ could restrict the contents of “links”, but doesn’t, so something like this validates:

  "data": {
    "type": "whatever",
    "id": "whatever"
  "links": {
    "custom": {
      "href": ""

That’s a limitation of the JSON Schema; I understand work is being done on a stricter schema.