Wiring DSL: A Text-Based Intermediate DSL Specification for Wiring Diagram Processing

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. Core Concepts

The DSL is built around three concepts:

4. Minimal Schema

Only two sections are required:

yaml devices: [] connections: []

5. Devices

5.1 Structure

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

5.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

5.3 Contact Fields

Notes:

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

6. Connections

6.1 Basic Form

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

6.2 Reference Format

All references must follow:

device_id.port_id.contact_id

Example:

controller.cn1.1 sensor.tb1.3

6.3 Optional Fields

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

6.4 Rules

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

7. 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 ```

8. 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.

9. 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

10. Extension Points (Future)

The following features are intentionally deferred but anticipated:

10.1 Nets (multi-point connections)

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

10.2 External Endpoints

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

10.3 Signals (normalized dictionary)

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

10.4 Cables

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

10.5 Variants / Conditions

yaml variants: - id: model_A

11. 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

12. 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.