Ambiguity of full-linkage requirement in v1.0 spec

1

Hello all!

I am writing a JSON:API library which for now will just support the creation of v1.0-compliant documents. I am working through validating that full-linkage is respected in input documents as-per JSON:API - Compound Documents, and I have questions as I compare the v1.0 spec to the v1.1 draft.

The description of full-linkage in 1.0 is much harder to parse than that of 1.1

The 1.0 spec says:

Compound documents require “full linkage”, meaning that every included resource MUST be identified by at least one resource identifier object in the same document. These resource identifier objects could either be primary data or represent resource linkage contained within primary or included resources.

This is quite different from the 1.1 spec which exclusively talks in terms of relationships:

Every included resource object MUST be identified via a chain of relationships originating in a document’s primary data. This means that compound documents require “full linkage” and that no resource object can be included without a direct or indirect relationship to the document’s primary data.

Some questions:

  1. Is the phrasing of the v1.1 version a breaking change or is it simply a better way of describing the full linkage requirement? (i.e. can I adopt this view of full linkage and still create a v1.0-compliant JSON:API library)
  2. If it is a breaking change, are we to interpret “could either be primary data” as: If the included resource object is also a primary data resource object? i.e.:
    {
  "data": {
    "id": "1",
    "type": "articles",
    "attributes": {
      "title": "A"
    }
  },
  "included": [
    {
      "id": "1",
      "type": "articles",
      "attributes": {
        "title": "A"
      }
    }
  ]
}
  3. What does it mean for resource identifier objects to “represent” resource linkage? Isn’t resource linkage just a level above resource identifier objects?
  4. There is no mention of a chain that leads to the primary data in the 1.0 version. Does that imply that closed-loop relationships within include data are technically valid JSON:API?
    For example this simple self-loop
    {
   ...,
   "included": [
      "id": "1",
      "type": "foo",
      ...,
      "relationships": {"bar": {"data": {"id": "1", "type": "foo"}}}
   ]
}
    Or a more complex example where two pieces of include data have relationships referencing each other but there is no other relationship in the document to refer to them (meaning they’re disconnected from primary data).
2

Thanks a lot for your question.

The changes in wording are not considered as breaking changes. They are only meant to provide more clarity of what has been specified. At least from intend perspective.

You are right that v1.0 does not explicitly state that every included resource must have a relationship path rooted in a primary resource. That’s considered a mistake in wording. It has been fixed in v1.1 as well.

V1.1 is additive. All changes to defining existing specification semantics are improvements on wording. I would recommend to use v1.1 as a reference and only have a look in v1.0 to identify what has been added.