YANG Model: A Data Modeling Approach to Network Management

Key takeaways:

• A YANG model is a schema for a network device: it defines which configuration and state data exist, their types, their keys, and the rules a valid change has to follow.
• NETCONF, RESTCONF, and gNMI all carry YANG-modeled data; the protocol changes the transport and encoding, and the model stays the same.
• Validating a change against the model before it reaches a switch catches a dangling VLAN reference, a value out of range, or two settings that conflict, each with an exact path to the bad field.
• SONiC models its own CONFIG_DB tables in YANG (143 sonic-*.yang modules on the master branch in October 2026), and its patch tool refuses changes to any table that has no model, while everyday config commands skip it by default.

Your automation pushes a VLAN change to 40 leaf switches, every job reports success, and one server port now carries an access VLAN and a trunk VLAN list, which your fabric design forbids. The template that generated the change had no way to know that rule, because it produced text, and text has no rules.

A YANG model is where those rules live. It describes a device’s configuration and state as typed, keyed, constrained data, so a tool can reject a bad change before any switch sees it.

This guide walks through a YANG model example you can compile, the errors it catches, and how SONiC uses YANG for its own configuration database.

What Is a YANG Model and What Does It Describe?

YANG is a data modeling language standardized by the IETF. Version 1.0 was published as RFC 6020 in October 2010, and YANG 1.1 followed as RFC 7950 in August 2016; SONiC’s sonic-port and sonic-vlan models, for example, declare yang-version 1.1.

A YANG model describes four kinds of things on a device. Configuration data is what you write, such as a VLAN ID or an interface MTU, and state data is what you only read, such as counters, oper-status, and learned routes.

The same split now reaches optical gear, where coherent transceivers report line telemetry over gNMI through OpenConfig models, a direction traced in SONiC in optical infrastructure.

The other two are operations and events: remote procedure calls (RPCs) and actions you trigger, such as a reboot, and notifications the device emits, such as a link going down. A management tool can tell from the model alone which fields it may set and which it may only watch.

The model is a schema, so it never holds values itself. The values sit in a separate instance document (XML or JSON) that conforms to the schema. Take a simple network data model example: a YANG model for VLANs says a VLAN ID is an integer from 1 to 4094, and the instance says your fabric uses VLAN 100 and VLAN 200.

Where YANG Sits Between Protocols, Encodings, and Devices

YANG defines the shape of the data and stops there. Three protocols commonly move YANG-modeled data between a management system and a device, and each one picks its own transport and encoding.

Each protocol in the table reads and writes paths defined by the same YANG data models. That is why one model can serve a NETCONF config push today and a gNMI telemetry subscription tomorrow.

Laid side by side, the three protocols all lead back to the same model.

The history behind these protocols, from SNMP polling to streaming telemetry, is told in From SNMP to gNMI. For modeling, switching protocols leaves your YANG work intact.

The YANG Language Building Blocks

The YANG language is built from statements, and a few of them do most of the work in any module. The table maps each common statement to what it models and to a networking example.

The YANG leaf carries the actual values in every model, and everything above it in the tree exists to group, key, and constrain leaves.

Vendor gear adds one more: a deviation statement documents where a device’s implementation differs from a published model.

A YANG Model Example, Line by Line

The module below models VLANs and the ports that use them on a leaf switch. It compiles under pyang –strict against ietf-yang-types from the current IETF standard, and every validation result later in this guide comes from it.

The Module Header and Reusable Types

The header names the module, gives it a namespace and a short prefix, and imports the IETF common types for the 64-bit counters.

The typedef gives VLAN IDs one definition, so every place that stores a VLAN ID inherits the 802.1Q range. The grouping declares two counters as config false, which marks them as state the device reports and a client can never write.

Containers, Lists, and Leaves

The data tree holds a list of VLANs keyed by ID and a list of ports keyed by name. Each port points at VLANs instead of copying their IDs.

The leafref type catches a whole class of broken VLAN changes. It says an access VLAN has to be the ID of a VLAN that already exists in the vlans list, so a typo in a VLAN number fails validation instead of creating a port that forwards nothing.

Constraints That Catch Bad Configuration

The must statement on trunk-vlans encodes the design rule from the opening scenario. In this fabric a port carries an access VLAN or a trunk list, and the XPath expression not(../access-vlan) rejects any instance that sets both.

Production models often use when instead: OpenConfig’s openconfig-vlan sets an interface-mode leaf to ACCESS or TRUNK, and when statements expose access-vlan only in ACCESS mode and trunk-vlans and native-vlan only in TRUNK mode, so a trunk keeps its untagged native VLAN.

Ranges, lengths, and defaults work like the must rule: the MTU leaf accepts 1280 to 9216 bytes and falls back to 9100 when the instance leaves it out. Every one of these rules travels with the model, so any tool that loads it enforces the same limits.

Reading a YANG Tree Diagram

Reading a long module statement by statement is slow, so the YANG community uses a compact tree format, standardized in RFC 8340 (2018), that gives a one-screen view of the data model network engineers can review at a glance. Running pyang -f tree example-vlans.yang prints this for the module above:

