👍 from me with those minor nits

Looks like the author of these rules in normative-statements.json made just the mixup this PR aims to prevent:

    "id": "resource-relationships-object",
    "type": "normative-statements",
    "attributes": {
      "level": "MUST",
      "description": "A \"relationship object\" **MUST** contain [...]
    },

id says "relationships object" but description says "relationship object".

This is my first time dealing with the normative statements file. May an existing id string be edited or will that screw something up?

You can edit the id strings if you like--to my knowledge nobody is using them (yet) :(.

Ideally, we'd mark up our format.md files such that we can generate the normative statement files, but we haven't done so yet. This is to assist with automated testing for the specification. If you have the bandwidth to make this happen, that would be amazing.

Commit updated. I ended up leaving the id alone for now, since relationships-object can also be read as "item object in section relationships", which leaves the hierarchy intact.

@ethanresnick: Looking at this again, I don't think "contents" is a necessary addition, particularly if you feel it's not well defined what makes up the contents.

By necessity, objects consist of key-value pairs, so if a key-value pair represents a relationship, then saying that "a relationship must be represented by an object" makes it very clear that we're referring to the value.

In the Links section there's an exactly similar case:

Each member of a links object is a "link". A link MUST be represented as either: [...]

As for a relationship's contents, there's one existing mention:

[...] a related resource link MUST NOT change because its relationship's content changes.

It does suggest that the content might refer to the set of the referenced resources, although it would be fairly easy (and probably a good idea) to come up with a dedicated term for this, such as a "relationship's target".

Just checking in here... is the current round of bike-shedding complete? Are we ready to re-review?

I'm not sure. The question raised by @ethanresnick was whether it's okay to say

Each relationship MUST be represented by an object [...]

when we actually mean

Each relationship MUST be represented by a member whose value is an object [...]

I'm curious as to what others think. To be sure, the latter is more accurate but perhaps a bit awkward. Another angle is to figure out a term for the value part of a relationship and say

Each relationship's value MUST be represented by an object [...]

First off, I agree that this PR as written is better than the current text, and it may be good enough. If we want to be totally accurate, though, I think there's a way to separate the definitions of the relationship's name, contents (which isn't a term we need to use necessarily), and "relationship object" without being too awkward.

Here's probably what I'd say (key changes in bold):

The value of the relationships key MUST be an object (a "relationships object"). Each member in the relationships object represents a "relationship", which is a named set of references from the resource object in which it is defined to other resource objects.

Relationships may be to-one or to-many.

A relationship's name is given by its key. The value at that key MUST be an object ("relationship object") that contains the set of referenced resources or information pertaining to that set.

A "relationship object" MUST contain at least one of the following:

....

Thoughts?

Each member in the relationships object represents a "relationship", which is a named set of references [...]

But isn't this accurate only for to-many relationships? A to-one relationship doesn't feel like a "set of references".

A relationship's name is given by its key.

+1. I think this alone is enough to supplant the "named set" addition.

The value at that key MUST be an object ("relationship object") that contains the set of referenced resources or information pertaining to that set.

A "relationship object" MUST contain at least one of the following: ...

Saying that the object "contains the set of referenced resources" sounds wrong to me; it only contains the references, not the resources. Or is this in preparation for embedded resource objects?

Since the entire bolded segment is basically a summary of what is normatively stated right in the subsequent paragraph, I'd just drop that part entirely:

The value at that key MUST be an object ("relationship object") containing at least one of the following: ...

But isn't this accurate only for to-many relationships? A to-one relationship doesn't feel like a "set of references".

In my mind, it applies for to-one relationships too (since a set can be limited to one item, which is what I think the next paragraph does), but I see how it could be confusing, so I'm fine with changing it. Ideas?

+1. I think this alone is enough to supplant the "named set" addition.

Ok, but would that mean going back to "[relationships are] references from the resource object in which they are defined to other resource objects". If so, that just sounds a bit weird to me... in my head it's the resource identifier object that's the reference, not the relationship, which is why I'd said the relationship is a set of references.

Saying that the object "contains the set of referenced resources" sounds wrong to me; it only contains the references, not the resources.

Good catch. If we were going to keep it, it should say something like "contains the references that constitute the relationship".

Since the entire bolded segment is basically a summary of what is normatively stated right in the subsequent paragraph, I'd just drop that part entirely:

Works for me. (Though aren't we just back to your original complaint, then, that the definition of a "relationship object" isn't really connected conceptually to what comes before?)

I love how deep this rabbit hole is going 😄

in my head it's the resource identifier object that's the reference, not the relationship, which is why I'd said the relationship is a set of references.

Aha, this explains a lot. I never considered "reference" with this kind of static meaning in mind.

Thus, I've thought it's perfectly okay to simultaneously say that

• a relationship is a reference from one resource (object) to another
• a resource identifier is a reference to a particular resource object

where the first statement implies nothing about the concrete representation or the cardinality of the target.

If we want to narrow the usage of "reference", the first paragraph could say:

Members of the relationships object represent "relationships", i.e., associations between the enclosing resource object and other resource objects.

In fact, "enclosing" might be preferable to "in which they are defined" regardless of the decision w.r.t. "reference".

Though aren't we just back to your original complaint, then, that the definition of a "relationship object" isn't really connected conceptually to what comes before?

No. In the published spec, the definition of relationship object just appears out of nowhere. In the current iteration, we have the statement:

The value at that key MUST be an object ("relationship object") ...

This bridges the gap and is associated with the concept of relationships via the first paragraph that defines relationships object members as relationships.

I love how deep this rabbit hole is going 😄

Indeed. At least we seem to be getting somewhere 😄 I'll take a look at this with fresh eyes tomorrow.

Ok, so it sounds like the text you're proposing is:

The value of the relationships key MUST be an object (a "relationships object"). Each member in the relationships object represents a "relationship", i.e., an association between the enclosing resource object and other resource objects.

Relationships may be to-one or to-many.

A relationship's name is given by its key. The value at that key MUST be an object ("relationship object").

A "relationship object" MUST contain at least one of the following:

....

(Or the above, but replacing "Each member..." with "Members...".)

If that's right, then I'm fine with it! Update the PR and we'll get it merged :)

Thanks a lot for working on this one. I reviewed it looking at latest state of v1.1. I think that clarification is still needed. I created a follow-up merge request at #1608 to finally get it in. I hope that's okay with everyone who had worked on this before. If you have time, I would appreciate a review of that one to ensure that I understood the consensus reached here correctly.