Symbol interface design guide

Binding spec for the symdef toolkit and the data repos built on it. Agreed with the repo owner on 2026-09-19; amended 2026-10-07 for 0.5.0, 2026-10-13 for 0.6.0 and 2026-10-15 for 0.7.0 (see the change list).

Change list

1. Why: one object, three jobs

A symbol library that makes one object do three jobs has the same recurring problems. All of them trace back to that.

• Port identity drifted. no_contact() had ports 13/14, no_contact(poles=2) had 1/2/3/4, and keys were remapped after construction. Resolvers broke on ids that were not port keys.
• Text was baked into geometry. Tags and pin numbers were text elements placed by heuristics, so layout could not tell label space from body space and labels collided.
• Wiring geometry was per-symbol luck. No shared port pitch, no guaranteed straight-through axis, no guaranteed clear exit for a wire.
• Variants were hand-written geometry. inverted=True, multi-pole and contact-plus-actuator forms each copied coordinates, so a correction had to be repeated everywhere.
• Electrical function lived in docstrings. Every consumer re-encoded "these four ports are one net" and "this is a switch".

2. Principles

1. A symbol is a definition. It has no tag, no terminal numbers, no position and no orientation. Those belong to the placement.
2. Port ids are roles. Stable, lowercase, semantic, never terminal numbers, never dependent on configuration.
3. Electrical function is data. Nodes and typed paths, so consumers netlist and check without per-symbol knowledge.
4. Text goes in slots. The symbol reserves boxes for the tag and for each port's marking. The consumer renders the text.
5. Data is the source of truth. One TOML file per symbol, validated by a published JSON Schema. Any language can consume the resolved JSON.
6. Composition mirrors the standard. IEC 60617 builds symbols from elements and qualifying symbols. Composites reference parts by anchor and contain no copied coordinates.
7. The wiring contract is strict and linted in all 8 orientations. A router never repairs a symbol.
8. Every gate is proven able to fail with a deliberately broken fixture.

3. Conventions

Orientations

There are exactly 8: R0 R90 R180 R270 MR0 MR90 MR180 MR270. M mirrors first (flip x: (x, y) -> (-x, y)), then Rn rotates clockwise on screen by n degrees. A 90 degree clockwise rotation is (x, y) -> (-y, x). Directions and slot sides transform the same way as vectors. Circle and arc centres transform as points and radii are unchanged. Rotation by n adds n to an arc's start and end. Mirroring maps an angle t to 180 - t and swaps start with end, so the arc is still swept clockwise. Angles are normalised to [0, 360). Text elements and slot boxes never rotate or mirror; only their at point moves. Flipping top to bottom is MR180. There is no other transform in the interface.

Port id vocabulary

A1/A2, 13/14, X1/X2 are terminal markings, not roles. They never appear in a symbol file. Generic consumers should chain symbols using the through path's from and to, not by assuming the ids in/out.

4. The symbol file

One file per symbol: symbols/<number>.toml in the data repo. Symbol elements and qualifying symbols from IEC 60617 Part 2 are files too, with a different kind.

Top-level keys

Elements

Each element is a table with exactly one shape key. Optional on all: weight (normal | thick). Optional on line, polyline, arc: style (solid | dashed). Optional on line: port, the id of the port the line leads to; see the wiring contract, section 8, and the lead-off-port rule, section 9.

Example: make contact (atomic, simplest case)

schema = 1
name = "Make contact, general symbol"
kind = "symbol"
status = "unverified"
reference = { standard = "IEC 60617", number = "S00227" }

ports = [
  { id = "in",  at = [0, -2], dir = "N" },
  { id = "out", at = [0, 2],  dir = "S" },
]

paths = [
  { from = "in", to = "out", kind = "switch_open", through = true },
]

anchors = [
  { id = "link", at = [-0.5, 0], dir = "W" },
]

elements = [
  { line = [[0, -2], [0, -1]] },
  { line = [[0, 2], [0, 1]] },
  { line = [[0, 1], [-1, -1]] },
]

[slots]
tag           = { at = [-1.5, 0],    side = "W", box = [6, 1] }
"marking.in"  = { at = [0.25, -1.5], side = "E", box = [1.5, 1] }
"marking.out" = { at = [0.25, 1.5],  side = "E", box = [1.5, 1] }

