IMHO, the wording on how relationships can be specified via linkage objects is not quite clear. Are the listed attributes (type, id, data) the only ones allowed in specifying the relationships, or custom attributes of relationships can be listed as well?

An example of a relationship with attributes: suppose that we have a tree of directories and files in a Unix filesystem, and that we need to describe two kinds of relationships between them: direct descendance (file or subdirectory belonging to a directory) and symlink. Does the spec allow to do it by including a custom attribute directly with the linkage object? I believe that meta is unsuitable for this because it describes relationship as a whole and not its specific members.

Specifically, is the example below compliant?

{
  "type": "directories",
  "id": "12",
  "name": "usr",
  "links": {
    "descendants": {
      "data": [{
        "type": "directories",
        "id": "34",
        "kind": "direct"
      },{
        "type": "directories",
        "id": "56",
        "kind": "symlink"
      },{
        "type": "files",
        "id": "78",
        "kind": "symlink"
      }]
    }
  }
}

To allow this explicitly, I propose to change the wording in the specification of linkage as follows (proposed addition is italicized):

• Linkage to other resource objects ("object linkage") included in a compound
  document. This allows a client to link together all of the resource objects
  included in a compound document without having to GET one of the
  relationship URLs. Linkage MUST be expressed as:

  • type and id members for to-one relationships. type is not required
    if the value of id is null.
  • type and id members for homogeneous to-many relationships. type is
    not required if the value of id is an empty array ([]).
  • A data member whose value is an array of objects each containing type
    and id members for heterogeneous to-many relationships.

  In all three cases, other members can be OPTIONALLY included alongside type and id
  to describe custom attributes of a relationship.

• A "meta" member that contains non-standard meta-information about the
  relationship.

Also, I think that the "complete example document with multiple included relationships" should be extended to include the illustration of data linkage.

Any chance to still consider this before the spec hits 1.0?
I would be glad to promptly provide a PR for both proposed changes.