Overview
The following study describes extending YANG language statements to allow customization of models.
References:
- - CPS-735Getting issue details... STATUS
- https://datatracker.ietf.org/doc/rfc8526/
- https://www.rfc-editor.org/rfc/rfc6095.html
- https://www.hjp.at/doc/rfc/rfc6020.html#sec_6.3.1
- https://docs.opendaylight.org/en/latest/release-notes/upgrade-process.html?highlight=extension%20annotation#unrecognized-yang-statement-handling
- https://datatracker.ietf.org/doc/html/rfc6110#section-9.4
- https://datatracker.ietf.org/doc/html/rfc8791
- Related JIRA stories:
YANG Language
- The YANG language provides us the ability to define and model configurations and state data by defining YANG modules
- Modules contain a sequence of statements
- Statement syntax is either of the following :
- statement = keyword [argument] ;
- statement = keyword [argument] { <substatement(s)..> } ;
- Statement syntax is either of the following :
- Modules contain a sequence of statements
* argument can be zero or one depending on the statement
* argument is a string
- An XML-based equivalent version of YANG is called YIN
- YANG uses a tree to define the hierarchy of data wherein each ‘node’ has a value or/and a set of child nodes
- 4 types of nodes
container nodes
- list nodes
- leaf nodes
- leaf-list nodes
- 4 types of nodes
Basic YANG statements
Sample YANG (stores.yang) | Statements and Description |
---|---|
stores model module stores { yang-version 1.1; namespace "org:onap:ccsdk:sample"; prefix book-store; revision "2020-09-15" { description "Sample Model"; } typedef year { type uint16 { range "1000..9999"; } } container bookstore { leaf bookstore-name { type string; } list categories { key "code"; leaf code { type string; } leaf name { type string; } list books { key title; leaf title { type string; } leaf-list authors { type string; } } } } } | module Statement see example from Line 1
see examples from Lines 2-16
typedef Statement see example from Line 12
container Statement see example from Line 18
leaf Statement see example from Line 27
list Statement see example from Line 35
leaf-list Statement see example from Line 41
|
Figure 1.1 Schema tree of module 'stores'
module: stores +--rw bookstore +--rw bookstore-name? string +--rw categories* [code] +--rw code string +--rw name? string +--rw books* [title] +--rw title string +--rw lang? string +--rw authors* string +--rw pub_year? year +--rw price? uint64
YANG extension Statement
Sample YANG (stores.yang with extension) | Statements and Description |
---|---|
stores model with extension module sync-extension { … prefix sync-ext; … extension sync-flag{ description “This is a sample extension statement description“ argument "value"; } } The following model shows that it imported the model above where extensions is declared. extended-stores model module extended-stores { yang-version 1.1; ... import sync-extension{ prefix sync-ext; } typedef year { type uint16 { range "1000..9999"; } } container bookstore { sync-ext:sync-flag "on"; ... } } | extension Statement see example from Lines 5-9 on stores model with extension
extension <keyword/identifier>{ <extension substatements...> }
see example from Line 15 on extended-stores model <module prefix>:<extension keyword> "argument";
argument Statement see examples from Line 6 on stores model
|
YIN-extended-stores model <?xml version="1.0" encoding="UTF-8"?> <module name="extended-stores" xmlns="urn:ietf:params:xml:ns:yang:yin:1" xmlns:ext-book-store="org:onap:ccsdk:sampleExtended" xmlns:book-store="org:onap:ccsdk:sample"> <namespace uri="org:onap:ccsdk:sampleExtended"/> <prefix value="ext-book-store"/> <revision date="2020-09-15"> <description> <text>Sample Extended Model</text> </description> </revision> <import module="sync-extension"> <prefix value="sync-ext"/> </import> <typedef name="year"> <type name="uint16"> <range value="1000..9999"/> </type> </typedef> <container name="bookstore"> <sync-ext:sync-flag value="on"/> <leaf name="bookstore-name"> <type name="string"/> </leaf> ... </container> </module> | yin-element Statement
Notes
|
** the YIN version and Schema trees above are generated by YANG validator 'pyang'
Existing YANG parser in CPS
(Please see https://wiki.onap.org/display/DW/Existing+Yang+Parser)
OpenDayLight Yang tools recognize YANG extensions
Contains interface which has methods to access data of a YANG extension statement
Yang tools ExtensionDefinition Interfacepackage org.opendaylight.yangtools.yang.model.api; import org.opendaylight.yangtools.yang.model.api.stmt.ExtensionEffectiveStatement; public interface ExtensionDefinition extends SchemaNode, EffectiveStatementEquivalent<ExtensionEffectiveStatement> { String getArgument(); boolean isYinElement(); }
Test cases and scenarios
The following test cases used and modified the standard stores model seen above.
Testing with groovy
The following cases were tested in YangTextSchemaSourceSetSpec.groovy using the test method 'Building a valid YangTextSchemaSourceSet using #filenameCase filename)'.
Key
**Green cell for case number indicates that tests have passed
**Red cell for case number indicates that tests have failed
- the extension is defined as substatement in the module with argument statement as its substatement
Case # | Description | JAVA object | Notes |
1 |
|
| |
2 |
|
| |
3 |
|
| |
4 |
|
| |
5 |
|
| |
6 |
|
| |
7 |
|
| |
8 |
|
| |
9 |
|
| |
10 |
|
Extra Notes:
- There seems to be no inheritance of the extension statement for the substatements wherein the extension was used
- The date tree and schema tree does not change sizes with the addition of the extensions for all cases shown above
Parsing a original data instance (json) using the extended model
Case # | Description | Result |
---|---|---|
1 |
|
|
2 |
|
*the same result acquired for all passed cases on the groovy tests table above |
3 |
|
|
4 |
|
|
Conclusions
- The YANG language extension analysis above is only applicable for seeing that it is good for type configuration.
- The extension does not extend the actual data of the model instance
- Based on the test scenarios above, extensions can only be seen on the schema sets and not on the data
- YANG extension can be used at every level of the tree model
- The test results show that the model is being recognized by the current YANG tools used to parse a model
- It fails for scenarios such as parsing a model without an argument defined when it is expecting it
- This analysis did not look further into the effect of setting yin-element to 'true' for the model instance
- Further investigation is required to cover interpretation as the analysis above only covers parsing