What is NamespaceArray in OPC UA?

Glossary · Address space

NamespaceArray

In OPC UA, the NamespaceArray is a String array Variable on the Server object that maps namespace indexes to namespace URIs by array position. Index 0 is always http://opcfoundation.org/UA/. Reading it at connect time is how a client turns a stable namespace URI into the volatile index its NodeIds need.

Where it lives and what it contains

The NamespaceArray is the Variable Server.NamespaceArray, addressable as ns=0;i=2255, one of the very few nodes whose NodeId you can safely hardcode. Its value is an array of namespace URI strings; the array index of an entry is that namespace's index on this server, in this session. Element 0 is always the OPC UA core namespace http://opcfoundation.org/UA/, so index 0 always means a standard node.

The connect-time resolve

The correct client startup sequence is: create the session, read ns=0;i=2255, build a URI-to-index dictionary, then construct every NodeId from a stored URI plus identifier. Every mature stack has helper API for this, and opcua-commander accepts nsu=http://samples.org/UA/MyNamespace;s=MyVariable and performs the lookup for you. OPC Publisher likewise accepts a namespace by full URI instead of index. Do the same in your own code.

It can grow while you are connected

A server may append namespaces at runtime - loading a nodeset, starting an aggregated downstream server, adding a device. Appending is safe; existing indexes keep their meaning. Reordering is not, and a restart or reconfiguration may reorder freely. Subscribe to the NamespaceArray, or to GeneralModelChangeEvent, if your client caches resolved indexes for a long-running session.

Reading it in the field

The array is also the fastest way to see what a server claims to implement. A NamespaceArray containing http://opcfoundation.org/UA/DI/ and http://opcfoundation.org/UA/Machinery/ tells you a device and machinery model are loaded before you browse a single node. Pair it with ServerProfileArray and ServerCapabilities for a complete first look at an unknown server.

Example

A typical NamespaceArray read from a machinery server, and the index it implies

Read ns=0;i=2255  (Server.NamespaceArray, String[])

[0] http://opcfoundation.org/UA/                     -> ns=0  (always)
[1] urn:PlantA-Line3-PLC:UA:Server                   -> ns=1  (server's own ApplicationUri)
[2] http://opcfoundation.org/UA/DI/                   -> ns=2
[3] http://opcfoundation.org/UA/Machinery/            -> ns=3
[4] http://example.com/PlantA/Line3/                  -> ns=4

Store this in configuration:
  { "uri": "http://example.com/PlantA/Line3/", "id": "s=Mixer_01.Speed" }
Not this:
  { "nodeId": "ns=4;s=Mixer_01.Speed" }

The mistake people make: Reading the NamespaceArray once during development, writing the resulting indexes into a config file, and shipping that. After a PLC download, a firmware update or a nodeset load the table can be reordered, and every previously working NodeId returns BadNodeIdUnknown - or worse, silently resolves to a different node of the same type in another namespace.

Defined in: Part 5 - Information Model defines the Server object and its NamespaceArray Variable; namespace semantics are in Part 3.

Related concepts

Namespace index Namespace URI NodeId Address space Information model

Status codes you will meet

BadNodeIdUnknown BadNotReadable BadUserAccessDenied

Last verified 7 September 2026 against OPC UA 1.05.07. OPC UA Connect is an educational resource and is not affiliated with the OPC Foundation.