WireViz connectors, pins, and loops

Every WireViz 0.4.1 connector field, pin count rules, named pins, simple terminals, loops, visibility, and BOM behavior.

A connector is a component with identifiable pins. It can represent a housing, socket, terminal, splice, or another connection point. The key under connectors is its designator; type is a description, not a lookup into a product database. All behavior below is based on the 0.4.1 Connector implementation.

Define pins explicitly

connectors:
  X1:
    type: Sensor connector
    subtype: Cable side
    pins: [A, B, C]
    pinlabels: [SUPPLY, RETURN, SIGNAL]
    pincolors: [RD, BK, WH]
    manufacturer: Example Components
    mpn: "SENSOR-3-P"
  X2:
    pins: [1, 2, 3]

cables:
  W1:
    colors: [RD, BK, WH]
    gauge: 0.34
    length: 1

connections:
  - - X1: [SUPPLY, RETURN, SIGNAL]
    - W1: [1-3]
    - X2: [1-3]

The three lists are positional: pin A has label SUPPLY and color RD. A normal cable connection can refer to an actual pin ID or a unique pin label. A label repeated on different pins is ambiguous when used as a connection reference. A value present in both pins and pinlabels must identify the same position. See the named pins example.

Complete field reference

Unless a default is listed, the field is optional and unset.

Field	Value	Behavior or default
Mapping key	String	Definition/designator name, for example `X1`; do not also add a `name` property.
`type`	Text	Main description.
`subtype`	Text	Additional description, shown with the type.
`category`	String	Accepted classification field; 0.4.1 does not define a connector category with behavior equivalent to cable `bundle`.
`style`	String	`simple` selects a one-pin component without the normal pin table; omit for a normal connector.
`pincount`	Integer	Number of positions; inferred when omitted.
`pins`	List of integers or strings	Actual pin IDs; defaults to integers `1` through `pincount`. IDs must be unique.
`pinlabels`	List of integers or strings	Optional labels aligned with `pins`; default empty list. Prefer clear nonnumeric text to avoid reference collisions.
`pincolors`	List of colors	Optional pin color marks aligned with `pins`; default empty list.
`color`	Color	Connector body color displayed as descriptive information and a color mark.
`manufacturer`	Text	Manufacturer name.
`mpn`	Text	Manufacturer part number. Quote numeric-looking part numbers.
`supplier`	Text	Supplier name.
`spn`	Text	Supplier part number.
`pn`	Text	Your internal part number.
`image`	Image mapping	Embedded diagram image; see images.
`notes`	Multiline text	Notes displayed in the component box.
`bgcolor`	Color	Component box background override.
`bgcolor_title`	Color	Designator/title row background override.
`show_name`	Boolean	Defaults to true, except for `simple` components and anonymous generated names.
`show_pincount`	Boolean	Defaults to true, or false with `style: simple`.
`hide_disconnected_pins`	Boolean	Default false; hides pins that are not activated by connections or loops.
`loops`	List of two-item lists	Internal pin-to-pin connections; default empty list.
`ignore_in_bom`	Boolean	Default false; excludes this connector's own automatic BOM line.
`additional_components`	List of component mappings	Contacts, seals, or other associated parts; default empty list. See BOM.

Text fields such as type, subtype, notes, and product information can contain line breaks. The library also handles hyperlinks in supported text fields, with different treatment in diagram and HTML output. Prefer plain text unless you need the native HTML behavior.

How pin counts work

If pincount is absent or false-valued, WireViz takes the largest length among pins, pinlabels, and pincolors. If all are empty, the connector cannot be instantiated. If pins is absent or empty, sequential numeric IDs are generated.

An explicit pincount does not resize a nonempty pins list. For example, pincount: 4 with pins: [A, B] is not automatically expanded into four IDs. The renderer also iterates across the longest of the pin-related lists. Keep all positional lists consistent: a declared count is not a repair mechanism for mismatched imported data.

Use real booleans for switches and quote text such as "ON", "OFF", "yes", and "no". WireViz's YAML dialect otherwise treats those words as booleans.

One-pin terminals and splices

This definition fragment creates a simple terminal. Its pin count is forced to one; an explicit count greater than one is rejected.

connectors:
  SPLICE:
    style: simple
    type: Crimp splice
    show_name: true

style: simple hides the regular pin table and defaults to hiding the name and count. A bare designator in a connection set addresses pin 1, so keep the generated numeric pin for this shorthand. Reuse a named instance when a splice joins several connection sets; anonymous instances are separate components. See templates and the branched harness.

Internal loops

connectors:
  X1:
    pincount: 4
    loops: [[1, 4], [2, 3]]
connections:
  - [X1]

Each loop must contain exactly two actual pin IDs. Unlike cable connections, loop validation in 0.4.1 does not resolve pin labels. Looped pins remain visible even when disconnected pins are hidden. A loop records and draws the connection; it does not specify jumper gauge or length and does not automatically add jumper wire to the BOM. Add that material explicitly if required. Open the connector loop example.