netviz YAML schema specification

Version: netviz.dev/v1alpha1 Status: draft — normative for netviz 0.1.x

This document specifies the on-disk YAML format that netviz reads. It is the contract between the inventory author, the loader (netviz.loader), the typed models (netviz.models) and the renderers (netviz.render).

Field names and value spaces are derived from the following standard data models:

Every YAML field that has a standard counterpart is mapped to its YANG path in §9 YANG mapping. netviz is a documentation and visualisation tool, not a configuration agent: it therefore records intended state, and happily accepts values for nodes that the YANG models declare config false (for example if:phys-address and if:speed). Those cases are called out individually.

See also. This document explains why the schema is shaped the way it is. Three companions answer narrower questions: schema-reference.md is the per-field lookup table, generated from the pydantic models; validation-rules.md documents every rule this release actually enforces and how to suppress it; yang-mapping.md expands §9 with the reasoning and with what is deliberately left uncovered.

Contents

1. Conventions
2. Inventory layout and loading
3. Document envelope
4. Names and references
5. Scalar types
6. Device kinds
7. Cables
8. Adapters
9. YANG mapping
10. Validation rules
11. Worked examples
12. Compatibility policy
13. Editor integration
14. Tunnels
15. Patch panels
16. Routing
17. Power
18. Layout: diagram geometry
19. Identity: users and groups
20. Test suites: executable assertions
21. Diagram annotations: notes, areas and legends
22. Per-element styling and themes
23. Network namespaces and veth pairs
24. Firewalls: zones and policy

1. Conventions

• The key words MUST, MUST NOT, SHOULD, SHOULD NOT and MAY are used as in RFC 2119.
• YAML keys are snake_case. Where a field is derived from a YANG node, the hyphens of the YANG identifier become underscores: prefix-length → prefix_length, phys-address → mac (renamed for readability, see §9). The three envelope keys apiVersion, kind and metadata keep their Kubernetes-style spelling because they are envelope, not model, fields. apiVersion is the only camelCase key outside a spec.style block, whose three compound names keep the spelling SVG and mxGraph give them for the reason §22.1 records.
• Unknown keys are rejected (NV-D005). Silently ignoring a misspelt trunk_vlan would produce a diagram that disagrees with the file, which is the exact failure mode this tool exists to prevent.
• Enumerated values are lower-case and hyphen-free unless quoted from a standard (for example admit-all-frames).
• Defaults are applied by the loader, not by the renderer. A document and its fully defaulted, normalised form MUST render identically.
• All parsing is done with a YAML 1.1 safe loader. Aliases and anchors are supported within a single document; custom tags are rejected.

1.1 Reading the tables

Each field table uses these columns:

• Field — the YAML key, path.to.key relative to the section's root.
• Type — see §5.
• Req. — M mandatory, O optional, C conditional (condition in Notes).
• Default — value applied when the key is absent.

2. Inventory layout and loading

An inventory is a directory tree. netviz walks it recursively and loads every YAML document it finds. Folders are for humans — group by site, by rack, by tenant, whatever suits the team. Cross-references (§4.2) work across any file in the tree; the only thing a folder contributes is a namespace (§2.2) that keeps names short without making them collide.

2.1 Discovery rules

Loading is total: a file that cannot be read, a YAML syntax error, a schema violation and a duplicate name are all reported with their location and the walk continues, so one broken file cannot hide the rest of the inventory.

2.2 Namespaces and name resolution

An element's fully-qualified name is the directory holding its document, relative to the inventory root, plus its metadata.name. A switch named sw1 declared in sites/berlin/rack1/sw1.yaml is therefore sites/berlin/rack1/sw1, and one declared at the root is just sw1.

References (§4.2) are written with the plain name and resolved outwards:

1. the namespace of the referring document,
2. each ancestor namespace, nearest first, the root last,
3. the inventory as a whole — but only when exactly one element carries that name; otherwise the reference is ambiguous and every candidate is named in the diagnostic (NV-N002).

So two racks may each hold a sw1 without qualification, and a device at the root is visible from everywhere. A reference MAY also be written fully qualified (sites/berlin/rack1/sw1), which is tried relative to the current namespace first and as an absolute name second.

2.3 .netvizignore

Optional, one per directory, applying to that directory and everything below it. Blank lines and # comments are skipped; ! negates a pattern and the last matching rule wins; a trailing / restricts a rule to directories; a pattern containing a / anywhere but at the end is anchored to the directory holding the file, otherwise it matches a basename at any depth; * and ? do not cross /, ** does. As in git, a path below an excluded directory cannot be re-included.

