OPC UA Modelling Best Practices

OPC 11030 (v1.0)

This whitepaper is intended to provide guidelines and best practice for information modellers creating OPC UA based information models. It is not a formal specification, i.e. it is not required to follow the recommendations in this whitepaper, but highly recommended.

The whitepaper is organized in several sections addressing different aspects of information modelling, from naming conventions to concrete modelling patterns for specific purposes.

The document is a living document, i.e. it will get extended with additional aspects over time, and will be published at a higher frequency than specifications would be.

Table of Contents

1.Scope
2. Naming Conventions
2.1. Naming Conventions for Nodes
2.1.1. General Rules for BrowseNames
2.1.2. Rules for specific NodeClasses
2.1.3. Additional Considerations
2.2. Naming Conventions for structured Fields
3. Rules for backward compatibility of Information Models
3.1. Overview
3.2. Rules
3.2.1. Adding mandatory components to ObjectTypes and VariableTypes
3.2.2. Adding optional components to ObjectTypes and VariableTypes
3.2.3. Adding Interfaces to ObjectTypes
3.2.4. Changing the values of an Enumeration DataType
3.2.5. Changing the fields of a Structure DataType
3.2.6. Changing the Type Hierarchy of ObjectTypes or VariableTypes
3.2.7. Changing the Type Hierarchy of DataTypes
3.2.8. Changing the Signature of a Method
3.2.9. Changing the DataType of a Variable
3.2.10. Changing the TypeDefinition of an InstanceDeclaration
3.2.11. Changing the Semantics of ReferenceTypes
3.2.12. Changing the Type Hierarchy of ReferenceTypes
3.3. Strategies for Breaking Changes
4. How to define StatusCodes in Companion Specifications
5. How to return application-specific statuses in Methods
5.1. Overview
5.2. Example

What follows is an excerpt from Chapter 2 of the whitepaper on Naming Conventions:

2. Naming Conventions

2.1. Naming Conventions for Nodes

OPC UA defines two attributes containing naming information about an OPC UA Node, the BrowseName and the DisplayName. Recommendations for DisplayName will be given in a later version of this document. The BrowseName is of DataType QualifiedName, containing a NamespaceIndex and a String. Unless the BrowseName is defined ins ome other Namespace or there is some specific handling for the BrowseName, the Namespace for the BrowseName should be the one the Node is defined in (i.e. the same Namespace as the NodeId). Nodes defined in a Companion Specification should use the Namespace of the Companion Specification for their NodeIds and BrowseNames. For the string-part the following naming conventions apply:

2.1.1.General Rules for BrowseNames

All BrowseNames should be upper camel case (also known as PascalCase), that is, all words written without spaces, and the first character of each word is upper case, the other characters are lower case. Examples: ReferenceType, BaseObjectType, Int32. If an acronym or abbreviation is used, upper camel case should also be used. Examples: PortMacAddress (where MAC is an acronym for Media Access Control), NodeId (where ID is an abbreviation for identification), UInt32 (where U is an abbreviation for unsigned). In general, it is recommended to only use letters, digits or the underscore (‘_’) as characters for the BrowseName for TypeDefinitions (ObjectTypes, VariableTypes, DataTypes, ReferenceTypes and InstanceDeclarations), unless it is explicitly defined like “<” and “>” for optional placeholders. Remark: If special chars like “&”, “<”, etc.are used, the NodeSet-File should define the optional SymbolicName for that Node. This can then be used for code generation. There is no recommendation on the use of prefixes. Companion Specifications may use a prefix because it suits their model. For example, if the Vision companion specification were to define types based on generic concepts (say a state machine), then using the prefix “Vision” may make sense (as in “VisionStateMachineType”).

2.1.2. Rules for specific NodeClasses

Think you might find such information useful?

Download OPC 11030 Whitepaper Here