The table decodes the symbols in this output.

Tree output is also a quick way to compare two revisions of a module, because a renamed leaf or a new key shows up as a one-line difference. It omits ranges, patterns, and must rules, so diff the source for those.

A YANG Data Model Example: Valid and Invalid Instances

YANG data modeling pays off when a model validates real data. The JSON instance below follows the encoding in RFC 7951 (2016), where each top-level node is prefixed with its module name.

Validated with yangson, this instance passes. Three small edits each fail, and the messages below are the validator’s actual output.

Pointing Ethernet0 at VLAN 300, which no vlan entry defines, breaks the leafref:

Setting both access-vlan and trunk-vlans on Ethernet4 trips the must rule and returns the model’s own message:

Defining VLAN 5000 falls outside the vlan-id type:

Each error names the exact path to the bad field, which is what you want in a pull request review or a pipeline log.

The same gate scales up to the whole network operating system, where a SONiC lifecycle white paper lays out CI/CD pipelines and iterative regression runs around every release.

YANG Model Tutorial: Build and Validate Your First Module

This YANG model tutorial rebuilds the YANG data model example above on a laptop, so it doubles as a short YANG language tutorial. You need Python 3 and a text editor. Both YANG networking tools it uses are open source: pyang compiles the module, and yangson validates the data.

The common types come first. The IETF refreshed ietf-yang-types and ietf-inet-types in RFC 9911 in December 2025. That revision obsoletes RFC 6991 and adds types such as date, time, ip-address-and-prefix, host-name, email-address, and protocol-number. Use the 2025-12-22 revision of both modules so your types match what new standard models will import.

1. Install the compiler and a validator with pip install pyang yangson.
2. Extract ietf-yang-types from the RFC 9911 text with xym or rfcstrip and save it as ietf-yang-types@2025-12-22.yang in a working folder.
3. Write your module in the same folder and name it module-name@revision.yang, so tools can match the revision.
4. Run pyang –strict -p . example-vlans.yang and fix every error before going further.
5. Print the tree with pyang -f tree -p . example-vlans.yang and check that each node’s rw or ro flag matches your intent.
6. Write a yang-library.json file that lists your module and the IETF module with their revisions, so yangson knows exactly which schema to load.
7. Load the library with yangson’s from_file, parse your JSON instance, and call validate() on it.
8. Break the instance on purpose (a missing leafref target, a value out of range) and confirm each break fails with a clear path.
9. Commit the model, the library file, and the test instances together, so the checks run again on every change.

Step 8 is the easiest to skip, and it is the only step that proves your constraints actually fire. A must expression with a typo can compile cleanly and never reject anything.

Wiring these checks into your infrastructure CI/CD pipeline is one step in an enterprise SONiC adoption plan, next to qualifying the release and the hardware, and model-level validation runs long before any testbed run.

Where YANG Models Come From: IETF, IEEE, OpenConfig, and Native

Four groups publish most of the YANG data models you will meet, and each one models the same interface or routing protocol from a different angle.

An OpenConfig path such as /interfaces/interface[name=Ethernet0]/config/mtu has the same structure on every device that implements the model, with only the key values changing, which is the whole case for a vendor-neutral networking data model. Native models trade that portability for coverage: they expose every knob the device has, including ones no standard has named yet.

Every open network operating system has to map the standard models it supports onto its own internal state, and every new feature needs both sides of that mapping, which makes it a standing part of open NOS engineering.

Before you automate against any device, ask it what it supports instead of reading a datasheet. NETCONF servers advertise modules in their hello message and through the YANG library (RFC 8525, 2019), and gNMI targets answer a Capabilities request with the models and encodings they serve.

How SONiC Uses YANG Models for Its Configuration Database

SONiC stores its configuration as tables in a Redis database called CONFIG_DB. A VLAN is a key such as VLAN|Vlan100 with fields like vlanid and mtu, and the switch’s daemons read their settings from those tables. The layout is described in SONiC’s containerized NOS architecture, where each function runs in its own container and shares state through Redis.

Redis itself stores strings and enforces no schema. The SONiC project closes that gap with native YANG models, one per feature: on the master branch in October 2026, sonic-buildimage carried 143 sonic-*.yang files, from sonic-port and sonic-vlan to sonic-bgp-neighbor, sonic-macsec, and sonic-srv6.

The models follow SONiC’s own guidelines: one module per feature, a top-level container named after the module, and one YANG container per CONFIG_DB table. Here is the VLAN ID from sonic-vlan.yang as the file reads today:

The must rule ties the key Vlan100 to the field vlanid: 100, so a table entry whose name and ID disagree fails validation. The range also starts at 2, stricter than the 802.1Q type in the example above. The same module uses leafrefs to bind each VLAN interface to an existing VRF and VNET.

What the Models Validate, and What They Skip

