Property Identifiers

Property identifiers define a syntax that can be used to reference and explore the properties and relationships between resources. Property identifiers are expressed using either Property Name or Property Path syntax.

To illustrate these important concepts, consider the following example resource definitions.

The diagram shows the relationships between WorkOrder, Asset and Site resources. It also shows the AssetDepreciation information for the Asset.

Property Name syntax

A Property Name identifier consists out of the full path for a property identifier. Relationships to other resources are expanded by appending the name of the resource property to the existing property name.

Note

Property name syntax is case-insensitive

Here are some examples of addressing the Asset resource and its relationships using Property Name syntax:

Asset Resource	Syntax
Id	Id
Code	Code
Description	Description
DevelopmentStatus	DevelopmentStatus
InheritanceType	InheritanceType
Depreciation Id	DepreciationId
Depreciation PercentagePerYear	DepreciationPercentagePerYear
Site Code	SiteCode
Site Description	SiteDescription
WorkOrder WorkRequired	IdWorkOrderAssetWorkRequired

Property Path syntax

A Property Path identifier consists out of:

Element	Description
Resource name	Name of the resource that the property belongs to
->	Delimiter to separate the resource name from the property path
Path	The path to the locate the property using the property path join syntax.

Note

Property path syntax is case-insensitive

Here are some examples of addressing the example Asset resource and its relationships using Property Path syntax:

Asset Resource	Syntax
Id	Asset->Id
Code	Asset->Code
Description	Asset->Description
DevelopmentStatus	Asset->DevelopmentStatus
InheritanceType	Asset->InheritanceType
Depreciation Id	Asset->Depreciation_Id
Depreciation PercentagePerYear	Asset->Depreciation_PercentagePerYear
Site Code	Asset->Site_Code
Site Description	Asset->Site_Description
WorkOrder WorkRequired	Asset->*Id.WorkOrder.Asset_WorkRequired

To understand the above mentioned Property Name and Property Path syntax examples, we need to further explain the join syntax used to expand and traverse the different associations/relationships between resources.

Join syntax

Resource joins are expanded in Property Path syntax using a _ delimiter. Every time a _ delimiter occurs, a join is executed onto the destination resource. Further expansion within the Property Path then refers to the properties that reside on the joined/target resource. For example, the property path Asset->Site_Code traverses the Site reference from the Asset to select the Code of the Site resource.

Resource joins are expanded in Property Name syntax by simply joining the property names of the resources together (i.e, no delimiters are used). For example, the property identifier SiteCode on an Asset, traverses the Site reference to select the Code of the Site resource.

Property Path and Property Name identifiers supports joining/linking/expanding to other resources using either normal or cross reference links.

Normal links

A normal link is defined as a strong association between two different resources or between different sub-elements of the same resource (aka extensions). For the above mentioned scenario, the relationships to the Site and AssetDepreciation on the Asset are considered normal links as the data model contains physical links from the Asset to these resources.

Name Syntax	Path Syntax
SiteCode	Asset->Site_Code
DepreciationPercentagePerYear	Asset->Depreciation_PercentagePerYear

Cross reference links

A cross reference link is defined as a weak association between two different resources. Cross references links are available on some resources to enable linking between resources when there is no direct relationship in the data model, but there still exists a logical relationship that can be explored. The available cross reference links for a resource can be identified by inspecting the Association hypermedia links published with a resource.

For the above mentioned scenario, the relationship from the WorkOrder to the Asset is a cross reference link. Expanding the WorkOrder cross reference on the Asset will allow us to find the Work Order related information for work executed on the Asset.

Name Syntax	Path Syntax
IdWorkOrderAssetWorkRequired	Asset->*Id.WorkOrder.Asset_WorkRequired
Not supported	Asset->*[Id.WorkOrder.Asset]_WorkRequired

Property Path Cross Reference

In Property Path syntax, cross reference links are written using the following syntax:

'*' SourceProperty '.' TargetResource '.' TargetProperty

Example:
Asset->*Id.WorkOrder.Asset_WorkRequired

The elements of the cross reference, can be broken down into:

Element	Description
*	Delimiter to indicate start of cross reference link for the current Source resource (Asset)
Id	Source property on the Source resource (Asset) to use in the cross reference join
.	Delimiter to separate the Source resource (Asset) from the Target resource (WorkOrder)
WorkOrder	Target resource to join Source resource (Asset) with
.	Delimiter to separate the Target resource (WorkOrder) from its Target property (Asset)
Asset	Target property on the WorkOrder Target resource to use in the cross reference join with the Id Source property on the Asset Source resource

Important

Cross reference links by default are compulsory which implies that if no association exists (i.e. the Asset has no WorkOrder associated with it), no information for the Asset resource will be returned (similar to INNER JOIN in a RDBMS).

To return data for the Asset resource even if it has no WorkOrder associated with it, you can mark the cross reference as an optional association (similar to LEFT OUTER JOIN in a RDBMS) by wrapping the cross reference with [ and ] delimiters.

The Property Path syntax for creating an optional cross reference property identifier is:

'*[' SourceProperty '.' TargetResource '.' TargetProperty ']'

Example:
Asset->*[Id.WorkOrder.Asset]_WorkRequired

Property Name Cross Reference

In Property Name syntax, cross reference links are written using the following syntax:

SourceProperty + TargetResource + TargetProperty

Example:
IdWorkOrderAssetWorkRequired

Important

Property Name syntax only supports compulsory cross reference links. Optional cross reference links can only be specified using Property Path syntax.