1 Scope
This document specifies an official OPC UA binding for the W3C Web of Things (WoT). WoT Thing Description can be specified with relevant OPC UA metadata that provides information such as how to access an OPC UA server and its datapoints (UA variables) and methods, as well as the security requirements.
OPC Foundation
OPC is the interoperability standard for the secure and reliable exchange of data and information in the industrial automation space and in other industries. It is platform independent and ensures the seamless flow of information among devices from multiple vendors. The OPC Foundation is responsible for the development and maintenance of this standard.
OPC UA is a platform independent service-oriented architecture that integrates all the functionality of the individual OPC Classic specifications into one extensible framework. This multi-layered approach accomplishes the original design specification goals of:
Platform independence: from an embedded microcontroller to cloud-based infrastructure
Secure: encryption, authentication, authorisation, and auditing
Extensible: ability to add new features including transports without affecting existing applications
Comprehensive information modelling capabilities: for defining any model from simple to complex
The W3C and W3C Web of Things
The World Wide Web Consortium (W3C), founded in 1994 by web inventor Tim Berners-Lee, plays a crucial role in shaping the future of the internet. By developing standards and guidelines, the W3C promotes a web that is accessible to everyone, while also ensuring that internationalization, privacy, and security remain core principles. These web standards serve as the foundational elements of a coherent and universally connected digital landscape, being implemented across browsers, blogs, search engines, and other software. This widespread implementation ensures a seamless and rich web experience for users worldwide.
The Web of Things (WoT) Working Group at the W3C aims to address the fragmentation within the Internet of Things (IoT) by leveraging and enhancing already existing standardized Web technologies. By offering standardized metadata and reusable technology building blocks, W3C WoT facilitates seamless integration across various IoT platforms and application domains.
2 Normative references
The following referenced documents are indispensable for the application of this document. For dated references, only the edition cited applies. For undated references, the latest edition of the referenced document (including any amendments and errata) applies.
OPC 10000-1, OPC Unified Architecture - Part 1: Overview and Concepts
http://www.opcfoundation.org/documents/10000-1/
OPC 10000-2, OPC Unified Architecture - Part 2: Security Model
http://www.opcfoundation.org/documents/10000-2/
OPC 10000-3, OPC Unified Architecture - Part 3: Address Space Model
http://www.opcfoundation.org/documents/10000-3/
OPC 10000-4, OPC Unified Architecture - Part 4: Services
http://www.opcfoundation.org/documents/10000-4/
OPC 10000-5, OPC Unified Architecture - Part 5: Information Model
http://www.opcfoundation.org/documents/10000-5/
OPC 10000-6, OPC Unified Architecture - Part 6: Mappings
http://www.opcfoundation.org/documents/10000-6/
OPC 10000-7, OPC Unified Architecture - Part 7: Profiles
http://www.opcfoundation.org/documents/10000-7/
W3C Web of Things (WoT) Thing Description 1.1
https://www.w3.org/TR/wot-thing-description11/
3 Terms, abbreviated terms and conventions
3.1 Overview
It is assumed that basic concepts of OPC UA information modelling and W3C Web of Things are understood in this document. This document will use these concepts to describe the Web of Things for OPC UA Information Model. For the purposes of this document, the terms and definitions given in OPC 10000-1, OPC 10000-3, OPC 10000-4, OPC 10000-5, as well as the following apply.
Note that OPC UA terms and terms defined in this document are italicized in the document.
3.2 WoT Connectivity for OPC UA terms
3.2.1 Protocol Binding
Part of Web of Things Thing Description describing the communication interface as well as the data “tags” available in an asset.
3.2.2 Untitled
3.3 Abbreviated terms
| JSON-LD | JavaScript Object Notation for Linked Data |
| TD | Thing Description |
| URI | Uniform Resource Identifier |
| WoT | Web of Things |
4 General information to W3C Web of Things and OPC UA
4.1 Introduction to W3C Web of Things
In most IoT projects, developers deal with a variety of technologies from multiple vendors. They need to handle different communication protocols, data models, and security requirements. Since IoT applications are usually tailored for particular uses, they can be challenging to expand, maintain, or reuse later on.
The Web of Things (WoT) simplifies IoT application development by using standard technology building blocks based on the successful Web paradigm. This approach enhances flexibility, interoperability, and cross-domain application use while enabling the reuse of established standards and tools. WoT also addresses the commercial limitations caused by IoT fragmentation.
WoT offers a simple interaction model with properties, events, and actions. Any IoT network interface can be described in terms of this abstraction. By using this abstraction, applications have a common anchor to retrieve an IoT service’s metadata as well as way to understand what and how the data and an IoT services' functions can be accessed.
The metadata of an IoT device, which includes all necessary information to enable a common abstraction, is documented in what is known as a WoT Thing Description (TD). The TD is a key component in the W3C Web of Things and serves as the entry point for an IoT instance, similar to how index.html functions for a website. It provides details on available data and functions, the protocols used, data encoding and structure, security mechanisms for access control, and additional machine-readable and human-readable metadata. A TD is written in JSON-LD and can be supplied by the IoT device itself or hosted externally in a repository such as a TD Directory.
In general, WoT is a protocol agnostic approach and provides a common mechanism to define how specific protocols such as MQTT, HTTP, CoAP or Modbus can be mapped to the WoT’s interaction properties-action-event abstraction.
This mapping and protocol specific metadata are provided by the WoT Binding Templates. A binding template for a specific protocol provides a guideline how a client can activate each WoT interaction abstraction through a corresponding network-facing interface for that protocol.
4.2 Introduction to OPC Unified Architecture
4.2.1 What is OPC UA?
OPC UA is an open and royalty free set of standards designed as a universal communication protocol. While there are numerous communication solutions available, OPC UA has key advantages:
A state of art security model (see OPC 10000-2).
A fault tolerant communication protocol.
An information modelling framework that allows application developers to represent their data in a way that makes sense to them.
OPC UA has a broad scope which delivers for economies of scale for application developers. This means that a larger number of high-quality applications at a reasonable cost are available. When combined with semantic models such as Web of Things, OPC UA makes it easier for end users to access data via generic commercial applications.
The OPC UA model is scalable from small devices to ERP systems. OPC UA Servers process information locally and then provide that data in a consistent format to any application requesting data - ERP, MES, PMS, Maintenance Systems, HMI, Smartphone, or a standard Browser, for examples. For a more complete overview see OPC 10000-1.
4.2.2 Basics of OPC UA
As an open standard, OPC UA is based on standard internet technologies, like TCP/IP, HTTP, Web Sockets.
As an extensible standard, OPC UA provides a set of Services (see OPC 10000-4) and a basic information model framework. This framework provides an easy manner for creating and exposing vendor defined information in a standard way. More importantly all OPC UA Clients are expected to be able to discover and use vendor-defined information. This means OPC UA users can benefit from the economies of scale that come with generic visualisation and historian applications. This specification is an example of an OPC UA Information Model designed to meet the needs of developers and users.
OPC UA Clients can be any consumer of data from another device on the network to browser based thin clients and ERP systems. The full scope of OPC UA applications is shown in Figure 1.