SONiC’s generic config updater, run as config apply-patch, applies an RFC 6902 JSON Patch to a copy of the running configuration, validates the result against the YANG models, and only then writes CONFIG_DB. Its patch sorter code, as changed in August 2026, refuses by default any patch that touches a table with no YANG model, and –dry-run shows the result without applying it.

Many everyday commands, such as config portchannel add and config interface ip add, run the same check only when yang_config_validation is set to enable in DEVICE_METADATA|localhost, and the model’s default is disable. Coverage is per command: on the master branch in October 2026, the config vlan group writes without it. Turn the flag on with config yang_config_validation enable, and treat apply-patch as the route that always validates.

Two limits are written into the code itself. A comment in the updater’s gu_common.py states that “YANG only validates state and not transitions,” so a rule about the order of changes lives in Python next to the model. A second list of validators for BGP peer groups and port lanes carries a note to move them into YANG later.

At the two extremes, apply-patch and a raw Redis write differ in one stop.

The practical reading: a change made through apply-patch, or through a validating config command with the flag on, is checked against the model, while a value written straight into Redis with redis-cli skips every rule above.

Two Models for One Feature: OpenConfig on Top of SONiC YANG

YANG management on SONiC runs through its management framework, which adds a REST server that follows RESTCONF (RFC 8040), a gNMI server, and a CLI, all built on a translation library called Translib. Clients can speak standard models such as OpenConfig, and Translib converts each request into CONFIG_DB tables.

The management framework design, last revised in March 2025, spells out the cost. A feature exposed through a standard model needs a separate SONiC YANG model for validating the Redis data, plus transformer annotations that map the standard paths onto SONiC tables. One feature therefore carries two models and a mapping between them.

Followed end to end, one OpenConfig request passes through both models before it lands.

That mapping decides what works. An OpenConfig path answers on a SONiC switch only if the image you run includes a transformer for it, so the same gNMI request can succeed on one build and return an error on another.

If you maintain your own build, those mappings become code your team owns and re-tests on every rebase, one of the trade-offs weighed in owning a vendor-neutral SONiC distribution.

Model Revisions Change What Your Automation Can Write

YANG models change with the software, and SONiC’s revision statements are a poor record of when. Of the 12 commits that changed sonic-vlan.yang between May 2023 and June 2026, four added a revision statement, and their dates trail the merges: static anycast gateway support carries revision 2025-04-22 and merged in June 2026.

The other eight changed the file with no new revision, including an interface-name length limit in November 2024 and ordered-by user on the DHCP server lists in November 2025. A new optional leaf rarely breaks automation. A new length limit, a narrowed range, or a new must rule can, because a patch that validated on the old image now fails on the new one, which is a sound result that still stops a rollout.

Before you move a fabric to a new release, run these checks:

• Diff the pyang -f tree output for every module your automation writes to.
• Diff the module files in /usr/local/yang-models between the two images, since revision statements miss most changes.
• Replay your stored test instances against the new models and confirm they still validate.
• Run config apply-patch –dry-run with a typical change on a lab switch running the new image.
• Re-check every OpenConfig path your tooling reads, since transformer coverage changes with the build.

Model drift is one of the reasons the choice of release carries weight, a point choosing the right SONiC version works through for different fabrics. Your test instances become a contract between your tooling and the switch, and the release you pick decides whether that contract holds.

Common YANG Modeling Mistakes in Network Automation

The YANG data modeling mistakes below share one root: treating the model as documentation instead of as an executable contract. The IETF’s updated guidelines for YANG authors, RFC 9907 from March 2026, address several of them directly.

Check your own models and tooling for each of these:

• Putting a platform limit into max-elements on the list itself, where RFC 9907 says to use a deviation for the platform’s hard limit.
• Copying the configuration tree into a separate -state tree, the pre-NMDA pattern RFC 9907 retires in favor of one tree under the datastore architecture from RFC 8342 (2018).
• Stacking several deviation statements on one target in one module, which RFC 9907 advises against because evaluation order changes the result.
• Validating examples by eye, where RFC 9907 names yangson and yanglint for checking JSON instances against their models.
• Writing a module with no revision statement, which leaves tools unable to tell two versions apart.
• Generating configuration from CLI templates while the device exposes the same data through a model.

Each item turns a review-time rule into a check a tool runs every time.

The upgrade side of the same contract is where a validated, frozen SONiC baseline pays off, because a fixed release means fixed models for as long as you stay on it.

Start with One Model and One Validation Gate

The fastest way to get value from YANG is to pick the one table your automation changes most often, such as VLANs or BGP neighbors in a data center fabric, and put a validation gate in front of it. A model, three test instances, and a dry run in CI catch the class of error that a template never can.

The cost difference is easy to put in front of a manager: a change rejected in CI costs a review comment, while the same change found in production costs a maintenance window and a rollback on every switch it reached.

If you run SONiC in your own data center, start with the sonic-*.yang files your release ships in /usr/local/yang-models, since they describe exactly what your switches accept. Which of your current configuration changes would fail validation today if you ran them through apply-patch –dry-run?