Example: change-over contact (two paths, one through)

schema = 1
name = "Change-over break before make contact"
kind = "symbol"
status = "unverified"
reference = { standard = "IEC 60617", number = "S00230" }
pole_pitch = 8          # 5.5 M wide with its markings, so it cannot repeat at 4 M

ports = [
  { id = "com", at = [0, 2],   dir = "S", description = "common" },
  { id = "no",  at = [0, -2],  dir = "N", description = "closes on actuation" },
  { id = "nc",  at = [-2, -2], dir = "N", description = "opens on actuation" },
]

paths = [
  { from = "no", to = "com", kind = "switch_open", through = true },
  { from = "nc", to = "com", kind = "switch_closed" },
]

anchors = [
  { id = "link", at = [-0.5, 0], dir = "W" },
]

elements = [
  { line = [[0, 2], [0, 1]] },
  { line = [[0, -2], [0, -1]] },
  { line = [[-2, -2], [-2, -1]] },
  { line = [[-2, -1], [-1, -1]] },
  { line = [[0, 1], [-1.125, -1.25]] },
]

[slots]
tag           = { at = [-4, 0],        side = "W", box = [6, 1] }
"marking.com" = { at = [0.25, 1.5],    side = "E", box = [1.5, 1] }
"marking.no"  = { at = [0.25, -1.5],   side = "E", box = [1.5, 1] }
"marking.nc"  = { at = [-2.25, -1.5],  side = "W", box = [1.5, 1] }

Example: relay coil (impedance)

schema = 1
name = "Operating device, general symbol; relay coil, general symbol"
kind = "symbol"
status = "unverified"
reference = { standard = "IEC 60617", number = "S00305" }

ports = [
  { id = "in",  at = [0, -3], dir = "N" },
  { id = "out", at = [0, 3],  dir = "S" },
]

paths = [
  { from = "in", to = "out", kind = "impedance", through = true },
]

anchors = [
  { id = "link", at = [2, 0], dir = "E" },
]

elements = [
  { line = [[0, -3], [0, -1]] },
  { line = [[0, 3], [0, 1]] },
  { polyline = [[-2, -1], [2, -1], [2, 1], [-2, 1]], closed = true },
]

[slots]
tag           = { at = [-2.5, 0],  side = "W", box = [6, 1] }
"marking.in"  = { at = [0.25, -2], side = "E", box = [1.5, 1] }
"marking.out" = { at = [0.25, 2],  side = "E", box = [1.5, 1] }

Example: connection point (one node, declared exceptions)

schema = 1
name = "Connection point"
kind = "symbol"
status = "unverified"
reference = { standard = "IEC 60617", number = "S00016" }

ports = [
  { id = "n", at = [0, 0], dir = "N" },
  { id = "e", at = [0, 0], dir = "E" },
  { id = "s", at = [0, 0], dir = "S" },
  { id = "w", at = [0, 0], dir = "W" },
]

nodes = [
  { ports = ["n", "e", "s", "w"] },
]

elements = [
  { circle = [0, 0], r = 0.25, fill = "solid" },
]

lint_allow = [
  { rule = "port-on-body-edge", reason = "junction: wires meet at the centre of the dot" },
  { rule = "port-lane-clear",   reason = "junction: wires start inside the dot" },
  { rule = "slot-missing",      reason = "a junction carries no tag or markings" },
]

[slots]

The examples in this guide are normative for the format and have been machine-checked: they parse as TOML, every reference resolves, and the four atomic ones pass port-off-geometry, port-on-body-edge, port-lane-clear, port-spacing, through-axis, slot-overlap-body, slot-overlap-slot, pitch-overflow and allow-unused in all 8 orientations, using a throwaway checker written from the definitions in this guide. The toolkit's first test fixture is these five files: they must load and lint clean. If the real linter disagrees with an example, stop and resolve which one is wrong before going on. The shapes themselves are unverified against IEC drawings, like all geometry.

5. Connectivity model

This is what keeps the electrical function explicit. It is declarative data only; the toolkit never simulates anything.

