YANG mapping

netviz's field names and value spaces are not invented. They are taken from the standard data models a real device already speaks, so that an inventory stays comparable with what the hardware reports.

This document explains the relationship: which standards netviz borrows from, how each YAML key lands on a YANG node, where netviz deliberately departs from the models, and — the part that usually matters most — which parts of those models netviz does not cover, and why.

The per-field lookup table lives in docs/schema-reference.md; the normative path list is §9 of the specification. This document is the reasoning around both.

• The models netviz borrows from
• Intended state, not a datastore
• RFC 8343 — interfaces
• RFC 8344 — IP
• IEEE 802.1Q — bridging and VLANs
• IEEE 802.11 — radios, SSIDs and BSSs
• Deliberately not covered
• RFC 8349 — routing
• Power — RFC 3621 and RFC 7460
• Things with no YANG home
• If you want to export

The models netviz borrows from

The last five are MIB modules, not YANG, and that is the standards landscape rather than a preference; Power below explains why.

Borrowing has three concrete benefits, and they are the reason the schema looks the way it does rather than like a drawing tool's file format:

1. The value spaces are already decided. A VLAN id is 1–4094 because dot1qtypes:vlanid says so, not because someone picked a range. An IPv6 MTU starts at 1280 because ip:ipv6/mtu does.
2. An inventory can be diffed against a live device. Pull the running configuration over NETCONF or RESTCONF, and the field names line up. What the network should be and what it is become comparable without a translation layer nobody maintains.
3. The hard questions are already answered. 802.1Q spent decades getting VLAN semantics right; adopting its model is cheaper and more correct than re-deriving "what does a trunk port actually do" from vendor documentation.

Intended state, not a datastore

netviz is a documentation and visualisation tool. It records intended state: what the network is supposed to be, as reviewed and merged by humans. That single decision explains most of the divergences below.

It accepts config false nodes. RFC 8343 marks if:phys-address, if:speed and if:lower-layer-if as operational state — a device reports them, you do not set them. netviz lets you write them anyway, because a burned-in MAC address and a negotiated link rate are exactly the sort of fact an inventory exists to record. An exporter targeting a live datastore must not write them; they are documentation here, not configuration.

There is no "device" node. YANG models a single device's datastore, so there is no data node meaning "a device". In netviz, metadata.name is the datastore boundary: everything under one document's spec is what that one device would report. This is why a cable — which is inherently between two datastores — has no YANG representation at all.

Defaults are materialised. RFC 8344 defaults ip:*/forwarding to false; a netviz router defaults it to true. Once a document is loaded, the resolved value is present rather than implied, which is what netviz show prints. The YANG default is still the fallback when nothing else supplies one.

RFC 8343 — interfaces

spec.interfaces[] is /if:interfaces/if:interface, keyed by name.

… expands to /if:interfaces/if:interface.

Interface types

netviz offers six types, each mapping to one IANA identity. Only the three marked cableable can terminate a cable.

The IANA registry has hundreds of identities. Six is not a limitation of the mapping; it is the set that a topology document needs. Adding another is a one-line change if a real inventory turns out to need it — but a type that no diagram would draw differently earns nothing.

What netviz does not model from RFC 8343

The rule behind all five: if a device's answer would change without anyone editing the inventory, netviz does not store it. See Deliberately not covered for the general form.

RFC 8344 — IP

ietf-ip augments /if:interfaces/if:interface, so … below expands to that path.

RFC 8344 models the subnet as a choice with a prefix-length case and a netmask case. netviz accepts both spellings on input and stores the prefix length, so a document and its normalised form always compare equal. IPv6 has no netmask case in the RFC either, which is why prefix_length is mandatory there.

Addresses are zone-free by construction: inet:ipv4-address-no-zone is the type RFC 8344 uses, and a fe80::1%eth0 in an inventory would tie the document to one host's interface naming.

The MTU gap

interfaces[].mtu — the layer-2 MTU — has no RFC 8343 counterpart. The IETF interface model only has per-address-family MTUs; the layer-2 one lives in the ietf-interfaces-common draft as if-cmn:mtu, which is not an RFC.

netviz models it anyway, because a link MTU mismatch is one of the most common and most miserable misconfigurations there is (W102 exists precisely to catch it). On export it is written to ip:ipv4/mtu and ip:ipv6/mtu, subject to their own ranges — so an MTU below 1280 propagates to IPv4 only. When if-cmn:mtu becomes standards-track, interfaces[].mtu maps there directly and this paragraph goes away.

What netviz does not model from RFC 8344

There is also no routing model at all: ietf-routing (RFC 8349), static routes, routing protocol configuration and VRFs are out of scope.

IEEE 802.1Q — bridging and VLANs