vendor/                 # a directory, anywhere below this file
*.bak.yaml              # a basename pattern, at any depth
/staging.yaml           # only in this directory
generated/**            # everything below generated/
!generated/keep.yaml    # ... except this one (the parent is not excluded)

2.4 Provenance

The loader attaches the source location (file, document index, line) to every element. It is not a user-writable field; anything the user puts under a reserved provenance key is rejected. Diagnostics quote it as sites/hq/switches/sw-access-01.yaml#0:17.

Provenance is tracked per field, not merely per document, and it survives the two rewrites the loader performs before validation: interface range expansion (§6.2.5) and template merging (§6.6). A value a template supplied is reported against the template's file and line, with a note naming the device that inherited it; a value the device overrode is reported against the device. netviz show --raw prints a document as written, unexpanded and unmerged, next to the resolved output the same command prints without it.

2.5 Suggested layout

inventory/
├── sites/
│   ├── hq/
│   │   ├── routers/rtr-edge-01.yaml
│   │   ├── switches/sw-access-01.yaml
│   │   ├── hosts/pc-alice.yaml
│   │   └── cables/hq-links.yaml          # several documents in one file
│   └── lab/
│       └── lab.yaml
├── .netvizignore                       # optional exclusions (NV-L006)
└── _drafts/                              # skipped (NV-L002)

sw-access-01 above is fully qualified as sites/hq/switches/sw-access-01; a cable in sites/hq/cables/ refers to it as plain sw-access-01 because the lookup walks up to sites/hq and finds it there (§2.2).

3. Document envelope

Every document is a mapping with exactly four top-level keys.

apiVersion: netviz.dev/v1alpha1
kind: switch
metadata:
  name: sw-access-01
  description: Access switch, HQ ground floor
  labels:
    site: hq
    rack: g-01
spec:
  ...

The first twelve kinds are elements: each becomes a node or an edge of the graph. The last six are not. template declares a reusable partial device spec and is merged away by the loader (§6.6); layout carries diagram geometry for elements declared elsewhere (§18); testsuite carries assertions about the network the other documents describe (§20); note, area and legend carry what the diagram says about that network, and nothing the tool concludes from it (§21). None of the six is ever drawn as a node, listed by netviz list, or resolvable as a cable endpoint.

3.1 metadata

Labels drive filtering (netviz render --select site=hq) and grouping (--group-by rack), so prefer a small, consistent key set: site, rack, role, env, owner.

Annotations are the opposite: they are read by the tool, not by the user. The one this revision defines is netviz/ignore, which suppresses validation rules on the element carrying it (§10.11):

metadata:
  name: spare-switch
  annotations:
    netviz/ignore: "W103, E004"   # or "*" for every rule

3.2 metadata.location

Where the hardware is. Optional, and available on every kind, because a patch panel is racked exactly as a server is.

metadata:
  name: srv-app-01
  location:
    site: hq
    room: mdf
    rack: r1
    position: 10        # lowest rack unit occupied
    height: 2           # rack units, upwards from `position`
    rack_height: 42     # how tall the cabinet is

Semantics

• A rack is identified by (site, room, rack) together, so two elements are in the same cabinet only when all three agree. An unset site or room is the empty string, never a wildcard: an inventory that gives one element a full address and another only a rack name has not said the two are in one place.
• position is the lowest unit and height counts up, so a 2U server at position: 10 fills U10 and U11. Two elements whose spans intersect are NV-U001; an element whose top exceeds rack_height is NV-U002.
• An element that names a rack but no position is in the room and nowhere in particular. It is not drawn on the elevation, and it collides with nothing.
• netviz render --layer rack draws one front elevation per rack, with empty units shown. Free-text spec.location (§6.1) is unaffected and stays a label.

4. Names and references

4.1 Name grammar

name        = label *( ( "-" / "_" / "." ) label )
label       = ALPHA-DIGIT *( ALPHA-DIGIT )
ALPHA-DIGIT = %x41-5A / %x61-7A / %x30-39   ; A-Z a-z 0-9

Element names are 1–253 characters, case-sensitive, and MUST NOT contain : — the colon is the reference separator (§4.2).

Interface names are 1–64 characters and use a wider set, because vendors do:

ifname = 1*( ALPHA-DIGIT / "-" / "_" / "." / "/" )

Examples: eno1, eth0, GigabitEthernet1/0/1, ge-0/0/1, bond0.30, enx001122334455. Interface names are unique within a device (NV-I001) and map directly to the if:interface list key, which is a plain string in RFC 8343.

4.2 Interface references

Cables and adapters point at interfaces with a two-part reference:

ifref = name ":" ifname

sw-access-01:GigabitEthernet1/0/1. The device part MUST resolve to a declared element of kind switch, router, hub, computer, server or adapter; the interface part MUST resolve to an interface declared on that element (NV-C002, NV-C003).

An equivalent mapping form is accepted and normalises to the same value — use it when a name would otherwise need quoting:

endpoints:
  - device: sw-access-01
    interface: GigabitEthernet1/0/1

A device reference (no colon) is used by adapter.spec.upstream.attached_to and resolves to the element as a whole.

5. Scalar types

6. Device kinds

switch, router, hub, computer and server share one spec shape. They differ only in which fields are permitted (§6.5) and in how the renderer draws them. computer and server are structurally identical; the distinction is purely presentational (workstation vs. rack-mount glyph) and for label-free filtering.

6.1 Device spec

6.1.1 forwarding

Maps to ip:ipv4/forwarding and ip:ipv6/forwarding, which RFC 8344 defines per interface. netviz declares it once per device as the device-wide default; an interface MAY override it (interfaces[].ipv4.forwarding).

Default by kind: true for router, false for every other kind. This matches the RFC 8344 default (false) for hosts while keeping router documents free of boilerplate.

6.2 interfaces[]

6.2.1 Interface type

The four core types are mandatory for every implementation:

Three extension types complete the model for the common cases that would otherwise be inexpressible (sub-interfaces, link aggregation and overlays):

Only ethernet, wifi and lag can terminate a cable (NV-C009); only tunnel can terminate a tunnel (NV-T003).

6.2.2 mtu

RFC 8343 has no interface-level MTU leaf — the only standard MTU leaves are per address family in RFC 8344 (ip:ipv4/mtu, uint16, min 68; ip:ipv6/mtu, uint32, min 1280). netviz therefore treats interfaces[].mtu as the layer-2 MTU and propagates it to both families unless they override it. See §9.2 for the exact mapping and the ietf-interfaces-common note.

6.2.3 ipv4 / ipv6

Canonical form mirrors the RFC 8344 containers:

ipv4:
  enabled: true
  forwarding: false
  mtu: 1500
  addresses:
    - ip: 10.10.10.1
      prefix_length: 24

gateway is the one field of these containers that RFC 8344 does not define: a default route lives in ietf-routing (rt:routing/…/static-routes/…/next-hop-address), not in ietf-ip. netviz keeps it on the interface anyway, because that is where an operator writes it and where the only check worth making — is the first hop on-link? — can be made. An IPv6 link-local gateway such as fe80::1 is exempt from that check.

Address entries:

Shorthands. Both are normalised to the canonical form on load, so tooling downstream of the loader only ever sees the long form:

ipv4:
  addresses: [10.10.10.1/24]      # address string  → {ip, prefix_length}
ipv6: [2001:db8:10::1/64]         # bare list       → {addresses: [...]}

6.2.4 vlan

access/trunk are operational vocabulary, not 802.1Q vocabulary. §9.3 gives the exact translation into dot1q:bridge-port leaves plus VLAN registration entries — read it before assuming a vendor-specific meaning.

6.2.5 range — declaring many interfaces at once

A 48-port access switch is 48 near-identical interfaces entries. Writing them out by hand is the single largest obstacle to describing a real access layer, so an entry MAY declare range instead of name:

interfaces:
  - range: GigabitEthernet1/0/[1-48]
    type: ethernet
    description: Access port {}
    enabled: false
    mtu: 1500
    vlan: {mode: access, access_vlan: 10}

The entry above is forty-eight entries. Expansion happens in the loader, immediately after the document is parsed and before any model validation, so everything downstream — netviz validate, the graph, every renderer, netviz show, an editor driven by the JSON Schema — sees an ordinary list of interfaces and needs no notion of a range at all. A range never appears in rendered output, and netviz show without --raw prints the expansion.

Grammar. A range is a string of interface-name characters (§4.1) with one or more spans [low-high] embedded in it. Both bounds are decimal, inclusive, and low MUST NOT exceed high. At most four spans per range.

Ordering. Several spans expand as an odometer: the rightmost span varies fastest. ge-[0-1]/0/[0-3] yields ge-0/0/0, ge-0/0/1, ge-0/0/2, ge-0/0/3, ge-1/0/0, … The expansion lands where the entry stood, so the interfaces around it keep their relative order.

Zero padding. The width of the low bound is the width of every value the span produces. [01-12] yields 01 … 12; [1-12] yields 1 … 12. A high bound needing more digits simply uses them: [01-100] ends at 100.

Per-index description. Inside description, {} and %d stand for the value of the last (fastest-varying) span, and {0}, {1}, … for a span by position, left to right. {{, }} and %% are the literal characters; a lone brace is an error rather than literal text, because it is almost always a typo. A % that does not begin %d or %% is left alone — a description is prose and may well say "50% utilised". No other field is substituted into.

  - range: ge-[0-1]/0/[0-3]
    type: ethernet
    description: Slot {0}, port {1}      # "Slot 0, port 3", …

Bounds. One document expands to at most 4096 interfaces in total. eth[1-99999999] is a typo, and the answer to a typo is a diagnostic (NV-R003), not an out-of-memory kill.

Collisions. An expanded name that another entry of the same element already claims — an explicit name, or the expansion of another range — is NV-R004, and the diagnostic quotes both source locations. Two explicitly named duplicates remain NV-I001.

6.2.6 wireless

A wifi interface without this block is a radio netviz knows nothing about: medium: wireless joins two of them and the diagram draws a dashed line, but nothing says which network is on the air, in which direction, or on which frequency. The block supplies exactly that.

6.2.6.1 role

A medium: wireless cable is an association, so it joins exactly one ap radio to one station or mesh radio (NV-W007). Two access points on one link describe interference rather than a link; two clients describe a link no frame can cross.

6.2.6.2 bss[]

On an ap radio each entry is one SSID the radio beacons; a dual-SSID access point has two. On a station or mesh radio there is at most one entry (NV-W006) — the association — and it names the SSID, and optionally the BSSID, the radio joined:

# On the access point
- name: wlan0
  type: wifi
  mac: '78:8a:20:aa:00:10'
  wireless:
    role: ap
    band: 5GHz
    channel: 36
    width_mhz: 80
    tx_power_dbm: 23
    bss:
      - {ssid: home, bssid: '78:8a:20:aa:00:11', vlan: 10, security: wpa3-psk}
      - {ssid: home-guest, bssid: '78:8a:20:aa:00:12', vlan: 20, security: wpa2-psk}

# On the client
- name: en0
  type: wifi
  wireless:
    role: station
    band: 5GHz
    channel: 36
    bss:
      - {ssid: home, bssid: '78:8a:20:aa:00:11'}

One association per radio. A cable terminates an interface once (NV-C005), and an association is a cable, so one radio serves one client in this model. An access point with thirty phones on it is not something an inventory is meant to enumerate: declare the associations that are part of the infrastructure — a mesh backhaul, a wireless bridge, a fixed client — and leave the transient ones out.

Channels are per band. Channel 1 exists at 2.4 GHz and at 6 GHz and means 5 MHz apart in one case and nearly 3.5 GHz apart in the other, which is why channel without band is refused rather than guessed. The legal numbers are 1–14 (2.4 GHz), the 802.11 UNII numbering 32–177 (5 GHz) and 1–233 in steps of four (6 GHz).

Frequency overlap is computed by centring width_mhz on the primary channel; the real centre of a bonded channel depends on which secondary channels the radio picked, which no document states. NV-W011 uses the approximation, which can only make it warn more readily, never less.

The projection onto ieee802-dot11 is §9.6.

6.3 bridge

Declares the 802.1Q bridge component that the device's switching ports belong to. Optional: a switch with a single implicit bridge does not need it.

6.4 vlans[]

The VLAN database. Declaring a VLAN here is optional but recommended: it gives the VLAN a name for rendering and lets the validator flag ports that reference an undeclared VLAN (NV-V004, a warning).

6.5 Per-kind constraints

A hub is a layer-1 repeater: it has no MAC table, no VLAN awareness and no IP stack, so those fields are errors rather than warnings. interfaces[].mac is accepted on a hub (some managed hubs have one) but ignored by the renderer.

6.6 template — reusable partial device specs

Fifty switches wired into the same access layer differ in three fields and agree in two hundred. A kind: template document declares the two hundred once:

apiVersion: netviz.dev/v1alpha1
kind: template
metadata:
  name: c9200l-48p
spec:
  vendor: Cisco
  model: C9200L-48P
  bridge: {name: br0, type: customer-vlan-bridge}
  vlans:
    - {id: 10, name: staff}
    - {id: 99, name: mgmt}
  interfaces:
    - range: GigabitEthernet1/0/[1-48]
      type: ethernet
      description: Access port {}
      enabled: false
      vlan: {mode: access, access_vlan: 10}
    - name: Vlan99
      type: vlan
      parent: br0
      vlan: {mode: access, access_vlan: 99}

A device then names it in spec.from:

apiVersion: netviz.dev/v1alpha1
kind: switch
metadata:
  name: sw-acc-07
spec:
  from: templates/c9200l-48p
  interfaces:
    - name: Vlan99
      ipv4: [10.1.99.17/24]

spec.from uses the ordinary reference grammar of §4.1 and resolves by the ordinary rules of §2.2 — the device's own namespace first, then each ancestor, then the whole inventory if the short name is unique — so a template may live anywhere, including a templates/ directory next to the sites that use it. Templates are indexed separately from elements: a template and a switch may share a name, because no field ever accepts both.

A template MAY itself declare from. The chain is resolved from the far end inwards, so the device always merges against one fully-resolved spec. A cycle is NV-M003.

from is only meaningful where spec is a device spec, so it is accepted on switch, router, hub, computer and server and rejected elsewhere (NV-M006).

6.6.1 Merge rules

The merge is between the device's spec and the template's spec, and nothing else: metadata is the device's own, so a template contributes no name, no description, no labels and no annotations. from itself is consumed and never appears in the merged spec.

Within spec, exactly four rules apply, in this order:

1. A key only the template declares is inherited. vendor, model, the VLAN database — whatever the device is silent about.
2. A key both declare, whose two values are both mappings, merges recursively by these same rules. This is what lets a device write bridge: {address: 00:1b:0d:01:a3:ff} and keep the template's bridge.name and bridge.type.
3. interfaces merges by interface name. The result is the template's interfaces, in the template's order, each merged (by rule 2) with the device's entry of the same name where there is one; followed by the device's remaining interfaces, in the device's order. Ranges on both sides are expanded before the match, so a device may override one port out of forty-eight by naming it.
4. Anything else the device declares wins wholesale. A scalar replaces a scalar. A list that is not interfaces — vlans, members, addresses, trunk_vlans — is replaced, not concatenated and not merged element by element. netviz has a key for interfaces and for nothing else, and a merge rule that only holds sometimes is worse than a rule that never does. A device that wants the template's VLAN database plus one more VLAN restates the list.

An interface entry that overrides a template's is a partial entry: it states name and the fields it changes, and may omit type and everything else. Only inside a spec that declares from is that legal; elsewhere type is mandatory as usual.

6.6.2 Templates are not elements

A template never appears in a graph, never appears in netviz list, and is never validated on its own. It has no interfaces to cable, no address to place in a subnet, and no node to draw. The only place it surfaces at all is as the source location of a field it contributed: a value the template got wrong is reported against the template's file and line, with a note naming the device that inherited it, rather than against the fiftieth device that used it.

That is also why a template's spec is checked only for shape — that it is a mapping of device-spec keys — and not field by field. A vlan block is legal on a switch and illegal on a hub, and a template does not know which it will be merged into. Deep checking happens on each merged device, where the value finally has a context that says what it must satisfy.

Use netviz show <name> --raw to see a device as written and netviz show <name> to see it merged. The pair is how a merge is inspected.

7. Cables

A cable is an undirected physical link between exactly two interfaces. It is a first-class element so that it can carry its own metadata (label, length, category) and be validated independently of the devices it joins.

apiVersion: netviz.dev/v1alpha1
kind: cable
metadata:
  name: cbl-rtr01-sw01
  labels: {site: hq}
spec:
  endpoints:
    - rtr-edge-01:ge-0/0/1
    - sw-access-01:GigabitEthernet0/1
  medium: copper
  speed: 1Gbps
  length_m: 2
  category: cat6
  connector: rj45
  label: A-014

7.1 Semantics

• A cable is undirected. [a:1, b:2] and [b:2, a:1] describe the same link and produce the same graph edge and the same canonical JSON export.
• An interface may terminate at most one cable (NV-C005). Multi-access media are modelled by an explicit hub element or, for radio, by a wireless cable per associated station.
• medium: wireless requires both endpoints to be type: wifi (NV-C006). It represents an association, not a physical cable; renderers draw it dashed.
• A cable between two interfaces of the same device is permitted (loopback cables and MLAG peer links on a single logical switch exist) but raises a warning (NV-C004).
• A cable is the physical link. Its logical counterpart — WireGuard, IPsec, OpenVPN, PPTP, L2TP, GRE, VXLAN, Geneve, and any of them nested inside another — is the tunnel kind, §14. Section numbers are append-only, which is why a kind added after §13 is documented there rather than next to this one.

8. Adapters

An adapter is a device that presents one or more network interfaces over a non-network host port: USB-to-Ethernet dongles, Thunderbolt docks, PCIe NICs seen as removable inventory. Modelling them explicitly keeps the physical truth ("the dongle is the thing that breaks") while still letting the renderer collapse them into the host.

apiVersion: netviz.dev/v1alpha1
kind: adapter
metadata:
  name: adp-usb-eth-01
spec:
  vendor: Anker
  model: A83130A1
  form_factor: usb-ethernet
  passthrough: true
  upstream:
    name: usb0
    type: usb
    speed: 5Gbps
    attached_to: laptop-01
  interfaces:
    - name: enx001122334455
      type: ethernet
      mac: 00:11:22:33:44:55
      mtu: 1500
      ipv4:
        addresses: [192.168.50.61/24]

8.1 upstream

upstream.type maps to ianaift:usb for usb/usb-c and to ianaift:other for the rest — the IANA registry has no Thunderbolt/PCIe identity. The upstream port is not an entry in spec.interfaces: it carries no L2/L3 configuration and must not accumulate addresses.

8.2 Graph semantics

• The attached_to reference creates a graph edge host → adapter with medium: copper and speed = upstream.speed. No cable document is needed or permitted for the host attachment; use a cable only for what leaves the adapter's downstream ports.
• An adapter with no attached_to is a free-standing node (spare in a drawer, or a media converter in a run). It raises NV-X002 (warning) if any of its downstream interfaces is cabled, since a cabled-but-unattached adapter is almost always an omission.
• passthrough: true tells the renderer it MAY collapse the adapter, drawing its downstream interfaces as if they belonged to the host and folding the adapter's name into the edge label. netviz render --no-collapse-adapters overrides this. passthrough: false (media converters, docks that switch) forces a distinct node.
• Collapsing never changes connectivity: the path host → adapter → cable → peer is preserved either way, so reachability analyses are unaffected by the rendering choice.
• Within the adapter, each downstream interface is stacked on the upstream port: if:lower-layer-if of enx001122334455 is usb0, and if:higher-layer-if of usb0 lists the downstream interfaces (§9.5).

9. YANG mapping

This section is normative for anyone exporting netviz data to NETCONF/RESTCONF or comparing an inventory against a live device. Paths are written with the module prefixes from the table at the top of this document. «dev» stands for the device the interface belongs to; netviz has no single YANG node for "a device", so metadata.name is the datastore boundary, not a data node.

9.1 Interface (RFC 8343)

RFC 8343 nodes netviz deliberately does not model: if:if-index, if:last-change, if:oper-status, if:statistics, if:link-up-down-trap-enable. They are operational counters or SNMP artefacts with no place in a source-of-truth document.

9.2 IP (RFC 8344)

ietf-ip augments /if:interfaces/if:interface; the prefix … below expands to that path.

interfaces[].mtu has no RFC 8343 counterpart. On export it is written to both ip:ipv4/mtu and ip:ipv6/mtu (subject to their range limits, so a layer-2 MTU below 1280 is not propagated to IPv6). The nearest standards-track home for a true layer-2 MTU is if-cmn:mtu in the ietf-interfaces-common draft, which is not yet an RFC; when it lands, interfaces[].mtu will map there directly.

Not modelled from RFC 8344: ip:neighbor lists (ARP/NDP caches are operational), ip:dup-addr-detect-transmits, ip:autoconf, ip:address/ip:origin and ip:address/ip:status (all config false).

9.3 VLAN (IEEE 802.1Q)

802.1Q has no "access port" or "trunk port" — those are vendor CLI abstractions over three independent knobs: the port VLAN ID, the acceptable-frame-types filter, and per-VLAN egress/untagged membership. netviz expands them like this.

Port configuration — augment /if:interfaces/if:interface/dot1q:bridge-port:

Derivation of acceptable_frames when not stated explicitly:

VLAN membership — entries in /dot1q:bridges/dot1q:bridge[name=«bridge.name»]/dot1q:component/dot1q:bridge-vlan/dot1q:vlan:

The VLAN database itself:

trunk_vlans is stored as dot1qtypes:vid-range-type (for example "10,20,100-110") and expanded to individual VLAN entries on export.

For a type: vlan sub-interface, vlan.access_vlan is the encapsulation VID. It maps to dot1q:pvid on the sub-port and identifies the l2vlan interface's VLAN; the parent trunk port MUST list that VID in its trunk_vlans or as its native_vlan (NV-V005). A bridge parent — where a switch's SVI hangs — carries the union of its members' VLAN sets instead, since the bridge itself declares no vlan block.

9.4 Cable

A cable has no YANG representation — 802.1Q and ietf-interfaces model devices, not the wire between them. Its fields project onto both endpoint interfaces:

If both endpoints and the cable declare a speed, they MUST agree (NV-C008).

9.5 Adapter

9.6 Wireless (IEEE 802.11)

ieee802-dot11 renders the dot11Xxx attributes of IEEE Std 802.11-2020 Annex C as YANG leaves. The wireless block augments the interface that is the radio — if:type = ianaift:ieee80211 — under /if:interfaces/if:interface/dot11:wireless-interface:

Associated stations, PHY capabilities, regulatory state and RSN cipher negotiation are not modelled; see docs/yang-mapping.md.

10. Validation rules

Every rule has a stable ID. The validator (netviz validate) reports them as NV-C005: interface sw-access-01:Gi0/2 is terminated by 2 cables (cbl-a, cbl-b). IDs are permanent: once assigned, an ID is never reused for a different rule.

Severity error fails the run (exit code 4, ValidationError); warning and info are reported but rendering proceeds. netviz validate --strict promotes every warning to an error. Individual rules can be re-graded or silenced per inventory (§10.11).

The semantic validator also prints a short id (E002, W103) alongside the NV-* id; the two vocabularies are interchangeable everywhere a rule can be named. §10.10 maps them.

10.1 Document and naming

10.2 Interfaces

10.3 Addresses

10.4 VLANs

10.5 Cables and topology

10.6 LAG resolution

When a cable endpoint is a member of a lag, VLAN and MTU checks (NV-C010, NV-C011) use the aggregate's configuration, not the member's. Members are expected to carry no vlan block of their own; one that does triggers NV-V008 (warning) unless it matches the master exactly.

10.7 Hubs

10.8 Adapters

10.9 Ranges and templates

Loader rules: they are checked while the document is being rewritten into the shape the models validate, so they are reported by every command that loads an inventory rather than by netviz validate alone, and they have no short-id alias. §6.2.5 and §6.6 state them in context.

10.10 Rule identifiers

The semantic validator (netviz.validate) reports the cross-document rules — and the per-element judgements that a single document cannot settle — under short ids. Each is an alias of the NV-* rule above it, and both spellings are accepted wherever a rule is named — in netviz.toml, in a netviz/ignore annotation, and on the command line. The letter is the severity the rule was first assigned: E error, W warning, I info.

Ids are permanent (§10), so a suppression written today keeps meaning the same thing. Where a short id covers two schema ids (E001), naming either alias selects the whole rule.

Three rules are graded more harshly here than in the tables above: E003 (NV-I008), E004 (NV-A004) and E010 (NV-I009). The first two because a duplicate address is far more often a copy-paste mistake than a deliberate VRRP or anycast design; the third because a multicast source address is not a design at all. Re-grade them per inventory (§10.11) where the exception is real.

10.11 Suppressing a rule

Two mechanisms, both additive; a rule is silenced if either applies.

Per inventory — netviz.toml at the inventory root:

[validate]
strict = false                    # promote surviving warnings to errors
ignore = ["W103", "NV-C010"]      # never report these at all

[validate.severity]
E004 = "warning"                  # re-grade rather than silence

An unknown rule id here is an error: a suppression that silently applies to nothing is worse than a failed run. Unknown keys inside [validate] are rejected for the same reason, while unknown top-level tables are ignored so a file shared with a later version still loads.

Per element — the netviz/ignore annotation (§3.1), whose value is a list of ids separated by commas, semicolons or spaces:

metadata:
  name: media-converter
  annotations:
    netviz/ignore: "W101 W103"

A finding names every element it involves, so annotating either end of a cable suppresses a finding about that cable. An unknown id in an annotation is ignored rather than fatal — inventory data must not be able to abort a run — and therefore simply fails to suppress anything.

10.12 Patch panels

Numbered after §10.11 rather than beside the other rule tables: section numbers are append-only (§12), so a group added in a later revision lands at the end.

10.13 Physical placement

10.14 Wireless

NV-W001 to NV-W006 are schema rules, reported while the document is parsed and not suppressible; the rest are semantic and carry the short ids of §10.10.

10.15 Routing

NV-F001 to NV-F007 and NV-F015 to NV-F021 are schema rules, reported while the document is parsed and not suppressible; NV-F008 to NV-F014 and NV-F022 to NV-F024 are semantic and carry the short ids of §10.10. The group is lettered F, for forwarding: NV-R was spent on interface ranges (§10.9) long before routing was modelled, and an id, once assigned, is never reused.

10.16 Power

The NV-E* group — PDU outlets, device power and PoE — is tabulated beside the model it constrains, in §17.8, because half of what each rule says is a sentence about watts that only makes sense next to the class table. The severities and the schema/semantic split are stated there.

10.17 Styling

NV-Z001, NV-Z002 and NV-Z004 are schema rules, reported while the document is parsed and not suppressible; NV-Z003 and NV-Z005 are semantic and carry the short ids above. §22.7 states them in context, with why each one is graded the way it is.

10.18 Network namespaces and veth pairs (§23)

NV-N020 to NV-N023 are schema rules, reported while the document is parsed; NV-N024 to NV-N027 need the whole inventory and are the semantic validator's. §23.4 states them in context.

11. Worked examples

Three complete, self-consistent inventories. Each one validates clean against §10 except where a warning is called out deliberately. The paths in the tree listings below name the example each section is written around; they are illustrative, and the inventories that actually ship are examples/home-lab/ (§11.1 and §11.2 combined into one small topology) and examples/campus/ (§11.3 scaled up to three sites). Both are loaded, validated and rendered by tests/test_examples.py, so they cannot drift away from this specification without failing the test suite.

11.1 Small office

Router on a stick: one physical trunk to an access switch, two user VLANs terminated on sub-interfaces, a management SVI on the switch, dual-stack addressing.

examples/small-office/
├── routers/rtr-edge-01.yaml
├── switches/sw-access-01.yaml
├── hosts/pc-alice.yaml
├── hosts/srv-nas-01.yaml
└── cables/hq-links.yaml

routers/rtr-edge-01.yaml

apiVersion: netviz.dev/v1alpha1
kind: router
metadata:
  name: rtr-edge-01
  description: |
    HQ edge router. Terminates the ISP hand-off and routes between the
    user (10) and IoT (20) VLANs.
  labels:
    site: hq
    role: edge
    env: prod
spec:
  vendor: Juniper
  model: SRX300
  location: HQ / G-01 / U1
  forwarding:
    ipv4: true
    ipv6: true
  interfaces:
    - name: lo0
      type: loopback
      description: Router ID and management target
      ipv4:
        addresses:
          - ip: 192.0.2.1
            prefix_length: 32
      ipv6:
        addresses:
          - ip: 2001:db8::1
            prefix_length: 128

    - name: ge-0/0/0
      type: ethernet
      description: ISP hand-off
      mac: 00:05:86:00:00:00
      mtu: 1500
      ipv4:
        addresses:
          - ip: 198.51.100.2
            prefix_length: 30

    - name: ge-0/0/1
      type: ethernet
      description: Trunk to sw-access-01
      mac: 00:05:86:00:00:01
      mtu: 1500
      vlan:
        mode: trunk
        trunk_vlans: [1, 10, 20, 99]
        native_vlan: 1

    - name: ge-0/0/1.10
      type: vlan
      parent: ge-0/0/1
      description: Users gateway
      vlan:
        mode: access
        access_vlan: 10
      ipv4:
        addresses: [10.10.10.1/24]
      ipv6:
        addresses: [2001:db8:10::1/64]

    - name: ge-0/0/1.20
      type: vlan
      parent: ge-0/0/1
      description: IoT gateway
      vlan:
        mode: access
        access_vlan: 20
      ipv4:
        addresses: [10.10.20.1/24]

ge-0/0/1 carries no addresses: it is a pure layer-2 trunk, and the layer-3 configuration lives on the two vlan sub-interfaces. Both sub-interface VIDs appear in the parent's trunk_vlans, satisfying NV-V005.

switches/sw-access-01.yaml

apiVersion: netviz.dev/v1alpha1
kind: switch
metadata:
  name: sw-access-01
  description: Access switch, HQ ground floor
  labels:
    site: hq
    rack: g-01
    role: access
spec:
  vendor: Cisco
  model: C9200-24P
  location: HQ / G-01 / U2
  bridge:
    name: br0
    type: customer-vlan-bridge
    address: 00:1b:0d:63:c2:00
  vlans:
    - id: 1
      name: default
    - id: 10
      name: users
    - id: 20
      name: iot
    - id: 99
      name: mgmt
  interfaces:
    - name: br0
      type: bridge
      description: Switching instance
      members:
        - GigabitEthernet0/1
        - GigabitEthernet0/2
        - GigabitEthernet0/3
        - GigabitEthernet0/4

    - name: Vlan99
      type: vlan
      parent: br0
      description: In-band management
      vlan:
        mode: access
        access_vlan: 99
      ipv4:
        addresses: [10.10.99.2/24]

    - name: GigabitEthernet0/1
      type: ethernet
      description: Uplink to rtr-edge-01
      mtu: 1500
      vlan:
        mode: trunk
        trunk_vlans: [1, 10, 20, 99]
        native_vlan: 1

    - name: GigabitEthernet0/2
      type: ethernet
      description: Desk 1 - alice
      mtu: 1500
      vlan:
        mode: access
        access_vlan: 10

    - name: GigabitEthernet0/3
      type: ethernet
      description: IoT patch, currently unused
      enabled: false
      vlan:
        mode: access
        access_vlan: 20

    - name: GigabitEthernet0/4
      type: ethernet
      description: NAS
      mtu: 1500
      vlan:
        mode: access
        access_vlan: 10

Vlan99 is a vlan sub-interface of the bridge interface rather than of a physical port — that is how a switch virtual interface is expressed here. Note that NV-V005 is satisfied because the bridge's member port Gi0/1 trunks VLAN 99; br0 itself carries no vlan block, and the validator resolves a bridge parent by taking the union of its members' VLAN sets.

hosts/pc-alice.yaml and hosts/srv-nas-01.yaml

apiVersion: netviz.dev/v1alpha1
kind: computer
metadata:
  name: pc-alice
  description: Alice's workstation
  labels: {site: hq, role: workstation, owner: alice}
spec:
  vendor: Dell
  model: OptiPlex 7010
  interfaces:
    - name: lo
      type: loopback
      ipv4:
        addresses: [127.0.0.1/8]
      ipv6:
        addresses: ["::1/128"]
    - name: eno1
      type: ethernet
      mac: 3c:97:0e:11:22:33
      mtu: 1500
      ipv4:
        addresses: [10.10.10.50/24]
      ipv6:
        addresses: [2001:db8:10::50/64]
    - name: wlp2s0
      type: wifi
      mac: 3c:97:0e:11:22:34
      enabled: false
      description: Disabled by policy while docked

apiVersion: netviz.dev/v1alpha1
kind: server
metadata:
  name: srv-nas-01
  description: Backup and file server
  labels: {site: hq, role: storage, env: prod}
spec:
  vendor: Synology
  model: DS923+
  location: HQ / G-01 / U4
  interfaces:
    - name: lo
      type: loopback
      ipv4:
        addresses: [127.0.0.1/8]
    - name: eth0
      type: ethernet
      mac: 00:11:32:aa:bb:cc
      mtu: 1500
      ipv4:
        addresses: [10.10.10.10/24]
      ipv6:
        addresses: [2001:db8:10::10/64]

cables/hq-links.yaml — one file, three documents:

apiVersion: netviz.dev/v1alpha1
kind: cable
metadata:
  name: cbl-rtr01-sw01
  labels: {site: hq}
spec:
  endpoints:
    - rtr-edge-01:ge-0/0/1
    - sw-access-01:GigabitEthernet0/1
  medium: copper
  speed: 1Gbps
  category: cat6
  connector: rj45
  length_m: 1.5
  label: A-014
---
apiVersion: netviz.dev/v1alpha1
kind: cable
metadata:
  name: cbl-sw01-alice
spec:
  endpoints:
    - sw-access-01:GigabitEthernet0/2
    - pc-alice:eno1
  medium: copper
  speed: 1Gbps
  category: cat6
  length_m: 12
  label: B-002
---
apiVersion: netviz.dev/v1alpha1
kind: cable
metadata:
  name: cbl-sw01-nas
spec:
  endpoints:
    - sw-access-01:GigabitEthernet0/4
    - srv-nas-01:eth0
  medium: copper
  speed: 1Gbps
  category: cat6a
  length_m: 2
  label: A-021

The hosts declare no vlan block while the switch ports they face are access ports. That is correct and does not trigger NV-C011: an untagged host on an access port is the expected pairing, and the host inherits the port's VLAN.

Two ports terminate no cable, and the difference between them is the whole of NV-C015 (info). Gi0/3 says enabled: false, which documents the spare patch and silences the rule at the same time. ge-0/0/0 is up and faces an ISP that is not an element of this inventory, so it is reported — annotate the router with netviz/ignore: "NV-C015" to say that the far end lives outside the tree on purpose.

11.2 Lab bench: adapter, hub and a wireless link

A laptop with no built-in Ethernet reaches a legacy lab segment through a USB-to-Ethernet dongle and a 100 Mbit hub, and reaches the lab access point over Wi-Fi. This example exercises adapter, hub, medium: wireless and duplex: half.

examples/lab-bench/
├── bench.yaml          # laptop, adapter, hub, legacy PC, access point
└── cables.yaml

bench.yaml

apiVersion: netviz.dev/v1alpha1
kind: computer
metadata:
  name: laptop-01
  description: Bench laptop; no built-in Ethernet
  labels: {site: lab, role: bench, owner: bob}
spec:
  vendor: Lenovo
  model: X1 Carbon Gen 11
  interfaces:
    - name: lo
      type: loopback
      ipv4:
        addresses: [127.0.0.1/8]
    - name: wlp0s20f3
      type: wifi
      mac: 8c:8c:aa:00:11:22
      mtu: 1500
      ipv4:
        addresses: [192.168.50.60/24]
      ipv6:
        addresses: [2001:db8:50::60/64]
---
apiVersion: netviz.dev/v1alpha1
kind: adapter
metadata:
  name: adp-usb-eth-01
  description: USB 3.0 gigabit dongle, lives in the bench drawer
  labels: {site: lab, asset: "A-4471"}
spec:
  vendor: Anker
  model: A83130A1
  serial: "AK2231007744"
  form_factor: usb-ethernet
  passthrough: true
  upstream:
    name: usb0
    type: usb
    speed: 5Gbps
    attached_to: laptop-01
  interfaces:
    - name: enx001122334455
      type: ethernet
      description: Dongle Ethernet port
      mac: 00:11:22:33:44:55
      mtu: 1500
      ipv4:
        addresses: [192.168.50.61/24]
---
apiVersion: netviz.dev/v1alpha1
kind: hub
metadata:
  name: hub-lab-01
  description: 4-port 100BASE-TX repeater; single collision domain
  labels: {site: lab}
spec:
  vendor: Netgear
  model: EN104TP
  location: Lab / bench 3
  interfaces:
    - name: p1
      type: ethernet
      description: Dongle
    - name: p2
      type: ethernet
      description: Legacy PC
    - name: p3
      type: ethernet
      description: Access point uplink
    - name: p4
      type: ethernet
      description: Spare
      enabled: false
---
apiVersion: netviz.dev/v1alpha1
kind: computer
metadata:
  name: pc-legacy-01
  description: DOS test machine for the serial rig
  labels: {site: lab, role: test}
spec:
  vendor: IBM
  model: PC 300GL
  interfaces:
    - name: eth0
      type: ethernet
      mac: 00:04:ac:de:ad:01
      mtu: 1500
      ipv4:
        addresses:
          - ip: 192.168.50.20
            netmask: 255.255.255.0
---
apiVersion: netviz.dev/v1alpha1
kind: switch
metadata:
  name: ap-lab-01
  description: Lab access point, bridging Wi-Fi onto the bench segment
  labels: {site: lab, role: wireless}
spec:
  vendor: Ubiquiti
  model: U6-Lite
  bridge:
    name: br0
    type: mac-bridge
  interfaces:
    - name: br0
      type: bridge
      members: [wlan0, eth0]
    - name: wlan0
      type: wifi
      description: SSID lab-bench
      mac: 78:45:58:00:0a:01
      mtu: 1500
    - name: eth0
      type: ethernet
      description: Uplink to hub-lab-01
      mac: 78:45:58:00:0a:02
      mtu: 1500

The hub declares no vlan, no addresses and no bridge/vlans block — those are errors on a hub (NV-H001–NV-H003). The access point is modelled as a switch with a mac-bridge (802.1D) component: it forwards frames but is not VLAN-aware, which is exactly what mac-bridge means. pc-legacy-01 uses the netmask form; the loader normalises 255.255.255.0 to prefix_length: 24.

cables.yaml

apiVersion: netviz.dev/v1alpha1
kind: cable
metadata: {name: cbl-dongle-hub}
spec:
  endpoints: [adp-usb-eth-01:enx001122334455, hub-lab-01:p1]
  medium: copper
  speed: 100Mbps
  category: cat5e
  length_m: 1
---
apiVersion: netviz.dev/v1alpha1
kind: cable
metadata: {name: cbl-legacy-hub}
spec:
  endpoints: [pc-legacy-01:eth0, hub-lab-01:p2]
  medium: copper
  speed: 10Mbps
  duplex: half
  category: cat5e
  length_m: 3
---
apiVersion: netviz.dev/v1alpha1
kind: cable
metadata: {name: cbl-ap-hub}
spec:
  endpoints: [ap-lab-01:eth0, hub-lab-01:p3]
  medium: copper
  speed: 100Mbps
  category: cat5e
  length_m: 2
---
apiVersion: netviz.dev/v1alpha1
kind: cable
metadata:
  name: assoc-laptop-ap
  description: 802.11ax association, 5 GHz
spec:
  endpoints: [laptop-01:wlp0s20f3, ap-lab-01:wlan0]
  medium: wireless
  speed: 866Mbps

Points worth noting:

• There is no cable between laptop-01 and adp-usb-eth-01. The host attachment comes from upstream.attached_to; adding a cable as well would be NV-X005.
• duplex: half on cbl-legacy-hub does not warn (NV-C013) because one endpoint is a hub.
• Everything on the hub is in 192.168.50.0/24, satisfying NV-H005.
• With passthrough: true the default rendering draws laptop-01 —(usb)— hub-lab-01 with the dongle folded into the edge label; netviz render --no-collapse-adapters draws adp-usb-eth-01 as its own node. Connectivity is identical either way.
• The graph is connected: the laptop reaches the bench segment twice, once over Wi-Fi via ap-lab-01 and once over USB via the hub, so NV-C014 stays quiet.

11.3 Data-centre rack: dual-homed server, LAG, routed fibre uplinks

One spine router, a pair of top-of-rack switches with a peer link, a dual-homed server bonding two 10G ports into a trunked LAG with per-VLAN sub-interfaces, a single-homed application server, and an out-of-band IPMI port. Exercises lag, vlan sub-interfaces, jumbo frames, /31 and /127 point-to-point links, fibre and DAC media.

examples/dc-rack/
├── fabric/rtr-spine-01.yaml
├── fabric/sw-tor-a.yaml
├── fabric/sw-tor-b.yaml
├── compute/srv-db-01.yaml
├── compute/srv-app-01.yaml
└── cables.yaml

fabric/rtr-spine-01.yaml

apiVersion: netviz.dev/v1alpha1
kind: router
metadata:
  name: rtr-spine-01
  description: Spine / rack gateway
  labels: {site: dc1, rack: r07, role: spine, env: prod}
spec:
  vendor: Arista
  model: DCS-7280SR
  location: DC1 / R07 / U40
  forwarding: {ipv4: true, ipv6: true}
  interfaces:
    - name: Loopback0
      type: loopback
      description: Router ID / BGP source
      ipv4:
        addresses: [198.51.100.1/32]
      ipv6:
        addresses: [2001:db8::1/128]

    - name: Ethernet1
      type: ethernet
      description: To sw-tor-a
      mac: 00:1c:73:00:07:01
      mtu: 9214
      ipv4:
        addresses: [10.255.0.0/31]
      ipv6:
        addresses: [2001:db8:ffff::/127]

    - name: Ethernet2
      type: ethernet
      description: To sw-tor-b
      mac: 00:1c:73:00:07:02
      mtu: 9214
      ipv4:
        addresses: [10.255.0.2/31]
      ipv6:
        addresses: [2001:db8:ffff::2/127]

fabric/sw-tor-a.yaml

apiVersion: netviz.dev/v1alpha1
kind: switch
metadata:
  name: sw-tor-a
  description: Top-of-rack A, R07
  labels: {site: dc1, rack: r07, role: tor, env: prod}
spec:
  vendor: Arista
  model: DCS-7050SX3
  location: DC1 / R07 / U41
  bridge:
    name: br0
    type: customer-vlan-bridge
    address: 00:1c:73:0a:00:00
  vlans:
    - id: 1
      name: default
    - id: 30
      name: app
    - id: 40
      name: db
    - id: 99
      name: ipmi
  interfaces:
    - name: Ethernet49
      type: ethernet
      description: Routed uplink to rtr-spine-01
      mac: 00:1c:73:0a:00:31
      mtu: 9214
      ipv4:
        addresses: [10.255.0.1/31]
      ipv6:
        addresses: ["2001:db8:ffff::1/127"]

    - name: Ethernet50
      type: ethernet
      description: Peer link to sw-tor-b
      mac: 00:1c:73:0a:00:32
      mtu: 9214
      vlan:
        mode: trunk
        trunk_vlans: all
        native_vlan: 1

    - name: Ethernet11
      type: ethernet
      description: srv-db-01 bond member A
      mtu: 9214
      vlan:
        mode: trunk
        trunk_vlans: [30, 40]

    - name: Ethernet12
      type: ethernet
      description: srv-app-01
      mtu: 9214
      vlan:
        mode: access
        access_vlan: 30

    - name: Management1
      type: ethernet
      description: srv-db-01 IPMI
      mtu: 1500
      vlan:
        mode: access
        access_vlan: 99

Ethernet49 is a routed port: it carries addresses and no vlan block, so it never becomes a dot1q:bridge-port. Ethernet11 is a trunk with no native_vlan, which derives dot1q:acceptable-frame = admit-only-VLAN-tagged-frames (§9.3) — the server tags every frame. trunk_vlans: all on the peer link expands to 1-4094.

fabric/sw-tor-b.yaml — the B-side twin. It differs from sw-tor-a only in its name, MAC/IP suffixes and the absence of the srv-app-01 and IPMI ports.

apiVersion: netviz.dev/v1alpha1
kind: switch
metadata:
  name: sw-tor-b
  description: Top-of-rack B, R07
  labels: {site: dc1, rack: r07, role: tor, env: prod}
spec:
  vendor: Arista
  model: DCS-7050SX3
  location: DC1 / R07 / U42
  bridge:
    name: br0
    type: customer-vlan-bridge
    address: 00:1c:73:0b:00:00
  vlans:
    - id: 1
      name: default
    - id: 30
      name: app
    - id: 40
      name: db
    - id: 99
      name: ipmi
  interfaces:
    - name: Ethernet49
      type: ethernet
      description: Routed uplink to rtr-spine-01
      mac: 00:1c:73:0b:00:31
      mtu: 9214
      ipv4:
        addresses: [10.255.0.3/31]
      ipv6:
        addresses: ["2001:db8:ffff::3/127"]

    - name: Ethernet50
      type: ethernet
      description: Peer link to sw-tor-a
      mac: 00:1c:73:0b:00:32
      mtu: 9214
      vlan:
        mode: trunk
        trunk_vlans: all
        native_vlan: 1

    - name: Ethernet11
      type: ethernet
      description: srv-db-01 bond member B
      mtu: 9214
      vlan:
        mode: trunk
        trunk_vlans: [30, 40]

compute/srv-db-01.yaml

apiVersion: netviz.dev/v1alpha1
kind: server
metadata:
  name: srv-db-01
  description: PostgreSQL primary, dual-homed to both ToRs
  labels: {site: dc1, rack: r07, role: database, env: prod}
spec:
  vendor: Dell
  model: PowerEdge R650
  serial: "JH4K2N3"
  location: DC1 / R07 / U12
  interfaces:
    - name: lo
      type: loopback
      ipv4:
        addresses: [127.0.0.1/8]
      ipv6:
        addresses: ["::1/128"]

    - name: eno1
      type: ethernet
      description: bond0 member, to sw-tor-a
      mac: b4:96:91:00:0d:01
      mtu: 9000

    - name: eno2
      type: ethernet
      description: bond0 member, to sw-tor-b
      mac: b4:96:91:00:0d:02
      mtu: 9000

    - name: bond0
      type: lag
      description: LACP 802.3ad across both ToRs
      members: [eno1, eno2]
      mac: b4:96:91:00:0d:01
      mtu: 9000
      vlan:
        mode: trunk
        trunk_vlans: [30, 40]

    - name: bond0.30
      type: vlan
      parent: bond0
      description: Application network
      mtu: 9000
      vlan:
        mode: access
        access_vlan: 30
      ipv4:
        addresses: [10.30.0.11/24]
      ipv6:
        addresses: [2001:db8:30::11/64]

    - name: bond0.40
      type: vlan
      parent: bond0
      description: Storage/replication network
      mtu: 9000
      vlan:
        mode: access
        access_vlan: 40
      ipv4:
        addresses: [10.40.0.11/24]

    - name: ipmi0
      type: ethernet
      description: Out-of-band BMC
      mac: b4:96:91:00:0d:03
      mtu: 1500
      ipv4:
        addresses: [10.99.0.11/24]

bond0 deliberately repeats eno1's MAC — that is what Linux bonding does. NV-I008 (duplicate MAC) exempts a member/aggregate pair, so this is silent. The bond members carry no addresses and no vlan block of their own; VLAN and MTU checks on their cables resolve through bond0 (§10.6).

compute/srv-app-01.yaml

apiVersion: netviz.dev/v1alpha1
kind: server
metadata:
  name: srv-app-01
  description: Stateless application node
  labels: {site: dc1, rack: r07, role: app, env: prod}
spec:
  vendor: Dell
  model: PowerEdge R450
  location: DC1 / R07 / U14
  interfaces:
    - name: lo
      type: loopback
      ipv4:
        addresses: [127.0.0.1/8]
    - name: eno1
      type: ethernet
      mac: b4:96:91:00:0e:01
      mtu: 9000
      ipv4:
        addresses: [10.30.0.12/24]
      ipv6:
        addresses: [2001:db8:30::12/64]

cables.yaml

apiVersion: netviz.dev/v1alpha1
kind: cable
metadata: {name: cbl-spine-tora, labels: {site: dc1, rack: r07}}
spec:
  endpoints: [rtr-spine-01:Ethernet1, sw-tor-a:Ethernet49]
  medium: fiber
  speed: 10Gbps
  category: om4
  connector: lc
  length_m: 5
  label: R07-F-001
---
apiVersion: netviz.dev/v1alpha1
kind: cable
metadata: {name: cbl-spine-torb, labels: {site: dc1, rack: r07}}
spec:
  endpoints: [rtr-spine-01:Ethernet2, sw-tor-b:Ethernet49]
  medium: fiber
  speed: 10Gbps
  category: om4
  connector: lc
  length_m: 5
  label: R07-F-002
---
apiVersion: netviz.dev/v1alpha1
kind: cable
metadata: {name: cbl-tora-torb-peer, description: MLAG peer link}
spec:
  endpoints: [sw-tor-a:Ethernet50, sw-tor-b:Ethernet50]
  medium: fiber
  speed: 10Gbps
  category: om4
  connector: lc
  length_m: 1
  label: R07-F-003
---
apiVersion: netviz.dev/v1alpha1
kind: cable
metadata: {name: cbl-tora-db01}
spec:
  endpoints: [sw-tor-a:Ethernet11, srv-db-01:eno1]
  medium: copper
  speed: 10Gbps
  category: dac
  connector: sfp+
  length_m: 2
---
apiVersion: netviz.dev/v1alpha1
kind: cable
metadata: {name: cbl-torb-db01}
spec:
  endpoints: [sw-tor-b:Ethernet11, srv-db-01:eno2]
  medium: copper
  speed: 10Gbps
  category: dac
  connector: sfp+
  length_m: 2
---
apiVersion: netviz.dev/v1alpha1
kind: cable
metadata: {name: cbl-tora-app01}
spec:
  endpoints: [sw-tor-a:Ethernet12, srv-app-01:eno1]
  medium: copper
  speed: 10Gbps
  category: dac
  connector: sfp+
  length_m: 2
---
apiVersion: netviz.dev/v1alpha1
kind: cable
metadata: {name: cbl-tora-db01-ipmi}
spec:
  endpoints: [sw-tor-a:Management1, srv-db-01:ipmi0]
  medium: copper
  speed: 1Gbps
  category: cat6
  connector: rj45
  length_m: 3

Known limitations this example makes visible:

• MTU. The switches use 9214 (Arista's layer-2 maximum) throughout while the servers use 9000. The spine↔ToR links agree at 9214, so NV-C010 stays quiet there; the three server-facing links do not agree, so NV-C010 warns on cbl-tora-db01, cbl-torb-db01 and cbl-tora-app01. The example keeps the mismatch on purpose: this is the common real-world state, and surfacing it is the point. Setting the ToR server ports to 9000 silences the warning.
• MLAG. bond0 spans two physically separate switches. The schema records the cabling faithfully but has no vocabulary for the MLAG relationship between sw-tor-a and sw-tor-b; the peer link's description and a role: tor label are the only hints. Modelling multi-chassis aggregation is deferred (§12).
• NV-C012 does not fire: the cables terminate on eno1/eno2, the physical members, not on bond0.

12. Compatibility policy

apiVersion is «group»/«version». The group is netviz.dev; the version follows the Kubernetes convention: v1alpha1 may change incompatibly between minor releases, v1beta1 only between majors, v1 never.

Within one apiVersion:

• Adding an optional field with a backward-compatible default is a non-breaking change and MAY happen in a patch release.
• Adding a value to an enum, or adding a new kind, is non-breaking for readers of older documents but makes newer documents unreadable by older netviz versions. It requires a minor release.
• Renaming or removing a field, changing a default, tightening a constraint, or changing a rule's severity from warning to error is breaking and requires a version bump.
• Validation-rule IDs (§10) are permanent. A retired rule's ID is tombstoned, never reused.

The loader accepts documents whose apiVersion it recognises and rejects everything else with NV-D002 rather than guessing. When a second version exists, documents of different versions may coexist in one inventory; the loader converts older documents to the current internal model on read.

This section is normative for the schema. The same policy for netviz's other public surfaces — the CLI, the JSON output documents, the exit codes, the rule ids, the published integrations — and the four things a breaking change to any of them has to carry, are in releasing.md. Each release records what changed in CHANGELOG.md.

12.1 Deferred to a later revision

Deliberately out of scope for v1alpha1, listed so that nobody designs around their absence:

• Spanning tree: STP/RSTP/MSTP roles and per-port cost.
• Multi-chassis aggregation: MLAG/vPC/stacking relationships between switch elements.
• Host-side expansion ports: a usb/thunderbolt interface type on devices, which would let upstream.attached_to name a specific receptacle (§8.1).
• Per-inventory configuration beyond validation and rendering: netviz.toml at the inventory root carries rule suppression and severity overrides (§10.11), a [render] table of renderer defaults and any number of named [profile.<name>] blocks — see docs/configuration.md. What remains deferred is configuration of the model: per-inventory defaults for a document's own fields, such as a default medium for every cable.
• Templating: reusable device profiles (kind: profile) to remove repetition across identically-configured switches.

13. Editor integration

Everything above describes what a document may contain. A JSON Schema says the same thing in a form an editor can act on, so a misspelt key is underlined as you type it rather than discovered by the next netviz validate.

$ netviz schema > netviz.schema.json          # every kind, in one schema
$ netviz schema --kind cable                    # just one kind
$ netviz schema -o schema/netviz.schema.json

The output is JSON Schema 2020-12, generated from the same pydantic models the loader uses. --all is the default and produces a union discriminated on kind, so one schema covers every file in a tree; -k/--kind narrows it to a single kind when a directory holds only one. A generated copy is committed at schema/netviz.schema.json and refreshed by python tools/gen_json_schema.py; the test suite fails when it drifts from the models.

13.1 What the schema checks

The schema is the fast, local half. It is not a substitute for netviz validate, and CI should keep running the latter.

range and from (§6.2.5, §6.6) are consumed by the loader, so the schema describes their shape — the bracket grammar, the reference grammar, that an interface declares one of name and range, that a spec omitting interfaces must inherit them — but cannot say whether a range collides, whether it fits inside the 4096-interface bound, or whether the template exists. Those need the tree.

13.2 Per-file modeline

netviz init writes both halves of this section into a new inventory — the schema next to the tree, and the modeline below on every document it generates — so a scaffolded tree is wired up before it is first opened. What follows is for a tree that already exists.

The yaml-language-server reads a comment on the first line. It needs no editor configuration at all, which makes it the right choice for a small tree or for a file you want to be self-describing:

# yaml-language-server: $schema=https://raw.githubusercontent.com/netviz/netviz/main/schema/netviz.schema.json
apiVersion: netviz.dev/v1alpha1
kind: switch
metadata:
  name: sw-office

A relative path works too, and keeps the tree usable offline:

# yaml-language-server: $schema=../../schema/netviz.schema.json

13.3 VS Code

Adding one entry to .vscode/settings.json covers a whole inventory without touching the files. The YAML extension provides the language server; the glob is matched against the workspace-relative path:

{
  "yaml.schemas": {
    "./schema/netviz.schema.json": [
      "inventory/**/*.yaml",
      "examples/**/*.yaml"
    ]
  },
  "yaml.customTags": [],
  "yaml.validate": true
}

