Update style guide to reflect path compression rules. #1424
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -3,7 +3,7 @@ | |
|
|
||
| **Contributors:** Anees Shaikh, Rob Shakir, Kristian Larsson, Darren Loher | ||
| **October 26, 2015**<br> | ||
| *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,39 @@ 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 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 adhered to within the OpenConfig models to | ||
| ensure that downstream tooling does not break. | ||
|
|
||
| * **`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 | ||
|
Contributor
There was a problem hiding this comment. Also, if you keep some requirement around you probably want to use must vs may, per RFC 2119 -- |
||
| for `/a/config/leaf` and `/a/leaf` to both exist nor for `/b/state/leaf` | ||
robshakir marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| 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` | ||
|
Comment on lines
+503
to
+505
Contributor
There was a problem hiding this comment. Optional way to rephrase (also fine as is): "The single exception to this rule is the OpenConfig list key pattern. The leaf inside the |
||
| 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)). | ||
|
|
||
| ## Appendix | ||
|
|
||
|
|
||
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
**A leaf node may not share a name with a grandparent**.Do we want this here still? Seems unrelated to the explanation that follows. (And is also not a true statement -- presumably having been replaced with the previous bullet about children of its grandparent.)