# YAML reference

Canonical: https://docs.shumoku.dev/en/library/yaml
Language: en

@shumoku/core · runtime schema

# YAML reference

[Runtime schema source](https://github.com/konoe-akitoshi/shumoku/blob/main/libs/@shumoku/core/src/parser/parser.ts)

Fields accepted by the Shumoku YAML parser.

## Document

| Field | Type | Description | Required |
| --- | --- | --- | --- |
| `version` | `string` | Document format version | no |
| `name` | `string` | Topology name | no |
| `description` | `string` | Topology description | no |
| `nodes` | `object[]` | Network devices | no |
| `links` | `object[]` | Connections between nodes | no |
| `subgraphs` | `object[]` | Logical or hierarchical regions | no |
| `settings` | `object` | Layout and rendering settings | no |
| `pins` | `object[]` | Top-level hierarchical boundary pins | no |

## Node

| Field | Type | Description | Required |
| --- | --- | --- | --- |
| `id` | `string` | Stable node identifier; a fallback is generated if omitted | no |
| `label` | `string | string[]` | Displayed node label | no |
| `shape` | `string` | Node shape such as rounded, rect, circle, or diamond | no |
| `type` | `string` | Device type used by the default icon resolver | no |
| `parent` | `string` | Parent subgraph identifier | no |
| `rank` | `number | string` | Optional layout rank hint | no |
| `style` | `object` | — | no |
| `metadata` | `object` | — | no |
| `vendor` | `string` | Hardware or cloud vendor | no |
| `service` | `string` | Cloud service name | no |
| `model` | `string` | Hardware model name | no |
| `resource` | `string` | — | no |
| `icon` | `string` | Custom icon URL | no |
| `identity` | `any` | — | no |
| `ports` | `any[]` | — | no |

## Link

| Field | Type | Description | Required |
| --- | --- | --- | --- |
| `id` | `string` | Stable link identifier; a fallback is generated if omitted | no |
| `from` | `string | object` | Source node or endpoint | yes |
| `to` | `string | object` | Destination node or endpoint | yes |
| `label` | `string | string[]` | Displayed link label | no |
| `type` | `string` | Line style such as solid, dashed, thick, or double | no |
| `arrow` | `string` | — | no |
| `standard` | `string` | Ethernet standard applied to both endpoints | no |
| `cable` | `object` | — | no |
| `redundancy` | `string` | — | no |
| `vlan` | `number | number[]` | VLAN ID or trunk VLAN IDs | no |
| `style` | `object` | — | no |

## Settings

| Field | Type | Description | Required |
| --- | --- | --- | --- |
| `direction` | `string` | Layout direction such as TB or LR | no |
| `theme` | `string` | Render theme: light or dark | no |
| `nodeSpacing` | `number` | Spacing between nodes in the same rank | no |
| `rankSpacing` | `number` | Spacing between layout ranks | no |
| `subgraphPadding` | `number` | — | no |
| `canvas` | `object` | — | no |
| `legend` | `boolean | object` | — | no |

## Executable example

```
name: Branch network
nodes:
  - id: router
    label: Router
    type: router
  - id: switch
    label: Access switch
    type: l2-switch
links:
  - from: router
    to: switch
```

`examples/getting-started.yaml`