Question about sorting of included resources by id

[pdrosos]

Hi,

I noticed, that in my JSONAPI response the included resources are sorted by id, instead by their original order.
After looking in the code I found out that this line sorts them by id.

I have a question, why is this behavior implemented? In my case I would like to have them sorted in the same way, in which they come from the DB and like they are sorted in the relationships data array. Am I missing something?

Thanks in advance!

[kocsismate]

Hey,

Fair question! The "included" array should be considered as an Identity Map, so ordering its content by ID seemed reasonable for aesthetics, in spite of the fact that doing so has no practical advantage to be honest.

Based on my understanding, that's why JSON:API clients shouldn't rely on the order of the included resources: the "included" array should be first loaded in memory, and when querying the response, the client should retrieve included resources for a relationship by associating them with resource identifier objects - which are correctly sorted.

But I am eager to hear your use-case! Maybe it can confirm that this ordering should be removed.

[pdrosos]

Hi,

thanks for your answer! In general I agree with you that the included resources order should not be considered as important, but the relationships array to be used instead.

In my use-case I use normalization of the JSONAPI response, based on this normalizer. As you could see here, it combines all entities from data + all entities from included resources and groups them by type, so they are easier to access after that. The final result is shown in the README.
When the included resources are used, this kind of normalization is achieved easier, than if the relationships array of each entity would be used instead. Especially if included resources have relationships too.

Please let me know what do you think and if it makes sense. I am currently trying to find out the best way to fix the problem and I should change the code of the normalizer in my client, if you think that it's better not to rely on the included resources order.

[kocsismate]

OK, now I understand your problem. :)

I did some investigation and fortunately found a discussion about sorting the included array: http://discuss.jsonapi.org/t/how-to-sort-included-resources/198. This means that I am willing to remove sorting because it isn't controversial to the spec and recommendations and this modification even improves the performance a tiny little bit. However, the included array won't be so neatly arranged as it is today. :P

By the way: does your normalizer handle cases well when there are multiple types in a relationship data?

Just for reference, I link a really interesting conversation here about the included array, maybe you find some insights there: http://discuss.jsonapi.org/t/why-is-included-an-array/76 Sorry if you have already seen it. :)

So I am going to release 1.0.2 in the following days with the aforementioned modification :) Thank you for your question!

[pdrosos]

Very nice resources, thanks! I haven't read them so far and I will very soon.

It's nice that you think the included array can be sorted too and it is not against the specifications. Waiting for this improvement, even it wouldn't look so neat any more ;)

Yes, the normalizer handles multiple included resources types and as it uses the included array to iterate trough them and group them, it's a relatively easy task. For example:

