Single-line diagram (SLD)

About single-line diagrams

A single-line diagram (also called a one-line diagram) represents the electrical power system of a facility or substation using a single line to stand in for all three phases of a three-phase AC system. Equipment — transformers, circuit breakers, buses, motors, loads — is shown with standardized symbols, and the power flow path connects them top-to-bottom from source to load. Electrical engineers, utility planners, and facility managers use SLDs as the primary reference document for every power system project: it is the first deliverable in any interconnection application, arc-flash study, or commissioning package.

Schematex follows IEEE Std 315 (ANSI Y32.2) graphic symbol conventions for equipment, extended with IEC 60617 winding-configuration notation for transformer variants. This page documents what the parser accepts today.

1. Your first single-line diagram

The simplest SLD: a utility source, a transformer, a breaker, and a load.

Four rules cover 80% of usage:

1. Start with sld, optionally followed by a quoted title.
2. Declare each equipment item as id = nodeType [attributes] — one per line.
3. Connect items with from -> to, optionally adding [cable: "…", label: "…"].
4. IDs may contain letters, digits, underscores, and hyphens — but must start with a letter.

Comments may start with #, //, or Mermaid-style %% on their own line.

2. Node types

A node line is id = nodeType [attr: value, …]. The node type determines the symbol drawn.

2.1 Sources

2.2 Transformers

2.3 Buses and nodes

2.4 Switching and protection

2.5 Protection and monitoring

2.6 Loads and equipment

2.7 Metering

3. Node attributes

Attributes are written inside […] after the node type, comma-separated.

Example with all common attributes:

xfmr = transformer_dy [
  label: "Main Transformer",
  voltage: "13.8kV/480V",
  rating: "1000 kVA",
  impedance: "5.75%Z"
]

The attribute block may span multiple lines — the parser joins lines until the ] is balanced.

4. Connections

A connection line is fromId -> toId, optionally followed by [cable: "…", label: "…"].

bus1 -> cb1
bus1 -> cb1 [cable: "3#2/0 AWG"]
bus1 -> cb1 [cable: "3#2/0 AWG", label: "Feeder A"]

Rules:

• Both IDs must be declared before or after the connection — all connections are validated at end of parse.
• Only -> (directed, source-to-load) is accepted. The connection direction is used for layout.
• An unknown node ID throws SLDParseError: Connection references unknown node "…".

5. Labels & comments

• Title: sld "Substation One-Line" — first line only.
• Node label: id = type [label: "…"] — the display name.
• Connection label: A -> B [label: "…"] — appears alongside the connecting line.
• Cable annotation: A -> B [cable: "3#2/0 AWG, 200ft"] — conductor specification.
• Comments: # at the start of a line. Inline # on the same line as a node or connection is also stripped.
• Residential aliases: IEC / REBT vocabulary such as mcb, rcd, rcbo, rccb, pia, iga, main_switch, consumer_unit, distribution_board, panel, and panelboard is accepted as input and mapped to existing SLD primitives.

6. Reserved words & escaping

Reserved at line start: sld (header).

Operator token — avoid -> inside node IDs. IDs may contain [A-Za-z][A-Za-z0-9_-]* — hyphens are valid (e.g. CB-101 is a legal ID).

Attribute block — […] brackets may span multiple physical lines. The parser joins continuation lines until the bracket depth reaches zero.

Duplicate IDs throw SLDParseError: Duplicate node id "…".

7. Common mistakes

8. Grammar (EBNF)

document      = header NEWLINE ( blank | comment | node-def | connection )*

header        = "sld" ( WS quoted-string )? NEWLINE
quoted-string = '"' any-char-but-quote* '"'

