Nice job @ethanresnick!

But this PR doesn't go so far as to use link objects to represent single relationships retrieved at relationship URLs.

Whether we want relationship URLs to return the extra layer provided by link objects is one discussion, but in any case I would like to reuse the concept of linkage in that section, too. Makes no sense to talk about "arrays of objects with type and id members" when the format has already been defined elsewhere.

Of course, linkage objects might gain further members that are not applicable to create/update operations, but I don't see a problem with just excluding them as they're defined.

Hey guys,

I've updated my original post to describe exactly what this PR now does.

I think there's only one thing left to discuss here... Right now, we only allow the user to set relationship values by providing linkage, rather than, e.g. a related url. While this PR makes that design decision more explicit, I'm wondering if we want to preserve the flexibility for JSON API to become truly hypermedia-based/distributed in the future, which would require the ability to set a resource's value to an arbitrary url.

If we do want to preserve ourselves that option, I think it's as easy as replacing language like "the value MUST be a link object which MUST contain a linkage key" with language like "the value MUST be a link object which SHOULD contain a linkage key. Servers MAY reject attempts to set the value of a relationship when linkage is not provided."

I'm in favor of the term "linkage object", which seems consistent with "link object" and "resource object".

I am totally fine with linkage objects and have no special feelings for relationship tuples, but I have a small reservation. If one compares linkage object with link object, then the latter is what is keyed by links, whereas one cannot say that linkage object is what is keyed by linkage -- it is wrong in case of to-many relationship. This can be confusing for readers. If this minor thing does not bother anyone else, please ignore it.

Also, I would suggest to extract definition of linkage object into a separate paragraph, not introduce it "on the run":

a "linkage object", which is an object containing...

@hhware

Also, I would suggest to extract definition of linkage object into a separate paragraph, not introduce it "on the run":

I completely agree with this in principle. I only introduced the definition in line for consistency with how the spec currently introduces many of its smaller definitions (e.g. "link object" and "relationship urls" are both defined in parentheticals).

That said, I think the spec would really benefit from having a glossary of terms at the bottom, with every usage of a defined term in the body text linked to its entry in the glossary. If others are onboard with having such a glossary, we could define "linkage object" there.

If one compares linkage object with link object, then the latter is what is keyed by links, whereas one cannot say that linkage object is what is keyed by linkage... If this minor thing does not bother anyone else, please ignore it.

I'll let others chime in about this, but it doesn't particularly bother me.

I would suggest to extract definition of linkage object into a separate paragraph

Agreed. Defining the thing as we're explaining to-one relationships doesn't seem right.

I would also like to add a tiny definition for it, similar to what I'm trying to do to linkage here: https://github.com/json-api/json-api/pull/498/files#diff-26e38355b69056b0db1c2b1c612241b2R301

Something like

A "linkage object" identifies an individual related resource. It MUST be represented by an object containing "type" and "id" members.

Ok! I've updated the PR to include the "linkage object" definition in its own paragraph, along the lines @bintoro suggested.

I've updated the PR to include the "linkage object" definition in its own paragraph

👍

I think the spec would really benefit from having a glossary of terms at the bottom

Sure, but I'm not crazy about the idea of actually removing definitions from their main context and stashing them only in some appendix.

As I've said elsewhere, I'm planning a big PR that would improve the formatting of primary definitions and add a ton of intra-document links. I just haven't been able to submit it because of the current backlog of conflicting PRs.

Let's re-evaluate the need for an index/glossary after the intra-doc links are in place. As long as stuff is defined in the body text, I view a full glossary as overkill. At most an alphabetical index linking to the primary definitions might be useful.

@bintoro sounds good :)

Thanks @ethanresnick et al - merging now. I believe that this removes the last remaining asymmetry in request / response documents. As a bonus, it tightens up the terminology used in the spec with the definition of "linkage object".

Great! Thanks @dgeb!