Skip to content

Customization Properties

The Connect API interface is implemented by multiple applications. These applications implement some features with different approaches and even different data. Adapting a single interface to the needs of all these applications can be challenging.

We want to maintain a strict schema for the Connect API interface, but we also want applications to support additional functionality that their users need without breaking the interface and without complicating the interface for other implementations.

For those reasons, Data Properties and Reference Properties were introduced.

After reading this article you will understand:

  • How to expose and use data properties.
  • How to expose and use reference properties.
  • What's the difference between data and reference properties.

Data Properties

The initial design of the Connect API minimized the number of properties that were exposed for a particular resource to the minimum needed to make the resource useful. We understood that if we found use cases where additional properties were needed, we could add them later without breaking the interface.

Later on, new implementations of the Connect API were created for other products and new use cases were found. This required that we expose additional properties in the interface, even when some of them did not apply to all implementations.

It became obvious that extending the interface by adding all types of properties to resources was not the right way to handle implementation-specific data, which led us to the design of Data Properties.

Data Properties are the means by which a specific implementation can extend the data provided to clients without enforcing those properties on other implementations. Data Properties place the burden on clients, which need to understand how to process them even when they might not be present. This approach works because clients are usually the ones dictating new use cases where Data Properties are required.

Data Properties Structure

Data Properties are exposed through a data property at the root of a resource. This property contains an array of properties representing the additional data. Data Properties can be added to any resource in the Connect API. As a matter of fact, most extensions in the future will be done through Data Properties.

The data array contains objects with the following schema:

{
  // Resource representation omitted for clarity.
  "data": [
    {
      "name": "Property Name",
      "key": "tmsPropertyIdentifier",
      "value": "property value",
      "type": "optional type"
    }
  ]
}

A data property is a JSON object that contains the following properties:

  • name: The standard name of the property. We want Product Management to dictate what the name of the property should be and it should always be provided in title-case as in "Property Name".
  • key: The key is an implementation specific value that helps the implementation to identify the property in their system. This value is optional, but it will help the implementation to deal with creation and updates of resources.
  • value: The value of the property; the data provided to/by the implementation.
  • type: The optional type of the property. It specifies how the property should be interpreted.

ℹ️ Properties have standard values in JSON. These are numbers, strings, booleans, etc. Sometimes a value has a specific interpretation. For example, a string can contain the representation of an ISO-formatted date/time. The type of the Data Property object should be used to indicate this so clients can choose how to process the value.

Data Properties Guidelines

The addition of Data Properties is usually driven by a client that needs the information out of the implementation. The implementation then exposes the data in a Data Property. Because of the optional nature of these properties, you should avoid business logic that depends on the values of those properties.

Data Properties are a good way to provide additional data for display purposes. They also are a good candidate for clients to add additional data to resources when they understand a specific implementation.

In all other cases, Data Properties should be handled generically, avoiding bad behavior if they are not present.

Reference Properties

Reference Properties are another means to provide custom values through the API. You might be confused by the similarity between Reference Properties and Data Properties, but they serve different purposes. Reference Properties expose data that refer to an external system.

For example, think about an implementation that exposes data about a Shipment resource, and a third-party client that integrates those Shipment orders with an accounting system. The internal ID of a customer within the implementation will likely differ from the ID or account number in the accounting system. A Reference Property can be used by the implementation to provide this scenario-specific data without forcing other implementations to support it.

Reference Properties Structure

The structure of Reference Properties matches that of the Data Properties, which causes some confusion until you understand the purpose of each one of them. Reference Properties are exposed as a referenceData property at the root of a resource, and it is also an array of objects.

The referenceData array will have the same structure we saw before:

{
  // Resource representation omitted for clarity.
  "referenceData": [
    {
      "name": "Reference Name",
      "key": "tmsReferenceIdentifier",
      "value": "reference value",
      "type":  "optional type"
    }
  ]
}

The purpose of each of the attributes in the Reference Property object is the exact same as with Data Properties.

Data vs. Reference Properties

Data and Reference properties allow implementations to provide custom values to clients. They have the same structure, which makes it confusing. Why separate them?

The reason for the separation has to do with their purpose. Where Data Properties apply to a resource and its characteristics, Reference Properties refer to the characteristics of external systems.

Imagine the Equipment Container resource that describes a container. An implementation might decide that a color property is important to their system, and a client might want to use it. This can be exposed through a Data Property.

Now imagine that Equipment Container has a tracking device implemented by a third-party, and the device itself has a serial number that only has meaning in the context of that third-party system. If the value should be exposed to clients, it should be done as a Reference Property.

Conclusion

Data and Reference Properties provide a means for implementations to customize the data they provide to clients without breaking the Connect API specification. They are a way to provide internal details to clients.

Data and Reference Properties are similar and sometimes confusing. To understand them, it is important to know that Data Properties describe characteristics of the resource, whereas Reference Properties describe properties of an external system.

In the future, most additions to the Connect API will be done as Data or Reference Properties in order to strengthen the common schema and ease implementation.