OPC UA provides a robust and reliable communication infrastructure having mechanisms for handling lost messages, failover, heartbeat, etc. With its binary encoded data, it offers a high-performing data exchange solution. Security is built into OPC UA as security requirements become more and more important especially since environments are connected to the office network or the internet and attackers are starting to focus on automation systems.
4.2.3 Information modelling in OPC UA
4.2.3.1 Concepts
OPC UA provides a framework that can be used to represent complex information as Objects in an AddressSpace which can be accessed with standard services. These Objects consist of Nodes connected by References. Different classes of Nodes convey different semantics. For example, a Variable Node represents a value that can be read or written. The Variable Node has an associated DataType that can define the actual value, such as a string, float, structure etc. It can also describe the Variable value as a variant. A Method Node represents a function that can be called. Every Node has a number of Attributes including a unique identifier called a NodeId and non-localized name called as BrowseName. An Object representing a ‘Reservation’ is shown in Figure 2.

Object and Variable Nodes represent instances and they always reference a TypeDefinition (ObjectType or VariableType) Node which describes their semantics and structure. Figure 3 illustrates the relationship between an instance and its TypeDefinition.
The type Nodes are templates that define all of the children that can be present in an instance of the type. In the example in Figure 3 the PersonType ObjectType defines two children: First Name and Last Name. All instances of PersonType are expected to have the same children with the same BrowseNames. Within a type the BrowseNames uniquely identify the children. This means Client applications can be designed to search for children based on the BrowseNames from the type instead of NodeIds. This eliminates the need for manual reconfiguration of systems if a Client uses types that multiple Servers implement.
OPC UA also supports the concept of sub-typing. This allows a modeller to take an existing type and extend it. There are rules regarding sub-typing defined in OPC 10000-3, but in general they allow the extension of a given type or the restriction of a DataType. For example, the modeller can decide that the existing ObjectType in some cases needs an additional Variable. The modeller can create a subtype of the ObjectType and add the Variable. A Client that is expecting the parent type can treat the new type as if it was of the parent type. Regarding DataTypes, subtypes can only restrict. If a Variable is defined to have a numeric value, a subtype could restrict it to a float.

References allow Nodes to be connected in ways that describe their relationships. All References have a ReferenceType that specifies the semantics of the relationship. References can be hierarchical or non-hierarchical. Hierarchical references are used to create the structure of Objects and Variables. Non-hierarchical are used to create arbitrary associations. Applications can define their own ReferenceType by creating subtypes of an existing ReferenceType. Subtypes inherit the semantics of the parent but can add additional restrictions. Figure 4 depicts several References, connecting different Objects.

The figures above use a notation that was developed for the OPC UA specification. The notation is summarized in Figure 5. UML representations can also be used; however, the OPC UA notation is less ambiguous because there is a direct mapping from the elements in the figures to Nodes in the AddressSpace of an OPC UA Server.

