Description
Currently the majority of examples for relationships in the specification include the resource linkage elements which a client could then infer if the relationship is "to-one" or "to-many" by examining the value of the "data" property. If the "data" property is an "object" or is null then "to-one", else if is an "array" empty or not then "to-many".
But if the resource linkage is not included in the response then a client could not infer if the relationship is a "to-one" or a "to-many" relationship. A client would want to know if it did a GET on the "related" resource URL for example should it expect 0 to 1 resource for a "to-one" relationship versus a 0 to many resources for a "to-many" relationship. This would apply to a GET/PUT/POST/PATCH on the "self" relationship URL as well.
Personally I don't think the client should have to infer anything, this should be explicit. The question is how should this be specified? Any suggestions?
I suppose some will say put this type of information in the "meta" object in the relationship "links" but this feels more like a hack/workaround IMHO - personally I think it should be part of the json-api specification? I came across this because in my C#/.NET modeling of JSON-API I have an abstract relationship class and concrete "to-one" and "to-many" relationship classes and on JSON deserialization without the resource linkage "data" element I hit an "uh-oh" moment.
As an example, taking your root example from the home page and removing the "resource linkage" elements you can not tell if the author or comments relationships are "to-one" or "to-many":
{
"links": {
"self": "http://example.com/posts",
"next": "http://example.com/posts?page[offset]=2",
"last": "http://example.com/posts?page[offset]=10"
},
"data": [
{
"type": "posts",
"id": "1",
"attributes": {
"title": "JSON API paints my bikeshed!"
},
"relationships": {
"author": {
"links": {
"self": "http://example.com/posts/1/relationships/author",
"related": "http://example.com/posts/1/author"
}
},
"comments": {
"links": {
"self": "http://example.com/posts/1/relationships/comments",
"related": "http://example.com/posts/1/comments"
}
}
},
"links": {
"self": "http://example.com/posts/1"
}
}
]
}