This is where netviz deviates most visibly, and deliberately.

802.1Q has no "access port" and no "trunk port." Those are vendor CLI abstractions layered over three independent knobs:

• the port VLAN id (dot1q:pvid) applied to untagged ingress frames,
• the acceptable-frame-types filter (dot1q:acceptable-frame),
• per-VLAN egress and untagged membership lists.

Nobody documents a network in those terms, and a schema that demanded it would be unusable. So netviz keeps mode: access | trunk as the authoring vocabulary and expands it to the standard nodes mechanically.

Port configuration

Augmenting /if:interfaces/if:interface/dot1q:bridge-port:

When acceptable_frames is not stated, it is derived:

This is the whole of the abstraction. An access port admits untagged frames and tags them with its PVID; a trunk without a native VLAN admits only tagged frames; a trunk with one admits both. Stating acceptable_frames explicitly overrides the derivation for the rare port that does something else.

VLAN membership

Membership is not a property of the port in 802.1Q — it is a property of the VLAN, which lists the ports. Entries live in /dot1q:bridges/dot1q:bridge[name=«bridge.name»]/dot1q:component/dot1q:bridge-vlan/dot1q:vlan:

trunk_vlans is a dot1qtypes:vid-range-type — the "10,20,100-110" string form — and expands to individual VLAN entries on export.

The VLAN database and the bridge

A type: vlan sub-interface (an SVI) carries its encapsulation VID in vlan.access_vlan, which maps to dot1q:pvid on the sub-port and identifies the l2vlan interface's VLAN.

What netviz does not model from 802.1Q

802.1Q is enormous. netviz implements the VLAN bridging core and nothing else:

The consistent test: would the diagram be different? If the answer is no, the node is not modelled.

IEEE 802.11 — radios, SSIDs and BSSs

The 802.11 management model is a MIB first and a YANG module second: IEEE publishes it as ieee802-dot11, whose containers and leaves are the dot11Xxx attributes of Annex C rendered in YANG's hyphenated lower-case spelling. That is the spelling used below, and the paths augment the RFC 8343 interface the radio is:

/if:interfaces/if:interface[if:type='ianaift:ieee80211']/dot11:wireless-interface

An interface of type: wifi already maps to ianaift:ieee80211 (§9.1). The wireless block of §6.2.6 is what hangs beneath it.

The radio

The service sets

What netviz does not model from 802.11

The same test applies: would the diagram be different?

Deliberately not covered

The four tables above — RFC 8343, RFC 8344, 802.1Q and 802.11 — are not a to-do list. They are the scope boundary, and every entry falls into one of three buckets:

1. Operational state. Anything a device's answer would change without anyone editing the inventory: if:oper-status, counters, ARP and NDP caches, the filtering database, learned VLAN registrations. Monitoring systems own these; this file owns intent, and a file that claimed to know them would be wrong within seconds of being written.
2. Protocol behaviour. Spanning tree, LACP negotiation, MVRP, PTP. These decide what happens on the topology; the inventory says what the topology is. Drawing the active spanning tree needs live state, and pretending a file can supply it would produce a diagram that is confidently wrong.
3. Configuration that changes nothing you would draw. QoS and priority maps, DAD tuning, SNMP trap enables, storm control. If two inventories differing only in that node would render identically, the node is not modelled.

Two boundaries have moved. Routing is the first: netviz now borrows the intent half of ietf-routing — static routes, and enough of a control-plane protocol to say which AS and which OSPF area a router is in — plus the network instance of RFC 8529 for VRFs; see RFC 8349 — routing below. What stays out is everything on the far side of the same three buckets: a routing table is operational state (rt:routes is config false, and comparing it with the inventory is a job for a tool that can read a live device), protocol behaviour is protocol behaviour — timers, BFD, LSA flooding, best-path selection — and route policy is a language, of which half would be worse than none.

Power is the second, and it moved for the same reason: which outlet a cord is in and which port sources PoE are as much as-built physical facts as a cable is, and a diagram that omits them cannot answer the question a rack fed from one strip poses. What stays out is on the far side of the first bucket — a measured watt reading, a PSE's detection status, an accumulated kilowatt-hour. See Power.

A tool that stored everything would be a configuration-management system with an inventory attached, and it would rot for exactly the reason the diagrams it replaced did: nobody would keep the parts nobody reads correct.

RFC 8349 — routing

Routing intent hangs off a device's spec, because that is where RFC 8349 puts it: a rt:control-plane-protocol and a rt:static-routes container live inside a routing instance, and a routing instance is what RFC 8529 calls a network instance and everybody else calls a VRF.

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

What netviz does not model from RFC 8349

Power — RFC 3621 and RFC 7460

