Quick Answer
A sub-resource is a resource, which means it can have properties, sub-properties, and be as complex as any resource. The critical difference is that sub-resources do not appear alone but rather as members of a parent property. This is similar to how sub-properties are displayed, but there can be more than one sub-resource belonging to a parent property. For this reason, sub-resources are contained within a JSON array.
Digging Deeper
Sub-resources are normally used for two reasons. First, when the type of data represented by the sub-resource is not merely a composite of the parent property. Second, and most importantly, when the data represented by the sub-resource is subject to being repeated. To illustrate, let's reconsider the final resource object used in the What is a sub-property? article:
{
"mailing":{
"address":"PO Box 1234",
"city":"New Orleans",
"county":"Orleans",
"state":"LA",
"zip":"70116"
},
"shipping":{
"address":"6649 N Blue Gum St",
"city":"New Orleans",
"county":"Orleans",
"state":"LA",
"zip":"70116"
}
}
This sample resource object uses sub-properties because it assumes the mailing and shipping parent properties are unique but require their own (albeit similar) composite properties. Perhaps we need a resource object that allows for any number of addresses. Perhaps we need a resource object that allows users to define the type of addresses. Either or both of these situations are perfect candidates for using sub-resources. Let's start by seeing how the above resource object would look using sub-resources:
{
"addresses":[
{
"type":"Mailing",
"address":"PO Box 1234",
"city":"New Orleans",
"county":"Orleans",
"state":"LA",
"zip":"70116"
},
{
"type":"Shipping",
"address":"6649 N Blue Gum St",
"city":"New Orleans",
"county":"Orleans",
"state":"LA",
"zip":"70116"
}
]
}
We see that the mailing and shipping parent properties have been replaced with a single addresses parent property. Furthermore, to properly identify each address sub-resource, a type property has been added and the values of Mailing and Shipping have been assigned to them.
