Hey. We're using the JSON:API spec for some REST APIs at TIDAL, and have discussed the topic of parallell relationships. We have weighed some pros and cons for a specific case, and we will probably go for a solution where we support parallell relationships. The SHOULD NOT wording seems to strike a good balance in the specification.

In addition to adding the SHOULD NOT clarification on to-many relationships, would it make sense to also update the wording in the Updating to-many relationships section? Currently it reads, for POSTs:

If a given type and id is already in the relationship, the server MUST NOT add it again.

Changing MUST NOT to SHOULD NOT also for CRUD operations wrt parallell relationships, would keep the recommendation not to support parallell relationships, but also clarify that it is a valid implementation.

Thanks!

In addition to adding the SHOULD NOT clarification on to-many relationships, would it make sense to also update the wording in the Updating to-many relationships section? Currently it reads, for POSTs:

If a given type and id is already in the relationship, the server MUST NOT add it again.

Changing MUST NOT to SHOULD NOT also for CRUD operations wrt parallell relationships, would keep the recommendation not to support parallell relationships, but also clarify that it is a valid implementation.

I feel we should keep the MUST NOT in this case. One of the design goals of JSON:API is ensuring that a client can change the server's state without needing to know it. That eases consumers a lot. E.g. in case a request to add a relationship fails, the client can send the request again without needing to check before if the server has processed the request or not.

Maybe we should add a similar clarification that a DELETE request for a specific member must delete all references to that member on the relationship. And not only a subset of it if the resource is referenced multiple times.

I get that this requires using full replacement to manage parallel relationships. But in my perspective that's only one of the many drawbacks you get when using that discouraged pattern. The benefits for the recommended usage of relationships strongly outweigh that trade-off in my perspective.

Please note that the primarily reason for using SHOULD NOT instead of MUST NOT for parallel relationships is not introducing breaking changes. So far I have not seen any use case, which is better solved by parallel relationships than intermediate resources.

Thank you for the swift and clear reply @jelhan, much appreciated.

First of all, I do agree that from a modelling perspective, using intermediate resources most likely represents the best solution. The reason we are leaning towards supporting parallell relationships are strictly practical. We are in essence retrofitting JSON:API on top of a previously existing system/API.

The way our data is currently structured, and the way we handle includes, would mean either quite a bit of work for us, or quite a compromise on performance and flexibility for clients, if we relied on intermediate resources. Also, each resource in the relationship will have a unique id in meta, making sure we have a way to uniquely address each relationship in the relationship object.

A few follow ups, just to make sure I understand correctly:

1. Does using SHOULD NOT wording in general for to-many relationships, and MUST NOT wording for mutation operations for to-many relationships, imply that - strictly speaking - it is valid JSON:API for a server to expose a read-only to-many relationship containing parallell resources, but not a mutable one?

2. Refs:

One of the design goals of JSON:API is ensuring that a client can change the server's state without needing to know it.

Got it, makes sense. What is your take on how compatible this goal is with the note in section 7.2.2.4, essentially saying that an implementation may choose to treat a to-many relationship as ordered (something we are also doing for several to-many relationships!). In essence, if an implementation chooses to treat a to-many relationship as ordered, doesn't the ordering of the to-many relationship represent a state that a client may need to relate to before mutating the relationship?

Thank you.

First of all, I do agree that from a modelling perspective, using intermediate resources most likely represents the best solution. The reason we are leaning towards supporting parallell relationships are strictly practical. We are in essence retrofitting JSON:API on top of a previously existing system/API.

The way our data is currently structured, and the way we handle includes, would mean either quite a bit of work for us, or quite a compromise on performance and flexibility for clients, if we relied on intermediate resources. Also, each resource in the relationship will have a unique id in meta, making sure we have a way to uniquely address each relationship in the relationship object.

I struggle imagining such a scenario. Would be great if you could elaborate. Maybe I'm missing relevant use cases for parallel relationships.

I assume it's just a matter of the serialization if representing it as an intermediate resource or not. If I get you right, you already have a unique identifier for each reference to a resource in that parallel relationship. In that case you already have an id for the intermediate resource. The type could be derived from the types of the related resources and the names of the relationship.

I expect you have a serialization such as the following today:

