I have been working with JSON API for the past 9 months and have been under the assumption after reading the specification several times that Resources can be composed of other Resources when the relationship is composition or whole/part type of containment between Resources. Not that the specification directly said this but never directly said it could not and composition is so fundamental I just assumed composition was legal.
Let me give you a real world example: Here at work is an example JSON API document that represents a layout for a theater auditorium. A layout is composed of sections and seats for this example and I removed a lot of content just to show the composition intent:
{
"links": {
"up": "http://localhost:8040/v2/en-us/layouts",
"self": "http://localhost:8040/v2/en-us/layouts/1190874"
},
"data": {
"type": "layouts",
"id": "1190874",
"attributes": {
"name" : "Auditorium 1",
"sections": [
{
"type": "sections",
"id": "1190874-11-47-0",
"attributes": {
"name": "Reserved Seating",
"tags": [],
"version": null
},
"relationships": {
"resource-seating-type": {
"links": null,
"data": {
"type": "seating-types",
"id": "SelectASeat"
}
},
"collection-seat": {
"links": {
"related": "http://localhost:8040/v2/en-us/layouts/1190874/sections/1190874-11-47-0/seats"
},
"data": []
}
},
"links": {
"self": "http://localhost:8040/v2/en-us/layouts/1190874/sections/1190874-11-47-0"
}
}
],
"zones": [],
"seats": [],
"version": null
},
"relationships": {
"collection-section": {
"links": {
"related": "http://localhost:8040/v2/en-us/layouts/1190874/sections"
},
"data": [
{
"type": "sections",
"id": "1190874-11-47-0"
}
]
},
"collection-zone": {
"links": {
"related": "http://localhost:8040/v2/en-us/layouts/1190874/zones"
},
"data": []
},
"collection-seat": {
"links": {
"related": "http://localhost:8040/v2/en-us/layouts/1190874/seats"
},
"data": []
}
},
"links": {
"self": "http://localhost:8040/v2/en-us/layouts/1190874"
}
},
"included": [
{
"type": "seating-types",
"id": "SelectASeat",
"attributes": {
"name": "Select-A-Seat",
"isSeatSelectable": true
},
"relationships": null,
"links": {
"self": "http://localhost:8040/v2/en-us/seating-types/SelectASeat"
}
}
]
}
But after reading the following from the specification I believe that composition is not legal because Resources in the Attributes section of another Resource contains Relationships and Links which seems to be illegal based on the following part of the specification talking about the attributes object
of a Resource.
Complex data structures involving JSON objects and arrays are allowed as attribute values. However, any object that constitutes or is contained in an attribute MUST NOT contain a relationships or links member, as those members are reserved by this specification for future use.
Is this really the case that Resources can not be composed of other Resources or am I misinterpreting the part of the specification talking about the attributes object
of a Resource.