Hyper-schema: Alternative forms for listing link relationships

[awwright]

For a variety of cases, it's often simpler to use:

{
links: { "self": { href:"/document/{id}" } }
}

or:

{
links: { "stylesheet": [ {href:"style.css"}, {href:"base.css"} ] }
}

HAL and other JSON-based hypermedia formats follow a similar convention.

[handrews]

I'm definitely in favor of this. I always have to translate the links into something like this inside code anyway because searching a list for the right rel value is really awkward.

[slurmulon]

I only see one minor downside to this, and it's consistency in a different sense - when links can only be an Array, you don't have to check for special cases (like is it an Object instead). This should be generally considered in the user's Hyper-Schema library that parses LDOs and the user should not have to worry about it at all, but I honestly don't even know of a Hyper-Schema library that does this (for instance, I had to write my own LDO parser because I couldn't even find a Hyper-Schema library for looking up or parsing LDOs)

[slurmulon]

My minor concern also applies to rel - in one case it's the LDO's key, in another case it will be defined in rel. This makes writing parsers more difficult and bug prone, but I think it's just a consideration that people should be aware of. Until is a more robust JSON Hyper-Schema consumer library that provides a simple API for finding and resolving LDOs is available, the user will always have to consider these complications themselves.

[handrews]

My minor concern also applies to rel - in one case it's the LDO's key, in another case it will be defined in rel. This makes writing parsers more difficult and bug prone

No, rel is always the key. It's never in the LDO as written out. The only cases to handle are whether there is one LDO attached to rel (the value is an object) or several (the value is an array of LDO objects). This can be normalized as the hyper-schema is read in.

[handrews]

Having given this some thought and looked at other media types more, I think I am reluctantly against this.

• RFC 5988 allows multiple space-separated "rel"s per link. While we could use keys with space-separated URI references, that's much more awkward than allowing a JSON array for a "rel" keyword in the LDO
• URI templating for "rel" as requested in #56 is a really useful feature that would be much easier to manage if "rel" is kept separate (this allows us to potentially use a "relVars" in the manner of "hrefVars" and "baseVars" from Eliminate template pre-processing #142 if it is accepted)

It's easy enough to internally parse things into a dict but, at least based on RFC 5988 link-to-rel is a many-to-many relationship and the current LDO format is better for that.

[Relequestual]

Sorry. LOD?

[handrews]

@Relequestual LDO == Link Description Object, a.k.a. the elements of the "links" array.

[Relequestual]

Right. I understand what an LDO is now. yay.

I'm struggling to work out what problem this issue is raising or trying to solve. Could the problem be rephrased with a clear problem statement, with an explanation of the suggested fix please?

[handrews]

@Relequestual The "links" keyword takes an array of LDOs because some link relation types allow a greater cardinality than 1. For instance, you may have many links of relation "stylesheet" because you are applying styles from multiple sources. You may have many links of relation "type" because your resource instantiates multiple types. etc.

At first glance, an array looks difficult to work with. If the link relation name is the important thing about finding which link to use, why not just make it an object keyed by link relation name? I think everyone starts out looking at the "links" keyword asking that- I know I and my colleagues on my last project did.

We were thinking of link types that were designed to appear only once, or if they did appear multiple times, each link was anchored to a separate point in the JSON representation (for example, representing a collection as an array of ids, and associating an "item" link with each id- there are many "item" links, but they just need to be specified once in the schema).

So I feel strongly that while using link relation names as a key seems nice at first, it is a trap and we should stick with the existing list approach. Otherwise, we need to do annoying things like have each link relation name take either an LDO or a list of LDOs (annoying to process) or make each link name map to a list of LDOs, even if that list often only has one LDO in it (annoying on general principle).

Does that help?

[Relequestual]

OK. Thanks for the explanation.

Unless we can get some reasoning from the other projects as to why they chose to do it that way, and why they consider it's preferable to our current approach, I'm against making this change. Following the crowd is sometimes the way to go, but only if there is valid reason beyond simply following for followings sake.

[handrews]

I've since come around to the array approach. It more closely matches formats such as HTTP's link header.

The main argument I can see in favor of the object approach is that most of the situations involving multiple links with the same relation type are handled by URI templating for us.

However, if an application wanted to generate an LDO list at runtime that is already fully resolved, then having it be in list format would make it easy to produce such a thing.

I'd like to make a decision on this one way or another, as it's a pretty fundamental thing for parsers to work with.

@awwright or anyone else still want to advocate for this change?