JSONAPI Meta object should be at same level as Data, not inside it

[genyded]

The JSONAPI spec at https://jsonapi.org/format/#document-meta shows the META object at the same level as the DATA object:

{
  "meta": {  //META IS OUTSIDE DATA
    "copyright": "Copyright 2015 Example Corp.",
    "authors": [
      "Yehuda Katz",
      "Steve Klabnik",
      "Dan Gebhardt",
      "Tyler Kellen"
    ]
  },
  "data": {
     //... 
  }
}

However Laravel JSONAPI seems to place the META object INSIDE the DATA object:

"data": {
        "type": "users",
        "id": "1",
        "attributes": {
            "firstName": "User",
            "lastName": "One",
            "email": "user1@email.com"
        },
        "relationships": {
            "profile": {
                "links": {
                    "related": "http://host.docker.internal/api/users/1/profile",
                    "self": "http://host.docker.internal/api/users/1/relationships/profile"
                }
            }
        },
        "links": {
            "self": "http://host.docker.internal/api/users/1"
        },
        "meta": {  // META IS INSIDE DATA
            "roles": [
                "super-admin"
            ]
        }
    },

While not a crisis, we're using some other stuff that populates some META info, and it put's it OUTSIDE the data object. So we end up with two META objects for the resource. Would it be possible to address this somehow? We can work around it, but the workaround involves manually manipulating the response body before sending and is a bit 'hacky'.

[lindyhopchris]

So no, it's actually both.

The top-level document can have meta, but also a resource object in the data top-level member can have meta within it.

So it depends where you are returning the meta from in your implementation as to where it will be in the resource object, or at the top-level document. Can you provide details of where you are returning this from?

[lindyhopchris]

The distinction is:

• Document level (top-level) meta is about the document as a whole - link
• Resource object meta is about that specific resource - link

[genyded]

https://jsonapi.org/format/#document-resource-objects OK - we're all good. When we searched the spec on Meta the link to the resource meta did not show up for some reason. Anyway, sorry for the false alarm and as always thanks for the quick response. Closing this based on the spec being adhered to.

We lost our lead frontend developer and I have been feeling that gap in addition to my day job. We have a replacement starting on 6/19 and once things settle down a bit, I'll try to find some time to respond to your questions regarding doc improvements from some of the other issues.

[lindyhopchris]

Hey - no worries, don't worry about creating this issue, all good!

Yeah that sounds stressful. I've actually started the v4 rewrite, and making good progress - so there's still a lot to do. But once I've finished writing it, I'm going to have to go through all the docs and update them - so a good point to incorporate any feedback you have on the docs. Ideally send me any ideas via Slack - link on the homepage.

[harmenjanssen]

Hi, sorry to respond to this closed thread, but I'm actually wondering if it's possible to add stuff to the top-level meta object using Laravel JSON API?
Is there a method for that?

Thanks in advance!

[lindyhopchris]

You'd need to use a controller hook:
https://laraveljsonapi.io/docs/3.0/routing/controllers.html#controller-hooks

To return one of our response classes using the withMeta() helper method:
https://laraveljsonapi.io/docs/3.0/responses/#withmeta

[harmenjanssen]

Ah, sounds good, thanks!
Good to know that this is possible. 👍