A complete description of the different types of Nodes and References can be found in OPC 10000-3 and the base structure is described in OPC 10000-5.
The OPC UA specification defines a very wide range of functionality in its basic information model. It is not required that all Clients or Servers support all functionality in the OPC UA specifications. OPC UA includes the concept of Profiles, which segment the functionality into testable certifiable units. This allows the definition of functional subsets (that are expected to be implemented) within a companion specification. The Profiles do not restrict functionality, but generate requirements for a minimum set of functionalities (see OPC 10000-7).
4.2.3.2 Namespaces
OPC UA allows information from many different sources to be combined into a single coherent AddressSpace. Namespaces are used to make this possible by eliminating naming and id conflicts between information from different sources. Each namespace in OPC UA has a globally unique string called a NamespaceUri which identifies a naming authority and a locally unique integer called a NamespaceIndex, which is an index into the Server's table of NamespaceUris. The NamespaceIndex is unique only within the context of a Session between an OPC UA Client and an OPC UA Server- the NamespaceIndex can change between Sessions and still identify the same item even though the NamespaceUri's location in the table has changed. The Services defined for OPC UA use the NamespaceIndex to specify the Namespace for qualified values.
There are two types of structured values in OPC UA that are qualified with NamespaceIndexes: NodeIds and QualifiedNames. NodeIds are locally unique (and sometimes globally unique) identifiers for Nodes. The same globally unique NodeId can be used as the identifier in a node in many Servers – the node's instance data can vary but its semantic meaning is the same regardless of the Server it appears in. This means Clients can have built-in knowledge of of what the data means in these Nodes. OPC UA Information Models generally define globally unique NodeIds for the TypeDefinitions defined by the Information Model.
QualifiedNames are non-localized names qualified with a Namespace. They are used for the BrowseNames of Nodes and allow the same names to be used by different information models without conflict. TypeDefinitions are not allowed to have children with duplicate BrowseNames; however, instances do not have that restriction.
4.2.3.3 Companion Specifications
An OPC UA companion specification for an industry specific vertical market describes an Information Model by defining ObjectTypes, VariableTypes, DataTypes and ReferenceTypes that represent the concepts used in the vertical market, and potentially also well-defined Objects as entry points into the AddressSpace.
5 Use cases
5.1 Untitled
5.2 Motivation
Smart Industry is associated with next generation of manufacturing to increase efficiency, flexibility, and productivity. This also includes the broader interplay between the OT and IT domain as well as the further integration of services from different application areas. Technology domains such as from smart infrastructure and web forecasting services like traffic and weather forecasts are expected to be integrated directly into the manufacturing process as well as in the product lifecycle. To realize cross-domain applications for the Industrie 4.0 context, a frequent exchange with suppliers or local infrastructure providers (e.g., power supplier) is needed and it is necessary to interact with manufacturing systems that usally offers an OPC UA interface. WoT can act as a common and standardized application layer and can be used to support Industry 4.0 use cases. In this context, well-formed bindings for most established industry standards such as OPC UA should be supported.
5.3 Sample Scenario
A bottling line consists of a filling module (switchable between 2 fillers and 4 fillers), a capping module, a labeling module, and a transport system. The production line is provided via an OPC UA endpoint for control and monitoring purposes.
In the context of enhancing productivity and sustainability, the goal is to operate the bottling line in such a way that production is further increased when sufficient or surplus renewable energy is available. The backend system checks periodically a Smart Grid endpoint (via HTTP) how the current power production is and how much renewable energy is produced. Based on the bottling line's current power consumption, which is measured via Modbus, the backend system decides to increase productivity when surplus renewable energy is available. In doing so, the backend system interacts via OPC UA to release the 4 fillers of the filling module and increases the speed of the transport system. If the backend system detects that less renewable energy is being produced, it will initiate standard production and reduce the transport speed and return the 2 fillers of the filling module.
6 OPC UA Binding for Web of Things Information Model Overview
6.1 Introduction and Examples
| The OPC UA Binding for WoT provides a standard guideline on how to design a WoT TD to describe an OPC UA interface. The example below illustrates a basic TD instance outlining an interface of an OPC UA Server, which provides access to a single datapoint (UA Variable) pumpSpeed. |
This example shows a minimal version of metadata that would be enough that a client can initiate a connection to an OPC UA server (opc.tcp://opcuademo.com:4840), selects a preferred security mode that the OPC UA server offers (auto_sc), and is able to execute a read or monitor service of the pumpSpeed datapoint via the provided NodeId in href
(nsu=http://example.nsu.com/demo/pump;s=PumpSpeed).
As an alternative a Thing Description can provide additional semantic metadata as specified in the specification to give a richer context of information. The following example extends the previous TD with potential terms:
The @context includes all namespaces that are used in the Thing Description. The http://opcfoundation.org/UA/WoT-Binding/ namespace points to the OPC UA WoT Binding ontology and http://example.namespace.com/demo/pump to an application class that is used in the OPC UA server. Terms such as uav:browseName specify the origin browse name (1:Pump and 1:PumpSpeed) of a corresponding UA Object marked with uav:object or of a UA Attribute marked with uav:variable in the Thing Description @type. The uav:browsePath provides the origin browse path in the OPC UA tree to the UA Variable that is associated with this property.
6.2 URI Format for base and href
The following BNF format shows the structure of an URI of the OPC UA Client / Server protocol that have to be followed in a WoT Thing Description:
opc.tcp://<address>:<port>[/<resourcePath>]/?id=<nodeId>Where is:
{address} OPC UA server endpoint (IP) address
{port} OPC UA server port number
{resourcePath} If used by the OPC UA server, an added resource path at the endpoint address.
{nodeId} OPC UA nodeId which should apply the following requirements: To prevent conflicts with reserved characters and to allow for deconstruction as specified by
RFC 3986, two specific characters in the nodeId must be percent-encoded when used
any hash character (#) shall be percent-encoded (%23)
any ampersand character (&) shall be percent-encoded (%26)
If this URI is extracted from the Thing Description and is transmitted (e.g., via a network), all non-ASCII characters must first be encoded into bytes using the UTF-8 character encoding, and then each resulting byte must be percent-encoded in accordance with RFC 3986.
Note that the URL can be used as a whole in href within a forms definition or divided into the global base term (for sever location only) and href term (relative to the base that provides only the nodeId information).
Examples:
"href": "/?id=nsu=http://example.nsu.com/demo/pump;s=PumpSpeed"
"href":"/?id=nsu=http://example.com/hello%23;s=temperature"
"href":"opc.tcp://192.168.120.237:4840/?id=nsu=http://widgets.com/schemas/hello;s=水 World"
If the namespace is resolved in the @context (see 6.5.5), its index value can be used in the nodeId:
"href":"/?id=ns=10;i=12345"
"href":"opc.tcp://192.168.120.237:4840/UA/Factory/?id=ns=10;i=12345"
"href":"opc.tcp://192.168.120.237:4840/?id=ns=10;i=12345"
6.3 Security Definitions
The standard definitions of the WoT Thing Description specification can be used to implicitly specify the endpoint security settings supported by the OPC UA server. Alternatively, an OPC UA specific scheme can be used to exchange explicit security knowledge.
6.3.1 NoSecurityScheme
Can be used when the OPC UA server only supports one endpoint that is set up without security options (securityMode=None, securityPolicy=None). Typical use cases include demo setups of an OPC UA server or an OPC UA server that provides public and read-only UA attributes, e.g., for monitoring purposes for a dashboard.
In that case WoT Thing Description should specify the NoSecurityScheme by the vocabulary term nosec (i.e., "scheme": "nosec").
6.3.2 AutoSecurityScheme
Recommended to be used to show implicit knowledge that a OPC UA server supports multiple endpoints with different configuration for the security mode (e.g., None, Sign, or SignAndEncrypt), security policy (e.g., Basic256Sha256, Aes256_Sha256_RsaPss), and supported user identity tokens (e.g., Anonymous, UserName, Certificate).
This reflects the default use case of an OPC UA Client-Server interaction during the OPC UA Session Establishment phase. The client must execute the OPC UA GetEndpoints service in order to select the desired (secured) endpoint to open the session with the OPC UA server. To indicate this, in the WoT Thing Description, the AutoSecurityScheme should be used with the term auto (i.e., "scheme": "auto").
Please note that login credentials such as passwords or certificates are not shared in WoT Thing Descriptions and must be provided separately, e.g., through a separate credential store or by an explicit prompt to the client to enter the credentials for the session.
6.3.3 OPCUASecurityChannelScheme and OPCUASecurityAuthenticationScheme
Recommended to be used to show explicit knowledge in the WoT Thing Description that a OPC UA server supports one or multiple endpoints with different security configuration settings.
This reflects the use case where an OPC UA server specifies which security option(s) should be used by specific client(s) via the WoT Thing Description.
To indicate this, in the WoT Thing Description, you should use OPCUASecurityChannelScheme by using the term uav:channelsec (i.e., "scheme": "uav:channelsec") and OPCUASecurityAuthenticationScheme by using the term uav:authentication (i.e., "scheme": "uav:authentication"). The ComboSecurityScheme from the WoT Thing Description 1.1 specification should be used to combine the schemes with allOf.
OPCUASecurityChannelScheme vocabulary terms:
| Vocabulary term | Description | Assignment | Type |
|---|---|---|---|
| uav:securityMode | Provides information about which modes are available from the supported endpoints of the OPC UA server: None Sign SignAndEncrypt | required | string |
| uav:securityPolicy | Provides information about which policy options are available from the supported endpoints of the OPC UA server: None Basic256Sha256 Aes128_Sha256_RsaOaep Aes256_Sha256_RsaPss Outdated (not recommended policies): Basic256 Basic128Rsa15 | required | string |
OPCUASecurityAuthenticationScheme vocabulary terms:
| Vocabulary term | Description | Assignment | Type |
|---|---|---|---|
| uav:userIdentityToken | Provides information about which policy options are available from the supported endpoints of the OPC UA server: Anonymous UserName Certificate IssuedToken Similar for the AutoSecurityScheme, the login credentials such as user name and passwords or certificates are not shared in WoT Thing Descriptions and must be provided separately, e.g., through a separate credential store or by an explicit prompt to the client to enter the credentials for the session. In the case of IssuedToken there may additional security schemes defined in the WoT Thing Description to describe an external authorization service such as OAuth2 (OAuth2SecurityScheme). To declare the combination of such a specific scheme with the OPCUASecurityScheme, the ComboSecurityScheme can be used with the term allOff (see WoT Thing Description 1.1 specification for more details). | required | String |
| uav:issueToken | Express a reference to a security scheme definition within the WoT Thing Description which should be applied to (e.g., OAuth2). | optional | String |
Examples:
Example usage of OPCUASecurityScheme in combination with an external OAuth2 authorization service:
Note that the terms of the OAuth2 and combo schemes are defined in the W3C WoT Thing Description 1.1 specifications.
6.4 Access Level
6.4.1 UA Variable readable
To specify that a UA variable is readable (CurrentRead) in the TD, the term op must be assigned the value readproperty (as array entry). If the UA Variable is read only (you cannot write), the corresponding readOnly term of the DataSchema class in the TD should be set to true.
Since a readable UA Variable can be also subscribed by a Client, the term op must be supplemented by the value observeproperty and the observable term of the PropertyAffordance class in the TD should be set to true.
6.4.2 UA Variable writeable
To specify that a UA variable is writable (CurrentWrite) in the TD, the op term must be assigned the value writeproperty (or has it as array entry). If the UA Variable is write only (you cannot read), the corresponding writeOnly term of the DataSchema class in the TD should be set to true.
6.5 OPC UA Vocabulary
6.5.1 WoT Binding Namespace and Prefix
The presented additional terms for the WoT Thing Description of this Companion Specification is identified by the following URI:
http://opcfoundation.org/UA/WoT-Binding/
In this specification, the prefix uav is used and associated to this namespace.
6.5.2 URL Terms
| Vocabulary term | Description | Assignment | Type | ||||
|---|---|---|---|---|---|---|---|
| uav:id | NodeId value as defined in OPC 10000-6: UA Part 6: Mappings (5.1.12 QualifiedName, NodeId and ExpandedNodeId String Encoding). | required | string | ||||
6.5.3 Forms Terms
The OPC UA binding does not need mandatory UA specific forms terms, the default forms terms from WoT Thing Description can be reused. Associated NodeId information for an interaction affordance (properties or actions) are reflected by the corresponding href as specified in 6.2..
The UA services are expressed by the TD op term and its corresponding values. In the following, the op values will correspond the following OPC UA Services:
| readproperty | UA Service Read |
| writeproperty | UA Service Write |
| observeproperty | UA Service Monitor |
| invokeaction | UA Service Call |
If the default serialization of the OPC UA server is used, the contentType should be assigned with the value "application/octet-stream".
Optional, following term can be used within the WoT TD forms container:
| Vocabulary term | Description | Assignment | Type |
|---|---|---|---|
| uav:browsePath | Provides information about the path of a UA node as string, following the guideline of OPC UA Part 4 (v104) in Chapter A.2, starting from the root node of an OPC UA address space. E.g., "/Root/Object/1:Machine/1:Pressure" | optional | String |
6.5.4 Overview of Generic OPC UA Terms for annotating Thing Descriptions
The following table gives an overview of the additional terms that can be used within a WoT Thing Description.
| Vocabulary term | Description | Assignment | Type |
|---|---|---|---|
| uav:object | Semantic annotation for @type of the TD root level to express that this TD instance represent a UA Object from the top level. | optional | - |
| uav:objectType | Semantic annotation for @type at root level to express that this instance represent a UA ObjectType (in TD context, this is called Thing Model (TM)) Note: This annotation is only applicable in a Thing Model definition. | optional | - |
| uav:variable | Semantic annotation for @type of a TD property to associate a UA Variable. | optional | - |
| uav:variableType | Semantic annotation for @type of a Thing Model property to associate a UA Variable Type. Note: This annotation is only applicable in a Thing Model definition. | optional | - |
| uav:method | Semantic annotation for @type of a TD action to associate a UA Method. | optional | - |
| uav:hasComponent | Term to express there is one or more has-child relationship. The value entry is a nodeId of the child node.
| optional | Array of String |
| uav:componentOf | Term to express there is one or more is-child-of relationship. The value entry is a nodeId of the parent node.
| optional | Array of String |
| uav:browseName | Provides the origin browse name of the UA node. The uav:browseName can be used at the top level to provide the browse name of the UA Object or UA ObjectType, and within the property or action level to give the browse name of the UA variable or UA method respectively. | optional | String |
| uav:mapToNodeId | This term can be used within a property definition to express that the associated runtime datapoint can be mapped to a (external) target OPC UA node (e.g. UA variable) with the corresponding NodeId. See Section 8.2 for example usage. | optional | string |
| uav:mapToType | This term can be used within a property definition to express that the associated runtime datapoint can be mapped to a (external) target OPC UA type with the corresponding NodeId. See Section 8.2 for example usage. | optional | string |
| uav:mapByFieldPath | This term can be only used with the uav:mapToType term. In the case that the target type of uav:mapToType is complex (e.g. based on BaseType 0:Structure), a specific field name can be addressed within this complex type definition to which the runtime data can be mapped to. See Section 8.2 for example usage. | optional | string |
6.5.5 UA and Application Namespaces
Typically, OPC UA server uses namespaces from the OCP UA core, Companion Specifications and application specific namespaces. If it should be evident in the TD that different namepaces are used (e.g., visible by the uav:browseName or uav:browsePath terms), then these should be specified in the @context of the TD. The associated namespace index id should be associated as prefix value in the TD.
Example:
Lets assume there are namespaces used in a OPC UA server as described in the following nodeset:
If the Thing Description (TD) utilizes definitions from these namespaces, they should be specified within the TD @context with the corresponding namespace index as a prefix, as illustrated here:
7 Thing Description Mapping from OPC UA Core Definitions
Most Thing Description elements map directly from OPC UA core definitions. This core terms can be discovered during a browse process or can be retrieved from a nodeset file. In this specification, only a subset is considered for transforming an OPC UA node representation into WoT Thing Descriptions.
For each Object entry defined at the top level, all nested Variables and Methods node classes can be converted into a Thing Description, represented as properties or actions respectively. However, it is recommended to just provide a subset of UA Variables and Methods in WoT Thing Description representation that contains only the relevant information that is assumed to be expected and used by client’s application.
Note: A WoT Thing Description will not directly reflect the origin UA tree structure by properties and actions definitions. For example, a nested UA Object representing complex data, such as GPS data, will not be converted into a WoT TD GPS property. Instead, the members of the UA Objects (which should be UA Variables or UA Methods) will be individually transformed into properties or actions (e.g., the members the GPS Object, latitude and longitude, will be transformed to a latitude and a longitude TD property). If it is desired to record the logical UA tree structure in the TD, it is recommended to use the additional metadata terms such as uav:componentOf or uav:hasComponent.
The mapping from OPC UA nodes to Thing Description terms is provided in the following subsections.
7.1 Mapping of OPC UA Node Classes
7.1.1 UA Object
| Equivalent WoT TD definition | Thing |
| Description | In OPC UA Objects are used to represent systems, system components, real-world objects and software objects. Objects are defined using the Object NodeClass. In WoT Thing Description, a Thing represents real-world objects and software objects and their elements through interaction affordances (properties and actions). It is recommended for each UA Object defined under the UA Root to create an individual TD. The mechanism may also facilitate the creation of individual TDs for nested UA Object nodes, provided these nodes contain a reasonable number of nested UA Variables or Methods, or possess a self-contained context. By default, nested UA Objects are not directly transformed into TDs. Instead, their nested UA Variables and Methods are aggregated into a single TD representing the top-level UA Object. |
| Example in OPC UA (as nodeset) | <UAObject NodeId="ns=3;i=5001" BrowseName="3:PaintingRobot_1" ParentNodeId="ns=2;i=5002"> <DisplayName>Painting Robot</DisplayName> …. |
| Transformed usage in a TD definition (as snippet) | { "@context":"https://www.w3.org/2022/wot/td/v1.1", "@type": ["Thing"], "title": "Painting Robot", "base": "opc.tcp://opcuademo.com:4840", "securityDefinitions": { "auto_sc": { "scheme": "auto" } }, "security": "auto_sc", … Alternative: { "@type": ["Thing", "uav:object"], "securityDefinitions": { "auto_sc": { "scheme": "auto" } }, "security": "auto_sc", |
7.1.2 UA Variable
| Equivalent WoT TD definition | PropertyAffordance |
| Description | In OPC UA variables are used to represent values which may be simple or complex. Variables are defined by VariableTypes. Variables are always defined as Properties or DataVariables of other Nodes in the AddressSpace. Similarly, in a TD a property affordance represents a simple or complex value that can be read / written / observed. Not all discovered UA Variables are recommended to transformed as TD properties, especially Variables that are part of a UA Method (InputArguments, OutputArguments). It is recommended to transform only UA variables into TD properties, which represent a standalone data point (e.g., dynamic values such as sensor or status values, static values that are not part of an HasProperty relationship). If an UA Variable is part of a logical complex definition (e.g., latitude Variable is component of an UA Object with the name GPS), it is recommended to annotate the property with the uav:componentOf term to make clear, that the TD property is part of a parent object (e.g., GPS). This may be important to trigger the client to make an atomic read by readmultipleproperties of all members that belongs to an UA Object (e.g., latitude and longitude). |
| Snippet example in OPC UA (e.g., as nodeset) | <UAVariable DataType="Double" NodeId="ns=3;i=6125" BrowseName="3:ActualPosition" ParentNodeId="ns=3;i=5058"> <DisplayName>Actual Position</DisplayName> …. |
| Transformed usage in a TD definition (as snippet) | "properties": { "3:ActualPosition": { … Alternative: "properties": { "3:ActualPosition": { "@type": ["uav:variable"], "type": "number", … |
7.1.3 UA Method
| Equivalent WoT TD definition | ActionAffordance |
| Description | In OPC UA methods are “lightweight” functions, whose scope is bounded by an owning (see Note) Object, similar to the methods of a class in object-oriented programming or an owning ObjectType, similar to static methods of a class. Methods are invoked by a client, proceed to completion on server and return the result to the client. The lifetime of the Method’s invocation instance begins when the client calls the Method and ends when the result is returned. Similary, in a TD an action affordance is a function or an action that can be invoked on a Thing. A TD action must contain the uav:componentOf term to express in which object the UA method is defined. The input and output terms reflect the InputArguments and OutputArguments data structure of the corresponding UA Variables. Thereby, the argument definitions within the UA Variables are mapped to the JSON Schema type=object structure where each argument is a member of the type=object definition. |
| Snippet example in OPC UA (e.g., as nodeset) | <UAMethod NodeId="ns=1;s=RunCalibration" BrowseName="1:Calibrate" ParentNodeId ="ns=1;s=CalibrationObject"> <References> <Reference ReferenceType="HasComponent" IsForward="false">ns=1;s=CalibrationObject</Reference> <Reference ReferenceType="HasProperty">ns=1;s=RunCalibration_InputArguments</Reference> <Reference ReferenceType="HasProperty">ns=1;s=RunCalibration_OutputArguments</Reference> </References> ... <UAVariable NodeId="ns=1;s=RunCalibration_InputArguments" BrowseName="InputArguments" DataType="Argument" ValueRank="1" TypeDefinition="PropertyType"> <DisplayName>InputArguments</DisplayName> <Description>Input parameter for the Run calibration method.</Description> <Value> <ListOfExtensionObject xmlns="http://opcfoundation.org/UA/2008/02/Types.xsd"> <ExtensionObject> <TypeId> <Identifier>i=297</Identifier> </TypeId> <Body> <Argument xmlns="http://opcfoundation.org/UA/2008/02/Types.xsd"> <Name>CalibrationFactor</Name> <DataType> <Identifier>i=6</Identifier> <!-- Integer --> </DataType> <ValueRank>Scalar</ValueRank> <Description>Factor used to adjust the calibration process.</Description> </Argument> </Body> </ExtensionObject> </ListOfExtensionObject> </Value> </UAVariable> … <UAVariable NodeId="ns=1;s=RunCalibration_OutputArguments" BrowseName="OutputArguments" DataType="Argument" ValueRank="1" TypeDefinition="PropertyType"> <DisplayName>OutputArguments</DisplayName> <Description>Output parameter of the Run calibration method.</Description> <Value> <ListOfExtensionObject xmlns="http://opcfoundation.org/UA/2008/02/Types.xsd"> <ExtensionObject> <TypeId> <Identifier>i=297</Identifier> </TypeId> <Body> <Argument xmlns="http://opcfoundation.org/UA/2008/02/Types.xsd"> <Name>CalibrationStatus</Name> <DataType> <Identifier>i=6</Identifier> <!-- Integer --> </DataType> <ValueRank>Scalar</ValueRank> <ArrayDimensions/> <Description>Status resulting from the calibration process.</Description> </Argument> </Body> </ExtensionObject> </ListOfExtensionObject> </Value> </UAVariable> … |
| Transformed usage in a TD definition (as snippet) | "actions": { "1:Calibrate": { "uav:componentOf": ["ns=1;s=CalibrationObject"], "input": { "type": "object", "properties": { "CalibrationFactor": { "type": "integer", "description": "Factor used to adjust the calibration process." }}}, "output": { "type": "object", "properties": { "CalibrationStatus": { "type": "integer", "description": "Status resulting from the calibration process." }}}, "forms": [ { "href": "/?id=ns=1;s=RunCalibration", "contentType": "application/octet-stream" } ]
|
7.1.4 UA ObjectType
| Equivalent WoT TM definition | tm:ThingModel |
| Description | ObjectType is a type definition of an object and its encompassing variables and methods. It is a template for an object. Therefore, an objectType definition can be mapped to a WoT Thing Model definition. A Thing Model is templates that can be used to instantiate Thing Description instances. The same restriction guideline is applied as defined in UA Object in Section Error! Reference source not found.. |
| Snippet example in OPC UA (e.g., as nodeset) | <UAObjectType NodeId=" ns=3;i=1002" BrowseName="3:PaintingRobotType"> |
| Transformed usage in a TD definition (as snippet) | "@context":"https://www.w3.org/2022/wot/td/v1.1", "@type": ["tm:ThingModel"], … Alternative: { "@type": ["tm:ThingMode", "uav:objectType"], |
7.1.5 UA VariableType
| Equivalent WoT TM definition | PropertyAffordance |
| Description | VariableType is a type definition of a variable and its values. It is a template for a variable. Therefore, a variableType definition can be mapped to a propertyAffordance definition in a Thing Model. Herby, it applies the same guideline as defined for UA Variable (see Section Error! Reference source not found.). |
| Snippet example in OPC UA (e.g., as nodeset) | <UAVariableType DataType="Double" NodeId="ns=3;i=6129" BrowseName="3:ActualPositionType" ParentNodeId="ns=3;i=5058"> …. |
| Transformed usage in a TD definition (as snippet) | "properties": { "3:ActualPositionType": { Alternative: "properties": { "3:ActualPositionType": { "@type": ["uav:variableType"], |
7.1.6 UA Reference
| Equivalent WoT TD definition | Additional semantic annotations at property and action level |
| Description | A reference in OPC UA is used to define the relationship between two nodes. OPC UA defines several hierarchical and non-hierarchical references. In this specification version, a minimal set of references (e.g., HasComponent, HasTypeDefinition) can be used in a TD to represent the relationship between interaction affordances or between a Thing and its interaction affordances. Some references are defined by own terms (e.g., uav:componentOf") or can be part of @types definitions. Details about the reference types that are mapped within a TD are provided in Section 7.3. |
| Snippet example in OPC UA (e.g., as nodeset) | … <References> <Reference ReferenceType="HasComponent" IsForward="false">ns=3;i=5001</Reference> </UAVariable> |
| Transformed usage in a TD definition (as snippet) | "properties": { "3:ActualPosition": { |
7.2 Mappings of OPC UA Attributes
7.2.1 BrowseName
| Equivalent WoT TD definition | Interaction Name |
| Description | The BrowseName is used as interaction name of a property or action. It is important to ensure that the interaction names within the properties and actions are unique within the TD. If the uniqueness is not guaranteed by a given BrowseName (same value is used at a different place in a UA tree), different strategies can be realized. In the following, two strategies are presented; others are also possible as long as uniqueness is guaranteed. 2:Root E.g., the interaction name can be augmented with additional characters such as with a separator character (e.g., "_", "-") and an ascending number or alphabet character. Example: "1:Pressure_1" for "1:Pressure" in "1:Data1". ""1:Pressure_2" for "1:Pressure" in "1:Data2". Alternatively, the browse path to the UA node can be sketched (e.g., without namespace prefixes) as unique interaction name: Example: "Root_Data2_Pressure" In the case the original BrowseName is not used, it is recommended to add the term "uav:browseName" within the interaction affordance to provide the origin browse name. |
| Snippet example in OPC UA (e.g., as nodeset) | … <UAVariable NodeId="ns=1;i=428" BrowseName="1:Pressure" ParentNodeId="ns=1;i=20" DataType="Double"> |
| Transformed usage in a TD definition (as snippet) | … "properties": { "1:Pressure_1": { …
Alternative: … "properties": { "Root_Data1_Pressure": { … |
7.2.2 DisplayName
| Equivalent WoT TD definition | title At the root and property / action level |
| Description | DisplayName and title represent a human-readable name of an OPC UA node or a WoT Thing or an interaction affordance (property / action). |
| Snippet example in OPC UA (e.g., as nodeset) | … <DisplayName>Product serial number</DisplayName> |
| Transformed usage in a TD definition (as snippet) | … "title" : "Product serial number " |
7.2.3 Description
| Equivalent WoT TD definition | description At the root and property / action level |
| Description | Description and description provides a human-readable description of an OPC UA node or a WoT Thing or an interaction affordance (property / action). |
| Snippet example in OPC UA (e.g., as nodeset) | … <Description>This attribute provides the position oft the robot arm.</ Description> |
| Transformed usage in a TD definition (as snippet) | … "description" : " This attribute provides the position oft the robot arm." |
7.2.4 DataType
| Equivalent WoT TD definition | type |
| Description | It represents the dataType of the data provided or consumed by an OPC UA node or a WoT interaction affordance (property/action). If data type values are from XSD Schema types or NodeIds to link, e.g., to BaseDataTypes, then those data type values shall be resolved and mapped to the corresponding JSON types and assigned to the type term in the TD. The mapping from OPC UA datatype to JSON types is specified in Chapter 5.4 OPC UA JSON in “OPC 10000-6: UA Part 6: Mappings” (5.4.2 Built-in Types). |
| Snippet example in OPC UA (e.g., as nodeset) | … <UAVariable NodeId="ns=1;i=2" BrowseName="1:ProductSerialNumber" ParentNodeId="ns=1;i=1" DataType="UInt64"> |
| Transformed usage in a TD definition (as snippet) | … "properties": { "1:ProductSerialNumber": { |
7.2.5 AccessLevel (currentRead, currentWrite)
| Equivalent WoT TD definition | readOnly writeOnly observable op |
| Description | It represents the permitted accesslevel for a client to a property affordance. Relevant bitfields in OPC UA are currentread (bit 0) and currentwrite (bit 1). Thing Description provides indicators of the data model level about accessibility by the terms readOnly and writeOnly. The term observable gives an hint if the property is observable. At the forms level the op term is used with the potential values readproperty, writeproperty, and observeproperty. Note: per default, UA Variables are observable. |
| Snippet example in OPC UA (e.g., as nodeset) | … <UAVariable NodeId="ns=1;i=35" BrowseName="1:IdealCycleTime" ParentNodeId="ns=1;i=20" DataType="UInt64" AccessLevel="3"> |
| Transformed usage in a TD definition (as snippet) | … "properties": { "1:IdealCycleTime": { … "readOnly": true, "writeOnly": false, "observable": true, … "forms" : [{ … "op": ["readproperty","observeproperty"] |
7.2.6 NodeId
| Equivalent WoT TD definition | href |
| Description | The NodeID of a UA Variable or Method is encoded as href in forms of a property or actions definition. Detail addressing mapping is specified in Section 6.2 |
| Snippet example in OPC UA (e.g., as nodeset) | … <NamespaceUris> <Uri>http://opcfoundation.org/UA/DI/</Uri> <Uri>http://example.namespace.com/demo/</Uri> </NamespaceUris> <UAVariable NodeId="ns=1;i=35" BrowseName="1:IdealCycleTime" ParentNodeId="ns=1;i=20" DataType="UInt64" AccessLevel="3"> |
| Transformed usage in a TD definition (as snippet) | … "properties": { "1:IdealCycleTime": { … "forms" : [{ "href":"/?id=ns=1;i=35" … Alternative: … "properties": { "1:IdealCycleTime": { … "forms" : [{ "href":"/?id=nsu= http://example.namespace.com/demo/;i=35" … |
7.3 Mapping of OPC UA Reference Types
The following subsections explains, which supported reference types can be used to map equivalent information into the WoT Thing Description.
7.3.1 HasTypeDefinition
| Equivalent usage in WoT TD | @type At the root/Thing or property level |
| Description | It gives information about the semantic type of an instance (e.g., a thing or an interaction affordance). It provides similar semantics as @type in a TD. Therefore, HasTypeDefinition reference can be mapped to @type. The value of the @type should always be the browse name of the corresponding HasTypeDefinition (e.g. AnalogItemType for NodeId i=2368). |
| Snippet example in OPC UA (e.g., as nodeset) | … <UAVariable NodeId="ns=1;s=Temperature" BrowseName="1:Temperature" DataType="Double" ValueRank="Scalar"> <DisplayName>Temperature</DisplayName> <References> <Reference ReferenceType="HasTypeDefinition">i=2368</Reference> <!-- AnalogItemType --> </References> </UAVariable> |
| Transformed usage in a TD definition (as snippet) | … "properties": { "1:Temperature": { "@type" : ["0:AnalogItemType"] … Alternative: "properties": { "1:Temperature": { "@type": ["uav:variable","0:AnalogItemType"], |
7.3.2 HasComponent
| Equivalent usage in WoT TD | uav:hasComponent At the root/Thing or property/action level |
| Description | Terms to express one or more has-child (uav:hasComponent) or has-parent (uav:componentOf) relationship. Also see terms definition in Section 6.5.4. |
| Snippet example in OPC UA (e.g., as nodeset) | … <References> <Reference ReferenceType="HasComponent" IsForward="false">ns=3;i=5001</Reference> </UAVariable> |
| Transformed usage in a TD definition (as snippet) | "properties": { "3:ActualPosition": { |
7.3.3 HasProperty
| Equivalent usage in WoT TD | unit description(s) title(s) … |
| Description | HasProperty references in OPC UA are typically used to provide static information about a node. This information are properties of a node that do not change frequently and provide useful metadata or context information. The TD provides terms such as unit, title(s), descriptions(s), etc. to annotate, e.g., properties and actions with additional information. Also additional terms from other ontologies can be used to make additional annotations in TDs. Depending of the purpose of the provided HasProperty variable, a corresponding mapping can be processed into the TD. E.g., unit information can be mapped to the unit term or descriptions can be mapped to the description or descriptions (multi languages text) term. |
| Snippet example in OPC UA (e.g., as nodeset) | … <DisplayName>Temperature</DisplayName> <References> <Reference ReferenceType="HasTypeDefinition">AnalogItemType</Reference> <Reference ReferenceType="HasProperty">ns=1;s=Temperature_Unit</Reference> </References> </UAVariable> <UAVariable NodeId="ns=1;s=Temperature_Unit" BrowseName="1:Unit" DataType="String" TypeDefinition="PropertyType"> <DisplayName>Unit</DisplayName> <Value> <String>Celsius</String> </Value> </UAVariable> |
| Transformed usage in a TD definition (as snippet) | … "properties": { "1:Temperature": { "@type" : ["AnalogItemType"], "type":"number", "unit":"Celsius", …
|
8 Thing Description Examples
8.1 Full Object to Thing Description Transformation
An OPC UA example server reflects the following UA node tree:
The namespace for ns=1 is "". A corresponding Thing Description can be generated for the Object NodeId "ns=1;s=IndustrialMotor" (IndustrialMotor):8.2 Auto Data Model Mapping with UA Binding Terms
The ontology of the OPC UA binding will allow mapping features that can be used also in Thing Description that are not directly related to a OPC UA binding.
The example below shows a Thing Description of a Modbus-based energy meter that offers 3 voltages of each phase as properties with the name VoltageL1-N, VoltageL2-N, and VoltageL3-N. Each property uses the uav:mapToType and uav:mapByFieldPath terms to make clear, that the corresponding property can be mapped to a AcPeDataType from the http://opcfoundation.org/UA/PNEM/ namespace. If an OPC UA server uses this namespace and has a node of this type, as shown on the right, then a processor can read the properties from the Modbus device and assign the runtime value to the OPC UA model.

Hint: The uav:mapToNodeId can also be used to specify the exact target node to which the runtime data should be mapped.
Agreement of Use
COPYRIGHT RESTRICTIONS
Any unauthorized use of this specification may violate copyright laws, trademark laws, and communications regulations and statutes. This document contains information which is protected by copyright. All Rights Reserved. No part of this work covered by copyright herein may be reproduced or used in any form or by any means--graphic, electronic, or mechanical, including photocopying, recording, taping, or information storage and retrieval systems--without permission of the copyright owner.
OPC Foundation members and non-members are prohibited from copying and redistributing this specification. All copies must be obtained on an individual basis, directly from the OPC Foundation Web site http://www.opcfoundation.org.
PATENTS
The attention of adopters is directed to the possibility that compliance with or adoption of OPC specifications may require use of an invention covered by patent rights. OPC shall not be responsible for identifying patents for which a license may be required by any OPC specification, or for conducting legal inquiries into the legal validity or scope of those patents that are brought to its attention. OPC specifications are prospective and advisory only. Prospective users are responsible for protecting themselves against liability for infringement of patents.
WARRANTY AND LIABILITY DISCLAIMERS
WHILE THIS PUBLICATION IS BELIEVED TO BE ACCURATE, IT IS PROVIDED "AS IS" AND MAY CONTAIN ERRORS OR MISPRINTS. THE OPC FOUDATION MAKES NO WARRANTY OF ANY KIND, EXPRESSED OR IMPLIED, WITH REGARD TO THIS PUBLICATION, INCLUDING BUT NOT LIMITED TO ANY WARRANTY OF TITLE OR OWNERSHIP, IMPLIED WARRANTY OF MERCHANTABILITY OR WARRANTY OF FITNESS FOR A PARTICULAR PURPOSE OR USE. IN NO EVENT SHALL THE OPC FOUNDATION BE LIABLE FOR ERRORS CONTAINED HEREIN OR FOR DIRECT, INDIRECT, INCIDENTAL, SPECIAL, CONSEQUENTIAL, RELIANCE OR COVER DAMAGES, INCLUDING LOSS OF PROFITS, REVENUE, DATA OR USE, INCURRED BY ANY USER OR ANY THIRD PARTY IN CONNECTION WITH THE FURNISHING, PERFORMANCE, OR USE OF THIS MATERIAL, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
The entire risk as to the quality and performance of software developed using this specification is borne by you.
RESTRICTED RIGHTS LEGEND
This Specification is provided with Restricted Rights. Use, duplication or disclosure by the U.S. government is subject to restrictions as set forth in (a) this Agreement pursuant to DFARs 227.7202-3(a); (b) subparagraph (c)(1)(i) of the Rights in Technical Data and Computer Software clause at DFARs 252.227-7013; or (c) the Commercial Computer Software Restricted Rights clause at FAR 52.227-19 subdivision (c)(1) and (2), as applicable. Contractor / manufacturer are the OPC Foundation, 16101 N. 82nd Street, Suite 3B, Scottsdale, AZ, 85260-1830.
COMPLIANCE
The OPC Foundation shall at all times be the sole entity that may authorize developers, suppliers and sellers of hardware and software to use certification marks, trademarks or other special designations to indicate compliance with these materials. Products developed using this specification may claim compliance or conformance with this specification if and only if the software satisfactorily meets the certification requirements set by the OPC Foundation. Products that do not meet these requirements may claim only that the product was based on this specification and must not claim compliance or conformance with this specification.
Trademarks
Most computer and software brand names have trademarks or registered trademarks. The individual trademarks have not been listed here.
GENERAL PROVISIONS
Should any provision of this Agreement be held to be void, invalid, unenforceable or illegal by a court, the validity and enforceability of the other provisions shall not be affected thereby.
This Agreement shall be governed by and construed under the laws of the State of Minnesota, excluding its choice or law rules.
This Agreement embodies the entire understanding between the parties with respect to, and supersedes any prior understanding or agreement (oral or written) relating to, this specification.