{
  "data": {
    "type": "teams",
    "id": "1",
    "relationships": {
      "members": {
        "data": [
          {
            "type": "teams_members",
            "id": "23",
            "meta": {
              "id": "101"
            }
          },
         {
            "type": "users",
            "id": "23",
            "meta": {
              "id": "102"
            }
          }
        ]
      }
    }
  }
}

What additional challenges due you face serializing it as the following:

{
  "data": {
    "type": "teams",
    "id": "1",
    "relationships": {
      "members": {
        "data": [
          {
            "type": "teamsMembers",
            "id": "101"
          },
         {
            "type": "teamsMembers",
            "id": "102"
          }
        ]
      }
    }
  },
  "included": [
    {
      "type": "teamsMembers",
      "id": "101",
      "relationships": {
        "user": {
          "type": "users",
          "id": "23"
        }
      }
    },
    {
      "type": "teamsMembers",
      "id": "102",
      "relationships": {
        "user": {
          "type": "users",
          "id": "23"
        }
      }
    }
  ]
}

Unless I missed something, I have just moved existing information around and made up a type for the intermediate resource. I know it is more complex if a unique identifier for the reference in the relationship does not exist yet. But that doesn't seem to be the case for you.

1. Does using SHOULD NOT wording in general for to-many relationships, and MUST NOT wording for mutation operations for to-many relationships, imply that - strictly speaking - it is valid JSON:API for a server to expose a read-only to-many relationship containing parallell resources, but not a mutable one?

No. Mutation of parallel relationships are possible. But with the limitation that full replacement must be used in some cases:

• Adding more than one reference to a resource to the same relationship requires full replacement. POST to a relationship link does not support adding a second (or more) references to the same resource to a relationship.
• Removing only some references to a resource on the same relationship requires full replacement. DELETE to a relationship link will delete all references to the resources referenced by the provided resource identifier objects.

One of the design goals of JSON:API is ensuring that a client can change the server's state without needing to know it.

Got it, makes sense. What is your take on how compatible this goal is with the note in section 7.2.2.4, essentially saying that an implementation may choose to treat a to-many relationship as ordered (something we are also doing for several to-many relationships!). In essence, if an implementation chooses to treat a to-many relationship as ordered, doesn't the ordering of the to-many relationship represent a state that a client may need to relate to before mutating the relationship?

The JSON:API specification does not define how a client can change the order of an ordered to-many relationship. If sending the same request multiple times could lead to unexpected results depends on the specific implementation. I expect that most implementations does not have such a problem. E.g. if the order is mutated by a full-replacement of the relationship, the client describes the desired state in the request independently of the server state. The result is the same regardless if the request is successfully processed once or multiple times. The same is true if the implementation provides some way for a client to specify adding a reference in a specific position of a relationship. It's only an issue if an implementation allows mutation depending on current state (e.g. "move one up/down").

Unless I missed something

You didn't miss anything, and your example illustrates exactly how we would model it using intermediate resources.

As I mentioned, the reasons we're leaning towards not using intermediate resources are strictly practical and a result of some design decisions/trade offs, and our current implementation. One concrete example is our logic that generates compound documents (included section). It currently doesn't support inclusion of nested paths. So, either we would have to rebuild our inclusion logic to support nested paths and generate full linkage (which, with the current setup we have, would introduce a performance decrease), or clients would have to make two consecutive calls to our backend in order to retrieve the same information. Basically, 1/ GET /teams/?include=members, and 2/ GET /teamMembers/?include=user.

No. Mutation of parallel relationships are possible. But with the limitation that ...

Thanks

The JSON:API specification does not define how a client can change the order of an ordered to-many relationship. If sending the same request multiple times could lead to unexpected results depends on the specific implementation. I expect that most implementations does not have such a problem. E.g. if the order is mutated by a full-replacement of the relationship, the client describes the desired state in the request independently of the server state. The result is the same regardless if the request is successfully processed once or multiple times. The same is true if the implementation provides some way for a client to specify adding a reference in a specific position of a relationship. It's only an issue if an implementation allows mutation depending on current state (e.g. "move one up/down").

Thanks, and yes - it is the "It's only an issue if an implementation allows mutation depending on current state (e.g. "move one up/down")." case I had in mind. "Move up/down" could be one scenario. "Insert after" could be another.