The YAML editor at the lower left contains the authoritative harness definition. Changes made through component controls and connection tools update that source. Editing the source directly reaches WireViz features that do not have dedicated visual controls.
Live compilation and source controls
Typing triggers a short debounce before compilation. The footer reports Loading engine, Compiling, Source has errors or Up to date. The dot beside the YAML heading indicates that the displayed result has not caught up with the current source.
The heading includes Copy YAML and Compile harness. Use Mod+Enter to compile immediately. Mod means Command on macOS and Control elsewhere. Source undo and redo use the editor's shared session history, so undoing an import or a visual edit also restores its associated images and positions.
Ordinary copy and paste operate on text while the source editor has focus. Click the canvas or use component context menus when you want to copy a component instead.
Document structure
A harness normally defines these top-level sections:
| Section | Content |
|---|---|
connectors |
Named connector and splice definitions. |
cables |
Cable or wire-bundle definitions. |
connections |
Ordered connection sets that instantiate and connect components. |
metadata |
Title, descriptions and other document information. |
options |
WireViz output and template options. |
tweak |
Advanced Graphviz overrides and appended DOT. |
additional_bom_items |
Extra parts to include in the bill of materials. |
The root and definition sections must be YAML mappings. connections and additional_bom_items must be lists. Unknown fields are preserved by source editing, but preservation is not a promise that WireViz uses a field.
The editor follows the YAML 1.1 scalar and merge conventions used by PyYAML. Quote a value when it must remain text, especially boolean-looking pin names such as "ON" or "NO". Syntax-valid YAML can still fail WireViz's semantic checks.
Shared definitions with anchors
Anchors and merges can reuse a common pinout:
connectors:
X1: &two_pin
pincount: 2
pinlabels: [POWER, GND]
X2:
<<: *two_pin
type: Output connector
An edit to an inherited property can create a local override without rewriting the shared definition. Removing an inherited property means removing its effective value, rather than merely restoring inheritance.
The editor protects a shared anchor from destructive visual edits that would alter its aliases unexpectedly. If it asks you to edit the shared template in YAML or detach aliases, use the full source editor deliberately. Recursive aliases and excessively expanded alias graphs are rejected.
Structured property editors parse only their own field value. Put references to anchors elsewhere in the document into the full YAML editor instead.
WireViz templates and generated instances
WireViz can create instances from a definition using a separator, normally a period. For example, SENSOR.LEFT creates an instance named LEFT from SENSOR when used in a connection set. The Reusable templates example demonstrates several named connectors and cables from shared definitions.
Layers shows instantiated components; Components also shows source definitions. A generated instance points back to its template in Design. Editing the template affects the instances that derive from it. A declaration that is never used by a connection set may be omitted from the compiled drawing and BOM.
Errors and text preservation
Visual transactions aim to retain comments, anchors and untouched source text rather than regenerate the whole document. A changed field or connection list may be reformatted. Keep a downloaded YAML copy when exact source formatting matters.
During an invalid edit, the last successful drawing and BOM can remain visible. Compilation-dependent exports are blocked until the current source succeeds. Checks reports available line numbers; selecting a diagnostic opens the YAML panel, but does not automatically move the cursor to that line.
See Import and export to keep a portable copy and current limits for the browser compiler's resource bounds.