Neovim (nvim-lspconfig with yamlls) and the JetBrains IDEs take the same yaml.schemas mapping; JetBrains also accepts the schema under Settings → Languages & Frameworks → Schemas and DTDs → JSON Schema Mappings.

When a directory holds one kind, generate that kind's schema and narrow the mapping to it — completion then offers only the fields that belong there, and a kind: switch document in cables/ is an error rather than a valid file in the wrong place:

$ netviz schema -k cable -o schema/netviz-cable.schema.json

{
  "yaml.schemas": {
    "./schema/netviz-cable.schema.json": ["inventory/**/cables/*.yaml"]
  }
}

13.4 Versioning

The schema is versioned with the documents it describes. Its $id carries the apiVersion it belongs to:

https://netviz.dev/schema/v1alpha1/element.json
https://netviz.dev/schema/v1alpha1/cable.json

A future v1beta1 gets its own $id alongside this one rather than replacing it, so a tree pinned to netviz.dev/v1alpha1 keeps validating against the schema that matches it. §12's compatibility rules apply to the schema exactly as they apply to the format: within one apiVersion the schema only ever grows optional fields.

13.5 A caveat about YAML

The schema constrains the data a YAML document parses to, so anything the parser decides before the schema sees it is out of reach. The one that bites in practice is an unquoted MAC address: a YAML 1.1 parser reads 12:34:56:12:34:56 as a sexagesimal integer, and by the time either the schema or the loader looks at it the original digits are gone. Quote MAC addresses (§5). netviz's own loader detects the case and says so; an editor will simply report that a number is not a string.

