What is a sub-property?

Quick Answer

In the context of a resource object (i.e., a resource represented as a JSON object), a sub-property is a synonym, or shorthand expression, for a JSON name/value pair that is subordinate to (i.e., belongs to) a parent property.

Digging Deeper

Sub-Properties are used when a regular property is a composite of other identifying properties. An example works well to illustrate:

{
   "shipping":{
      "address":"6649 N Blue Gum St",
      "city":"New Orleans",
      "county":"Orleans",
      "state":"LA",
      "zip":"70116"
   }
}

The above resource object is very similar to the one used in our What is a property? article. The difference is that the shipping property is the parent property of address, city, county, state, and zip. The latter are considered sub-properties.

Developers are not required to use sub-properties. In the above example, each of the sub-properties could have been regular properties in the resource object. However, let's suppose there are different types of addresses in the resource object. We'll use mailing and shipping. If both types of addresses were represented by regular properties then the resource object might look like this:

{
   "mailingAddress":"PO Box 1234",
   "mailingCity":"New Orleans",
   "mailingCounty":"Orleans",
   "mailingState":"LA",
   "mailingZip":"70116",
   "shippingAddress":"6649 N Blue Gum St",
   "shippingCity":"New Orleans",
   "shippingCounty":"Orleans",
   "shippingState":"LA",
   "shippingZip":"70116"
}

This isn't horrible, but we might consider that sub-properties help to make this look better and help it to be better organized:

{
   "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"
   }
}