netlab icon indicating copy to clipboard operation
netlab copied to clipboard

Draft: Add YANG modeling and validation feature for topology files

Open jbemmel opened this issue 1 month ago • 8 comments

Note: This PR is a “sneak preview” of a potential feature and is not intended to be merged as-is.

This PR introduces a Netlab YANG topology validation feature, which validates a topology file against an internal YANG schema.

The schema defines the structure of a valid topology and includes declarative must statements, such as “the node name referenced in a link must exist.” The included schema is partially complete, covering all tests in tests/integration/initial to start. Currently, it has four must statements, which can be extended over time.

Additionally, the PR includes preliminary support for detecting the 'wtf' link type in errors/.

The intention of this PR is to illustrate a possible approach to declarative topology validation. Structural validation is handled in YANG, while detailed semantic rules (like type coercion for interfaces) remain in Python. This approach demonstrates how extended validation could evolve without replacing existing functionality.

Features:

  • New 'netlab yang' command to validate topology files
  • YANG model (netlab-topology.yang) with comprehensive topology structure
  • Support for YANG MUST statement validation using yangson library
  • JSON cache support for faster validation (via consolidate feature)
  • All tests/integration/initial/*.yml files pass validation

YANG Model:

  • Defines complete topology structure (nodes, links, defaults, etc.)
  • Supports device-specific and module-specific attributes (anydata)
  • Validates node roles, MTU, loopback configuration
  • Validates link types, interfaces, addressing, and attributes
  • Flexible structure using anydata for extensibility

CLI Command:

  • netlab yang [topology-file] --model [yang-model] --output [text|json]
  • Supports --json-cache option for faster validation
  • Supports NETLAB_JSON_CACHE environment variable
  • Detailed error reporting with full tracebacks

Dependencies:

  • yangson >= 1.4.19
  • jsonschema v4+ compatibility fixes in consolidate.py

Files:

  • netsim/cli/yang.py: CLI command handler
  • netsim/cli/yang_validator.py: YANG validation implementation
  • netsim/yang/netlab-topology.yang: YANG model definition
  • MANIFEST.in: Include YANG model files in package
  • requirements.txt: Update yangson version requirement

jbemmel avatar Dec 12 '25 22:12 jbemmel