• Node. A set of ports that are the same electrical point inside the symbol. Every port belongs to exactly one node. A port not listed under nodes is a node of its own. Ports may share a position only if they share a node.
• Node potential (optional): a word the set declares in [vocabulary] potentials, for example earth, protective_earth, functional_earth or frame. This is how an earth symbol says what it does: nodes = [{ ports = ["pe"], potential = "protective_earth" }]. A word the set did not declare is a load error naming the word, the file and the line.
• Path. A two-terminal relation between ports of two different nodes, with a kind. At most one path per unordered node pair.
• Through path. At most one path per symbol has through = true. It is the axis series chains run along, and it fixes the base orientation: from is the N port, to is the S port. A kind = "symbol" file with two or more nodes and no potential should have one.

What a consumer can do with this and nothing else: build a netlist across placed symbols, find nets with a source and no load, find nets that are shorted through conductors, trace which switch states complete a circuit, and know that a terminal's or junction's ports are one net. Tag letter codes (IEC 81346) and device behaviour stay in the consumer: they classify devices, not symbols.

6. Text slots and boxes

A slot reserves room for text the consumer will draw. A symbol never contains tag or marking text.

Each slot is { at = [x, y], side = "N|E|S|W", box = [w, h] } with w and h positive. Text is always upright. side says which way the box grows from at, and therefore the alignment:

Orientation. at transforms as a point and side as a direction. box stays [w, h], because the text stays upright. So one declaration covers all 8 orientations, and because the box does not rotate with the symbol, slot rules must be linted in every orientation, not just the base one.

Two boxes for layout engines. body_box is the extent of the elements. keepout_box is the body box united with every slot box. A layout engine that keeps keep-out boxes apart can never produce a label collision between symbols.

Consumer duty. The box is a maximum extent. A consumer that draws text larger than the box has broken the contract on its side; it should shrink or report, never overflow silently.

7. Composition

Parts

A composite lists parts. Each part is { as, use, ... }: a local id and the number of another file.

Placement, exactly. Parts are resolved in file order, and to may only name an anchor of an earlier part. Let T and dT be the target anchor's position and unit direction in the composite's frame, and A and dA the attaching anchor's position and direction in the part's own frame after repeat and orient. It is an error unless dA = -dT. The part is translated by T + length × dT - A. With via set to a word the set declares in [vocabulary] links (for example "mechanical_link") the composite gains the element { line = [T, T + length × dT], style = "dashed" }; length must then be positive. The flattened result is linted like any other symbol, so a placement that pushes a port off the wiring grid fails there.

What a composite inherits

• Ports: only through the explicit rename map ports = { new = "part.port" }. Every port of every part must be exported. There is no implicit export.
• Nodes and paths: inherited automatically through the renames. A path declared in the composite's own paths replaces the inherited path between the same nodes. If more than one inherited path is marked through, the composite must redeclare the one that stays; the through flag is then cleared on all the others.
• Anchors: not inherited. A composite declares its own if it is meant to be a part.
• Slots: not inherited silently. A slot value may be a string reference ("marking.in" = "contact.marking.in") or a new table. A part's tag slot is usually where the next part goes, so composites normally declare a new tag.
• Elements: all parts' elements, plus the composite's own elements if present.

Example: push-button (no coordinates except the tag slot)

schema = 1
name = "Switch, manually operated, push-button, automatic return"
kind = "symbol"
status = "unverified"
reference = { standard = "IEC 60617", number = "S00254" }

parts = [
  { as = "contact",  use = "S00227" },
  { as = "actuator", use = "S00171", attach = "link", to = "contact.link", length = 2, via = "mechanical_link" },
]

ports = { in = "contact.in", out = "contact.out" }

[slots]
tag           = { at = [-3.5, 0], side = "W", box = [6, 1] }
"marking.in"  = "contact.marking.in"
"marking.out" = "contact.marking.out"

S00171 stands for the Part 2 qualifier "operated by pushing". Its number, like every number in this guide, must be confirmed against the IEC database overview before the file is committed.

repeat: the only multi-pole mechanism

repeat(symbol, n) places n copies along +x in base orientation and returns an ordinary symbol. Pole k (counting from 1) is the symbol translated by ((k - 1) × pitch, 0), where pitch is the symbol's pole_pitch, default 4. It requires n >= 1 and a symbol with a through path; repeat(symbol, 1) still renames the ports.

