Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Clarify usage of parallel relationships #1677

Open
wants to merge 2 commits into
base: gh-pages
Choose a base branch
from

Conversation

jelhan
Copy link
Contributor

@jelhan jelhan commented Oct 28, 2022

This PR tries to implement the agreement we came up in #1361.

I struggled with the wording to be honest to be honest. I found it difficult to distinguish between the different kinds of parallel relationships. For sake of clarity let me show them in code:

  1. Different relationships

    {
      "data": {
        "type": "articles",
        "id": "1",
        "relationships": {
          "author": {
            "data": {
              "type": "users",
              "id": "12"
            }
          },
         "editors": {
           "data": [
             {
               "type": "people",
               "id": "12"
             }
           ]
         }
      }
    }
  2. Intermediate resource

    {
      "data": {
        "type": "teams",
        "id": "1",
        "relationships": {
          "members": {
            "data": {
              "type": "teamMembers",
              "id": "12"
            }
          },
         "editors": {
           "data": [
             {
               "type": "teamMembers",
               "id": "13"
             }
           ]
         }
      },
      "included": [
        {
          "type": "teamMembers",
          "id": "12",
          "attributes": {
            "startDate": "2021-01-01",
            "endDate": "2021-12-31",
          },
          "relationships": {
            "user": {
              "data": {
                "type": "users",
                "id": "23"
              }
            }
          }
        },
        {
          "type": "teamMembers",
          "id": "13",
          "attributes": {
            "startDate": "2022-06-01",
            "endDate": "2022-12-31",
          },
          "relationships": {
            "user": {
              "data": {
                "type": "users",
                "id": "23"
              }
            }
          }
        }
      ]
    }
  3. Multiple, direct reference on same relationship

    {
      "data": {
        "type": "teams",
        "id": "1",
        "relationships": {
          "members": {
            "data": [
              {
                "type": "users",
                "id": "23",
                "meta": {
                  "startDate": "2021-01-01",
                  "endDate": "2021-12-31",
                }
              },
             {
                "type": "users",
                "id": "23",
                "meta": {
                  "startDate": "2022-06-01",
                  "endDate": "2022-12-31",
                }
              }
            ]
          }
        }
      }
    }

We only aim to discourage using the third type of parallel relationships. We recommend to use the second type instead. I'm not sure how well this is expressed in the current wording.

Open questions:

  1. Do we want to backport this recommendation to v1.1?
  2. Do we need a better wording to distinguish between relationships of a resource (author, editors) and references to resource in such relationships?

Closes #1361

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Support for parallel relationships
1 participant