Cycles in relationships

1

Under Compound Documents the spec says:

In a compound document, all included resources MUST be represented as an array of resource objects in a top-level included member.

Later it says:

A compound document MUST NOT include more than one resource object for each type and id pair.

In the event of cycles in the relationship graph, I’m not sure it’s possible to comply with both of these in a reasonable way. In the simplest case, imagine a resource foo with a to-one relationship bar of type foo. And with this data:

foo1:
   bar: foo3

foo2: 
   bar: foo3

foo3:
   bar: null

If I get the collection of foos I expect to receive all three:

{
	"data": [
		{
			"type": "foos",
			"id": "foo1",
			"attributes": …,
			"relationships": …
		},
		{
			"type": "foos",
			"id": "foo2",
			"attributes": …,
			"relationships": …
		},
		{
			"type": "foos",
			"id": "foo3",
			"attributes": …,
			"relationships": …
		}
	]
}

And if I include bar (GET /foos?include=bar):

{
	"data": [
		{
			"type": "foos",
			"id": "foo1",
			"attributes": …,
			"relationships": {
				"bar": {
					"data": {"type": "foos", "id": "foos3"}
				}
			}
		},
		{
			"type": "foos",
			"id": "foo2",
			"attributes": …,
			"relationships": {
				"bar": {
					"data": {"type": "foos", "id": "foos3"}
				}
			}
		},
		{
			"type": "foos",
			"id": "foo3",
			"attributes": …,
			"relationships": {
				"bar": {
					"data": null
				}
			}
		}
	]
}

This document presumably violates the first rule because because the included resource foo3 (by way of bar) is not in the included array. If I put a second copy of foo3 into included (which seems wrong) then the first rule is satisfied, but the second is violated. And if I put foo3 into included, and remove it from data then both rules are satisfied, but it seems to violate my expectations as an API user (and produces some ambiguous semantics in the general case).

I assume the right answer is that included resource really must be in either the data or included sections but not both, and that clients are expected to resolve relationship data by searching both data and included.

Is that correct?

2

Yes, that is correct.

foo3 is already included in the compound document and cannot be under the included array.

I would interpret “included resources” in the first rule you mentioned as “included resources that need to be added to the document in addition to the primary data”.