WireViz 0.4.1 library reference

Learn the WireViz YAML document model, supported harness features, generated outputs, and the difference between the library and browser editor.

WireViz turns a text description of connectors, cables, and their connections into a harness diagram and a bill of materials. This reference documents WireViz 0.4.1, the library version used by this editor. It follows the pinned release source rather than assuming that behavior in a newer upstream branch is available here. The upstream project is distributed under GPLv3. Pinned upstream source, license.

Start with one complete harness

This file describes a two-conductor cable between two connectors. The order of each connection list establishes which pin is connected through which conductor.

metadata:
  title: Sensor extension

connectors:
  X1:
    type: Two-position plug
    pincount: 2
    pinlabels: [POWER, GND]
  X2:
    type: Two-position socket
    pincount: 2
    pinlabels: [POWER, GND]

cables:
  W1:
    gauge: 22 AWG
    length: 0.5 m
    colors: [RD, BK]

connections:
  - - X1: [1, 2]
    - W1: [1, 2]
    - X2: [1, 2]

colors supplies the wire count here: two entries mean two conductors. Pin numbering starts at 1 unless you provide explicit IDs. The part descriptions are illustrative; WireViz does not resolve them to a purchasable connector or verify that two products mate. Open the simple harness example to explore a similar document.

Document sections

Section	Shape	Purpose
`connectors`	Mapping of designator to properties	Connector, terminal, splice, and other pin-bearing definitions.
`cables`	Mapping of designator to properties	Multicore cables and bundles of individual wires.
`connections`	List of connection sets	Instantiates definitions and joins their pins and conductors.
`additional_bom_items`	List of item mappings	Parts that belong in the BOM independently of a diagram component.
`metadata`	Mapping	Title and information consumed by HTML output templates.
`options`	Mapping	Document-wide appearance and template separator settings.
`tweak`	Mapping	Experimental changes to generated Graphviz source.

Definitions are templates until referenced in connections. An unused connector or cable is omitted from both the resolved diagram and the automatically generated BOM, and WireViz prints a warning. A one-item connection set can instantiate an otherwise unconnected component. Missing connectors, cables, or connections sections are treated as empty by the library. Parser implementation.

What the model supports

The library supports arbitrary pin identifiers, pin and wire labels, color codes, shields, connector loops, connection ranges, branched harnesses, multiple cables in a connection set, connector mating arrows, reusable templates, and anonymous instances. There is no general upstream rule that a harness must have only two connectors or at most eight wires. A branch is expressed using shared pins or splice components across connection sets; it is not a separate top-level branch object.

WireViz documents the connectivity and attributes you provide. It does not calculate wire routing lengths from geometry, select a safe wire gauge, certify connector compatibility, simulate a circuit, or generate a three-dimensional manufacturing model. Gauge and length are document data, not results of an electrical or mechanical solver.

Library and editor

This reference describes the YAML language and native library. The browser editor runs the pinned engine and also provides an interactive canvas and property controls. Its editable canvas is a separate presentation of the harness; layout or styling in the official Graphviz rendering can differ. YAML is the way to express library features that do not have a dedicated visual control. Browser imports, asset handling, and resource limits belong to the web application and are additional to the native library.

Native WireViz produces SVG and PNG diagrams, Graphviz source, a TSV BOM, and an HTML document containing a diagram and BOM. The native CLI and Python examples in this reference run on your own computer; they are not commands to type into the browser editor.

Where to go next

Define the endpoints with connectors.
Describe the conductors with cables and bundles and colors.
Join them using connection sets.
Reuse parts through templates.
Add purchasing information through the BOM reference.
Learn the YAML rules, CLI, or Python API.

The reference is pinned to tag v0.4.1, commit 1c4fd68a2e34e12ff1513aac52323890c6a8c695. Examples on these pages are newly written explanations of that release's behavior.