Reference Types

Custom reference types let you define domain-specific relationships between nodes beyond the standard OPC UA reference types (HasComponent, HasProperty, Organizes, etc.).

Basic reference type
referenceTypes:
  - browseName: HasMotor
    inverseName: IsMotorOf
    isAbstract: false
    symmetric: false
    subtypeOf: ua:HierarchicalReferences
    description: |
      Connects a machine to its motor assembly.

Fields

Field	Required	Description
`browseName`	✅	Name of the reference type (PascalCase, prefix with `Has` or `Is…Of` by convention)
`inverseName`	—	The inverse name shown when browsing in the reverse direction
`isAbstract`	—	`true` if this type cannot be used directly (default: `false`)
`symmetric`	—	`true` if the reference has the same meaning in both directions (e.g. `Connects`)
`subtypeOf`	—	Parent reference type (default: `ua:References`)
`description`	—	Human-readable description

Standard subtypes to extend

Base type	Use for
`ua:HierarchicalReferences`	Parent–child relationships (tree navigation)
`ua:NonHierarchicalReferences`	Peer relationships (cross-links)
`ua:HasComponent`	Composition (object contains another object)
`ua:HasProperty`	Property ownership

Example: physical topology references

Physical topology reference types
referenceTypes:
  - browseName: IsPhysicallyConnectedTo
    inverseName: IsPhysicallyConnectedTo
    symmetric: true
    subtypeOf: ua:NonHierarchicalReferences
    description: Indicates a physical cable or pipe connection between two components.
  
  - browseName: HasSafetyController
    inverseName: IsSafetyControllerOf
    subtypeOf: ua:NonHierarchicalReferences
    description: Links a machine to the safety controller that supervises it.

Using custom reference types

Once defined, use a custom reference type in the top-level references: section. Each entry requires both a source: and a target: as absolute browse paths:

Applying a custom reference
# Cross-instance references go in the top-level references: section,
# with both source: and target: as absolute browse paths.
references:
  - referenceType: IsPhysicallyConnectedTo
    source: /ua:Objects/Pump1
    target: /ua:Objects/Motor1

note

references: entries always require an explicit source: and target: field, both as absolute browse paths (e.g. /ua:Objects/Motor1). See Explicit References for the full reference.

📄 Full working example — reference-types.model.yaml

reference-types.model.yaml
# yaml-language-server: $schema=../../../../schemas/nodeset2.schema.json
#
# Living documentation example for: s35_reference-types.md
# Validate: opcua-modeler generate --input reference-types.model.yaml

namespaceUri: http://example.com/doc/reference-types/
version: 1.0.0

referenceTypes:
  - browseName: HasMotor
    inverseName: IsMotorOf
    isAbstract: false
    symmetric: false
    subtypeOf: ua:HierarchicalReferences
    description: |
      Connects a machine to its motor assembly.

  - browseName: IsPhysicallyConnectedTo
    inverseName: IsPhysicallyConnectedTo
    symmetric: true
    subtypeOf: ua:NonHierarchicalReferences
    description: Indicates a physical cable or pipe connection between two components.

  - browseName: HasSafetyController
    inverseName: IsSafetyControllerOf
    subtypeOf: ua:NonHierarchicalReferences
    description: Links a machine to the safety controller that supervises it.

# ── Types needed by the "using custom references" snippet ─────────────────────
objectTypes:
  - browseName: MotorType
  - browseName: PumpType

instances:
  - browseName: Motor1
    typeDefinition: MotorType
    organizedBy: /ua:Objects

  - browseName: Pump1
    typeDefinition: PumpType
    organizedBy: /ua:Objects

# Cross-instance references go in the top-level references: section,
# with both source: and target: as absolute browse paths.
references:
  - referenceType: IsPhysicallyConnectedTo
    source: /ua:Objects/Pump1
    target: /ua:Objects/Motor1

📄 Generated NodeSet2.xml — reference-types.model.Nodeset2.xml

