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.