WireViz provides two different forms of reuse. YAML anchors share property data while loading a file. WireViz template syntax instantiates connector and cable definitions while resolving connections. They can be combined, but they operate at different stages. The rules here follow the 0.4.1 parser and upstream syntax reference.
Definitions and named instances
Every entry under connectors or cables can be used as a template. PLUG.X1 means “instantiate template PLUG with actual designator X1.”
connectors:
PLUG:
type: Two-position connector
pincount: 2
pinlabels: [SUPPLY, RETURN]
cables:
PAIR:
colors: [RD, BK]
gauge: 22 AWG
length: 0.5
connections:
- - PLUG.X1: [1, 2]
- PAIR.W1: [1, 2]
- PLUG.X2: [1, 2]
- - X2: [1, 2]
- PAIR.W2: [1, 2]
- PLUG.X3: [1, 2]
The resolved harness contains X1, X2, X3, W1, and W2. PLUG and PAIR are their source definitions, not extra diagram components. The bare X2 in the second set reuses the already-created instance. Named instances remain available in later connection sets.
Use template-qualified syntax on the first use of a generated name. A later bare name can reference an existing instance, but an undefined bare name is interpreted as a definition name. WireViz rejects an attempt to redefine an existing actual designator with a different template.
Named instances ordinarily display their actual names. Anonymous instances below default to hiding their internal generated names; style: simple independently hides connector names by default.
Anonymous instances
Omitting the part after the separator creates a new anonymous instance at each use. In a parallel set, a bare anonymous terminal template creates one instance per lane.
connectors:
X1: {pincount: 3}
TERMINAL:
style: simple
type: Insulated terminal
cables:
W1:
category: bundle
colors: [RD, BK, WH]
gauge: 0.5
length: 0.4
connections:
- - X1: [1-3]
- W1: [1-3]
- TERMINAL.
This creates three separate terminal components. The engine assigns names such as __TERMINAL_1, but those names are implementation details and depend on creation order. Do not write later references to them. A second TERMINAL. means another new component, not a reference to the previous terminal.
Anonymous instances work well for a terminal used once, or a splice located inside one continuous connection set. A splice shared across multiple sets needs an explicit name, as in the branched harness example.
Change the separator
options:
template_separator: ":"
connectors:
PLUG: {pincount: 2}
cables:
PAIR: {colors: [RD, BK], length: 1}
connections:
- - "PLUG:X1": [1, 2]
- "PAIR:W1": [1, 2]
- "PLUG:X2": [1, 2]
The default separator is .. Choose a nonempty separator that does not occur in ordinary component names or arrow tokens. The parser rejects a template reference containing the separator more than once. Although the option is stored as a string without a dedicated one-character validator, a single unambiguous character is the documented convention. Quote references when the chosen separator has YAML significance.
YAML anchors and merges
Anchors let two distinct source definitions share a base property mapping. An explicit local key overrides a merged value.
connectors:
X1: &two_pin
type: Two-position connector
pincount: 2
pinlabels: [SUPPLY, RETURN]
X2:
<<: *two_pin
subtype: Panel side
cables:
W1: {colors: [RD, BK], length: 0.8}
connections:
- - X1: [1, 2]
- W1: [1, 2]
- X2: [1, 2]
X1 and X2 are separate designators here, not autogenerated instances. Editing the anchor's base properties changes every definition that inherits them unless a local key overrides the value. A direct alias such as X2: *two_pin refers to the same loaded mapping; it has no place to put a local property alongside that alias.
To combine bases, use <<: [*base_a, *base_b]. With PyYAML's merge sequence semantics, earlier mappings take precedence over later ones; explicit keys in the receiving mapping take precedence over both. Repeated << merge keys also occur in upstream examples and are accepted by the native loader, but a single merge sequence is clearer and more portable. See YAML behavior.
Editing and versioning shared definitions
Changing a WireViz template's properties affects all instances that use it. To customize one instance, define a new source component or template, optionally inheriting a YAML anchor, and reference that definition for the instance. A generated designator is not automatically a source mapping you can edit independently.
Keep frequently used definitions in version-controlled YAML. The native CLI prepend option can combine reusable text with an input file, but it concatenates text; it does not provide a semantic include system or reconcile duplicate top-level mappings.