Disjoint resources with same relation in json-home documents

[jackfirth]

Say I have three completely different resources A, B, and C that are all described by some relation X (possibly a very general relation such as "hosts"). In a JSON Home document, there seems to be two ways to link to these resources:

• With a URI template as a Resource Template. This can easily be inappropriate, as the resources may have very different URI structures, supported formats, authentication hints, etc. etc.
• With multiple entries in the "resources" object that all have the same relation, e.g. {X: A, X: B, X:C. While this is technically acceptable in the JSON spec, many client implementations don't handle it well and the JSON Home spec implies that non-templated entries in the "resources" object are the only entries with a particular relation:

A Resource Object links to resources of the type indicated in their name using one of two mechanisms; either a direct link (in which case there is exactly one resource of that relation type associated with the API), or a templated link, in which case there are zero to many such resources.

This makes it difficult for me to build tools consuming JSON Home documents, as I was planning on using more standard relations and tool-specific relations that describe a variety of resources rather than primarily API-specific relations, to make tools that work across multiple APIs. I was expecting an array of resources and resource templates for each relation rather than a single resource or template.

[mnot]

Can you give me some more detail about your use case? I'm trying to understand how you want to use the spec.

[dret]

it seems that this is a valid point, and one issue that tends to surface in certain ways of representing links in JSON. some designs then go the route of changing the JSON structure so that they can accommodate multiple links of the same relation.
i am not saying that JSON home has to do this. but it might be useful to add some informative text that makes this limitation of the format explicit, so that people are not left wondering.
one use case i could easily think about would be to say that there is more than one associated documentation resource available. service-doc then would repeat as a link relation, and these links could be further qualified by media type hints, one linking to HTML documentation and the other to a PDF version (this example probably applies best to the API object, which has the same limitation).

[handrews]

We're struggling a bit with this in JSON Hyper-Schema as well. Currently, our links is an array of objects (which may use URI Templates), so multiple objects in the array can have the same rel. However, some prefer rel as an object key, which would probably result in the values being a list of objects, which doesn't simplify things all that much IMHO.

As for use cases, you may want to link to resources in multiple other systems. For instance, links from a person to "publications" of various sorts that are not all hosted by the same other service. Some may not be online and may be better identified by URNs than URLs.

Off the top of my head I can't come up with a use case within a single API where the same entity designs all of the URIs, but I just woke up and the caffeine hasn't really kicked in yet :-P

[jackfirth]

I lost track of this issue, whoops.

A specific tool I had in mind when I wrote this was a hypothetical command line tool that could do some generic CRUD operations on any REST API with a home document that linked to collections that should support CRUD operations. There'd be some link relation defined by the tool, maybe an http url to the tool's docs or something, and each link with that relation would equal one collection. Forcing a server to ensure the collections all fit a particular URI template just to get this tool integration working seems restrictive.

To deal with this specific problem, I'd probably just have the home document link to a single resource that represents a list of links to use as collections. So it's more of an inconvenience of the format for me than a blocking issue.

[dret]

On 2017-10-10 18:04, Henry Andrews wrote: We're struggling a bit with this in JSON Hyper-Schema as well. Currently, our |links| is an array of objects (which may use URI Templates), so multiple objects in the array can have the same |rel|. However, some prefer |rel| as an object key, which would probably result in the values being a list of objects, which doesn't simplify things all that much IMHO.

this pattern just seems to be something that "reads well" to the human eye. as long as you're not trying to have more than one link with one relation type, it works well.