14. Tunnels

A tunnel is an undirected logical link between two or more interfaces. It is to a logical topology what a cable (§7) is to a physical one, and a first-class element for the same reason: it carries its own metadata, has its own identity, and is validated independently of the devices it joins.

Section numbers in this document are append-only, so the kind added after §13 is documented here rather than between §7 and §8. Everything else about it mirrors the cable: the same device:interface endpoint grammar (§4.2), the same undirected semantics, the same namespace rules.

apiVersion: netviz.dev/v1alpha1
kind: tunnel
metadata:
  name: ipsec-hq-branch
  labels: {site: hq}
spec:
  type: ipsec
  mode: tunnel
  endpoints:
    - rtr-hq:ipsec0
    - rtr-branch:ipsec0
  mtu: 1400
  cipher: aes-256-gcm
  auth: certificate
---
apiVersion: netviz.dev/v1alpha1
kind: tunnel
metadata:
  name: vx-100
spec:
  type: vxlan
  vni: 100
  endpoints:
    - rtr-hq:vxlan100
    - rtr-branch:vxlan100
  over: ipsec-hq-branch      # VXLAN over IPsec
  mtu: 1350

14.1 Tunnel types

type is not a free-text tag: it fixes five facts the renderer and the validator both use, so a diagram can say what a tunnel actually does rather than only what it is called.

