JSON:API sparse fieldsets break include relationships - included section missing

[cay89]

API Platform version(s) affected: 4.1.3 (Laravel)

Description
When using JSON:API sparse fieldsets (fields[ResourceType]=field1,field2) in combination with include relationships (include=relationName), the included section is completely missing from the response. The include parameter works correctly when used alone, but any sparse fieldset parameter (even for unrelated resources) causes the included relationships to disappear.

How to reproduce

1. Set up two related models with ApiResource annotations:

// ListItem model
#[ApiResource(
    uriTemplate: '/list/items',
    operations: [
        new GetCollection(
            parameters: [
                new QueryParameter(key: 'include'),
                new QueryParameter(key: 'fields', filter: SparseFieldset::class),
            ],
        ),
    ],
)]
class ListItem extends AbstractModel
{
    public function translations(): HasMany
    {
        return $this->hasMany(ItemTranslation::class, 'item_id');
    }
}

// ItemTranslation model  
#[ApiResource(/* ... */)]
class ItemTranslation extends AbstractModel
{
    // fields: locale, value, etc.
}

2. Test these API calls:

Working (include only):

GET /api/list/items?include=translations

Response includes included section with translation data.

Not working (include + sparse fieldsets):

GET /api/list/items?include=translations&fields[ListItem]=id,data&fields[ItemTranslation]=locale,value

Response missing included section entirely.

Also not working (include + any sparse fieldset):

GET /api/list/items?include=translations&fields[ListItem]=id,data
GET /api/list/items?include=translations&fields[ItemTranslation]=locale,value

Both missing included section.

Expected behavior: When both include and fields parameters are used, the response should contain the included section with only the specified fields for each included resource type.

Example request:

GET /api/list/items?include=translations&fields[ListItem]=id,data&fields[ItemTranslation]=locale,value

Expected response:

{
  "links": {"self": "/api/list/items?include=translations&fields[ListItem]=id,data&fields[ItemTranslation]=locale,value"},
  "meta": {"totalItems": 3, "itemsPerPage": 20, "currentPage": 1},
  "data": [
    {
      "id": "/api/list_items/1ae0ddf1-d361-465e-9ff7-cdabecf82cb2",
      "type": "ListItem",
      "attributes": {
        "id": "1ae0ddf1-d361-465e-9ff7-cdabecf82cb2",
        "data": {"validation": {"regex": "^[0-9]{8}-[1-5]-[0-9]{2}$"}}
      },
      "relationships": {
        "translations": {
          "data": [{"type": "ItemTranslation", "id": "/api/item_translations/e57d9880-a064-4352-85a0-29391d0e5b5f"}]
        }
      }
    }
  ],
  "included": [
    {
      "id": "/api/item_translations/e57d9880-a064-4352-85a0-29391d0e5b5f",
      "type": "ItemTranslation",
      "attributes": {
        "locale": "en",
        "value": "Tax number format"
      }
    }
  ]
}

[soyuka]

Actually you should try using the property name, see my example I use fields[bars]=name, in your case probably just fields[translations]=locale,value

[cay89]

According to the JSON:API documentation, the fields[TYPE] parameter refers to the resource type, not the name of the relationship.

For example, in the official documentation:

author → people

The relationship is author, but the resource type is people, and fields[people] is used to specify the sparse fieldset.

In my case, the relationship is translations, but the actual resource type is ItemTranslation, which is what I used in the fields parameter:

/api/list/items?include=translations&fields[ItemTranslation]=locale,value

I also tested the version you suggested (with fields[translations]=...). In that case, the translations are included in the response, but only as references (with type and id), not as full resource objects with filtered attributes.

/api/list/items?include=translations&fields[translations]=locale,value

{
   "links":{
      "self":"\/api\/list\/items?fields%5Btranslations%5D=locale%2Cvalue\u0026include=translations"
   },
   "meta":{
      "totalItems":3,
      "itemsPerPage":20,
      "currentPage":1
   },
   "data":[
      {
         "id":"\/api\/list_items\/9b6dffe1-3b79-4767-a345-3543d2b2e8a9",
         "type":"ListItem",
         "relationships":{
            "translations":{
               "data":[
                  {
                     "type":"ItemTranslation",
                     "id":"\/api\/item_translations\/0cf87ed6-d250-4f49-a4c3-6195b5b4549c"
                  }
               ]
            }
         }
      },
      {
         "id":"\/api\/list_items\/323e6f11-cc89-4255-8f12-72f5cc11b760",
         "type":"ListItem",
         "relationships":{
            "translations":{
               "data":[
                  {
                     "type":"ItemTranslation",
                     "id":"\/api\/item_translations\/85408cf2-4864-474f-a432-0d25a78399a2"
                  }
               ]
            }
         }
      },
      {
         "id":"\/api\/list_items\/a7a4f4cf-fab2-464a-a169-bfdd6d7f9e75",
         "type":"ListItem",
         "relationships":{
            "translations":{
               "data":[
                  {
                     "type":"ItemTranslation",
                     "id":"\/api\/item_translations\/35f46593-c764-4c96-af2a-1da591727e5a"
                  }
               ]
            }
         }
      }
   ],
   "included":[
      {
         "id":"\/api\/item_translations\/0cf87ed6-d250-4f49-a4c3-6195b5b4549c",
         "type":"ItemTranslation"
      },
      {
         "id":"\/api\/item_translations\/85408cf2-4864-474f-a432-0d25a78399a2",
         "type":"ItemTranslation"
      },
      {
         "id":"\/api\/item_translations\/35f46593-c764-4c96-af2a-1da591727e5a",
         "type":"ItemTranslation"
      }
   ]
}

Additionally, I noticed that in your example, the new QueryParameter(key: 'include') is not added to the model. This might also be a relevant difference in behavior.

[soyuka]

You don't need new QueryParameter(key: 'include') as this is always available with JSON:API. Maybe we missed a documentation entry for this though?
The Fields logic is handled at: https://github.com/api-platform/core/blob/main/src/JsonApi/Filter/SparseFieldsetParameterProvider.php

From what I understand I need to add the property mapping and get all the relationships available so that everything works correctly. I won't have much time feel free to take a look and help it'd be really appreciated! You can even fix this in your own code, the filter is quite basic: https://github.com/api-platform/core/blob/main/src/JsonApi/Filter/SparseFieldset.php. The idea is to transform the fields query into Symfony Attributes for serialization https://symfony.com/doc/current/serializer.html#using-the-serialization-context

[cay89]

Well, this seems a bit complicated. I think the problem might be that the SparseFieldsetParameterProvider doesn't know what fields exist in the objects under the included key, so it can't filter them. Maybe these also need to be added to the extra properties. Then I'm not sure how to return the $normalizationContext, because we don't need to filter within the main data, but rather step out of data and into the included key. This seems to require some deeper modification.