From 0f0336296ab41e0bacf3aff485a6030534c1e262 Mon Sep 17 00:00:00 2001
From: Damien Arnodo <damien@noreply.localhost>
Date: Fri, 26 Dec 2025 13:47:00 +0000
Subject: [PATCH] docs: add README for yang module

Usage examples for all path classes:
- Interfaces, Loopbacks, VLANs
- BGP with AFI-SAFI
- VXLAN VNI mappings
- MLAG, EVPN (with limitations noted)
- Port-Channel
- Subscription helpers

Part of #3
---
 src/yang/README.md | 200 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 200 insertions(+)
 create mode 100644 src/yang/README.md

diff --git a/src/yang/README.md b/src/yang/README.md
new file mode 100644
index 0000000..d8e269a
--- /dev/null
+++ b/src/yang/README.md
@@ -0,0 +1,200 @@
+# YANG Module
+
+This module provides YANG path constants and utilities for managing Arista EVPN-VXLAN fabrics via gNMI.
+
+## Overview
+
+The module contains validated gNMI paths for Arista EOS 4.35.0F, organized by feature:
+
+| Class | Model | Description |
+|-------|-------|-------------|
+| `Interfaces` | OpenConfig | Physical and logical interfaces |
+| `Loopbacks` | OpenConfig | Loopback interfaces |
+| `VLANs` | OpenConfig | VLAN configuration and SVIs |
+| `BGP` | OpenConfig | BGP global, neighbors, AFI-SAFI |
+| `VXLAN` | Arista Exp | VXLAN VNI mappings |
+| `MLAG` | Arista Exp | MLAG config (state via eAPI) |
+| `EVPN` | Arista Exp | EVPN instances (state via eAPI) |
+| `PortChannel` | OpenConfig | LAG/Port-Channel |
+| `System` | OpenConfig | System configuration |
+
+## Installation
+
+```python
+from yang.paths import Interfaces, BGP, VXLAN
+```
+
+## Usage Examples
+
+### Interfaces
+
+```python
+from yang.paths import Interfaces
+
+# Get all interfaces
+path = Interfaces.ROOT
+# -> "/interfaces/interface"
+
+# Get specific interface
+path = Interfaces.interface("Ethernet1")
+# -> "/interfaces/interface[name=Ethernet1]"
+
+# Get interface state
+path = Interfaces.state("Ethernet1")
+# -> "/interfaces/interface[name=Ethernet1]/state"
+
+# Get operational status
+path = Interfaces.oper_status("Ethernet1")
+# -> "/interfaces/interface[name=Ethernet1]/state/oper-status"
+```
+
+### Loopbacks
+
+```python
+from yang.paths import Loopbacks
+
+# Get loopback interface
+path = Loopbacks.interface(0)
+# -> "/interfaces/interface[name=Loopback0]"
+
+# Use predefined constants
+path = Loopbacks.LOOPBACK0  # Router ID
+path = Loopbacks.LOOPBACK1  # VTEP source
+```
+
+### VLANs
+
+```python
+from yang.paths import VLANs
+
+# Get all VLANs
+path = VLANs.ROOT
+# -> "/network-instances/network-instance[name=default]/vlans/vlan"
+
+# Get specific VLAN
+path = VLANs.vlan(40)
+# -> "/network-instances/network-instance[name=default]/vlans/vlan[vlan-id=40]"
+
+# Get SVI interface
+path = VLANs.svi(40)
+# -> "/interfaces/interface[name=Vlan40]"
+```
+
+### BGP
+
+```python
+from yang.paths import BGP, AfiSafi
+
+# Get all neighbors
+path = BGP.NEIGHBORS
+# -> "/network-instances/.../bgp/neighbors/neighbor"
+
+# Get specific neighbor
+path = BGP.neighbor("10.0.1.0")
+
+# Get neighbor session state
+path = BGP.neighbor_session_state("10.0.1.0")
+
+# Get EVPN AFI-SAFI for neighbor
+path = BGP.neighbor_afi_safi("10.0.250.1", AfiSafi.L2VPN_EVPN)
+```
+
+### VXLAN
+
+```python
+from yang.paths import VXLAN
+
+# Get all VNI mappings
+path = VXLAN.VLAN_TO_VNIS
+# -> "/interfaces/interface[name=Vxlan1]/arista-vxlan/vlan-to-vnis"
+
+# Get specific VNI
+path = VXLAN.vlan_to_vni(40)
+# -> ".../vlan-to-vnis/vlan-to-vni[vlan=40]"
+
+# Get L3 VNI (VRF-to-VNI)
+path = VXLAN.vrf_to_vni("gold")
+# -> ".../vrf-to-vnis/vrf-to-vni[vrf=gold]"
+
+# Get VTEP source interface config
+path = VXLAN.SOURCE_INTERFACE
+```
+
+### MLAG
+
+```python
+from yang.paths import MLAG
+
+# Get MLAG config
+path = MLAG.CONFIG
+# -> "/arista/eos/mlag/config"
+
+# ⚠️ Note: MLAG state is NOT available via gNMI
+# Use eAPI for: show mlag
+```
+
+### EVPN
+
+```python
+from yang.paths import EVPN
+
+# Get all EVPN instances
+path = EVPN.INSTANCES
+# -> "/arista/eos/evpn/evpn-instances"
+
+# Get specific instance
+path = EVPN.instance("40")
+
+# Get route-targets
+path = EVPN.route_target("40")
+
+# ⚠️ Note: EVPN state is NOT available via gNMI
+# Use eAPI for: show bgp evpn
+```
+
+### Port-Channel
+
+```python
+from yang.paths import PortChannel
+
+# Get port-channel interface
+path = PortChannel.interface(999)
+# -> "/interfaces/interface[name=Port-Channel999]"
+
+# Get LAG aggregation config
+path = PortChannel.aggregation(999)
+```
+
+### Subscriptions
+
+```python
+from yang.paths import FabricSubscriptions, SubscriptionPath
+
+# Get pre-built subscription paths
+for sub in FabricSubscriptions.all():
+    print(f"Path: {sub.path}, Mode: {sub.mode}")
+
+# Individual subscriptions
+sub = FabricSubscriptions.INTERFACE_STATE
+sub = FabricSubscriptions.BGP_SESSIONS
+sub = FabricSubscriptions.VXLAN_VNIS
+
+# Create custom subscription
+custom = SubscriptionPath(
+    path="/interfaces/interface[name=Ethernet1]/state",
+    mode="on-change"
+)
+```
+
+## Limitations
+
+| Feature | Config | State | Notes |
+|---------|--------|-------|-------|
+| MLAG | ✅ | ❌ | Use eAPI for state |
+| EVPN | ✅ | ❌ | Use eAPI for state |
+
+## References
+
+- [Full YANG Paths Documentation](../../docs/yang-paths.md)
+- [Arista YANG Models](https://github.com/aristanetworks/yang/tree/master/EOS-4.35.0F)
+- [OpenConfig Models](https://github.com/openconfig/public)