From ae4bc59943104b679db2aeea82ca75fdc016c327 Mon Sep 17 00:00:00 2001 From: Rob Shakir Date: Fri, 9 Jan 2026 17:47:53 -0800 Subject: [PATCH 1/2] Update style guide to reflect path compression rules. * (M) doc/openconfig_style_guide.md - Provide further documentation in the OpenConfig style guide on the rules required to allow programmatic schema transformation. These rules have been adhered to throughout the lifetime of OpenConfig, and are implemented by widely used code generation tools. This PR simply records these defacto style guide rules. This PR is accompanied by https://github.com/openconfig/oc-pyang/pull/59 which implements the relevant linter checks for the rules described herein. --- doc/openconfig_style_guide.md | 30 +++++++++++++++++++++++++++++- 1 file changed, 29 insertions(+), 1 deletion(-) diff --git a/doc/openconfig_style_guide.md b/doc/openconfig_style_guide.md index d70c1cd902..ba72cf5adb 100644 --- a/doc/openconfig_style_guide.md +++ b/doc/openconfig_style_guide.md @@ -3,7 +3,7 @@ **Contributors:** Anees Shaikh, Rob Shakir, Kristian Larsson, Darren Loher **October 26, 2015**
-*Updated: June 12, 2025* +*Updated: January 9th 2026* ## Background This document describes conventions adopted in the OpenConfig operator group @@ -49,6 +49,7 @@ and released soon. - [`choice`](#choice) - [XPath](#xpath) - [Regular expressions](#regular-expressions) + - [Schema Usability](#schema-usability) - [Appendix](#appendix) - [Example groupings for containers](#example-groupings-for-containers) - [OpenConfig YANG module template](#openconfig-yang-module-template) @@ -476,6 +477,33 @@ reference for [regular expressions](http://www.w3.org/TR/2004/REC-xmlschema-2-20041028/#regexs). However, this is not a commonly used standard for implementors. +## Schema Usability + +Some elements of the OpenConfig style guide are implemented in order to provide +consistent programmatic handling of the schema. For instance, the `config` and +`state` containers used for operational state, and surrounding containers for +YANG `list` statements. In some cases (e.g., programmatically generating +configuration), this schema verbosity negatively impacts usability -- e.g., +requiring programmers to reference longer paths that they could. Tooling +generating programmatic APIs around OpenConfig can improve usability by +transforming the schema. Clearly, this is wholly reliant on consistency +in the modelling approach. + +The following rules MUST be adherered to within the OpenConfig models to +ensure that downstream tooling does not break. + +* **`list` nodes MUST NOT share their identifier with any grandparent + node.** It is not legal for `/foos/foo` and `/foo` to exist. This rule + exists to allow the `foos` container to be removed during schema + transformation. +* **A leaf-node may not share a name with a grandparent**. It is not legal + for `/a/config/leaf` and `/a/leaf` to both exist nor for `/b/state/leaf` + and `/b/leaf` to both exist. This rule ensures that the `config` and `state` + containers can be removed during schema transformation. + +An example of programmatic compression is implemented for the generation of +code in ygot -- both for Go and Protobuf artifact generation +((reference)[https://github.com/openconfig/ygot/blob/master/docs/design.md#openconfig-path-compression]). ## Appendix From 025da020a0988bd88166ab755d18ae18d9eadc6a Mon Sep 17 00:00:00 2001 From: Rob Shakir Date: Tue, 3 Feb 2026 14:57:12 +0000 Subject: [PATCH 2/2] Address review comments. --- doc/openconfig_style_guide.md | 26 ++++++++++++++++---------- 1 file changed, 16 insertions(+), 10 deletions(-) diff --git a/doc/openconfig_style_guide.md b/doc/openconfig_style_guide.md index ba72cf5adb..a630fd0cc8 100644 --- a/doc/openconfig_style_guide.md +++ b/doc/openconfig_style_guide.md @@ -484,26 +484,32 @@ consistent programmatic handling of the schema. For instance, the `config` and `state` containers used for operational state, and surrounding containers for YANG `list` statements. In some cases (e.g., programmatically generating configuration), this schema verbosity negatively impacts usability -- e.g., -requiring programmers to reference longer paths that they could. Tooling +requiring programmers to reference longer paths than are necessary. Tooling generating programmatic APIs around OpenConfig can improve usability by transforming the schema. Clearly, this is wholly reliant on consistency in the modelling approach. -The following rules MUST be adherered to within the OpenConfig models to +The following rules MUST be adhered to within the OpenConfig models to ensure that downstream tooling does not break. -* **`list` nodes MUST NOT share their identifier with any grandparent - node.** It is not legal for `/foos/foo` and `/foo` to exist. This rule - exists to allow the `foos` container to be removed during schema - transformation. -* **A leaf-node may not share a name with a grandparent**. It is not legal +* **`list` nodes MUST NOT share their identifier with any of the children + of its grandparent node.** It is not legal for `/a/foos/foo` and `/a/foo` + to exist, or for `/interfaces/interface` and `/interface` to exist, where + `/a/foos/foo` and `/interfaces/interface` are `list` nodes. This rule + exists to allow the (style-guide-required) "surrounding" container of + a list to be removed during schema transformation. +* **A leaf node may not share a name with a grandparent**. It is not legal for `/a/config/leaf` and `/a/leaf` to both exist nor for `/b/state/leaf` - and `/b/leaf` to both exist. This rule ensures that the `config` and `state` - containers can be removed during schema transformation. + and `/b/leaf` to both exist. The single exception to this rule is the + special case of nodes which act as the `key` of a `list`, where the leaf + must be a direct child of the `list` node. Such leaves MUST be the `key` + of the `list` and must be of type `leafref` as specified elsewhere in this + guide. This rule ensures that the `config` and `state` containers can be removed + during schema transformation. An example of programmatic compression is implemented for the generation of code in ygot -- both for Go and Protobuf artifact generation -((reference)[https://github.com/openconfig/ygot/blob/master/docs/design.md#openconfig-path-compression]). +([reference](https://github.com/openconfig/ygot/blob/master/docs/design.md#openconfig-path-compression)). ## Appendix