• Carries decides whether the tunnel is a layer-2 link. A layer-2 tunnel extends a broadcast domain across the underlay, so it carries the VLANs its endpoints are configured for and netviz render --layer l2 annotates it exactly as it annotates a trunk. A layer-3 tunnel carries no VLAN.
• Encrypts is a property of the technology, not of the deployment. PPTP is listed as cleartext deliberately: MPPE is broken, so a PPTP tunnel protects nothing. A cleartext tunnel that is not nested inside an encrypting one is NV-T012.
• Overhead is the widely published worst case over IPv4 — the number an operator would set an overlay MTU from — not an exact packet layout, which varies with cipher, IP version and NAT traversal. NV-T011 measures an mtu against it.

port, mode and encrypted are materialised on load from this table (§1), so a loaded document states them explicitly even when the file did not.

14.2 What a tunnel does not hold

There is nowhere in this schema to put a private key, a pre-shared key, a password, a passphrase or a certificate, and the field names people reach for are rejected by name with an explanation rather than as unknown keys (NV-T010). An inventory is a file in version control that gets rendered into diagrams and pasted into tickets; it is the wrong place for key material, and a schema that accepted some would be inviting the mistake.

auth records the authentication method — which is what a reader of a diagram needs and what an auditor asks for — and cipher the negotiated suite.

14.3 Semantics

• A tunnel is undirected, exactly as a cable is. The endpoint order carries no meaning and the loader sorts it for canonical output.
• An endpoint names a type: tunnel interface (NV-T003) — the virtual interface the operating system presents (wg0, ipsec0, vxlan100), never the physical port the outer packets leave by. That interface holds the overlay configuration: the addresses inside the tunnel, which is what puts both ends in one prefix at layer 3. Its optional parent may name the underlay port, which is if:lower-layer-if (§14.4).
• Unlike a cable, an interface may terminate several tunnels: a router that is the hub of three VPNs presents three virtual interfaces, but a VTEP may legitimately carry several VXLANs. What is checked instead is that two of them do not claim the same vni on one element (NV-T014).
• Two or more endpoints. Three or more make the tunnel multipoint — a VXLAN mesh, a hub-and-spoke VPN — and it is then drawn as a node with one leg per endpoint rather than as a line, the same choice a subnet gets at layer 3.
• over nests one tunnel inside another. vxlan over ipsec is written by naming the IPsec tunnel in the VXLAN's over. The chain is walked outwards to give every tunnel a depth, a stack (("vxlan", "ipsec")) and the nearest underlay that encrypts; it must not loop (NV-T005), and each step should reach every endpoint of the tunnel above it (NV-T006). Nesting is what makes a cleartext overlay confidential, so it is what silences NV-T012.
• A tunnel is not a cable. It is not part of the physical topology, does not join two islands for NV-C014, and is not something a technician can unplug. Renderers draw it dashed and violet, or crimson when nothing in its stack encrypts.

14.4 YANG mapping

A tunnel has no YANG representation of its own — ietf-interfaces models devices, not the encapsulation between them, exactly as it does not model a cable (§9.4). It projects onto the interfaces at its ends:

14.5 The overlay view

netviz render --layer overlay draws the encapsulation graph: every tunnel becomes a node, joined to each element it terminates on and to the tunnel it runs inside. The tunnel has to become a node there because nesting is a relation between two links, and a link cannot end on a link — which is exactly why VXLAN over IPsec is undrawable at layer 1 and obvious here.

Below that layer a point-to-point tunnel stays an edge, so netviz render shows the VPNs over the physical topology without a box in the middle of each one. netviz list tunnels prints the same resolution as a table.

15. Patch panels

A patchpanel is a passive cross-connect: numbered positions on the front, the same numbers on the rear, and a fixed coupler joining each front position to one rear position. Nothing in it powers on, nothing in it makes a decision, and a frame that enters one side leaves the other unchanged.

It is a separate kind because a real run almost never goes device to device. It goes switch port → panel front → structured cabling → panel rear → server port, and an inventory with no panel has to lie about that run by cabling the two devices together directly — losing the two things a patch record exists for: which position the run occupies, and which position is still free.

apiVersion: netviz.dev/v1alpha1
kind: patchpanel
metadata:
  name: pp-mdf-a
  location: {site: hq, room: mdf, rack: r1, position: 42, rack_height: 42}
spec:
  vendor: Panduit
  model: CPPL24WBLY
  form_factor: keystone
  ports: 1-24

15.1 spec

A panel owns no interfaces key. Its ports are derived from ports: every position n becomes an interface named front/<n> and one named rear/<n>, of type: ethernet, with no address, no VLAN and no MAC — a hole with a number. Writing 48 near-identical entries by hand is exactly the typing the interface ranges of §6.2.5 exist to avoid, and here there is nothing to vary.

The zero padding of a span follows its low bound, as in §6.2.5: 01-12 yields 01 … 12 and 1-12 yields 1 … 12.

A cable terminates on a panel position exactly as on a device port (§4.2):

apiVersion: netviz.dev/v1alpha1
kind: cable
metadata: {name: cbl-sw-pp-07}
spec:
  endpoints:
    - sw-access-01:GigabitEthernet1/0/7
    - pp-mdf-a:front/7
  medium: copper
  length_m: 3

15.2 Electrical transparency

A panel is not a hop, so the same inventory has two honest readings and build_graph offers both.

netviz render --layer physical : The cabling record. The panel is a node and each cable segment is an edge of its own, which is what a technician standing in the room would find.

every other layer (l1, l2, l3, overlay, routing, power) : The panel is spliced out. The run switch → front/7 ⇄ rear/7 → server becomes the single edge switch → server it is indistinguishable from, between the two active ports.

Splicing walks the run rather than deleting the panel, because the properties of the run belong to all of its segments:

The result is that a spliced graph is the graph the same inventory produces when the two devices are cabled together directly. That equivalence is what makes the panel free to model: adding one to a correct inventory cannot change any layer but physical.

The spliced edge remembers what it crossed. netviz render -f json exports it as a patch object naming the segments and the positions, netviz path names the panels on the link line — as a pass-through, never as a waypoint, because a panel takes no decision — and an SVG tooltip lists the same record.

A run that does not arrive anywhere is not spliced. A coupler with nothing patched into its far side is NV-P002, a position with two cables is NV-P003, and a run that closes on itself is NV-P005; in each case the incomplete run is dropped from every spliced layer and stays visible at --layer physical.

15.3 What a panel is not

• Not a host. upstream.attached_to on an adapter and a tunnel endpoint both require an active element (NV-P004). A media converter that looks like it wants to be a panel is an adapter with passthrough: false (§8.2).
• Not a repeater. A hub is active: it regenerates a signal and joins a collision domain, so it is a node at every layer. A panel joins nothing; it continues one link.
• Not configurable. There is nowhere on a panel to put a VLAN, an address or an MTU, which is why its ports are derived rather than declared.

15.4 YANG mapping

A patch panel has no YANG counterpart: RFC 8343 models interfaces of a system, and a panel is not one. Its derived positions are described here as if:interface entries of type ianaift:ethernetCsmacd for internal consistency only; nothing exports them, and couplers is netviz's own.

16. Routing

Routing is state of a box, not a thing between boxes: a route is written on one device, and an adjacency is configured on one device towards a neighbour it names by address. So every block hangs off a device's spec, which is also the shape RFC 8349 (ietf-routing) gives it — a control-plane protocol and a routing table live inside a network instance, which is what a VRF is (RFC 8529).

None of them is required, and a device that declares none of them is exactly what every device in an inventory written before this section was one: routing is additive, and an inventory that says nothing about it is not wrong, only silent.

There is nowhere to put a secret. As with tunnels (§14.2), a BGP password or an OSPF authentication key has no field: a secret in an inventory is a secret in version control, and netviz has no use for one.

16.1 vrfs[] — routing instances

spec:
  vrfs:
    - name: mgmt
      rd: '65001:99'          # RFC 4364 §4.2; quote it, see below
      description: In-band management
  interfaces:
    - name: Vlan99
      type: vlan
      ipv4:
        addresses: [10.1.99.1/24]
      vrf: mgmt               # names an entry of spec.vrfs
      parent: br0

interfaces[].vrf binds one interface to one instance and must name an entry of the same device's vrfs (NV-F002). An interface that binds to none is in the global instance, which is where every address is until something says otherwise.

Binding is what partitions the address space. An address only collides with another address in the same instance, so 10.0.0.1/24 in blue and 10.0.0.1/24 in the global table are two addresses and not a duplicate (NV-A004); two interfaces of one device may hold overlapping prefixes when they are in different instances (NV-A006); and netviz list subnets, netviz ipam and --layer l3 each report one row, one prefix and one node per instance. That is the whole reason to model a VRF: it is a routing table of its own, so it is an address space of its own.

Two devices that use the same name are taken to mean the same VRF — that is what an operator means by "the blue VRF". The route distinguisher is recorded because MPLS needs it, not because netviz identifies the instance by it.

A VRF nothing is bound to holds no address and no connected route, so the isolation it was declared to create does not exist; that is NV-F014.

Quote the rd. 65001:59 is the base-60 integer 3900059 to a YAML 1.1 reader and 65001:99 is a string, so the class is quoted whole — exactly as MAC addresses are (§5). netviz fmt adds the quotes if you forget them.

An adapter has no vrfs of its own and its interfaces may not declare vrf (NV-F002): an adapter is a port of the host it hangs off, and the routing instance belongs to that host.

16.2 route_tables[] — additional routing tables

A routing table is a container routes are placed in. Every stack is born with three of them — main, local and default — and a device that routes every packet the same way needs no others. Declaring one is how a device gets a second answer to "where does this packet go", which is the mechanism policy-based routing is built on (§16.4).

spec:
  route_tables:
    - name: uplink-b
      id: 100
      description: Everything that leaves by the backup uplink
  routes:
    - prefix: 0.0.0.0/0
      via: 198.51.100.1
      table: uplink-b       # names an entry of spec.route_tables

The reserved three are never declared. main (254), local (255) and default (253) exist on every stack, are nameable from routes[].table and routing_policy[].table without appearing here, and cannot be declared: neither their names nor their numbers (NV-F015). A second main is not a second table, it is a document that has stopped describing the device.

A VRF is a table too. table: mgmt resolves against spec.vrfs as readily as against spec.route_tables (NV-F019) — a routing instance is a routing table, which is the whole of §16.1. What netviz does not have for it is a number: a route distinguisher identifies the VRF in BGP and says nothing about which table an implementation gave it, so every emitter that needs a number refuses rather than inventing one, and says so in its manifest.

A table is inert on its own. Nothing consults it until a policy rule looks it up, so a declared table nothing selects is NV-F023 and a rule selecting a table nothing is placed in is NV-F022. The two halves are only useful together, which is why they are declared next to each other.

16.3 routes[] — static routes

spec:
  routes:
    - prefix: 0.0.0.0/0
      via: 203.0.113.1
      dev: wan0
      metric: 10
    - prefix: 10.1.0.0/16
      blackhole: true
    - prefix: 0.0.0.0/0
      vrf: mgmt
      blackhole: true

A route needs somewhere to send the packet, so at least one of via, dev and blackhole is required, and blackhole excludes the other two (NV-F004). via is of the same family as prefix (NV-F003) — a next hop is resolved on the destination's own address family — and must be on-link: inside a prefix this device configures, on an interface in the route's own instance (NV-F008). An IPv6 link-local next hop is exempt, being on-link by definition. dev names an interface of this device (NV-F009).

prefix rejects a destination with host bits set. 10.0.0.1/24 as a destination is either a typo or a /32, and guessing which would put a route in the diagram that the device does not have.

table names an entry of spec.route_tables, a VRF, or one of the reserved three (NV-F019). A route that names neither table nor vrf is in main, which is where routing looks unless a policy rule sends it elsewhere. vrf and table are alternatives, not a pair: a VRF is a table of its own, so naming both is a contradiction rather than a refinement (NV-F018).

Nothing here computes a best path. metric is recorded, routes are not sorted, and two routes for one prefix are two declarations rather than a decision: netviz describes the configuration, and which route wins is the device's business.

16.4 routing_policy[] — policy-based routing

Ordinary routing asks one question: which route in the table matches this destination? Policy-based routing puts a question in front of it — which table should this packet be routed by at all? — and answers it from where the packet came from, what the firewall marked it with, which interface it arrived on, or what it asked for in its DSCP.

