Aller au contenu principal

Introducing the OPC UA YAML DSL — An Open Specification

· 5 minutes de lecture
Etienne Rossignon
Etienne Rossignon
CEO sterfive

Last week we made the case that OPC UA desperately needs a standard, human-readable modeling language. Today, we're delivering on that promise. We are publicly releasing the OPC UA YAML DSL Specification — a formal, vendor-neutral document that defines a declarative YAML authoring format compiling to conformant NodeSet2 XML. The specification is available now at /specification/.

What the Specification Covers​

The OPC UA YAML DSL specification is a comprehensive document spanning 22 sections. It covers the full OPC UA address-space vocabulary:

AreaWhat You Can Define
DataTypesBasic types, Enumerations, Structures, Unions, Option Sets
ReferenceTypesCustom hierarchical and non-hierarchical references
ObjectTypes & VariableTypesFull type hierarchies with components, properties, methods
InterfaceTypesLean interface materialisation with HasInterface semantics
EventTypesEvent declarations with GeneratesEvent references
State MachinesFiniteStateMachineType with states, transitions, and effects
InstancesObjects and Variables with connection properties and overrides
Add-InsReusable aggregates referenced by type definition
InitializersDeclarative default values for variables
MethodsInput/output argument declarations

Beyond the type system, the spec also defines a complete processing model (parse → resolve → sort → materialise → serialise), diagnostics requirements, NodeSet2 equivalence criteria, and security considerations.

Design Principles​

Three principles guided every design decision:

1. Human-Readable, Machine-Processable​

Nodes are addressed by browse name and browse path — not by opaque numeric NodeIds. The DSL auto-assigns NodeIds and persists them in a symbol-table CSV that survives regeneration. You never have to think about ns=1;i=6001 again.

2. Version-Control Friendly​

Every construct is expressed as clean, indented YAML. Diffs are meaningful. A one-line change in a model produces a one-line diff in Git. No more wading through thousands of lines of re-ordered XML references.

3. Formally Specified, Vendor-Neutral​

The specification uses RFC 2119 normative keywords (MUST, SHOULD, MAY) and defines two explicit conformance classes. Any tool vendor, any open-source project can implement a conformant processor. There is no proprietary lock-in by design.

Conformance Classes​

The specification defines two conformance classes:

Conformant Document — a YAML 1.2 document whose root mapping satisfies every MUST requirement in the spec. Think of it as "a valid model file."

Conformant Processor — an implementation that, given a Conformant Document, produces a NodeSet2 XML document equivalent to the address space described by the YAML, and rejects with a diagnostic any document that violates a requirement.

This separation is deliberate. It means you can validate a YAML model without generating XML (schema validation alone), and it means multiple competing processors can coexist — all producing interchangeable NodeSet2 output from the same source file.

Before and After: XML vs. YAML​

Here's the same model expressed in both formats — a temperature sensor type with one variable, plus an instance.

NodeSet2 XML (~30 lines):

<UAObjectType NodeId="ns=1;i=1001" BrowseName="1:TemperatureSensorType">
  <DisplayName>TemperatureSensorType</DisplayName>
  <References>
    <Reference ReferenceType="HasSubtype" IsForward="false">
      ns=2;i=1004
    </Reference>
    <Reference ReferenceType="HasComponent">ns=1;i=6001</Reference>
  </References>
</UAObjectType>
<UAVariable NodeId="ns=1;i=6001" BrowseName="1:Temperature"
            DataType="Double" ParentNodeId="ns=1;i=1001">
  <DisplayName>Temperature</DisplayName>
  <References>
    <Reference ReferenceType="HasTypeDefinition">i=2368</Reference>
    <Reference ReferenceType="HasModellingRule">i=78</Reference>
    <Reference ReferenceType="HasComponent" IsForward="false">
      ns=1;i=1001
    </Reference>
  </References>
</UAVariable>
<UAObject NodeId="ns=1;i=5001" BrowseName="1:Sensor01">
  <DisplayName>Sensor01</DisplayName>
  <References>
    <Reference ReferenceType="HasTypeDefinition">ns=1;i=1001</Reference>
    <Reference ReferenceType="Organizes" IsForward="false">
      ns=2;i=5001
    </Reference>
  </References>
</UAObject>

OPC UA YAML DSL (~15 lines):

namespaceUri: http://acme.com/UA/TemperatureSensor
version: 1.0.0
publicationDate: 2026-01-01T00:00:00.000Z
namespaces:
  - di
objectTypes:
  - browseName: TemperatureSensorType
    subtypeOf: di:DeviceType
    components:
      - browseName: di:ParameterSet
        components:
          - browseName: Temperature
            typeDefinition: ua:AnalogItemType
            dataType: ua:Double
            engineeringUnits: "degree Celsius"
instances:
  - browseName: Sensor01
    typeDefinition: TemperatureSensorType
    organizedBy: /ua:Objects/di:DeviceSet

The YAML version is shorter, yes — but the real advantage isn't line count. It's intent. You can immediately see that TemperatureSensorType extends di:DeviceType, that it has a Temperature component measured in degrees Celsius, and that Sensor01 is an instance organized under DeviceSet. No NodeIds, no reverse references, no boilerplate.

Namespace Handling: Simple but Powerful​

The spec defines a clean namespace system. Well-known OPC Foundation companion specs (di, ia, machinery, robotics, adi, and 20+ others) are available as simple aliases:

namespaces:
  - di
  - ia
  - machinery

For custom or third-party namespaces, the imports block accepts an alias, a URI, and a path to the NodeSet2 XML file:

imports:
  - alias: ts
    uri: http://acme.com/UA/TemperatureSensor/
    filename: ../temperature_sensor.NodeSet2.xml

The reserved alias ua always refers to the OPC UA standard namespace. No index juggling, no ns=3;i=... mental arithmetic.

The Spec Is Open — Build Your Own Processor​

This is not a proprietary format with a published description. The specification is written to enable independent, conformant implementations. The companion JSON Schema (schemas/nodeset2.schema.json) provides machine-readable syntactic validation rules. The normative prose defines semantics, cross-property invariants, and NodeSet2 equivalence.

If you're building an OPC UA SDK, a modeling tool, a code generator, or an AI agent that manipulates information models — you can implement a conformant processor and guarantee interoperability with every other conformant tool in the ecosystem.

Read the Full Specification​

The complete OPC UA YAML DSL Specification (v0.0, public draft) is available at:

👉 /specification/

We welcome feedback from the OPC UA community — integrators, companion-spec authors, SDK developers, and end users alike. In the next post, we'll explore how this specification unlocks modern DevOps workflows, AI-assisted modeling, and a new era of multi-vendor collaboration for OPC UA.