• Ports, and their marking slots, are prefixed with the pole number: 1.in, 2.in, "marking.2.in". Nodes and paths repeat per pole. Pole 1's through path stays the through path; the flag is cleared on the other poles. The result's pole_pitch is n × pitch.
• The tag slot is taken from pole 1 only. A value slot likewise.
• If the symbol has an anchor with the id link and n > 1, the result gains one element: a dashed line from pole 1's link anchor to pole n's. It may cross the poles in between; that is how the standard draws it. Pole 1's anchors become the result's anchors; the other poles' anchors are dropped.
• It is available as a toolkit function for consumers, and as a data op in a part: { as = "main", use = "S00227", repeat = 3 }.

There are no poles=, pins= or inverted= parameters anywhere. Pole count is repeat, markings belong to the placement, and inversion is the orientation MR180.

table(row, n, axis, head=None): rows of cells

Returns n copies of row, copy k (from 1) stepped by the row's body extent along axis. Ports, nodes, paths and bound leads are prefixed k.. Every slot is kept: marking.<port> becomes marking.k.<port> and any other id becomes k.<id>. No through path is needed. head, if given, keeps its own ids and is placed once before the rows, as authored in the row's frame; with a stretch on axis it is first stretched to span the rows. n is at most 64. The result has no stretch and keeps the row's pole_pitch (D54).

stretch(symbol, axis, length, offsets=None): a cut line

Moves every point beyond the symbol's stretch cut on axis by length minus the natural extent: element points, ports, anchors and slots. A circle, arc or text across the cut raises ValueError, as does a length below the natural extent, a symbol with no stretch on axis, and an offset that names no port, a port not on the edge across the axis, or a place off the wiring grid or outside the stretched body. offsets places each named port, with its bound lead and its marking.<port> slot, at a coordinate along the axis. The result has no stretch on that axis, so a frame is stretched on both axes by two calls (D53).

8. Wiring contract

What every flattened symbol guarantees a router, in all 8 orientations:

1. Every port is on the 1 M wiring grid.
2. Every port is the free end of a lead (or lies on the outline) and sits on the side of the body_box that matches its direction. Its direction is that side's outward normal.
3. The wire lane of every port is clear. For a port at P with direction d, the lane is the open, unbounded region of points P + t × d + u × n with t > 0 and |u| < 0.25, where n is perpendicular to d. No element and no slot box overlaps it. The port's own lead ends at t = 0 and a marking box 0.25 M beside the wire only touches the lane, so both are fine. A wire that leaves a port straight crosses nothing of its own symbol.
4. The through path is collinear on x = 0 with ports at (0, -a) and (0, a). Series chains wire dead straight, and chained symbol heights are whole M.
5. Same-side ports are a multiple of 2 M apart, and repeated poles are 4 M apart, so a 3-pole breaker, a 3-pole contactor and a motor's u v w line up without jogs.
6. For a symbol with a through path, the x extent in base orientation of the body box united with every slot box except tag and value is at most its pole pitch, so repeated poles never overlap each other.

A symbol that cannot comply declares each exemption in lint_allow with a reason. An exemption whose rule would not have fired is itself an error, so exemptions cannot rot.

9. Lint rules

lint(symbol, required_slots=()) runs on a flattened symbol and returns findings: rule, severity, message, optional location, optional orientation. Geometric rules run in all 8 orientations. Composition rules run in the resolver and are reported the same way. All are errors unless marked. Data repo gates require zero findings of either severity, so a warning is simply a finding that more often deserves a lint_allow entry; exemptions work the same for both. slot-missing, through-missing and pitch-overflow apply only to kind = "symbol"; every other rule applies to every kind.

Every rule ships with a deliberately broken fixture file that makes it fire, and a test that asserts it does.

10. Resolved output

The build flattens every file and writes JSON. This is the interface for consumers that are not Python, and for simple consumers of any kind: they never implement composition.

• build/resolved/<number>.json: one flattened symbol. Same schema as the source, with parts gone, composite ports expanded to the array form, slot references expanded to tables, nodes listing every node explicitly, and two computed keys: body_box and keepout_box, each [[min_x, min_y], [max_x, max_y]] in base orientation. A stretch key, an array of { "axis", "at" }, is written only when set.
• src/<package>/bundle.json: the bundle, shipped as package data: { "schema": 1, "standard": "IEC 60617", "symbols": { "S00227": { ... }, ... } }. It is generated and tracked like build/, and stale_build covers it. An optional wires array of { "id", "weight", "style" } is written only when the set has wire styles.
• Output is deterministic: UTF-8, LF line endings, 2-space indent, object keys sorted, arrays in source order, a whole number written without a decimal point and any other number in its shortest exact decimal form, one trailing newline. A symbol change shows up as a reviewable diff.

