Generic relationships linked to heterogeneous resources


regardless that there’s probably some other/better way to model the following relationships (like in some related discussions, this and this), but just want to see, from a pure technical perspective,

  • does JSON:API support modeling generic relationships that linked to heterogeneous resources (like following)?

if yes,

  • in a request, is it possible to include only assets of type houses? i.e., what relationship path could be used for the include query param?
  "links": {
    "self": ""
  "data": {
    "id": "d0001",
    "type": "debtors",
    "attributes": {
    "relationships": {
      "assets": {
        "data": [
          {"type": "houses", "id": "house-0001"},
          {"type": "cars", "id": "car-0002"},
          {"type": "securities", "id": "stock-0003"}


You probably want the assets relationship to provide a related link that can then be filtered by type.


thanks @fdrake , but was more about to see if can support a relationship path that’s beyond the filtered by type. i.e.,

instead of[assets.type]=houses

trying to see if with a generic relationship (assets) that links to heterogeneous resource types (houses/cars/securities etc),

would it be possible to achieve something like this


with JSON:API spec, would that kind of relationship path be possible? or that would be implementation semantic?

The filter parameter can be handled however an application wants, but that’s up to the application. What you’ve described doesn’t really seem like a good match, but that’s opinion rather than a prohibition from the specification.

The include parameter is clearly spelled out in the specification, and I don’t think it can be easily reinterpreted for use as you describe.

The approach I described would be compliant with the specification, and I believe it would “fit” with the intentions expressed in the specification as well.

If your concern with that is with the number of requests being passed back & forth, you might be able to address the concern using the assets relationship’s self link; that might be reasonable to support filtering on, and can support include as well.

How much any of this helps depends on how you’re building your JSON:API support. If you’re using a library to provide most of that, what’s provided by the library can inform what’s readily achievable without additional work on the server.


thanks @fdrake,

just want to clarify that this is not a real issue that I need or try to resolve, but more a hypothetical example to understand (and see),

technically, would it be possible to construct a relationship path using a generic relationship pointing to heterogeneous resource types (as shown in the included param example here). i.e.,

  • would that be something that could be supported by implementation semantic? or it’s not possible based on specification semantic?

I guess i am looking for confirmation/thoughts from the community for comments like what you said regarding

The include parameter is clearly spelled out in the specification, and I don’t think it can be easily reinterpreted for use as you describe.

thanks again.

Just about anything could be done with parameters that are not defined by the specification. The specific filtering you describe would not be something I’d expect to be requested using the query parameters identified in the specification.

Not sure if that really answers your question, but that’s my thought on the matter.


Yes, JSON:API supports heterogenous relationships and collections. (At least implicitly; there is nothing in the spec that prohibits this. I use it myself.) Whether it’s a good idea is another issue. I usually try to re-model to avoid this and find that this often leads to a simpler API.

JSON:API does provide a (standard) way for clients to include only some members of a relationship.

You could work around this by having separate (possibly read-only) relationships for the different resource types.

Alternatively, you must get creative with the filter parameter. Take a look at this issue for a proposal (and discussion) of a syntax for filtering either primary or included data (at any level) based on arbitrary filters (e.g. resource types or other fields at any level below what is being filtered).