# node-opcua-uanodeset-json

> pure nodejs OPCUA SDK - the Annex I JSON NodeSet serialisations (OPC 10000-6 Annex I)

Latest version **2.187.31** (published 2026-11-17) · MIT license · 0 weekly downloads

## Install

```sh
npm install node-opcua-uanodeset-json
pnpm add node-opcua-uanodeset-json
yarn add node-opcua-uanodeset-json
bun add node-opcua-uanodeset-json
```

## Health

**Score 75/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; has provenance; recently updated; high maintenance score; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 2.187.31 |
| Published | 2026-11-17 |
| First published | 2026-09-08 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=22.13.0 |
| Dependencies | 10 |
| Unpacked size | 240.7 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 1664 |
| Author | Etienne Rossignon |
| Maintainers | erossignon |
| Keywords | OPCUA, opcua, m2m, iot, opc ua, internet of things |

## Links

- npm: https://www.npmjs.com/package/node-opcua-uanodeset-json
- Repository: https://github.com/node-opcua/node-opcua
- Homepage: http://node-opcua.github.io/
- Issues: https://github.com/node-opcua/node-opcua/issues
- npm.io page: https://npm.io/package/node-opcua-uanodeset-json

## Dependencies (10)

- [node-opcua-json](https://npm.io/package/node-opcua-json.md) 2.187.31
- [node-opcua-utils](https://npm.io/package/node-opcua-utils.md) 2.187.28
- [node-opcua-nodeid](https://npm.io/package/node-opcua-nodeid.md) 2.187.28
- [node-opcua-factory](https://npm.io/package/node-opcua-factory.md) 2.187.28
- [node-opcua-variant](https://npm.io/package/node-opcua-variant.md) 2.187.28
- [node-opcua-date-time](https://npm.io/package/node-opcua-date-time.md) 2.187.28
- [node-opcua-data-model](https://npm.io/package/node-opcua-data-model.md) 2.187.28
- [node-opcua-basic-types](https://npm.io/package/node-opcua-basic-types.md) 2.187.28
- [node-opcua-address-space](https://npm.io/package/node-opcua-address-space.md) 2.187.31
- [node-opcua-extension-object](https://npm.io/package/node-opcua-extension-object.md) 2.187.28

## Recent versions

- 2.187.31 (latest) — 2026-11-17
- 2.187.30 — 2026-11-17
- 2.187.29 — 2026-11-16
- 2.187.28 — 2026-11-16
- 2.187.27 — 2026-11-13
- 2.187.26 — 2026-11-10
- 2.187.24 — 2026-11-07
- 2.187.23 — 2026-11-06
- 2.187.21 — 2026-11-03
- 2.187.20 — 2026-11-03
- 2.187.19 — 2026-11-01
- 2.187.18 — 2026-10-29
- 2.187.17 — 2026-10-28
- 2.187.16 — 2026-10-25
- 2.187.12 — 2026-10-21
- … 38 more at https://npm.io/package/node-opcua-uanodeset-json/versions

## README

# node-opcua-uanodeset-json

The **JSON NodeSet** of OPC 10000-6 Annex I, in all three of its serialisations, readable and
writable by node-opcua.

see http://node-opcua.github.io/

```bash
npm install node-opcua-uanodeset-json
```

## Why

An information model has been a NodeSet2 XML document for as long as OPC UA has had one. Annex I
is the normative JSON form of the same thing, and it is what you want when the consumer is not an
OPC UA stack: a browser, a `jq` pipeline, a document database, a diff in a code review, or a
build step that has to add one node to a companion specification without a full XML toolchain.

The annex specifies three shapes of the same model, and this package implements all three:

| extension | Annex | what it is | reach for it when |
|---|---|---|---|
| `.jsonl` | I.4 | one JSON object per line, header first | you want to stream, `grep`, or diff a model line by line |
| `.json` | I.1 | one document, children nested inside their parent | you want to read it, or hand it to a JSON API |
| `.uanodeset` | I.3 | a TAR.GZ of a manifest and numbered members | the model is large enough that one file is unwieldy |

## Reading: nothing to call

Importing the package registers all three with the address-space loader, so a path is enough:

```ts
import { AddressSpace } from "node-opcua-address-space";
import { generateAddressSpace } from "node-opcua-address-space/nodeJS";
import "node-opcua-uanodeset-json";

const addressSpace = AddressSpace.create();
await generateAddressSpace(addressSpace, [
    "Opc.Ua.NodeSet2.xml",     // still XML
    "Opc.Ua.Di.jsonl",         // Annex I line form
    "MyCompanionSpec.uanodeset" // Annex I archive
]);
```

`node-opcua-server` already imports it, so a server gets this for free. Formats are chosen by
**sniffing the content**, not the extension, and the head a sniffer is shown is already inflated,
so `.jsonl.gz` and `.json.gz` work as well and a misnamed file still loads.

To register only one form, import only that subpath. It is the point of the subpaths:

```ts
import "node-opcua-uanodeset-json/jsonl";
```

Reading is **exact**, and that claim is tested rather than asserted. The DI nodeset loaded from
`.jsonl`, `.json` and `.uanodeset` produces an address space with the same digest as the one
loaded from its NodeSet2 XML, where the digest hashes every node's id, browse name, class,
reference count and, for variables, status code and value. Agreeing node counts would not be that
claim.

## Writing

The writers take a stream of `NodesetRecord`, the intermediate form the loader produces, so
converting between any two formats is reading one and writing the other:

```ts
import { writeFile } from "node:fs/promises";
import { recordsToAnnexIJson } from "node-opcua-uanodeset-json";

await writeFile("Opc.Ua.Di.json", recordsToAnnexIJson(records), "utf8");
```

```ts
import zlib from "node:zlib";
import { recordsToAnnexIArchiveTar } from "node-opcua-uanodeset-json";

const tar = recordsToAnnexIArchiveTar(records, { maxNodesPerFile: 1000 });
await writeFile("Opc.Ua.Di.uanodeset", zlib.gzipSync(Buffer.from(tar)));
```

Writing is a **fixpoint**: `write(read(write(read(x))))` is byte-identical to `write(read(x))`,
for the document form and for the archive down to the tar bytes. Splitting an archive never
divides a subtree across two members, and the members carry no `Models`, because I.3 says the
manifest specifies them.

Cross-implementation, which is the check that actually matters: the OPC Foundation's
`UA-NodeSetTool` reads what this writes and its `compare` reports the result identical to the
original XML.

## What the annex does differently

Three decisions in I.1 will surprise a reader who knows NodeSet2 XML, and each one is why a
naive translation does not work:

- **No namespace table.** A NodeId embeds its namespace URI: `nsu=http://…/DI/;i=1002`, and a
  QualifiedName likewise. Nothing is relative to a document-scoped index, so a node can be moved
  between documents unchanged. `parseAnnexINodeId` and `formatAnnexINodeId` are the conversion,
  and they split on the **first** semicolon, since a URI may contain one.
- **No aliases.** Reference types are written out.
- **Three references are not references.** `HasTypeDefinition` becomes the `TypeId` field,
  `HasModellingRule` becomes `ModellingRuleId`, and the forward edge from a parent to its child
  is implied by `ParentId`. A reader that only walks `References` silently loses all three; this
  package puts them back.

The document form adds two more:

- Nodes are partitioned into **eight containers** by NodeClass, and children nest inside their
  parent's `ChildList` rather than sitting at the top level.
- `Ordered` and `Declarations` handle cycles. I.2 makes reading order normative so a decoder
  reading forwards never meets a NodeId it has not already seen, and `Declarations` carries stubs
  for the ones that cannot be ordered. A test model exists specifically to exercise this, because
  it is what breaks a naive reader.

## API

Most callers need only the side-effect import. The rest is for building tools.

| export | what it is |
|---|---|
| `recordsToAnnexIJson(records)` | records as an Annex I document, serialised |
| `recordsToAnnexIDocument(records)` | the same as an `AnnexIUANodeSet` object |
| `recordsToAnnexIArchiveTar(records, options?)` | records as the tar bytes of an archive, before gzip |
| `flattenAnnexIDocument(nodeSet)` | a document's nodes in I.2 reading order, un-nested, with `ParentId` filled in |
| `annexIHeaderRecord` / `annexINodeRecord` | the codec: Annex I to `NodesetRecord` |
| `decodeAnnexIVariant`, `AnnexIValueError` | a Part 6 1.05 JSON Variant, as Annex I carries it |
| `parseAnnexINodeId`, `formatAnnexINodeId`, and the `QualifiedName` pair | the `nsu=` canonical forms |
| `annexINamespaceTable`, `OPCUA_CORE_NAMESPACE` | namespace resolution |
| `isAnnexIHeaderLine`, `isAnnexIDocumentHead`, `isAnnexIArchiveHead` | the three sniffers, usable directly |
| `readTar`, `writeTar`, `isTar`, `TarEntry` | the tar layer |
| `ANNEX_I_JSONL_FORMAT`, `ANNEX_I_JSON_FORMAT`, `ANNEX_I_ARCHIVE_FORMAT` | format names, for `nodesetFormatByName` |
| `registerAnnexIJsonlFormat()` and friends | explicit registration; idempotent, and the imports already call them |
| `AnnexINode`, `AnnexIUANodeSet`, `AnnexIReference`, … | the model types |

### The tar layer

`.uanodeset` is a TAR.GZ, and the monorepo has no tar dependency. This should not be the package
that adds one, so `readTar` / `writeTar` are about 150 lines here: they read both the original V7
layout and ustar, and write ustar.

`isTar` recognises an archive by its **header checksum** rather than by a magic string, because
V7 leaves the magic empty and that is what the reference implementation writes. A checksum is the
only structural test that works on both.

Archives are validated against I.3 rather than read optimistically. A manifest naming a file the
archive lacks, and a file the archive holds that the manifest does not name, are both refused:
either one silently changes which nodes get loaded.

## License

MIT

---
_Source: https://npm.io/package/node-opcua-uanodeset-json · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._
