Data Addressability with Trimble Resource Names (TRNs)
Trimble’s data inherently forms a web of linked resources. Users are linked to Entitlements; Drivers are linked to Vehicles; Projects are linked to Sites. To link these data resources – Users, Entitlements, Drivers, Vehicles, Projects, or Sites – they must have unambiguous, unique identifiers.
Trimble data resources are shared and retrieved across product boundaries via API. All Trimble resources exposed via API are assigned a specific structure and called a Trimble Resource Name or TRN. This identifier is intended to enhance internal system identifiers to ensure uniqueness across products and provide the necessary context to retrieve the resource.
There are currently two versions of the TRN structure. Both of these versions are described below.
Structure
TRNs are a form of URI using a custom URI scheme, “trn.” A TRN is composed of a series of path segments separated by a colon (”:”). Path segments are not case-sensitive and must use only valid URI characters.
All path segments are mandatory.
TRN Version 1
Structure
trn:<service>:<resource-type>:<extension>
Path Segments
Service
The first component after the TRN scheme identifies the service or system (e.g., TID) that created the TRN.
Resource Type
The type component of a TRN such as files has traditionally been used to identify the TRN’s service-specific data type. Resource types are assumed to be local to the Service.
The name of the resource type must match the name of the resource type in the url path of the resource server (or equivalent). For example, in the Processing Framework service, the path to retrieve an execution is .../processing/executions/{execution_id}, so the TRN should be trn:2:processing:ap_au:executions:{execution_id}.
Extension
The final component of a TRN represents any relevant addressing information such as a service-specific identifier like k-PEcTYKNqo for the associated data within the service’s internal context. The extension supports integration with existing applications, many of which already have application-local identifiers for exposed data. This component is unrestricted for service-specific use. Trimble suggests alphanumeric local IDs that align with the service’s primary keys.
Example
trn:profiles:devices:3bvTIG_hLCjwhMCFTZy15R
TRN Version 2
Version 2 adds two new fields to the TRN: version and region.
Structure
trn:<version>:<service>:<region>:<resource-type>:<extension>
Path Segements
Version
Identifies the major version of the TRN format. This can be used by clients to determine how to parse the remainder of the TRN. TRN versions are meant to change infrequently (on the order of years). The structure documented here is version 2.
Service
Identifies the service or system (e.g., tid) that created and owns the TRN. This name must match the name of the application in IAM.
Region
Defines the physical region where the resource metadata is stored. This is relevant for data residency, compliance, and contractual requirements.
Since Trimble follows a multi-cloud paradigm, the names of the regions that we support will not match the ones used by cloud providers like AWS or Azure. Instead, values are defined for the Trimble platform. The currently supported region values are: us (United States), eu (Europe), eu-gb (United Kingdom), ap (Asia Pacific), and ap-au (Australia).
In cases where a resource is truly global, for example, TID applications, the region value should be specified as global.
Resource Type
Identifies the TRN’s service-specific data type. For example, file, application, comment, or user. The name of the resource type should match the name of the resource type in the path of the resource server. For example, in the Processing Framework service, the path to retrieve an execution is .../processing/executions/{execution_id}, so the TRN should be trn:2:processing:ap_au:executions:{execution_id}.
Extension
Represents the relevant addressing information for the associated data within the service’s internal context. For example, a service-specific identifier, such as a UUID.
The extension supports integration with existing applications, many of which already have application-local identifiers for their resources. This component is unrestricted for service-specific use.
Example
trn:2:fileservice:us:files:3529d0b3-5856-41ab-88b3-86f7955cddf2