reference-types.model.Nodeset2.xml
<?xml version="1.0"?>
<UANodeSet xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:uax="http://opcfoundation.org/UA/2008/02/Types.xsd" xmlns="http://opcfoundation.org/UA/2011/03/UANodeSet.xsd" xmlns:ns1="http://example.com/doc/reference-types/Type.xsd">
    <NamespaceUris>
        <Uri>http://example.com/doc/reference-types/</Uri>
    </NamespaceUris>
    <Models>
        <Model ModelUri="http://example.com/doc/reference-types/" Version="1.0.0" PublicationDate="2026-05-26T09:25:00.000Z">
            <RequiredModel ModelUri="http://opcfoundation.org/UA/" Version="1.05.06" PublicationDate="2025-11-08T00:00:00.000Z"/>
        </Model>
    </Models>
    <Aliases>
        <Alias Alias="1:IsPhysicallyConnectedTo">ns=1;i=1001</Alias>
        <Alias Alias="HasSubtype">i=45</Alias>
        <Alias Alias="HasTypeDefinition">i=40</Alias>
        <Alias Alias="Organizes">i=35</Alias>
    </Aliases>
<!--ReferenceTypes-->
    <UAReferenceType NodeId="ns=1;i=1001" BrowseName="1:IsPhysicallyConnectedTo" Symmetric="true">
        <DisplayName>IsPhysicallyConnectedTo</DisplayName>
        <Description>Indicates a physical cable or pipe connection between two components.</Description>
        <References>
            <Reference ReferenceType="HasSubtype" IsForward="false">i=32</Reference>
        </References>
    </UAReferenceType>
    <UAReferenceType NodeId="ns=1;i=1002" BrowseName="1:HasSafetyController">
        <DisplayName>HasSafetyController</DisplayName>
        <Description>Links a machine to the safety controller that supervises it.</Description>
        <References>
            <Reference ReferenceType="HasSubtype" IsForward="false">i=32</Reference>
        </References>
        <InverseName>IsSafetyControllerOf</InverseName>
    </UAReferenceType>
    <UAReferenceType NodeId="ns=1;i=1000" BrowseName="1:HasMotor">
        <DisplayName>HasMotor</DisplayName>
        <Description>Connects a machine to its motor assembly.</Description>
        <References>
            <Reference ReferenceType="HasSubtype" IsForward="false">i=33</Reference>
        </References>
        <InverseName>IsMotorOf</InverseName>
    </UAReferenceType>
<!--ObjectTypes-->
<!--ObjectType - 1:MotorType {{{{ -->
    <UAObjectType NodeId="ns=1;i=1003" BrowseName="1:MotorType">
        <DisplayName>MotorType</DisplayName>
        <References>
            <Reference ReferenceType="HasSubtype" IsForward="false">i=58</Reference>
        </References>
    </UAObjectType>
<!--ObjectType - 1:MotorType }}}}-->
<!--ObjectType - 1:PumpType {{{{ -->
    <UAObjectType NodeId="ns=1;i=1004" BrowseName="1:PumpType">
        <DisplayName>PumpType</DisplayName>
        <References>
            <Reference ReferenceType="HasSubtype" IsForward="false">i=58</Reference>
        </References>
    </UAObjectType>
<!--ObjectType - 1:PumpType }}}}-->
<!--VariableTypes-->
<!--Other Nodes-->
<!--Object - 1:Motor1 {{{{ -->
    <UAObject NodeId="ns=1;i=1005" BrowseName="1:Motor1">
        <DisplayName>Motor1</DisplayName>
        <References>
            <Reference ReferenceType="Organizes" IsForward="false">i=85</Reference>
            <Reference ReferenceType="HasTypeDefinition">ns=1;i=1003</Reference>
        </References>
    </UAObject>
<!--Object - 1:Motor1 }}}} -->
<!--Object - 1:Pump1 {{{{ -->
    <UAObject NodeId="ns=1;i=1006" BrowseName="1:Pump1">
        <DisplayName>Pump1</DisplayName>
        <References>
            <Reference ReferenceType="Organizes" IsForward="false">i=85</Reference>
            <Reference ReferenceType="HasTypeDefinition">ns=1;i=1004</Reference>
            <Reference ReferenceType="1:IsPhysicallyConnectedTo">ns=1;i=1005</Reference>
        </References>
    </UAObject>
<!--Object - 1:Pump1 }}}} -->
</UANodeSet>

Fields​

Standard subtypes to extend​

Example: physical topology references​

Using custom reference types​

Fields

Standard subtypes to extend

Example: physical topology references

Using custom reference types