Table of Contents

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.

WorkOrderIdCodeRequiredByCompletedOnWorkRequiredAssetAssetIdCodeDescriptionDevelopmentStatusInheritanceTypeDepreciationSiteCreatedOnModifiedOnAssetDepreciationIdPercentagePerYearPeriodSiteIdCodeDescriptioncontainsreferencesreferences

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.

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

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.