A consumer in another language needs the bundle, the schema, and the orientation and slot-box rules from sections 3 and 6. That is about thirty lines of code.

11. Toolkit API and consumer usage

All types are frozen dataclasses. All functions are pure except those in files, project and cli. Transforms are free functions, never methods.

Point(x, y)   Box(min, max)   Direction: N E S W   Orientation: R0 .. MR270
Vocabulary(path_kinds, potentials, links)
Line | Polyline | Circle | Arc | Text                      = Element
Port(id, position, direction, description)
Node(ports, potential)          Path(from_port, to_port, kind, through)
Anchor(id, position, direction) Slot(id, position, side, box)
Reference(standard, number, edition, form)
Symbol(name, kind, status, reference, elements, ports, nodes, paths, anchors, slots, pole_pitch, stretch)
Library(standard, title, number_pattern, symbols, vocabulary, required_slots, wires)    get(number), __iter__ (sorted by number), __len__
Finding(rule, severity, message, location, orientation)
Stretch(axis, at)               WireStyle(id, weight, style)

load_library(root) -> Library             read library.toml and symbols/*.toml, validate, resolve, flatten
load_bundle(json_path) -> Library         read a resolved bundle
orient(symbol, orientation) -> Symbol       ports, nodes, paths, anchors and slots all carried along
translate(symbol, dx, dy) -> Symbol         used by composition and repeat; consumers place symbols themselves
repeat(symbol, n) -> Symbol
stretch(symbol, axis, length, offsets=None) -> Symbol    section 7
table(row, n, axis, head=None) -> Symbol    section 7
wire(library, style_id, points) -> Symbol    the wire styles of library.toml
body_box(symbol) -> Box    keepout_box(symbol) -> Box    slot_box(slot) -> Box
lint(symbol, required_slots=()) -> tuple[Finding, ...]
to_svg(symbol, *, module_mm=2.5, annotate=False, texts=None, tint=None) -> str
write_build(library, root) -> tuple[Path, ...]    writes build/ and the bundle
stale_build(library, root) -> tuple[Path, ...]    files that differ from what write_build would write, stale extras included
init(root) -> tuple[Path, ...]    build(root) -> tuple[Path, ...]    check(root) -> tuple[Finding, ...]    the three verbs of the symdef command

annotate=True draws the grid, ports with ids and lanes, anchors, slot boxes, and both boxes. texts maps slot ids to sample strings so the gallery can show a filled-in symbol.

to_fragment_mm writes the same placeable <g> fragment as to_fragment, in millimetres, with no scale transform (D52). Each coordinate and radius is multiplied by module_mm. Stroke widths come from weights_mm, one entry per weight, dash lengths from dash_mm, and the font size from font_mm; these are the caller's millimetres. Text capitals are centred on the anchor by cap_ratio, the capital height as a fraction of the font size. The caller passes the font family. to_svg and to_fragment are unchanged.

to_svg, to_fragment and to_fragment_mm take the keyword tint, the colour of every fill = "tint" shape. It must be #rgb, #rrggbb or a letters-only name, or the call raises ValueError; with None a tinted shape draws fill="none". Output without a tinted shape does not change (D57).

A set declares wire styles in library.toml as [[wire]] tables with id, weight (normal | thick) and style (solid | dashed). wire returns an element symbol of one open polyline in that style, with no ports; points are Points or (x, y) pairs, at least two (D56).

A data repo's Python package is a thin wrapper: from my_symbols import LIBRARY, loaded from the bundled JSON shipped as package data.

What a drawing library does

from symdef import Orientation, keepout_box, orient, repeat
from my_symbols import LIBRARY

breaker = orient(repeat(LIBRARY.get("S00287"), 3), Orientation.R0)

# The placement is the consumer's own type. The symbol stays a definition.
placed = Placement(
    symbol=breaker,
    at=Point(40, 120),
    tag="-Q1",
    markings={"1.in": "1", "1.out": "2", "2.in": "3", "2.out": "4", "3.in": "5", "3.out": "6"},
)

• Layout keeps keepout_box rectangles apart and aligns through axes.
• Routing starts each wire at a port, along its direction. The lane is guaranteed clear.
• Text is drawn into slot_box(slot) with the alignment given by the slot's side.
• Netlisting and checks read nodes and paths.
• Markings are keyed by port id. The keys are validated against the symbol's ports, so a marking for a port that does not exist fails loudly at placement.

12. Repo layout, build and gates

symdef/                                  standard-agnostic toolkit
  src/symdef/
    schema/symbol.schema.json            the published contract
    model.py geometry.py units.py        types
    load.py resolve.py vocabulary.py     TOML and JSON in, flattening, declared words
    orient.py repeat.py boxes.py         pure operations
    lint/                                one module per rule group
    svg.py                               rendering
    files.py project.py cli.py           the impure modules: files, the three verbs, the command
  tests/fixtures/broken/                 one failing file per lint rule

my-symbols/                              a data repo: data only (`symdef init` writes it)
  library.toml                           standard, title, number_pattern, vocabulary, rules
  symbols/resistor.toml ...              source of truth
  src/mysymbols/bundle.json              generated, tracked
  build/                                 generated by `symdef build`, tracked
    resolved/  svg/  annotated/  README.md

The toolkit knows nothing about any standard. Everything standard-specific is in the data repo's library.toml, including its words and its required slots; an optional package key names the folder under src/ that holds the bundle:

standard = "IEC 60617"
title = "IEC 60617 symbols"
number_pattern = '^S\d{5}$'

[vocabulary]
path_kinds = ["conductor", "switch_open", "switch_closed", "impedance", "source", "diode"]
potentials = ["earth", "protective_earth", "functional_earth", "frame"]
links = ["mechanical_link"]

[rules]
required_slots = ["tag", "marking.<port>"]

Any other standard is a sibling data repo that reuses the toolkit and every gate.

Gates in a data repo (symdef check)

• Every file validates against the schema and resolves.
• Every flattened symbol lints with zero findings, warnings included, in all 8 orientations.
• Every symbol with a through path also lints clean as repeat(symbol, 3).
• stale_build reports nothing, so build/ always matches symbols/.
• The packaged bundle holds the source's symbols, and they lint clean.
• Reference numbers are unique, match the standard's pattern and equal the file stems.

Gates in the toolkit

• Every lint rule has a fixture that makes it fire.
• orient round-trips: applying an orientation and its inverse returns the same symbol (property test).
• The five example files in this guide load and, once the rules exist, lint clean.
• The JSON Schema and the Python loader agree: a file accepted by one is accepted by the other (fixture-driven).
• Every pure module is free of file and console I/O, the clock, randomness and state writes (scripts/fp_purity_gate.py).

Constraints carried over

Python >=3.14, uv only, every dependency pinned to the exact latest stable version, ruff, ty, pytest with hypothesis, vulture. There is no runtime dependency. TOML is read with the standard library's tomllib. Geometry is unverified until compared with the IEC database drawings; the gallery shows the status next to each symbol.

13. What is not built

• Never build: Python symbol factories, a kit module, a dashed_line helper (dashed is a line style), a Registry of factories, or a Ports: docstring convention. The symbol file is the documentation.

14. Deferred and open

• Coupling between paths (a coil actuating contacts, magnetically coupled windings). In detached representation this lives between separately placed symbols, so it belongs to the consumer's device model. Revisit for attached composites such as a contactor drawn as one symbol.
• Conventional marking hints. EN 50005 function digits (make = 3/4, break = 1/2, change-over = 1/2/4) could be optional per-port data so consumers without a catalog get sensible defaults. Not in schema 1.
• Connections between parts inside a composite (merging two parts' nodes). Not needed for IEC composites found so far.
• Small symbols such as the terminal (S00017), whose natural port positions are on a 0.5 M circle. Decide per symbol: leads to the wiring grid, or a declared exemption as for the connection point.
• Reference numbers quoted here (S00230, S00171, S00287) come from memory of the IEC database overview and must be confirmed before use.
• Verification. The IEC drawings are behind a subscription. Until bought, every symbol stays unverified.