Wiring DSL: An Intermediate Specification for Wiring Diagrams

1. Purpose

This DSL describes device wiring and terminal-level connections in a structured, machine-readable format.

It is designed as an authoring format, not a final rendering format.

Typical outputs:

• Connection diagrams
• Wiring tables
• Textual descriptions
• Validation reports

2. Design Principles

2.1 Minimal but Unambiguous

The DSL must:

• Avoid ambiguity in connection targets
• Be easy for humans and AI to write
• Avoid premature abstraction

2.2 Authoring vs Normalization

This format is authoring-oriented.

Downstream systems are expected to:

• Parse and normalize references
• Enrich missing structure
• Validate consistency

3. YAML Authoring Features

This DSL MAY use standard YAML authoring features where they improve readability and reduce repetition.

These features are treated as authoring conveniences, not as part of the DSL's semantic model.

3.1 Supported Authoring Features

The following YAML features MAY be used:

• Anchors (&name)
• Aliases (*name)

Processors MUST resolve these features before DSL validation and normalization.

The canonical form of this DSL is the fully expanded structure.

3.2 Merge Keys

YAML merge keys (<<) are optional in v1.

Processors MAY support them, but documents SHOULD NOT rely on them for interchange between tools.

3.3 Authoring Guidance

Use YAML reuse features only when they improve clarity.

If a structure becomes harder to inspect after expansion, prefer explicit repetition.

Example:

```yaml connections: - from: controller.cn1.1 to: sensor.tb1.1 label: RS-485 A note: &twisted_pair twisted pair

• from: controller.cn1.2 to: sensor.tb1.2 label: RS-485 B note: *twisted_pair ```

Downstream systems should interpret this only after YAML expansion.

4. Core Concepts

The DSL is built around three concepts:

5. Minimal Schema

Only two sections are required:

yaml devices: [] connections: []

6. Devices

6.1 Structure

yaml devices: - id: controller name: Main Controller ports: - id: cn1 contacts: - id: "1" label: A - id: "2" label: B

6.2 Rules

• id is required and must be unique
• name is for display only
• Each device must define at least one port
• Each port must define at least one contact

6.3 Contact Fields

Notes:

• id is used in references
• label is optional display metadata

7. Connections

7.1 Basic Form

yaml connections: - from: controller.cn1.1 to: sensor.tb1.1

7.2 Reference Format

All references must follow:

device_id.port_id.contact_id

Example:

controller.cn1.1 sensor.tb1.3

7.3 Optional Fields

yaml connections: - from: controller.cn1.1 to: sensor.tb1.1 label: RS-485 A note: twisted pair

7.4 Rules

• Connections must always be between contacts
• Device-to-device connections are not allowed
• References must resolve to defined contacts

8. Example

```yaml devices: - id: controller name: Controller ports: - id: cn1 contacts: - id: "1" label: A - id: "2" label: B - id: "3" label: SG

• id: sensor name: Sensor ports:
  • id: tb1 contacts:
    • id: "1" label: 485+
    • id: "2" label: 485-
    • id: "3" label: GND

connections: - from: controller.cn1.1 to: sensor.tb1.1 label: RS-485 A

• from: controller.cn1.2 to: sensor.tb1.2 label: RS-485 B

• from: controller.cn1.3 to: sensor.tb1.3 label: Signal GND ```

9. What This DSL Does NOT Define

The following are intentionally excluded in v1:

• Diagram layout (coordinates, geometry)
• Cable definitions
• Signal dictionaries
• Validation rules
• Rendering instructions

These belong to downstream systems, not the authoring DSL.

10. Expected Post-Processing

A processing pipeline should:

1. Parse references
2. Normalize structure
3. Validate:

• Missing contacts
• Invalid references

• Duplicate connections

  1. Generate outputs:

• Diagrams (Mermaid / D2 / SVG)

• Tables (Markdown / Word)

• Documentation text

11. Extension Points (Future)

The following features are intentionally deferred but anticipated:

11.1 Nets (multi-point connections)

yaml nets: - id: rs485_a members: - controller.cn1.1 - sensor1.tb1.1 - sensor2.tb1.1

11.2 External Endpoints

yaml external: - id: plc_ai1 name: PLC Analog Input 1

11.3 Signals (normalized dictionary)

yaml signals: - id: RS485_A name: RS-485 A

11.4 Cables

yaml cables: - id: cable1 cores: - id: WH

11.5 Variants / Conditions

yaml variants: - id: model_A

12. Authoring Guidelines (for AI and Engineers)

• Always use full references (device.port.contact)
• Do not omit hierarchy levels
• Prefer clarity over brevity
• Use label for human meaning, not identifiers
• Do not encode layout information
• Do not assume implicit connections

13. Philosophy

This DSL treats wiring as:

A set of explicit relationships between contact points

It avoids:

• Visual assumptions
• Tool-specific constraints
• Premature standardization

The goal is stable structure first, rendering later.