Relationships within abstract relationship


Imagine the situation that you have parking with relationship cars.
Cars relationship is an array of resources of types sedan or truck.

It’s works perfectly when you need to get parking with all the cars it contains.

GET /parkings/{parking_id}?include=cars

But what to do when you need to get descendant relationships of sedans & trucks resources. For sedans you need trunk and for trucks you need trailer.

GET /parkings/{parking_id}?include=cars.trunk,cars.trailer

sedan has trunk but don’t has trailer and vice versa for truck. Isn’t it wrong and do we need to avoid abstractions when related resources they has different relationships?

GET /parkings/{parking_id}?include=sedans.trunk,trucks.trailer

I understand that sometimes abstract resources could have abstract descendant relationship names, but there are cases when only one resource has relationship of name X and others don’t have anything similar to it.

Thanks in advance!


@michaelhibay sorry for calling you again, but your advices are best :}


Haha, alright I’ve been busy doing conference work and starting a new job but I’ll see what I can do here to help. :smiley:

I’m not sure if this is the API you’re working with or a contrived example, but the problem here looks like you want the cars relationship to be polymorphic, and then utilize a feature of {json:api} which doesn’t support it.

If you look here, you’ll see some discussion from a while back where I make a bunch of points about resources not being objects.

The data shaping capabilities of {json:api} are not polymorphic, and are shaped by expected structure of the relationship hierarchy. This is OK and a really good design, as it is a motivator to keep the design simple and think about the design from another perspective.

Consider this, if you have a polymorphic ambiguous payload being returned to the consumer client, how much duplication of business logic would you expect that client to carry out? An ideal application would create a model completely reactive to the data returned, and by including this ambiguity you would require your clients to tightly couple themselves to your data model to simultaneously support all response messages for your resource model.

However, if the calling agent were to filter and explicitly understand the resource representation it was going to receive, it would be much easier to make changes to any particular representation or its client side handling without the addition of cyclomatic complexity.

My suggestion would be to refactor this in some way to allow for data shaping when filtering, or break it up into multiple requests. The other option if you control the client and the consumer, is to remember you control the default shape of the data so you could simply /parkings/{parking_id}?filter[type]=cars,trucks to get whatever shape you want. You could make this work within spec, but I think it really exposes an underlying flaw in the API design. Resources are not objects.

I hope this helps!


Thank you for the answer, @michaelhibay! I’m hope you are doing well with your new job.

This is contrived example, for easier understanding without subject area specific vocabulary.

You are right, I’m talking about polymorphic collection which will return resources of different types, but I understand that each type could have different relations in it (they are differ, thats why they have different types). I understand that resource !== object.

By providing example /parkings/{parking_id}?filter[type]=cars,trucks I suppose you meant /parkings/{parking_id}?filter[cars][type]=sedans,trucks. Because it’s not a parking for trucks only or sedans only. It’s parking, which could contain sedans as well as trucks. Parking could have it’s own types: open, underground, rooftop. And if we need to get all open parkings with cars of type sedan and truck only:

But all this stuff isn’t solving original issue I’ve tried to explain here. If I understand you right, we should avoid to have collection of resources which will return resources of different types if their descendant relations differ from each other.

In other words:

  • If resource1 has descendant relations child1 and child2 and resource2 has the same relations they could be collected into polymorphic-relation.
  • If descendant relations are differs - resource1 and resource2 shouldn’t be collected into polymorphic-relation.
  • If descendant relations are differs and resource1 and resource2 were collected into polymorphic-relation we should make extra requests to collect all relations for each item of this collection.

Did I understand you right?


Thanks, so far so good!

Ok, that certainly gives me some more perspective to understand the difficulty you are talking about.

The issue I was speaking about is the data shaping of a non-uniform set of message representations. The spec is very lenient to provide you the capability to offer this type of functionality, however the more customized you get the less likely the behavior of consumers would be across the ecosystem. If you control both, you can be a bit more custom but you need to project the definition of this behavior explicitly and completely.

The ability to construct this kind of data modeling is stretching the capabilities of the simple relationship traversal mechanism. In addition to the ability to determine the default included resources for any resource, you also have the option to include the deep nested relationship links to include higher order relationships without traversal of the long chains. In your example this could be something like cars-features, where the features are the trunk / trailer …etc.

One final note, since this is a contrived example I wasn’t trying to pick apart the example itself but perhaps this could give you an idea. The definition of cars and trucks as different resources is something which is complicating the solution space, because there is similar resources which are differentiated by something other than the query parameters.


The include parameter is expected to operate on a uniform set of resources, so what you can do is make the set uniform by containing the dynamic nature of the resource representations to a uniform pattern. Pass include parameter to include the features resource as well, and send only the relevant features by filtering.

Apologies if this example is a bit rushed and not completely vetted or confusing, but I’m out of time and my family is eager to begin the holiday celebrations! I hope something in here helps!


Thank you for diving deep and providing such detailed overview.

Thats very interesting idea to extract all uncommon relationships within collection to new abstract relationship and then filter it out by types you need.
For example if all the types MUST have wheels it could be kept as separate relationship, but all the rest will be collected to features relationship. Or even keep all the parts of the vehicle inside this features relationship.

The only thing I don’t like about this solution that frontend client will be required to have 2 separate transformers for truck resource which was received from /trucks?include=trailer and one more for truck resource which were received from polymorphic relation /parkings?include=vehicles,vehicles.features. And the same for each resource type which could be located in polymorphic collection.

At the beginning I’ve thought that you offer to make something like virtual ?include=vehicle.features parameter which will be transformed to something like ?include=sedan.trunk,truck.trailer under the hood. In this case structure of sedan & truck resources will be consistent in any time, but this breaks json:api spec as I understand.


The main issue with this way in my opinion - inconsistent resource structure. By the way this isn’t problem, it’s just possibility of the problem in the future. I cannot be 100% sure that it’s right or wrong, just leaving it here as a notice that more research required.

GET /trucks?include=trailer output:

  "data": [{
    "type": "truck",
    "id": "vehicle-1",
    "relationships": {
      "trailer": {
        "data": {
          "type": "trailer",
          "id": "vehicle-1-trailer"

GET /parkings?include=vehicles,vehicles.features

  "data": [{
    "type": "truck",
    "id": "vehicle-1",
    "relationships": {
      "features": {
        "data": {
          "type": "trailer",
          "id": "vehicle-1-trailer"



This could be open ended and asked in both directions, why does the structure have to be different from the two? I don’t think that is a good idea. Why is there a /truck resource? Shouldn’t it be /vehicle?filter[type]=truck, or is there some other reason? If the filter defines the truck resource well enough, why would the front end need a transformer in any other shape than the one?

Remember, resources are not objects and complex types are composed of other types so you have the latitude to define the composition format which makes most sense while serving the needs of the consumer.


I thought that creation of the trucks will be in POST /trucks endpoint, to have more precise relations (do not drop everything to features relation, but have many relations). Otherwise POST /vehicles endpoint handler will be very complex and hard to maintain if there will be a lot of types of vehicles, each type has it’s own collection of relations one of them required, and other don’t.


Remember that {json:api} documents are typed, so a simple switch statement or dynamic handler can easily allow each type processing to be separately developed and executed based on the type attribute in the root of the compound document. No additional complexity is introduced, the URL processor is simply behaving differently for a different message.

APIs are not CRUD, your payload does not need to be in the same format all the time at the same URL. You will always need to manage the ingestion of each message type, the only difference is that it isn’t at the /truck endpoint, instead it is at a common abstracted resource URL like /vehicle or /asdfnailsdilfasdf.