Power is the one area of this document where the standard model is a MIB rather than a YANG module, and that is not an omission on netviz's part. The IETF never migrated the power work to YANG: PoE lives in RFC 3621, the POWER-ETHERNET-MIB, and a device's own power lives in the Energy Management pair, RFC 7460 ("Power and Energy Monitoring MIB") and RFC 7461 ("Energy Object Context MIB"), whose framework and vocabulary — Energy Object, power inlet, power outlet — come from RFC 7326. IEEE publishes no YANG module for PoE at all: the class tables are normative text in IEEE Std 802.3-2022, clauses 33 (802.3af/at) and 145 (802.3bt), so the MIB is the only machine-readable reference there is and it is the one netviz borrows from.

The division of labour between the three is exactly the division §17 uses, which is why the schema is shaped that way:

• RFC 3621 is per port and per box: a PSE port, its class, its limit, and the pool the whole switch hands out. That is interfaces[].poe and spec.power.poe_budget_watts (§17.3).
• RFC 7460 is per box: what it draws and what it is rated for. That is draw_watts and a PDU's capacity_watts (§17.1, §17.2).
• RFC 7461 is the relation: which Energy Object powers which. That is power.inputs and a PDU's input_feed (§17.4) — the only half of power that is a fact between two elements, and the reason it needed a standard of its own rather than a leaf on either end.
• RFC 6933, the ENTITY-MIB, is where an outlet is a thing at all: a physical component of a chassis, which is what entPhysicalTable enumerates.

Power over Ethernet

pethPsePortTable/pethPsePortEntry is one row per PSE port, indexed by a group number and a port number rather than by the interface name RFC 8343 keys on. netviz hangs the block off the interface instead, because an inventory names a port the way a configuration does:

pethPsePortPowerClassifications is an enumeration in the MIB (class0…class4, extended by later work) while netviz writes the integer 0–8, because 802.3bt classes 5 to 8 postdate RFC 3621 and an inventory should not have to spell a class the MIB has no name for.

A device's power, and a PDU's

eoPowerTable/eoPowerEntry is one row per Energy Object, and a netviz element — a server, a switch, a PDU — is one Energy Object:

eoPower is read-only in the MIB, because it is a measurement. netviz writes an intended figure there anyway, for the same reason it accepts if:phys-address and if:speed (above): a nameplate draw is exactly the sort of fact an inventory exists to record, and it is the only figure a load schedule can be built from before the rack is powered on. An exporter aiming at a live datastore must not write it back.

What netviz does not model from the power MIBs

The same test as everywhere else: would the diagram be different? A PSE's detection status changes twice a day and never changes the drawing. Which outlet the cord is in changes once, when somebody moves it, and changes the drawing entirely.

Things with no YANG home

Three netviz concepts have no standard counterpart, because the standards model devices and these are not device configuration.

Cables

A cable is between two datastores, so neither ietf-interfaces nor 802.1Q has anywhere to put it. netviz makes it a first-class element anyway — it is the single most important fact in a topology document — and projects its fields onto the endpoints:

medium distinguishing copper from fibre while both export as ethernetCsmacd is not an oversight: the IANA identity describes the MAC layer, and a 10GBASE-SR link is ethernetCsmacd too. The medium is drawn differently because a fibre run and a patch cable are different objects to the person holding the diagram, not because the device sees them differently.

Adapters

USB dongles, docks and media converters are hardware that presents interfaces without being a device anyone configures.

IANA registers no identity for Thunderbolt, PCIe, M.2 or SFP as a host bus, which is why everything outside USB collapses to ianaift:other. The distinction is preserved in the YAML because it is worth drawing.

Namespaces, labels and annotations

The directory a document lives in becomes its namespace; metadata.labels and metadata.annotations follow Kubernetes conventions. None of this is YANG — it is inventory organisation, which YANG has no opinion about because a datastore is not a folder tree.

If you want to export

netviz does not ship a NETCONF or RESTCONF exporter. If you write one, three rules keep it honest:

1. Never write a config false node to a live datastore: if:phys-address, if:speed, if:lower-layer-if and if:higher-layer-if are all read-only there. netviz stores them as documentation of intent.
2. Expand, do not copy. vlan.mode and trunk_vlans are netviz vocabulary. The datastore wants dot1q:pvid, dot1q:acceptable-frame and per-VLAN port lists, produced by the tables above.
3. Materialise defaults first. Load the document through netviz.loader; the models resolve forwarding, the address-family MTUs, bridge.name and acceptable_frames. netviz show NAME prints exactly what an exporter would see.

netviz -i inventory show sw-access-01 -F json | your-exporter

The JSON graph export (netviz render -f json) is the other direction: the resolved topology, nodes and edges, for tools that care about connectivity rather than device configuration.