node-def      = id WS "=" WS node-type ( WS "[" attr-list "]" )? NEWLINE
node-type     = "utility" | "generator" | "solar" | "wind" | "ups"
              | "transformer" | "transformer_dy" | "transformer_yd"
              | "transformer_yy" | "transformer_dd"
              | "autotransformer" | "transformer_3winding"
              | "bus" | "bus_tie" | "hub"
              | "breaker" | "breaker_vacuum" | "switch" | "switch_load"
              | "ground_switch" | "ats" | "recloser" | "sectionalizer"
              | "fuse" | "fuse_cl"
              | "ct" | "pt" | "relay" | "surge_arrester" | "ground_fault"
              | "motor" | "load" | "capacitor_bank" | "harmonic_filter" | "vfd"
              | "watthour_meter" | "demand_meter"
              | residential-alias

residential-alias
              = "mcb" | "mccb" | "rcd" | "rcbo" | "rccb"
              | "differential" | "diferencial" | "pia" | "iga"
              | "main_switch" | "isolator" | "disconnector"
              | "consumer_unit" | "distribution_board" | "panel" | "panelboard"

attr-list     = attr ( "," attr )*
attr          = key ":" WS quoted-string

connection    = id WS "->" WS id ( WS "[" conn-attrs "]" )? NEWLINE
conn-attrs    = conn-attr ( "," conn-attr )*
conn-attr     = "cable" ":" WS quoted-string
              | "label" ":" WS quoted-string

id            = [A-Za-z] [A-Za-z0-9_-]*
key           = [A-Za-z] [A-Za-z0-9_]*
comment       = ( "#" | "//" | "%%" ) any NEWLINE

The attribute block […] may span multiple physical lines — the parser joins continuation lines until the bracket depth returns to zero.

Authoritative source: src/diagrams/sld/parser.ts. If this diverges from the parser, the parser wins — please open an issue.

9. Standard compliance

Schematex SLDs follow IEEE Std 315 (ANSI Y32.2) graphic symbol conventions for switching equipment, transformers, and sources. Transformer winding configuration variants (transformer_dy, transformer_yy, etc.) use IEC 60617 Δ/Y notation. Protection relay device numbers follow ANSI/IEEE C37.2.

What is implemented today:

• ✅ All source types: utility, generator, solar, wind, UPS
• ✅ Six transformer variants plus autotransformer and three-winding
• ✅ Bus, bus-tie, hub
• ✅ IEC / REBT residential vocabulary aliases mapped onto canonical primitives
• ✅ Full switching set: breaker, vacuum breaker, switch, load switch, ground switch, ATS, recloser, sectionalizer, fuse, current-limiting fuse
• ✅ Protection and monitoring: CT, PT, relay (with ANSI device number), surge arrester, ground-fault detector
• ✅ Load equipment: motor, load, capacitor bank, harmonic filter, VFD
• ✅ Metering: watt-hour meter, demand meter
• ✅ Directed connections with cable and label annotations
• ✅ label, voltage, rating, device node attributes; arbitrary nameplate data
• ⏳ Bus-tie switching with open/closed state indicator
• ⏳ Protection zones (dashed boundary lines enclosing relay + CT)
• ⏳ Arc-flash label blocks (incident energy, PPE level, working distance)
• ⏳ Voltage-level banding (automatic color-coded horizontal bands by kV level)

References:

• IEEE Std 315-1975 / ANSI Y32.2-1975 — Graphic Symbols for Electrical and Electronics Diagrams
• IEC 60617:2025 (BS 3939) — Graphical symbols for diagrams
• ANSI/IEEE C37.2 — Electrical Power System Device Function Numbers

10. Related examples

11. Roadmap

Planned — not yet parseable. Do not use these in generated DSL today; the parser will reject or ignore them.

• Bus-tie open/closed state — bus_tie with explicit open/closed attribute so the symbol renders in the correct switching position.
• Protection zones — a zone: or boundary: block that draws a dashed rectangle around a set of nodes (relay + CT + breaker) to indicate a protection zone.
• Arc-flash annotation blocks — arc_flash: [incident_energy: "8 cal/cm²", ppe: "2", distance: "18in"] per IEEE 1584.
• Voltage-level banding — automatic horizontal shading bands by kV level; nodes are placed in their voltage tier automatically.
• Bidirectional connection (<->) — for bus-tie or normally-open tie paths where direction is undefined.

Track in the GitHub issues if you need any of these sooner.