Explicit References

The top-level references: section declares explicit OPC UA references between nodes. Use this when the placement helpers (organizedBy, componentOf, etc.) are not expressive enough, or when you need a custom reference type.

Each entry requires both source: and target: as absolute browse paths:

Basic explicit reference

references:
  - referenceType: IsPhysicallyConnectedTo
    source: /ua:Objects/Pump1
    target: /ua:Objects/Motor1
    isForward: true

---

Fields

Field	Required	Description
referenceType	✅	The reference type to use. Can be a standard UA type or a custom referenceType defined in this file.
source	✅	Absolute browse path of the source node (e.g. /ua:Objects/Pump1)
target	✅	Absolute browse path of the target node (e.g. /ua:Objects/Motor1)
isForward	—	Direction of the reference. true (default) = source → target; false = target → source

important

Both source: and target: must be absolute browse paths starting with /. Plain browse names (e.g. Motor1) are not resolved in this context.

---

Standard reference types

Reference type	Description
ua:HasComponent	Composition
ua:HasProperty	Property
ua:Organizes	Folder organisation
ua:HasTypeDefinition	Type instantiation
ua:HasModellingRule	Modelling rule
ua:HasInterface	Interface implementation
ua:GeneratesEvent	Event generation

---

Custom reference types

References defined in the referenceTypes: section of your model can be used directly. Define the types, declare the instances, then link them in the top-level references: section:

Using a custom reference type

# Additional reference (appended to references: section)
  - referenceType: IsPhysicallyConnectedTo
    source: /ua:Objects/Pump2
    target: /ua:Objects/Motor1

Because IsPhysicallyConnectedTo is symmetric, the modeler generates only one reference (the forward one) and the OPC UA server handles the inverse automatically.

---

Cross-namespace targets

Reference a node in an imported namespace using its namespace alias and browse path:

references:
  - referenceType: ua:Organizes
    source: /ua:Objects/MyDevice
    target: /ua:Objects/ua:Server
    isForward: false

📄 Full working example — references.model.yaml

references.model.yaml

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

namespaceUri: http://example.com/doc/references/
version: 1.0.0

# ── Custom reference type + types needed by instance snippets ─────────────────
referenceTypes:
  - browseName: IsPhysicallyConnectedTo
    inverseName: IsPhysicallyConnectedTo
    symmetric: true
    subtypeOf: ua:NonHierarchicalReferences
    description: Physical cable or pipe connection between two components.

objectTypes:
  - browseName: MotorType
  - browseName: PumpType

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

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

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

# Cross-instance references use the top-level references: section.
# Each entry needs both source: and target: as absolute browse paths.

references:
  - referenceType: IsPhysicallyConnectedTo
    source: /ua:Objects/Pump1
    target: /ua:Objects/Motor1
    isForward: true

# Additional reference (appended to references: section)
  - referenceType: IsPhysicallyConnectedTo
    source: /ua:Objects/Pump2
    target: /ua:Objects/Motor1

📄 Generated NodeSet2.xml — references.model.Nodeset2.xml

references.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/references/Type.xsd">
    <NamespaceUris>
        <Uri>http://example.com/doc/references/</Uri>
    </NamespaceUris>
    <Models>
        <Model ModelUri="http://example.com/doc/references/" 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=1000</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=1000" BrowseName="1:IsPhysicallyConnectedTo" Symmetric="true">
        <DisplayName>IsPhysicallyConnectedTo</DisplayName>
        <Description>Physical cable or pipe connection between two components.</Description>
        <References>
            <Reference ReferenceType="HasSubtype" IsForward="false">i=32</Reference>
        </References>
    </UAReferenceType>
<!--ObjectTypes-->
<!--ObjectType - 1:MotorType {{{{ -->
    <UAObjectType NodeId="ns=1;i=1001" 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=1002" 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=1003" BrowseName="1:Motor1">
        <DisplayName>Motor1</DisplayName>
        <References>
            <Reference ReferenceType="Organizes" IsForward="false">i=85</Reference>
            <Reference ReferenceType="HasTypeDefinition">ns=1;i=1001</Reference>
        </References>
    </UAObject>
<!--Object - 1:Motor1 }}}} -->
<!--Object - 1:Pump1 {{{{ -->
    <UAObject NodeId="ns=1;i=1004" BrowseName="1:Pump1">
        <DisplayName>Pump1</DisplayName>
        <References>
            <Reference ReferenceType="Organizes" IsForward="false">i=85</Reference>
            <Reference ReferenceType="HasTypeDefinition">ns=1;i=1002</Reference>
            <Reference ReferenceType="1:IsPhysicallyConnectedTo">ns=1;i=1003</Reference>
        </References>
    </UAObject>
<!--Object - 1:Pump1 }}}} -->
<!--Object - 1:Pump2 {{{{ -->
    <UAObject NodeId="ns=1;i=1005" BrowseName="1:Pump2">
        <DisplayName>Pump2</DisplayName>
        <References>
            <Reference ReferenceType="Organizes" IsForward="false">i=85</Reference>
            <Reference ReferenceType="HasTypeDefinition">ns=1;i=1002</Reference>
            <Reference ReferenceType="1:IsPhysicallyConnectedTo">ns=1;i=1003</Reference>
        </References>
    </UAObject>
<!--Object - 1:Pump2 }}}} -->
</UANodeSet>