HarnessXML

Architecture Overview#

The pipeline#

HarnessXML end-to-end architecture A visual graph is authored in a designer such as Rumima and held as an internal object model. It is serialised to a HarnessXML document, which is the open interchange point. A validator checks the document against the schema and the specification rules. A conforming runtime loads the validated document, resolves resources and artifacts, and executes it, emitting traces to monitoring. Authoring tools, validators, runtimes and SDKs may all be independently implemented against the specification. AUTHORING Visual Graph Rumima Enterprise Studio or any other editor the authoritative design Internal Object Model nodes · edges · resources HarnessXML the document — .hxml portable · diffable · signable THE OPEN INTERCHANGE POINT EXECUTION Validator XSD + HX-nnnn rules Harness Runtime schedule resolve execute retry compensate Monitoring traces · audit · provenance an execution trace resolves back to the document and design revision that produced it

The five stages#

1. Authoring — the visual graph#

Where the design lives. Rumima Enterprise Studio is VisML's commercial designer and the flagship authoring environment, but nothing about the architecture depends on it: the graph could come from another editor, from a generator, or from a program emitting documents directly.

The requirement that matters is the round trip. A document generated from a graph must reopen as that graph, without loss. If the round trip is lossy, teams start editing the generated file by hand, and the graph stops being authoritative — which collapses the whole model.

See Visual Authoring for what an editor must preserve, why layout is deliberately absent from the document, and how a host format embeds a harness.

2. The internal object model#

The in-memory shape a tool holds: nodes, typed edges, resources, artifacts, metadata. The specification defines this object model normatively so that independent implementations agree on what a document means before they argue about how to run it.

The object model is where a designer's conveniences get resolved away. Layout coordinates, colours and grouping are presentation, not semantics — they do not belong in the executable document and do not affect execution.

3. HarnessXML — the interchange point#

The serialised document. This is the only part that has to be identical across vendors, which is why it is the only part the specification pins down completely. Everything upstream and downstream is an implementation.

A document is:

  • complete — sufficient to execute, not a sketch requiring code to fill in;
  • portable — no vendor-specific semantics outside a declared extension namespace;
  • diffable — a change to a threshold is one line in a pull request;
  • signable — canonical enough to sign and verify years later.

4. Validation#

A two-layer check, deliberately.

Layer one: the XSD. Structure, types, enumerations, and referential integrity between edges, nodes, resources and artifacts — expressed as xs:key / xs:keyref, so a plain schema-validating parser in any language already rejects a dangling edge. No HarnessXML-aware tooling required.

Layer two: specification rules. What XSD 1.0 cannot express — acyclicity of control flow, reachability, expression well-formedness, type compatibility across a data edge, a retry policy on a non-idempotent node. Each rule carries an HX-nnnn code, and each code has a conformance fixture that must be rejected with exactly that code.

Validation is a gate, not advice. A conforming runtime must not execute an invalid document.

5. Runtime and monitoring#

A conforming runtime loads a validated document, resolves resources and artifacts, and executes the graph according to the specified semantics: the node lifecycle state machine, edge-type-driven scheduling, deterministic decisions, bounded loops, declared retry policies, and compensation on failure.

Runtimes are expected to differ enormously in everything else — distribution, persistence, crash recovery, scale, latency. That is where implementations should compete. What they may not differ on is what the document means.

Monitoring closes the loop. Because the document carries provenance — the generator, the source design and its digest, artifact digests — an execution trace resolves back to the exact design revision that authorised it. That is the difference between logs and an audit trail.

What anyone may build#

Everything except the specification itself:

componentwhat it does
Editorsauthor graphs, emit HarnessXML
Parsersread documents into an object model
Validatorsenforce the XSD and the HX-nnnn rules
Runtimesexecute documents per the specification
Compilerslower HarnessXML to another execution substrate
Importers / exportersconvert to and from BPMN, DAG YAML, framework graphs
SDKslanguage bindings for building and inspecting documents

No permission is required, no royalty is due, and there is no agreement to sign. Check your implementation against the conformance suite rather than against anyone's opinion — including VisML's.

Where the reference implementation fits#

reference-runtime/ is an Apache-2.0 Rust implementation of the parser, validator and execution model. Its job is to be unambiguous, not fast: it exists so that every normative rule has running code and a test behind it, and so that a disagreement about what the specification means can be settled by reading an implementation instead of by arguing about prose.

It is explicitly not Rumima. If the reference runtime and Rumima disagree, the specification decides, and at most one of them is right.