{
  "jsonapi": {
    "version": "1.0"
  },
  "data": {
    "type": "mobile-users",
    "id": 1,
    "links": {
      "self": "/mobile-users/1",
      "education": "/mobile-users/1/education",
      "experience": "/mobile-users/1/experience"
    },
    "attributes": {
      "firstName": "Pavlina",
      "lastName": "Drosos",
      "summary": "Summary"
    },
    "relationships": {
      "industry": {
        "data": {
          "type": "industries",
          "id": 64
        }
      },
      "location": {
        "data": {
          "type": "location",
          "id": 56
        }
      },
      "education": {
        "data": [
          {
            "type": "education",
            "id": 48
          },
          {
            "type": "education",
            "id": 47
          }
        ]
      },
      "experience": {
        "data": [
          {
            "type": "experience",
            "id": 507
          },
          {
            "type": "experience",
            "id": 509
          },
          {
            "type": "experience",
            "id": 508
          },
          {
            "type": "experience",
            "id": 506
          }
        ]
      }
    }
  },
  "included": [
    {
      "type": "education",
      "id": 47,
      "links": {
        "self": "/education/47"
      },
      "attributes": {
        "school": "UE Varna",
        "fieldOfStudy": "Master of Informatics",
        "startMonth": "9",
        "startYear": "2002",
        "endMonth": "9",
        "endYear": "2008"
      }
    },
    {
      "type": "education",
      "id": 48,
      "links": {
        "self": "/education/48"
      },
      "attributes": {
        "school": "Asd",
        "fieldOfStudy": "Fgh",
        "startMonth": "8",
        "startYear": "2013",
        "endMonth": null,
        "endYear": null
      }
    },
    {
      "type": "experience",
      "id": 506,
      "links": {
        "self": "/experience/506"
      },
      "attributes": {
        "position": "Web Developer",
        "company": "Test",
        "area": "Sofia",
        "industryName": "Computer Software",
        "startMonth": "5",
        "startYear": "2013",
        "endMonth": "11",
        "endYear": "2016"
      },
      "relationships": {
        "industry": {
          "data": {
            "type": "industries",
            "id": 25
          }
        }
      }
    },
    {
      "type": "experience",
      "id": 507,
      "links": {
        "self": "/experience/507"
      },
      "attributes": {
        "position": "asd",
        "company": "fghghhhhhhhhh",
        "area": "qwerty",
        "industryName": "Airlines/Aviation",
        "startMonth": "2",
        "startYear": "2016",
        "endMonth": null,
        "endYear": null
      },
      "relationships": {
        "industry": {
          "data": {
            "type": "industries",
            "id": 2
          }
        }
      }
    },
    {
      "type": "experience",
      "id": 508,
      "links": {
        "self": "/experience/508"
      },
      "attributes": {
        "position": "aaaaa",
        "company": "bbbbb",
        "area": "ccccccc",
        "industryName": "Animation",
        "startMonth": "4",
        "startYear": "2014",
        "endMonth": "1",
        "endYear": "2015"
      },
      "relationships": {
        "industry": {
          "data": {
            "type": "industries",
            "id": 5
          }
        }
      }
    },
    {
      "type": "experience",
      "id": 509,
      "links": {
        "self": "/experience/509"
      },
      "attributes": {
        "position": "last added",
        "company": "dsd",
        "area": "212",
        "industryName": "Accounting",
        "startMonth": "7",
        "startYear": "2015",
        "endMonth": null,
        "endYear": null
      },
      "relationships": {
        "industry": {
          "data": {
            "type": "industries",
            "id": 1
          }
        }
      }
    }
  ]
}

becomes

{
  "results": {
    "mobile-users": [
      1
    ],
    "education": [
      47,
      48
    ],
    "experience": [
      506,
      507,
      508,
      509
    ]
  },
  "entities": {
    "mobile-users": {
      "1": {
        "id": 1,
        "type": "mobile-users",
        "firstName": "Pavlina",
        "lastName": "Drosos",
        "summary": "Summary",
        "industry": 64,
        "location": 56,
        "education": [
          48,
          47
        ],
        "experience": [
          507,
          509,
          508,
          506
        ]
      }
    },
    "education": {
      "47": {
        "id": 47,
        "type": "education",
        "school": "UE Varna",
        "fieldOfStudy": "Master of Informatics",
        "startMonth": "9",
        "startYear": "2002",
        "endMonth": "9",
        "endYear": "2008"
      },
      "48": {
        "id": 48,
        "type": "education",
        "school": "Asd",
        "fieldOfStudy": "Fgh",
        "startMonth": "8",
        "startYear": "2013",
        "endMonth": null,
        "endYear": null
      }
    },
    "experience": {
      "506": {
        "id": 506,
        "type": "experience",
        "position": "Web Developer",
        "company": "Test",
        "area": "Sofia",
        "industryName": "Computer Software",
        "startMonth": "5",
        "startYear": "2013",
        "endMonth": "11",
        "endYear": "2016",
        "industry": 25
      },
      "507": {
        "id": 507,
        "type": "experience",
        "position": "asd",
        "company": "fghghhhhhhhhh",
        "area": "qwerty",
        "industryName": "Airlines/Aviation",
        "startMonth": "2",
        "startYear": "2016",
        "endMonth": null,
        "endYear": null,
        "industry": 2
      },
      "508": {
        "id": 508,
        "type": "experience",
        "position": "aaaaa",
        "company": "bbbbb",
        "area": "ccccccc",
        "industryName": "Animation",
        "startMonth": "4",
        "startYear": "2014",
        "endMonth": "1",
        "endYear": "2015",
        "industry": 5
      },
      "509": {
        "id": 509,
        "type": "experience",
        "position": "last added",
        "company": "dsd",
        "area": "212",
        "industryName": "Accounting",
        "startMonth": "7",
        "startYear": "2015",
        "endMonth": null,
        "endYear": null,
        "industry": 1
      }
    }
  }
}

You can even see how the ordering of the experience and education relationships is different in relationships and included arrays and how the normalizer uses the included ordering, which is the reason to open this question :)

[kocsismate]

Released v1.0.2 :)

P.S.: It's nice to hear that the normalizer handles this case too!