Native WireViz 0.4.1 loads input through yaml.safe_load from PyYAML. Its scalar behavior follows the familiar YAML 1.1 conventions used by that loader, which can differ from a YAML 1.2 editor's defaults. The browser's document editing layer works alongside the pinned compiler; compilation is the final check of library behavior. Pinned input loader.
File structure
Use one YAML mapping at the document root. Indent nested mappings and lists with spaces, and maintain consistent indentation. Both block lists and flow lists are accepted.
connectors:
X1:
pincount: 2
pinlabels: ["ON", "OFF"]
X2:
pincount: 2
cables:
W1:
colors: [RD, BK]
length: 1.25
connections:
- - X1: ["ON", "OFF"]
- W1: [1, 2]
- X2: [1, 2]
The root sections and their expected shapes are listed in the overview. A multi-document stream separated with --- is not a batch of harnesses for safe_load; use separate files and the CLI's multiple-file input.
Quote text deliberately
| Intended value | Write | Why |
|---|---|---|
| Pin label ON | "ON" |
Unquoted ON is loaded as a boolean. |
| Pin label no | "no" |
Unquoted no is also a boolean. |
| Part number with leading zeros | "001234" |
Preserve text and leading zeros. |
| Hex display color | "#112233" |
An unquoted hash starts a comment. |
| Date stored as metadata text | "2026-09-14" |
Prevent automatic date-object loading. |
| Numeric cable length | 1.25 |
The numeric scalar is accepted; "1.25" is a string with no unit and fails length parsing. |
| Length with unit | 1.25 m |
The value-and-unit string is parsed by WireViz. |
| Boolean switch | true or false |
Use actual booleans for show_name, fixedsize, and similar fields. |
| Image scale mode | "true" or "false" |
image.scale is a string mode, not the fixedsize boolean. |
The YAML boolean spellings include yes/no, on/off, and true/false in their recognized capitalizations. Some numeric-looking scalars also receive special treatment: leading-zero integers can be interpreted as octal, and hexadecimal literals can become numbers. Quoting protects text values from the loader, but the connection selector expansion stage has additional rules below.
null, ~, and an omitted value load as null. Null is not a universal instruction to use a default. Some options deliberately fall back when null; fields such as cable length require a number or valid unit-bearing string. To use a field's native default, omission is generally clearer than an empty string or explicit null.
Pin IDs and selectors are different stages
Connector pins preserves loaded integer or string values. Connection selectors then pass through WireViz's expand helper. That helper converts integer-looking selectors to integers even if they were quoted, and expands strings representing integer ranges. Expansion source.
For example, an actual pin ID "01" remains a string in pins, but a connection selector "01" becomes integer 1. Those are not the same ID. Give such a pin a unique nonnumeric label and reference that label in a normal cable connection, or choose straightforward integer pin IDs. A selector "1-4" means a numeric range rather than a literal ID; quoting alone does not disable range expansion.
Use the actual value type consistently for connector loops, which check IDs directly. Use exact designator spelling and case throughout a document; designators are mapping keys, not a case-normalized product catalog.
Multiline notes and comments
notes: |
View from the mating face.
Keep this drain wire separate until final assembly.
The literal block marker | preserves line breaks. The folded marker > folds most line breaks into spaces. A YAML comment begins with # outside quoted text. Comments help document design intent, but the native library consumes loaded data and does not include comments in generated BOM or diagram information.
Anchors and merge precedence
connectors:
X1: &base
pincount: 2
type: Two-position connector
X2:
<<: *base
subtype: Panel side
An anchor must be defined before its alias. A merged base supplies properties; explicit local keys override inherited keys. For <<: [*first, *second], earlier mappings take precedence over later ones. Native PyYAML also accepts repeated merge keys, including patterns in the upstream corpus. Prefer a single merge sequence for clarity and portability.
A direct alias shares the loaded object; it is not an independent deep copy. When editing source, make a local merge-based definition if you want per-component overrides. See the separate explanation of WireViz template instantiation.
Validation boundaries
The native library is not a comprehensive JSON-Schema validator. Unknown connector/cable property names normally fail when that definition is instantiated, because they are passed to a dataclass constructor. An unused definition may never reach that stage. Unknown top-level keys are not automatically turned into diagram content.
Ordinary duplicate mapping keys are especially risky: native PyYAML generally keeps the last value, while source-preserving editor validation can reject ambiguous duplicates. Do not use duplicate connectors, cables, or component-property keys to combine documents. Use anchors, merge mappings, or a single combined section instead.
Likewise, successful parsing does not guarantee consistent pin-list lengths, valid manufacturing dimensions, or an electrically safe design. Keep IDs unique, positional lists aligned, ranges bounded to existing conductors, and quantities meaningful. The browser adds resource and asset restrictions appropriate to a web runtime; those are separate from upstream YAML syntax.