I support this. Another argument in favor: there are several ways to specify relationships, why is one of them effectively preferred in a sense that the spec provides a shortcut for it? Removing the shortcut will also make top-level links and links of relationships more aligned.

Suggestion in #478 (actually inspired by this PR) can be viewed as a further improvement to it in terms of "readability at the first glance".

@lsylvester, BTW, the paragraph containing "The URL can therefore be specified directly as the attribute value" and the example which it describes should also be updated as part of this PR.

@hhware Thanks. I have updated to remove the comments from the example as it added no further value of the author example.

+1! I was also going to suggest this. It's a further move toward consistency over concision. Not only are the responses containing links now more uniform but, pending #482, there'll be more uniformity between link input and output formats as well! Finally, I agree with @hhware that it seems odd to privilege the hypermedia format here when it sits on equal footing with linkage everywhere else in the spec.

I'm curious about what @dgeb thinks of this, though, since he did a pretty thorough revision of the spec and this exception survived.

I support this change on the grounds that providing a related resource URL as a direct attribute value causes a mismatch between the JSON structure and the recommended URL structure:

• links/someresource is a relationship URL, while
• links.someresource contains the related resource URL.

I think it's a good rule that if there's a URL path that corresponds to a member in the JSON representation, the two should have similar semantics.

@dgeb @tkellen What's your take on this?

Something to think about is if the definition of related resource URL is just too long to sit comfortably in the middle of the bulleted list.

Here's an alternative version where both remaining definitions (relationship URL and related resource URL) are moved to their own paragraphs, just like linkage:

https://gist.github.com/bintoro/344c19a7ac29345b00b9

Another consideration I just realized: if we remove the url-only format, then the format for the resource-level self link becomes:

"self": {
  "related": "..." 
}

Maybe that's not awful, but it is worth noting.

@ethanresnick self is a separate thing, defined in the section Resource URLs.

@bintoro I guess...but do we really want implementations to have to have one rule for parsing the "self" value in a link object (and the values of the top-level links) and a different rule for parsing every other value in a link object? So it seems to me that keeping this format actually ends up being simpler.

Hmm. My first impression is that this is totally a non-issue, but let's see what others have to say. Think of it this way: a self member always contains a URL. That's pretty consistent, no? 😄

If we really want consistency among links object members, then let's do what I've been saying for a long time and place self directly on the resource object.

I don't consider it much of a burden to parse strings vs. objects. It adds a little bit of complexity but also offers benefits. The string option for link values provides a clean and simple approach to include fetch-only related resource URLs. It allows deeply nested related resource URLs, such as "comments.author", to be included alongside direct relationships, such as "comments".

I don't consider it much of a burden to parse strings vs. objects.

Agreed.

For me this issue is mostly about the incongruity between links/foo and links.foo. It can also be argued that the most logical (albeit useless) scalar-value replacement for a link object would be its self.

So, there are in fact two reasons why one might expect the value to be a relationship URL instead of the related resource URL.

It allows deeply nested related resource URLs, such as "comments.author", to be included alongside direct relationships

Hmm, I don't see why deep associations should need a string value any more than direct relations...

That last sentence doesn't stand well on its own. My emphasis on "clean and simple" from the previous sentence applies to the last one:

The string option for link values provides a clean and simple approach to include fetch-only related resource URLs. It allows deeply nested related resource URLs, such as "comments.author", to be included alongside direct relationships, such as "comments".

Anyway, your prior argument is fairly compelling:

It can also be argued that the most logical (albeit useless) scalar-value replacement for a link object would be its self.

I will milestone this for consideration, but I should say that we are very reluctant to make even minor breaking changes at this point.

From an implementors standpoint this is six of this half a dozen of the other to me.

I'm going to close this having spoken with several implementors who consider it rather trivial to implement the alternative string representation.

Thanks for the good discussion.