webnn-graph

webnn-graph is a Rust library and command-line tool for a WebNN-oriented graph DSL. It parses and serializes .webnn files, validates graph structure, manages external weights, emits JavaScript and interactive HTML, and optionally converts ONNX models into the DSL.

The browser-based graph visualizer is published at rustnn.github.io/webnn-graph.

File model

A model consists of a graph and, when constants are external, a weight sidecar:

• .webnn is the compact, human-readable graph representation.
• GraphJson is the equivalent JSON AST used by the Rust API and tooling.
• .safetensors is a self-describing external-weight archive.
• .weights plus .manifest.json is the raw binary alternative used by the weight utilities and ONNX converter.

The canonical contracts are documented in:

• WebNN graph format
• External weight format

Install and build

cargo build
cargo test

ONNX conversion is enabled by the default onnx feature. Build only the parser, serializer, validators, emitters, and weight utilities with:

cargo build --no-default-features

CLI

The CLI accepts .webnn or GraphJson where indicated. Run webnn-graph <command> --help for the complete option list.

Command	Purpose
parse	Parse .webnn and print GraphJson.
serialize	Serialize GraphJson as .webnn.
validate	Validate a graph and, optionally, a raw-weight manifest.
emit-js	Emit WebNN builder JavaScript and the raw .weights loader.
emit-html	Emit a standalone interactive graph visualizer.
pack-weights	Pack tensor files into a WGWT .weights archive.
unpack-weights	Extract tensors from a WGWT .weights archive.
create-manifest	Create a raw-weight manifest from tensor files.
extract-weights	Move inline graph constants into a raw-weight archive.
inline-weights	Copy raw external weights into GraphJson.
convert-onnx	Convert ONNX to .webnn or GraphJson when the onnx feature is enabled.

Examples:

# Parse and validate a graph.
cargo run -- parse examples/resnet_head.webnn > /tmp/resnet_head.json
cargo run -- validate /tmp/resnet_head.json

# Serialize GraphJson back to the text format.
cargo run -- serialize /tmp/resnet_head.json > /tmp/resnet_head.webnn

# Generate JavaScript or a standalone visualizer.
cargo run -- emit-js examples/resnet_head.webnn > /tmp/build_graph.js
cargo run -- emit-html examples/resnet_head.webnn > /tmp/graph.html

See examples/README.md for the raw-weight workflow.

ONNX conversion

The converter accepts ai.onnx opsets 11 through 18. Static dimension overrides and optional constant folding can resolve shape-critical ONNX expressions. Experimental bounded dynamic input metadata is available, but operations whose arguments must be static still require concrete values.

cargo run -- convert-onnx \
  --input model.onnx \
  --output model.webnn \
  --weights model.weights \
  --manifest model.manifest.json \
  --override-dim batch_size=1 \
  --override-dim sequence_length=128 \
  --optimize

Without --inline-weights, conversion produces .webnn, .weights, and .manifest.json artifacts. Use --experimental-dynamic-inputs to preserve unresolved input dimensions as bounded dyn(...) metadata where the lowering can otherwise proceed.

See:

• ONNX to WebNN lowering
• Dynamic dimensions

Rust library

The public library exposes the format AST, parser, serializer, validation helpers, external-weight resolver and SafeTensors writer, JavaScript/HTML emitters, and the optional ONNX converter.

use std::error::Error;

use webnn_graph::parser::parse_wg_text;
use webnn_graph::serialize::{serialize_graph_to_wg_text, SerializeOptions};

fn main() -> Result<(), Box<dyn Error>> {
let graph = parse_wg_text(r#"
webnn_graph "identity" v1 {
  inputs { x: f32[1]; }
  nodes { y = identity(x); }
  outputs { y; }
}
"#)?;

let text = serialize_graph_to_wg_text(&graph, SerializeOptions::default())?;
# Ok::<(), Box<dyn std::error::Error>>(())

Development

make fmt-check
make lint
make test
cargo test --all-features
cargo test --no-default-features

The repository keeps prose lines at or below 120 characters.