spec.routing_policy is that question, modelled the way every implementation implements it (RFC 1812 §5.2.4.3, and Linux's routing policy database): an ordered list of rules, walked from the lowest priority upwards, first match deciding.

spec:
  route_tables:
    - name: uplink-b
      id: 100
  routes:
    - prefix: 0.0.0.0/0          # what the guest VLAN gets
      via: 198.51.100.1
      table: uplink-b
    - prefix: 0.0.0.0/0          # what everything else gets
      via: 203.0.113.1
  routing_policy:
    - priority: 100
      src: 10.20.0.0/16          # guests leave by the backup uplink
      table: uplink-b
      description: Guest VLAN egress
    - priority: 110
      fwmark: '0x1'              # and so does anything the firewall marked
      table: uplink-b
    - priority: 200
      src: 192.0.2.0/24
      action: blackhole          # this prefix goes nowhere at all
    - priority: 32766
      table: main                # the terminator: everything else, as usual

The five actions.

A goto jumps forward: the database is walked from the lowest priority upwards, so a target that is not greater than the rule's own priority is a loop, and is refused (NV-F016).

Priority is the rule's identity. It is where the rule sits in the walk, and it is what makes a document say what the device does: two rules of one family at one priority leave the order they are consulted in unstated, which is NV-F020. The document may list them in any order — netviz sorts by priority everywhere it shows the database, because that is the only order in which the list means anything.

A rule with no selector matches everything, which is how the database is terminated (the 32766: lookup main above) and also the most common way to break one: everything after it in the same family is unreachable, whatever it says. That is NV-F024. invert needs something to invert, so a rule carrying it and no selector is refused outright (NV-F017).

A rule with no family is installed in both. src: 10.20.0.0/16 says IPv4 by itself; a rule selecting only on fwmark says nothing, so it goes in both databases — which is what an operator typing ip rule and ip -6 rule would do. State family to install it in one.

Layer 4 is deliberately not a selector. There is no sport, no dport and no protocol field: the portable way to route by port, by user or by application is to mark the packet where marking belongs and match fwmark here. See §16.7.

netviz export routes writes the database as ip rule commands beside the routes it selects; netviz export networkd writes it as [RoutingPolicyRule] sections. See docs/export.md.

16.5 routing — dynamic protocols

spec:
  routing:
    ospf:
      area: 0.0.0.0           # or the plain number 0
      router_id: 192.0.2.1
      interfaces: [lo0, xe-0/0/0]
    bgp:
      asn: 65001
      router_id: 192.0.2.1
      neighbors:
        - address: 192.0.2.2
          remote_asn: 65001
          description: iBGP to rtr-south-core-01

Both blocks are optional and neither implies the other.

ospf

bgp

A router id is unique across the inventory (NV-F012): it names the router itself, so OSPF drops an adjacency with a neighbour claiming the local id (RFC 2328 §10.5) and BGP refuses a session with a duplicate identifier (RFC 4271 §6.8). One device giving OSPF and BGP the same value is one identity, not a duplicate, and is the normal configuration.

One area per device, deliberately. An area border router is a real thing, but modelling it needs per-interface areas; see §16.7.

16.6 Peers are addresses, never names

A BGP neighbour is written as an address, because that is what the device is configured with. netviz resolves it against every address the inventory declares, and that resolution is what draws the session in the routing view and what lets the two ends be compared:

• the peer's own asn is checked against remote_asn (NV-F011) — a disagreement is a session that never establishes;
• an address that matches nothing is a warning, not an error (NV-F013): a correct eBGP session towards a transit provider points at an address on their router, which is not an element of this inventory and never will be. What the warning says is that netviz cannot check the far end, and that the diagram has nothing to draw the edge to.

There is deliberately no second reference grammar. A peer: rtr-south-core-01 field would be a name that could point somewhere the device does not, which is the one thing an inventory must not be able to say.

An OSPF adjacency is not declared at all. It is discovered, so netviz derives it the way the protocol does: two interfaces that run OSPF in the same area and are addressed in one subnet form one. Deriving it from the addressing rather than from the cables is what makes it right for two routers facing each other across a layer-2 switch, which no cable joins directly.

16.7 What routing does not hold

Deferred, and listed so nobody designs around the absence:

• Per-interface OSPF areas, and therefore area border routers, stub and NSSA area types, interface costs and network types.
• Route policy — which is a different thing from the policy-based routing of §16.4, and the two are worth telling apart. §16.4 decides which table a packet is routed by. Route policy decides which routes a protocol accepts, advertises and rewrites: prefix lists, route maps, communities, local preference. A policy language is a language, and inventing a half of one would make an inventory that says what a router does not do.
• Layer-4 selectors in a policy rule: no sport, no dport, no protocol. ip rule grew them late, no two implementations agree on them, and the portable way to route by port, by user or by application is to mark the packet where marking belongs and match fwmark (§16.4). The marking itself is the firewall's business rather than routing's, and it is §24.3 — which also checks the two halves against each other, since each is silent alone and wrong only together.
• Table numbers for a VRF: §16.1 records a route distinguisher, which identifies the instance in BGP and says nothing about which table an implementation gave it. A rule may look a VRF up by name; an emitter that needs the number refuses rather than inventing one.
• Protocols other than OSPF and BGP: IS-IS, RIP, EIGRP, and the redistribution between any two of them.
• Route reflectors and confederations: an iBGP mesh here is a set of sessions, with no hierarchy over it.
• BFD, timers, graceful restart and everything else that tunes a session rather than describing one.
• Learned state. spec.routes is what somebody configured; a routing table is what a router computed from it, and comparing the two is netviz drift's business, not the schema's.

16.8 The routing view

netviz render --layer routing draws the control plane:

• Nodes are the elements that take part in routing — anything declaring routing, routes, vrfs, route_tables or routing_policy — labelled with the AS number and router id their peers know them by, and carrying their instances, their tables, their static routes and their policy database. The label counts the policy rules; the tooltip and the JSON list them, in priority order, which is the order the device walks them.
• Edges are the adjacencies: a BGP session is drawn solid and labelled with the AS pair (65001 → 65002, or iBGP 65001 when both ends are in one AS), an OSPF adjacency dotted and labelled with the area.
• Clusters are the VRFs. A router with interfaces in exactly one instance is drawn inside that instance's box; one that straddles several belongs to no box, exactly as a cross-site prefix belongs to no namespace at layer 3, and names its instances on its label instead.

Nothing physical appears. Two routers are adjacent here because they exchange routes, which a cable neither guarantees nor is needed for.

netviz export routes writes the same static routes and the same policy database out as an iproute2 script, one shell function per device; see docs/export.md.

16.9 YANG mapping

The IPv6 routes use the v6ur: paths of the same module; only the IPv4 ones are written out above.

17. Power

An as-built physical document has two halves. §15 and metadata.location are the first — what is bolted where, and what is patched into what. This is the second: which outlet each power supply is plugged into, how many watts the box draws, and which ports hand power down the cable instead of taking it from an outlet.

It is worth modelling for the same reason cabling is: the mistakes are silent and expensive. A rack fed from one PDU looks perfect on a topology diagram and fails as a unit. A PoE budget oversubscribed by two cameras works until the third one is plugged in and then browns out a switch. A device with no declared power path is a device nobody will find during a maintenance window.

Three places say something about power, and one new kind holds the sockets:

None of it is required. An inventory that says nothing about power is not wrong, only silent — power is additive, exactly as routing is (§16).

No measured watts. As everywhere else in this schema there is nowhere to put a reading: a number a file claims about a live load is stale before the file is saved. draw_watts and capacity_watts are the nameplate figures a load schedule is built from, and comparing them with what a meter says is netviz drift's business, not the schema's.

17.1 Power distribution units

A pdu is the power half of what a patch panel is for data: a strip of numbered holes, bolted in a rack, that things plug into. Like a panel it is shaped by its numbering rather than by its configuration — a 24-outlet vertical strip is twenty-four identical facts — so outlets takes the same count-or-range shorthand ports does (§15.1), and for the same reason.

It is an element rather than a field on a device because two devices share one, and that sharing is the fact worth drawing. A power block on a server can say "PSU 1 is fed from outlet 7"; only a document for the PDU itself can answer "what else is on that strip, and is there capacity left". Both questions are what a load schedule is, and the second is the one that catches a rack fed from a single unit.

apiVersion: netviz.dev/v1alpha1
kind: pdu
metadata:
  name: pdu-r1-a
  description: Left-hand vertical strip, rack 1
  labels: {site: hq, role: power}
  location: {site: hq, room: mdf, rack: r1, rack_height: 42}
spec:
  vendor: APC
  model: AP8959EU3
  form_factor: 0U
  outlets: 24
  capacity_watts: 3680
  input_feed: A
---
apiVersion: netviz.dev/v1alpha1
kind: pdu
metadata:
  name: pdu-r1-b
  description: Right-hand vertical strip, rack 1
  labels: {site: hq, role: power}
  location: {site: hq, room: mdf, rack: r1, rack_height: 42}
spec:
  vendor: APC
  model: AP8959EU3
  form_factor: 0U
  outlets: 24
  capacity_watts: 3680
  input_feed: B

The outlets shorthand is the one §15.1 uses. A bare count 24 means outlets 1 to 24; spans are written 1-24, 7, or 1-12,17-24 for a strip with a gap in its numbering. The zero padding of a span follows its low bound, as in §6.2.5, so a strip printed 01…24 is transcribed 01-24 and yields 01 … 24, while 1-24 yields 1 … 24. The two are different labels and are compared as written: naming outlet 7 on a strip that calls it 07 puts a cord in a hole nobody can find, so NV-E011 reports it. At most 512 outlets, with no number declared twice (NV-E001) — the largest strip anybody ships has 54, and the ceiling is what bounds what a typo can ask for.

An outlet is not an interface, and nothing is cabled to a PDU. A patch-panel position is an interface, because a cable document terminates on it. An outlet is not: a power cord is not a cable, it carries no frames, and giving a PDU forty-eight derived interfaces would put it in the layer-1 topology as a node nothing connects to. So a pdu owns no interfaces key at all, is not a legal cable endpoint, and appears in no data layer. The reference goes the other way instead — a device's power.inputs names pdu:outlet (§17.2) — which is also the direction the fact is discovered in: you read the label on the cord, not on the strip.

Placement is metadata.location, unchanged (§3.2). A PDU is racked hardware like anything else, so it takes the same block, and a position is what puts it in a slot of netviz render --layer rack — where the elevation annotates it with how full the unit is (§17.5). The two strips above name a rack and no position, which is the honest model of a 0U vertical unit: it occupies no rack unit, so it is in the room without being in a slot, it collides with nothing (NV-U001), and it is not drawn on the elevation. A 1U horizontal strip declares a position like any other 1U box, and appears on it.

Feeds are what make A/B redundancy expressible. Two PDUs in one rack are only independent if they are fed from different places, and the inventory has no way to know whether they are unless somebody writes it down. input_feed is free text on purpose: what counts as "a different feed" is site knowledge — two utility feeds, two UPS strings, a UPS and a generator — and netviz's job is to notice that two feeds a device calls redundant carry the same name (NV-E015), not to decide what the names mean.

17.2 Device power

spec.power is a device's power in both directions, which is the whole shape of it. A switch takes power through inputs and gives it through poe_budget_watts and the poe blocks on its ports; an access point takes power over its uplink and gives none. One block covers all three because they are one question — where does the power in this box come from and go to — and splitting it would put two halves of one answer in two places.

apiVersion: netviz.dev/v1alpha1
kind: server
metadata:
  name: srv-app-01
  location: {site: hq, room: mdf, rack: r1, position: 10, height: 2, rack_height: 42}
spec:
  vendor: Dell
  model: PowerEdge R660
  interfaces:
    - name: eno1
      type: ethernet
      mtu: 1500
      ipv4:
        addresses: [10.1.10.11/24]
  power:
    draw_watts:
      typical: 240          # steady state, as configured — what a schedule sums
      maximum: 495          # nameplate; what the breaker has to survive
    redundant: true
    inputs:
      - pdu: pdu-r1-a
        outlet: '7'
        psu: psu1
      - pdu-r1-b:7          # the compact form of the same fact

draw_watts — the nameplate load of the box:

draw_watts: 45 is accepted as shorthand for draw_watts: {typical: 45}. The typical figure is the one every load schedule is built from and the only one most nameplates state, so requiring a mapping to say it would be ceremony. A boolean is refused with an explanation rather than coerced (NV-E003), and a wattage is strictly positive and at most 1 MW (§5): 0 W is not a load, it is the absence of one.

inputs[] — one power supply and the outlet feeding it:

An entry may be written as the compact string pdu:outlet — pdu-r1-a:7, sites/hq/mdf/pdu-r1-a:B12 — or as the equivalent mapping, which is the same grammar and the same choice a cable endpoint offers (§4.2), because it is the same kind of fact: a named thing on a named element. Anything that is not one identifier either side of one colon is NV-E002. The mapping form is what a psu label needs, and the label is worth writing: it is what an operator reads off the back of a chassis, and it is what makes a diagnostic about "the second input" name something real. outlet is alphanumeric rather than digits alone so that a two-bank unit printed A1…B12 can be transcribed as it is printed.

At most eight inputs. Four-PSU chassis exist; forty do not, and the bound keeps a copy-paste accident from becoming a load schedule nobody reads. Two of a device's own inputs naming one outlet is NV-E002; two different devices naming one outlet is NV-E010.

redundant: true is a claim, not a description: losing one feed does not lose the device. It needs at least two inputs to be sayable at all (NV-E002), and NV-E015 checks the claim is true of where they land — two cords into one strip are not redundant, and neither are two strips on one input_feed.

powered_by: poe is for the box with no power cord — a ceiling access point, a camera, a doorbell. Its power path is the cable that carries its traffic, so it declares no inputs (NV-E005), and the feed is derived by walking that cable rather than declared (§17.4). NV-E014 then checks the far end of the walk offers PoE at all, and offers enough of it.

17.3 Power over Ethernet

Declaring an interfaces[].poe block is what makes a port power sourcing equipment: a port that hands power down the twisted pairs of the run instead of only frames. It is permitted on ethernet and lag only (NV-E006) — PoE travels over copper, so a loopback, a vlan sub-interface, a bridge or a tunnel cannot source it, and wifi is refused for the same reason and one further one: a radio is precisely the port with no cable. lag is permitted because an aggregate of two PoE ports is how a multi-gigabit access point is fed.

spec.power.poe_budget_watts (§17.2) is the other half of the same fact: the pool the whole box can hand out across every PSE port together. The ports say what each one wants and the pool says what there is, so NV-E013 compares the two — and which ports count towards it is the question the rest of this section answers.

The class table

A class fixes two numbers, and they differ by the cable loss the standard budgets for over 100 m. Both are here because a switch budget is computed from the first and a device's draw is compared against the second (IEEE 802.3-2022, clauses 33 and 145):

standard therefore fixes which classes exist: 802.3af stops at class 3, 802.3at adds class 4, 802.3bt adds 5 to 8. A class outside its standard is NV-E004 — an 802.3af port cannot deliver class 4, so declaring one is a mistake about the hardware rather than a preference, and the diagnostic says which standard would make it true.

How much a port reserves

Say it with class or with budget_watts, never both (NV-E004): a class already fixes the reservation, and two answers cannot both be the budget.

• With class, the port reserves the PSE-side figure for that class, which is what the switch actually takes out of its pool.
• With budget_watts, the port reserves exactly that.
• With neither, the port reserves its standard's maximum — 15.4 W for 802.3af, 30 W for 802.3at, 90 W for 802.3bt. That is what a switch with no per-port configuration does, and assuming less would make an oversubscribed budget look fine, which is the one thing this rule exists to prevent.

A disabled port (enabled: false) reserves nothing, whichever of the three applies: a switch does not set power aside for a PSE it is told not to use. Recording the block anyway is worth it, because enabled: false is the difference between "no PoE here" and "PoE turned off here" — and the second is what NV-E014 names when a camera on that port will not come up.

Capability versus allocation

A poe block on an empty port is a capability and takes no budget. A 48-port PoE+ switch can source 30 W on every port and is sold with a 740 W supply; counting all 48 would report every real switch as oversubscribed, and a rule that fires on correct inventories is worse than no rule. Two things do count towards poe_budget_watts:

• a port the walk of §17.4 found something on — power that is actually being drawn;
• a port whose budget_watts was written down — because writing it down is the act of reserving it, whether or not anything is plugged in yet.

So class describes the port and budget_watts commits the pool, which is the other reason the two are not interchangeable.

A PoE access switch

apiVersion: netviz.dev/v1alpha1
kind: switch
metadata:
  name: sw-access-01
  location: {site: hq, room: mdf, rack: r1, position: 20, rack_height: 42}
spec:
  vendor: Cisco
  model: C9300-24P
  power:
    draw_watts: 90            # the switch itself, before it hands anything out
    poe_budget_watts: 445
    inputs: [pdu-r1-a:11]
  interfaces:
    - name: GigabitEthernet1/0/1
      type: ethernet
      poe: {standard: 802.3at, class: 4}      # reserves 30 W: the AP
    - name: GigabitEthernet1/0/2
      type: ethernet
      poe: {standard: 802.3af, class: 2}      # reserves 7 W: the camera
    - name: GigabitEthernet1/0/3
      type: ethernet
      poe: {standard: 802.3at}                # capable, nothing on it, 0 W held
    - name: GigabitEthernet1/0/24
      type: ethernet
      poe: {standard: 802.3at, enabled: false}
---
apiVersion: netviz.dev/v1alpha1
kind: switch
metadata:
  name: ap-floor-1
  description: Ceiling access point; no power cord
spec:
  vendor: Ubiquiti
  model: U6-Pro
  power:
    draw_watts: 22
    powered_by: poe           # excludes 'inputs' (NV-E005)
  interfaces:
    - name: eth0
      type: ethernet
      mtu: 1500
    - name: ra0
      type: wifi
      wireless:
        role: ap
        band: 5g
        channel: 36
        bss:
          - ssid: hq-corp
            security: wpa2-psk
---
apiVersion: netviz.dev/v1alpha1
kind: computer
metadata:
  name: cam-lobby-01
  description: Lobby dome camera
spec:
  vendor: Axis
  model: M3216-LVE
  power:
    draw_watts: 6.2
    powered_by: poe
  interfaces:
    - name: eth0
      type: ethernet
      mtu: 1500
      ipv4:
        addresses: [10.1.60.21/24]
---
apiVersion: netviz.dev/v1alpha1
kind: cable
metadata: {name: cbl-sw-ap-01}
spec:
  endpoints: [sw-access-01:GigabitEthernet1/0/1, ap-floor-1:eth0]
  medium: copper
  category: cat6
---
apiVersion: netviz.dev/v1alpha1
kind: cable
metadata: {name: cbl-sw-cam-01}
spec:
  endpoints: [sw-access-01:GigabitEthernet1/0/2, cam-lobby-01:eth0]
  medium: copper
  category: cat6

The switch allocates 37 W of its 445 W pool: 30 W on 1/0/1 and 7 W on 1/0/2. 1/0/3 is a capability and 1/0/24 is switched off, so neither holds any. The AP draws 22 W and the class-4 port delivers 25.5 W PD-side, so it fits; a class-2 port would not, and that is exactly the NV-E014 this example is shaped to show the right side of.

17.4 How power paths are resolved

Two ways to be fed, and only one of them is written down.

An outlet feed is declared by the load. A device's spec.power.inputs names pdu:outlet once per power supply. Nothing on the PDU mentions the device, which is the right direction twice over: it is the direction the fact is discovered in — you read the label on the cord — and a PDU carrying a list of its own downstream devices would be a second place for the same fact to be wrong.

A PoE feed is derived. A device that says powered_by: poe takes its power over the run that carries its traffic, so nothing declares the feed at all: netviz walks that run to the far end and looks for a poe block on the port it lands on. The walk crosses patch panels — a run that enters front/7 continues from rear/7, because a run through a panel is electrically one run, for power exactly as for frames (§15.2) — since a ceiling access point patched through an IDF panel is the normal case and not the exotic one. It gives up after sixteen hops, because a run that long is a loop (NV-P005) or a plant nobody could trace, and the bound is what keeps a cross-wired pair of panels from hanging the resolver.

A device with two runs to two switches is fed over whichever actually sources power, and over the more capable of the two when both do. Every run is recorded whether or not its far end sources anything, because "the uplink lands on a port with no PoE" is precisely what NV-E014 has to be able to say.

A reference that does not resolve is recorded rather than dropped: the validator grades it (NV-E011) and the renderer still has to draw the feeds that did resolve, because --force must produce a picture.

Load sharing. A dual-corded server draws its load through both cords, so each of a device's n feeds carries typical / n. That is the figure summed per PDU, and it is what capacity is graded against (NV-E012), because it is the load the strip carries in normal operation — the state the plant is in on every day that nothing has failed. The share is computed once per device, so two cords of one server always add up to exactly its draw whatever the arithmetic rounds to.

It is not the only figure worth having. When the other unit of an A/B pair fails, this one carries the whole load of everything dual-corded to it, each load counted once at its full draw. That is the failover figure, and both appear in the utilisation table (§17.6) and the load schedule (§17.7).

Only the normal-operation figure is graded. A pair of PDUs each sized for half the rack is a design, not an error: that is what redundancy costs, and every correctly built A/B rack would fail a rule that graded the failover number. So NV-E012 reports a strip with more plugged into it than it is rated for, the failover column is reported without a verdict, and the gap between the two is the redundancy plan, stated where somebody can read it.

A PoE feed's reservation is the PSE-side class figure of the port (§17.3), not the device's draw: that is what the switch sets aside. Its PD-side counterpart is what NV-E014 compares a declared draw against.

17.5 The power view

netviz render --layer power draws the distribution plant:

• Nodes are the PDUs and everything the inventory says draws or sources power. A PDU is not in the topology at all — it owns no interfaces (§17.1) — so its node is built for this layer, labelled with how many outlets are used, its load against its capacity, and its input_feed. Everything else is the node it already is at layer 1, with its ports, labels and description intact, and only gains what it says about power.
• Edges are the feeds, drawn distinctly because they are found differently: an outlet feed is a cord somebody can unplug, and a poe feed is the run of §17.4 seen electrically.
• Everything else is discarded. A cable is not a power path — two servers joined by a patch lead may be on opposite sides of the room electrically — and a PDU is joined to the boxes it feeds by cords no data diagram draws.

--layer rack (§3.2) annotates each occupied unit with the same plan: a PDU shows how full it is, everything else shows what it draws. That is the one question an elevation cannot otherwise answer, which is whether the rack can take another box.

17.6 netviz list power

One row per PDU — feed, outlets, used, free, capacity, load, failover, utilisation and the number of loads — shaped after the netviz ipam utilisation table and for the same reason: the question is capacity planning, so the columns are what is there, what is used, what is left, and the percentage that decides whether anybody has to act. LOAD is the normal-operation figure NV-E012 grades; FAILOVER is what the unit carries when its partner dies (§17.4). A single-fed rack has the two the same; an A/B pair does not.

17.7 The load schedule

netviz export power writes the electrical counterpart of the pull list: one row per feed, with both ends located — which outlet, on which strip, on which feed, powering which box in which rack unit, drawing how many watts. A dual-corded server is two rows, which is the point. A PoE-powered camera is a row too, marked as a PoE feed so a reader summing outlet loads does not double-count something that occupies no outlet. --schedule-format csv is the sheet somebody prints and initials; json is the same rows plus the per-PDU and per-PSE totals. See docs/export.md.

17.8 Rules

The group is lettered E, for electrical. NV-E001 to NV-E006 are schema rules, reported while the document is parsed and not suppressible; NV-E010 to NV-E016 are semantic and carry the short ids of §10.10. NV-E007 to NV-E009 are unassigned, and stay that way: numbering the schema half from 1 and the semantic half from 10 means a rule added to either does not disturb the other, and an id, once assigned, is never reused (§10).

NV-E016 is a warning deliberately. Recording draws before recording the outlets they are plugged into is the normal order in which an as-built document gets written, and refusing the half-finished state would make the model unusable exactly while it is being adopted. It is still worth saying: a load that appears on no PDU appears on no schedule either, so the rack looks emptier than it is.

NV-E015 accepts two PDUs that record no input_feed at all. Silence is not a claim, and a rule that treated a missing fact as evidence would punish the inventory for being incomplete rather than for being wrong.

18. Layout: diagram geometry

Everything above describes the network. This section describes the drawing of it, and it is the one part of the schema that carries no network fact at all.

A diagram netviz lays out from scratch on every render cannot be arranged: drag a switch to where it belongs and the next render puts it back, because nothing in the tree remembers that you moved it. A kind: layout document is what remembers. Once every node in a view has a position, the renderers reproduce the arrangement exactly — the same coordinates in the SVG, in the HTML and in the JSON export — and the layout engine is asked to place nothing.

apiVersion: netviz.dev/v1alpha1
kind: layout
metadata:
  name: default
spec:
  routing: orthogonal
  views:
    l1:
      nodes:
        core/sw-core:  {position: {x: 240, y: 396}}
        core/rtr-edge: {position: [240, 540]}
        subnet:10.0.0.0/24: {position: {x: 480, y: 396}}
      edges:
        core/cbl-uplink:
          waypoints: [{x: 240, y: 470}]
          routing: straight
          label: {at: 0.35, offset: {x: 0, y: 12}}
      groups:
        core: {position: {x: 240, y: 468}, size: {width: 220, height: 260}}

18.1 It is a sidecar, and not an element

A layout is a document kind, like template (§6.6), and not an element. It is never indexed among the elements, never drawn as a node, never listed by netviz list, never cabled and never counted. It names elements; it does not join them.

The alternative — spec.position on each device — was considered and rejected; docs/follow-ups.md §16 records the four reasons in full. The short version:

• the same device sits somewhere different in l1, l3 and routing, so one field on the device cannot hold the answer;
• a subnet node, a rack elevation and a collapsed namespace are drawn but not declared, so they have no spec to put a position in;
• a device document is a description of hardware, reviewed as one, and four numbers per view interleaved with that is noise in every diff forever;
• an arrangement is dropped, regenerated, .gitignored and reviewed as a unit, none of which is expressible once it is spread across a hundred files.

Several layout documents may coexist — one per site, one per audience. They are merged per view; where two place the same node, the first in load order wins and netviz layout reports the conflict.

18.2 Coordinates

Points (1/72 inch). x grows rightwards, y grows upwards, the origin is the bottom left of the drawing, and a position is the centre of what it places.

That is Graphviz's coordinate system, deliberately and exactly. The whole mechanism rests on being able to hand a stored arrangement straight back to the layout engine, and a system that needed converting would be a system that could be converted wrongly.

A point is written {x: 240, y: 396} or, as shorthand, [240, 396]. A size is {width: 220, height: 90} or [220, 90]. Both spellings mean the same thing, both are read, and netviz layout leaves whichever one it finds alone when the value has not changed.

18.3 Views

spec.views is keyed by the layer being drawn — physical, l1, l2, l3, ipam, overlay, routing, rack, power, identity, netns, security — because the same device sits somewhere different in each. The l3 diagram is a different graph with different neighbours, not the same diagram recoloured.

An unknown view name is NV-Y003.

18.4 Keys

A node key is an address, spelled the way references are spelled everywhere else (§2.2): a short name resolved against the layout document's own namespace, or a fully-qualified one.

A node the inventory does not declare is keyed by the id the graph gives it:

An edge key is a cable's or a tunnel's address, or the synthetic id of a derived edge. A group key is a namespace.

A key naming nothing the inventory declares is NV-Y001 — a warning, not an error. Deleting a switch must not make netviz validate fail, and geometry for a node that is not in the diagram places nothing. netviz layout --prune drops them.

18.5 What is stored

size on a node is optional, and is written by netviz layout --write only for a node a stored route leaves from. Graphviz derives the same box from the same label on every run, so a stored size otherwise buys the renderer nothing and goes stale the moment a device grows an interface — but a route netviz computes itself has to stop at the shape it runs into, and netviz cannot measure a label, so for those nodes the size is a fact the drawing needs. It is honoured on read wherever it appears, for an editor that lets somebody resize a box on purpose.

An edges entry is where a link's own geometry goes. None of its three fields is required, but an entry must carry at least one of them (NV-Y003): a key with nothing under it says nothing, and the way to say nothing is to leave the key out.

waypoints are interior points. The two ends of a route are always the nodes themselves, so moving either device carries the bends along instead of stranding them — which is what makes a hand-routed trunk worth placing. An entry with no waypoints is a link running directly between its two nodes. They are honoured but not seeded unless netviz layout --write --waypoints is asked for: a computed route is a handful of points per link that the render recomputes identically, while a hand-placed bend is a decision worth keeping.

routing is one of spline (the curve Graphviz draws), orthogonal (right angles, the way a patch schedule is drawn) or straight (segment to segment). It is spelled the way a person would say it rather than the way Graphviz spells it, because this is inventory somebody writes by hand. Three levels are answered most specific first — the link, then the view, then the inventory — and --routing on render supplies a default the first of them still beats.

label is {at: 0.5, offset: {x: 0, y: 0}}: at is how far along the route the annotation sits, from 0 at the source end to 1 at the target, and offset nudges it off the line in points. It is stored on the link rather than as a coordinate so that a label nudged clear of a crossing cable survives both endpoints being dragged somewhere else.

18.6 What a renderer does with it

Per view, and decided from the drawing rather than from the document:

In fixed mode netviz also draws the namespace cluster frames itself, from the stored group boxes, because the no-op layout engine does not draw clusters. A frame is therefore where you put it rather than wherever a layout happened to land; its caption sits centred above it rather than inside it, for the reason in docs/follow-ups.md §17.

A link's geometry follows the same split. In fixed mode netviz computes each route itself and hands Graphviz the finished line, which is the only way a per-link routing style can be expressed at all — Graphviz has a graph-wide splines attribute and nothing per edge — and it is also the only mode in which a pinned label position is honoured. Anywhere else the engine is routing, so the default style reaches the drawing as splines and the bends and label positions do not; the renderer says what it could not honour rather than emitting something broken. docs/rendering.md is that story in full, with a worked example.

The json renderer publishes the coordinates — a layout object per node, per edge and at the top level — so a client can draw the graph without running Graphviz at all. An edge's object carries both what the document pinned (waypoints, routing, label) and, in fixed mode, the line netviz drew (route, controls, drawnAs).

18.7 Rules

19. Identity: users and groups

Every other kind in this specification answers what is there. These two answer whose is it, and who may touch it — the question an audit asks first and the one an inventory of boxes and cables cannot answer at all. A wireless network with a per-user PSK, a jump host with a list of authorised keys, a VLAN that exists because one department needed it: all three are facts about people, written down today in a spreadsheet nobody diffs.

So an identity is an element like any other. It has a document, a namespace, a name unique within it (NV-N002), labels, a description and a source location; it is planned, applied, formatted, listed, exported and drawn by exactly the machinery every other kind goes through. Nothing here is a special case, which is the point: the moment identity needs its own loader or its own diff, the single source of truth has stopped being single.

Neither kind owns interfaces. A person is not a host, so a user and a group terminate no cable, appear in no data layer, and are excluded from every rule about ports — the same arrangement a pdu has (§17.1), and for the same reason.

19.1 user

apiVersion: netviz.dev/v1alpha1
kind: user
metadata:
  name: ana
  description: Runs the lab. Holds the only account on the router.
spec:
  full_name: Ana Brandt
  email: ana@example.invalid
  uid: 1000
  ssh_keys:
    - ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIExampleKeyForTheDocsOnlyAAAAAAAAAAA ana@pc-desk

type is not cosmetic: it decides which rules have anything to say. A service account belongs to no group on a great many estates, so reporting that as an oversight would be noise (NV-S016 is silent for one); a shared account has no single person to depart, so NV-S015 is silent for one too.

status: departed is the field the whole section turns on. The tempting response to somebody leaving is to delete their user document — which removes them from the inventory and from every group naming them, losing exactly the list somebody has to work through. The memberships are the access still to be revoked; they cannot be revoked from a record that no longer exists. Marking the account departed keeps the work visible until it has been done, and NV-S015 is the worklist.

19.2 group

apiVersion: netviz.dev/v1alpha1
kind: group
metadata:
  name: household
spec:
  gid: 101
  members:
    - admins            # a nested group
    - kit               # a user

Membership is written on the group and nowhere else. A user does not list its groups. Both spellings are readable and only one can be authoritative, and writing the fact twice is how an inventory starts disagreeing with itself — the failure this tool exists to prevent. The group side is the one chosen because it is the side an access rule is written against ("the vpn group may dial in") and because the count that matters — how many people can do this? — is then a property of one document rather than a search across all of them.

The reverse index is derived: netviz list users prints a GROUPS column, and it is the one fact about a person their own file cannot state.

Nesting is what makes a hierarchy expressible: everyone holds engineering, which holds ana, and ana is in everyone without being listed twice. netviz list groups prints both numbers — HOLDS is what the document names, PEOPLE is how many accounts the group reaches once the nesting has been walked — because the second is what an access rule actually grants to and no single document holds it.

19.3 The identity view

netviz render --layer identity draws the identities and nothing else.

Nodes are the user and group documents. A user is drawn as an oval, the shape every organisation chart uses for a person; a group as a folder, because something is inside it. Both are in a rose palette no element kind had taken, so an identity diagram cannot be misread as a fragment of a network one, and both have an icon in the bundled themes.

Edges are the memberships, one per entry of spec.members, drawn from the group to the member — the direction the fact is written in and the direction a reader follows to answer "who is in this?". A member that does not resolve is not drawn: NV-S010 is the place that says so, and --force must still produce a picture.

Everything else is discarded, exactly as the power view discards the cabling (§17.5). A cable between two servers says nothing about who may log into either, and drawing both graphs at once produces a picture in which neither is readable.

19.4 Rules

The group is lettered S, for subject — the term an access-control system uses for a principal it names. NV-U was spent on rack units (§10.13) and NV-I on interfaces, so neither initial was available. NV-S001 to NV-S003 are schema rules, reported while the document is parsed and not suppressible; NV-S010 onwards are semantic and carry the short ids of §10.10.

NV-S014 is a warning deliberately: a group created before the people who will be in it is a normal intermediate state, and so is one emptied on purpose to keep its name reserved. NV-S016 is only info, and only about a person: granting a person access directly and putting them in nothing is a normal way to run an estate. It is printed because the opposite reading — "she is in no group, therefore she has no access" — is a claim an auditor wants confirmed rather than assumed.

20. Test suites: executable assertions

An inventory records what the network is. A kind: testsuite document records what somebody is relying on — that the tills reach the payment gateway, that the guest VLAN reaches nothing else, that no two switches claim the same management address — and netviz test grades it, exiting non-zero when one of those claims has stopped being true.

The distinction from netviz validate is the whole point of the kind. Validation says whether the files are coherent: a cable endpoint resolves, an address is inside its subnet, a VLAN is declared before it is trunked. Every one of its rules is a statement about inventories in general, which is exactly why it cannot say that the ward switch must not be the only path to the ward. That is a fact about this network, known only to the people who built it, and until it is written down it survives only as long as the person who remembers it.

apiVersion: netviz.dev/v1alpha1
kind: testsuite
metadata:
  name: connectivity
spec:
  description: staff, servers and management reach what they are supposed to
  assertions:
    - assert: reachable
      name: a north desk reaches its own file server
      from: pc-north-01
      to: srv-north-01
      layer: l3

    - assert: not-reachable
      name: staff and servers are separated by a router, not by a switch
      from: pc-north-01
      to: srv-north-01
      layer: l2

    - assert: unique
      name: no two switches claim the same management address
      select: kind=switch
      field: spec.interfaces[name=Vlan99].ipv4.addresses[].ip

A test suite is not an element, for the same reasons layout (§18) and template (§6.6) are not: it declares no device, terminates no cable, is never drawn as a node and is never listed by netviz list. It is indexed in a name space of its own, so a suite called core next to a switch called core is not a clash — nothing ever resolves one where the other is meant.

Where the suites live in the tree is a matter of taste and nothing else. One tests.yaml at the root is what both bundled examples do; a suite per site, next to the site, is the other arrangement that reads well.

20.1 spec

assertions may not be empty. A suite that asserts nothing reports a green run having checked nothing, which is worse than having no suite at all — it is the false green that the exit code of this command exists to prevent.

20.2 An assertion

assert chooses the claim, and every other key is read in its light. A key that belongs to a different assertion is rejected by name (NV-K003) rather than ignored, so hops written on a same-vlan is a diagnostic naming both keys and not a silently unchecked bound.

Every assertion that takes select also takes query — the same question in the selector language of docs/query.md — and either satisfies the requirement. Written together they are ANDed, which is how "the switches, and of those the ones with no uplink" is said without one long expression.

Two keys are shared by all of them:

layer is any (the default), l2 or l3 on a reachability assertion, and any, l1, l2, l3 or power on no-single-point-of-failure. It is what makes "reachable, but only through a router" expressible: the pair of assertions in the example above says that two hosts do reach each other and that a switch is not how, which is the shape a segmentation requirement actually has.

20.3 Selectors

select is written in the vocabulary netviz render already filters with, spelled as one scalar because a YAML document has nowhere to put a repeated flag:

select: kind=switch, namespace=sites/north, name=sw-*

Terms are comma-separated. A term is key=value, or a bare word which is short for name=<word> — so select: sw-core and select: sw-* both work. The keys are the long forms of the flags: namespace, vlan, kind, name, neighbors-of and depth. A repeated key is an alternative exactly as a repeated flag is (kind=switch, kind=router selects both); different keys are combined with AND. It parses to the very same filter the renderer uses, so an assertion and a diagram cannot disagree about what kind=switch selects.

from and to take the three spellings netviz path takes — an element, element:interface, or an IP address — and, when they contain = or a globbing character, a selector. from: name=sw-*-acc-* with to: sw-dist-01 is "every access switch reaches the distribution switch", one line instead of twelve; the product of the two sides is capped, and an assertion above the cap is refused with a message saying to narrow one side.

An empty selection fails every assertion except count and query, where equals: 0 — and, for query, no bound at all — is a legitimate claim. A test graded against nothing is a test that reports green having checked nothing.

query is the other spelling, and the one that can say what the vocabulary above cannot. It is the whole selector language: attribute predicates over the resolved model, existential scopes over interfaces, links, namespaces and zones, and bounded graph traversal, combined with and / or / not and grouping. docs/query.md is its reference; netviz query --explain prints its grammar.

- assert: query
  name: no switch or router is missing a management address
  query: kind in (switch, router) and not interface[name ~ 'Vlan*' and has address]

- assert: query
  name: the campus has three core routers
  query: kind = router and label.role = core
  equals: 3

- assert: has-interface
  name: every access switch has an uplink port
  query: label.role = access and not neighbors of (label.role = distribution)
  interface: "TenGigabitEthernet*"

An assert: query with no equals, at_least or at_most claims that the query matches nothing, and reports the matches as the failure detail. That is the shape a network invariant actually has: "no device is missing a management address" is a search for the counterexamples, and the counterexamples are the report.

20.4 Field expressions

unique takes a path into the element as the loader resolved it — ranges expanded, template merged, shorthands normalised — so it sees what the graph sees rather than what the file happens to say:

field: spec.interfaces[name=Vlan99].ipv4.addresses[].ip

Dotted keys, each optionally followed by bracket steps:

The negated form is what makes "every address except the loopback" writable — spec.interfaces[type!=loopback].ipv4.addresses[].ip — and without it the most useful unique assertion of all, that no two hosts share an address, would be defeated by the 127.0.0.1 every host declares.

A path that runs off the end of a document yields nothing rather than failing: a device with no Vlan99 cannot collide with one that has one. The assertion still fails if no selected element produced a value, so a silent zero cannot be mistaken for a pass.

20.5 Rules

The group is lettered K, for check: NV-C was spent on cables and NV-T on tunnels, so neither obvious initial was available. NV-K001 to NV-K003 are reported while the document is read and are not suppressible. A false assertion is not a rule violation at all — it is a failing test, reported by netviz test against the assertion's own file and line.

21. Diagram annotations: notes, areas and legends

A diagram is not only its devices. A callout saying why a link is orange, a dashed box round the DMZ, a key explaining what the colours mean — every diagramming tool has them, and until this revision netviz had nowhere to write one down. Whatever somebody added to an exported drawing was lost the next time the picture was rendered, which is a hole in the one-to-one contract between the visual form and the textual one that this specification exists to keep.

Three kinds close it. A note is a callout, an area is a zone, a legend is a key:

apiVersion: netviz.dev/v1alpha1
kind: note
metadata:
  name: why-orange
spec:
  text: |
    **Orange** links are fibre. The run to the annexe is 180 m,
    which is past what copper does.
  anchor:
    link: cables/cbl-annexe
  color: "#fef3c7"
---
apiVersion: netviz.dev/v1alpha1
kind: area
metadata:
  name: dmz
spec:
  label: DMZ
  members: [edge/fw-1, edge/srv-proxy]
  color: "#fee2e2"
---
apiVersion: netviz.dev/v1alpha1
kind: legend
metadata:
  name: key
spec:
  title: Key
  corner: bottom-right
  auto: layers

An annotation is purely presentational, and that is a rule of this schema rather than a property of the current implementation. It is barred from:

• validation — the only two rules §21.4 defines about an annotation's content are warnings, and no annotation can produce an error that fails a build. Deleting a switch must not stop netviz validate because somebody once wrote a note about it;
• the graph — a view with three annotation documents has exactly the nodes and the edges of the same view without them, at every layer;
• netviz path — nothing an annotation says can move a hop, add one, or change which route is shortest;
• netviz plan and netviz apply — the infrastructure half of a changeset is byte-identical with the annotations in the tree and without them. They are addressed after it, never paired with an element by rename detection, and never proposed for removal by an import;
• generated device configuration — nothing the configuration dialects of netviz export write for a device — netplan, networkd, ifupdown, frr, wireguard — knows that a note about it exists.

That bar is what makes the three kinds safe to add at all. netviz's argument is that the diagram and the network description should be one artefact, and the price of that argument is that the description is also what generates configuration and answers "can these two hosts reach each other". A decorative layer inside such a file is only worth having if it provably cannot reach the conclusions — otherwise the first review question about any diagnostic becomes "is that real, or is it the annotations?". So each clause above is asserted separately, by tests/test_render_annotations.py and tests/test_plan_annotations.py, and the strongest of them is asserted as byte equality rather than as a spot check.

They are sidecars, not elements. Like layout (§18) and testsuite (§20), an annotation is a document kind and not an element: it declares no network fact, owns no interface, terminates no cable, is never drawn as a node, is never resolvable as a cable endpoint and is never listed by netviz list. It names elements; it does not join them.

Each of the three is indexed in a name space of its own. A note called core beside a switch called core is not a clash, and neither is an area called core beside both of them: nothing ever resolves one where the other is meant, because an anchor and a member reference resolve against the elements and a kind: note document is only ever reached as a note. Uniqueness is therefore per kind and per namespace (NV-G002), exactly as it is for a layout.

The alternative was metadata.annotations (§3.1), which already exists on every element and is already a bag of per-element input to the tooling. It was rejected for three reasons:

• a callout is often about a link, or about a region of the canvas that no element owns — "everything below this line is on the UPS" — and there is no element to hang either on;
• an annotation carries geometry, and geometry per element per view is exactly what §18.1 refused to put on a device document, for the four reasons recorded there;
• metadata.annotations is read by the tool and never drawn; §21 is drawn and never read. Two opposite contracts in one key is how a reviewer ends up guessing which is which.

Two keys are shared by all three kinds, and they are the two questions a renderer asks about one:

views is the closed set §18 scopes geometry by — physical, l1, l2, l3, ipam, overlay, routing, rack, power, identity, netns, security — and an unknown name is refused (NV-G003) rather than accepted and silently drawn nowhere. Empty is the default because a remark about a site is a remark about the site in every picture of it; views: [l3] is for the remark that only makes sense once the diagram is prefixes rather than cables.

color is a hex colour and nothing else: no red, no rgb(), no hsl(), no palette names of netviz's own. That is deliberately narrow. The same value has to reach a Graphviz attribute, a Mermaid classDef, an SVG fill and an mxGraph style, and #rrggbb is the one syntax all four agree about — an annotation whose colour rendered in one exporter and came out black in another would be worse than one with no colour at all. It is lower-cased on load, so two documents that mean the same colour compare equal and a change of case does not show up in netviz plan. The outline is derived from the fill rather than configured separately, so a custom colour brings its own matching stroke and there is no second field for somebody to leave inconsistent.

21.1 note — a callout

views and color are as above. Four thousand characters is the ceiling because a note is a callout and not a document: past a couple of thousand it is unreadable in a diagram and belongs in metadata.description, or in a file of its own that the note points at.

The markdown subset. Exactly five constructs are understood, and they are the five a callout uses:

Everything else is literal. A heading, a table, a link, a nested list, a block quote, a numbered list, an image, an unterminated * — each is drawn exactly as it was typed, character for character. That is said plainly here because a formatting language that silently swallows what it does not implement is worse than one that draws it: # Note coming out as an empty line is a bug report, and # Note coming out as # Note is a person removing a #.

The subset is small for the same reason color is narrow. The text has to be drawn by Graphviz's HTML-like labels, by a Mermaid node caption, by an mxGraph cell and by the editor, and these are the constructs all of them can express — Graphviz has <B> and <I> but no <CODE>, so a code span becomes the monospace face, which is the difference a reader is looking for. Soft line breaks inside a paragraph are joined with a space, the way markdown joins them, so a note wrapped at 72 characters in YAML does not draw as a column of stumps. The parser never fails: it runs while a diagram is being rendered, so a note it does not understand degrades to its own text rather than to a traceback.

anchor — what the note is about.

Exactly one of the two, and writing both — or neither — is NV-G005. They are separate keys rather than one target because a reader of the file should be able to tell what sort of thing is being commented on without resolving the name, and because the two are drawn differently: a note about a device sits beside a shape, a note about a cable sits beside a line.

References are spelled the way every reference in this schema is spelled (§4): a short name resolved against the annotation document's own namespace, or a fully-qualified one. An anchor naming nothing is NV-G001 — a warning — and the note keeps its text and loses its leader line.

geometry — where it sits.

The coordinates are §18.2's, deliberately and exactly: points, x rightwards, y upwards, origin at the bottom left, and x/y is the centre of the box rather than a corner. A note dragged around a canvas is stored by the same machinery that stores a dragged switch, so it had better be stored in the same system. Half a position — x without y — is NV-G005: it places nothing, and accepting it would draw the note at an origin nobody asked for.

The shape is flat (x, y, width, height) rather than §18's nested position/size, because these four numbers are what one drag and one resize produce and what an editor writes back. A note is one box; a node is a thing with an optional extent.

An anchor, a point, or both. At least one of anchor and a placed geometry is required (NV-G005); otherwise nothing knows where to draw the note. The two are not alternatives so much as two different promises:

• anchored — the note follows what it is about when the diagram is laid out again. This is the form worth writing by hand;
• placed — the note is pinned at a coordinate, and a re-layout moves everything else around it.

When a note carries both, the point places it and the anchor is what the leader line points at. That combination is exactly what dragging an anchored note produces, so it has to be expressible — reading it any other way would mean an editor could not write back what somebody had just done.

apiVersion: netviz.dev/v1alpha1
kind: note
metadata:
  name: ups-boundary
spec:
  text: |
    Everything in this room is on the *UPS*.

    - 40 minutes at the measured load
    - the door controller is `not` on it
  anchor:
    element: edge/sw-core
  geometry: {x: 640, y: 900, width: 220}
  views: [l1, power]

21.2 area — a zone

An area is a box drawn behind the nodes.

At least one of members, selector and a fully specified geometry is required (NV-G005): an area that encloses nothing is a caption with no subject. members and selector may be combined, and the box is then the hull of both — the explicit names first, in the order they were written, then whatever the selector adds in load order. That ordering is not cosmetic: a committed rendering should not shuffle because a device was added somewhere unrelated.

dashed is the default because a zone is a convention rather than a piece of hardware, and a solid box in a diagram of solid boxes reads as a real container — a chassis, a stack, something with a serial number. none keeps the fill and drops the edge, for a wash of colour behind part of the picture.

A member that names nothing is NV-G001 and is dropped from the hull; a selector that matches nothing is NV-G004 and the box is not drawn at all. Both are warnings — W142 and W143 — and both pages say when it is right to suppress them.

selector — a zone said as a query.

Clauses are conjunctive — an element must satisfy every one that is given — and a selector with no clause at all is refused (NV-G005), because it would silently box the whole inventory. A relative namespace is resolved against the namespace the area was declared in, exactly as every other reference is: an area in sites/hq selecting access means sites/hq/access.

An area over a namespace is the declarative form of --collapse. The flag folds a namespace into one node for the duration of one command; a kind: area over the same namespace draws the same set of elements boxed rather than folded, and it does it on every render, for everybody, because it lives in the tree instead of in somebody's shell history. The two are one selection seen from opposite ends — which is why a namespace clause matches the whole subtree rather than one level of it.

apiVersion: netviz.dev/v1alpha1
kind: area
metadata:
  name: north-site
spec:
  label: Site North
  selector:
    namespace: sites/north
  border: solid
  padding: 24
---
apiVersion: netviz.dev/v1alpha1
kind: area
metadata:
  name: on-the-ups
spec:
  label: On the UPS
  geometry: {x: 480, y: 260, width: 900, height: 420}
  color: "#f1f5f9"
  views: [l1]

The second form — an explicit rectangle — is the one case where an area is about the paper rather than about a set of devices. It encloses whatever the arrangement happens to put inside it, which is why it is never reported as empty: "nothing in it yet" is a legitimate state for a region of canvas, and is not a legitimate state for a selector that was meant to match something.

21.3 legend — a key

Exactly one of auto and entries (NV-G005): a key that was both generated and written out would have to merge two lists that disagree, and there is no right answer to which of them wins.

A corner rather than a coordinate, because a key belongs at the edge of the paper and should stay there when the drawing is laid out again — a coordinate would put it in the middle of the diagram the first time the topology grew. How exactly a corner is honoured depends on the backend and on whether the view is arranged; docs/rendering.md is that story, and the short of it is that a stored arrangement (§18) makes the corner exact while an automatic layout leaves the placement to Graphviz.

auto: layers builds the entries from what this view contains: one swatch per node kind present, then one per reason a link is drawn, with the colours read out of the same palette the renderer draws with. It is the only form of key that cannot go stale — a hand-written one is wrong the first time somebody adds a fibre run, and a generated one on a --vlan 10 diagram describes the ten devices that were drawn rather than the four hundred that were not. A legend is also the one annotation kind that never trips NV-G001: its content is colours and words, so it names nothing that can go missing.

entries[].