Why not let it be up to the API? A set can be ordered, and it's still a set. There's no conflict between performing set operations and guaranteeing that the items are processed in a particular order.

I agree with @bintoro here and am 👎 on this.

Ordering may be significant for some relationships. For instance, an implementation might allow for the updating of tags on an article and want to preserve the specified order.

Why not let it be up to the API? A set can be ordered, and it's still a set.

I agree, but it is likely that any given API that contains ordered relationships, also contains unordered ones (just because order makes no sense for some relationships, and it is an unnecessary burden on the server to require all relationships be ordered if at least one of them is ordered: it requires facilities to store that ordering information).

How the client can tell the difference between them? Is this detail supposed to be described in the API docs, and response format alone is not enough to define the semantics? How can HATEOAS approach be achieved by the API designer wrt ordering relationships? I might be missing something, but the only idea which comes to mind is to specify in meta that links.this_relationship is ordered, but links.that_relationship is unordered.

IMHO, at the very least, it should be clarified in the spec that any given relationship can be either a set or a totally ordered set, to avoid misunderstanding.

How the client can tell the difference between them?

Why must the client be able to tell the difference? If the order doesn't have any meaning to the client, it simply doesn't have to care, even if the server internally manages the linkages in an ordered fashion.

I'm not convinced this warrants any mention in the spec. Nowhere is it implied that relationships maintain or do not maintain some kind of order, so obviously if an API needs to make or demand such guarantees, the API should explain this in its documentation.

Why must the client be able to tell the difference?

Suppose someone wants to use JSON API to build a HATEOAS API. Things like authentication mechanism, allowed characters, etc., must indeed be specified in the documentation. However, when the client is browsing the API in the HATEOAS sense, it may want to be able to tell whether a given relationship is ordered or not, e.g., to decide whether it makes sense to allow reordering control on it in the UI, etc. If both ordered and unordered relationships are allowed to appear in the same API, the format should distinguish between them.

Nowhere is it implied that relationships maintain or do not maintain some kind of order

IMHO, it is not only implied, but stated directly: "the server MUST append the specified members to the relationship using set semantics". AFAIK, sets are unordered by definition: wikipedia, wolfram.

I'm not convinced this warrants any mention in the spec.

I think it does. @bintoro, you think the spec allows both ordered and unordered relationships. @ethanresnick expressed a different view. The spec's size is relatively small, and if two active contributors understand it differently, is not it a clear indicator that the spec itself needs improvement?

I am not saying that the statement which this PR makes is correct (in fact, my personal preference is totally different: #431 (comment)). This PR is only trying to establish consistence with the statement which already exists in the spec: "the server MUST append the specified members to the relationship using set semantics". I am ready to update this PR with whatever is decided on this issue, I just want to see it through.

I think we may end up giving each api freedom here, as @bintoro and @dgeb suggest, but I'm with @hhware in that I think we really should think this point through more and the spec should take a better-defined position.

Otherwise, we're going to end up with a situation like javascript object property enumeration: objects were nominally supposed to be unordered, but then people started relying on the the enumeration order of implementations, to the point that ES6 now defines a deterministic enumeration order. In JSON API terms, the analogy would be that poor clients start relying on server processing order, such that an API couldn't make the relationships truly unordered even if it wanted to (which it might to support some databases etc).

@tkellen, @dgeb, is any development planned here for 1.0?

I don't think we need normative text for this. Per @ethanresnick's suggestion, I'm open to a small non normative note to clarify our stance. I'm removing the 1.0 milestone from this issue but I'd be happy to review that addition any time if you're willing to update @hhware!

@tkellen, I have updated the PR. I strongly feel the clarification, whatever it is, is needed in 1.0.

@hhware I think your non-normative note is great here! For your changes in the base text, what if we just did something really minimal, like this:

• Change the word "append" (in the phrase "the server MUST append the specified members") to "add", since "append" has a strong connotation of sticking the new thing onto the end, which implies an order.
• Then, we'd drop the phrase "set semantics" entirely, since all we really mean by it is "test for membership", so that we don't have to go into ordered vs unordered sets, etc.

So the change would be to rewrite this:

If a client makes a POST request to a relationship URL, the server MUST append the specified members to the relationship using set semantics. This means that if a given type and id is already in the relationship, the server MUST NOT add it again.

to:

If a client makes a POST request to a relationship URL, the server MUST add the specified members to the relationship if they are not already present. If a given type and id is already in the relationship, the server MUST NOT add it again.

Thoughts?

@hhware I like your non-normative note and prefer @ethanresnick's suggestion. Do you mind updating?

@dgeb, updated with a slight change in wording, hopefully it is OK.

@hhware thanks - LGTM 👍