Jira Legacy
server System Jira
serverId 4733707d-2057-3a0f-ae5e-4fd8aff50176
key CPS-735
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:
- Jira Legacy
  server System Jira
  serverId 4733707d-2057-3a0f-ae5e-4fd8aff50176
  key CPS-866

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)..> } ;

...

Sample YANG

(stores.yang with extension)

Statements and Description

Code Block

language	yml
title	stores model with extension
linenumbers	true

module storessync-extension {
…
prefix booksync-storeext;
…
   extension sync-flag{
     description
           “This is a sample extension statement description“
      argument "value";
   }
container}
bookstore { 
        leaf bookstore-name {
            type string;
        }
….
}

The following model shows that it imported the model above where extensions is declared.

Code Block

language	yml
title	extended-stores model
linenumbers	true

module extended-stores {
    yang-version 1.1;
	...
    import storessync-extension{
	    prefix booksync-storeext;
	}

    typedef year {
        type uint16 {
            range "1000..9999";
        }
    }

    container bookstore {
        booksync-storeext:sync-flag "on";
    ...
	}
}

extension Statement

see example from Lines 5-9 on stores model with extension

Syntax

Code Block

language	text

extension <keyword/identifier>{
     <extension substatements...>
}

Usage

see example from Line 15 on extended-stores model

Code Block

language	text

<module prefix>:<extension keyword> "argument";

to be used to define new statements
available to be imported and used by other modules just like a normal YANG statement
- - by use of 'import statement' to import the module where the extension is defined
statements that do not have any substatements can have extensions defined if wanted
its only one argument is the identifier and keyword for the extension
Optional substatements:
- - argument Statement
  - description Statement
  - reference Statement
  - defined extension Statements

argument Statement

see examples from Line 6 on stores model

takes a string argument which is the name of the argument to the keyword
Optional substatement
- - yin-element Statement

Code Block

language	xml
theme	Midnight
title	YIN-extended-stores model
linenumbers	true

<?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="storessync-extension">
    <prefix value="booksync-storeext"/>
  </import>
  <typedef name="year">
    <type name="uint16">
      <range value="1000..9999"/>
    </type>
  </typedef>
  <container name="bookstore">
    <book<sync-storeext:sync-flag value="on"/>
    <leaf name="bookstore-name">
      <type name="string"/>
    </leaf>
	...
  </container>
</module>

yin-element Statement

takes a string argument which is true or false
yin-element is 'false' by default
if the argument is 'true' it indicates that the argument is mapped to an XML element in YIN or to an XML attribute

Notes

Line 22 on YIN-extended-stores model
1. result of using the argument without specifying the yin-element value
  1. yin-element is 'false'
  2. the argument 'value' is only an XML attribute

if argument statement (Line 6 on stores model) contains yin-element substatement YIN-extend-stores model would result to the following:

extension statement will produce a child node

Code Block

theme	Midnight
title	YIN-extended-stores model where yin-element is 'true'

...
  <container name="bookstore">
    <book<sync-storeext:sync-flag>
      <book<sync-storeext:value>on</booksync-storeext:value>
    </booksync-storeext:sync-flag>
...
  </container>
...

** extension does not extend the data

** the YIN version and Schema trees above are generated by YANG validator 'pyang'

Existing YANG parser in CPS

(Please see https://wikilf-onap.onapatlassian.orgnet/wiki/display/DW/Existing+Yang+Parser)

OpenDayLight Yang tools recognize YANG extensions

...

The following test cases used and modified the standard stores model seen above.

Key

...

Testing with groovy

The following cases were tested in YangTextSchemaSourceSetSpec.groovy using the test method 'Building a valid YangTextSchemaSourceSet using #filenameCase filename) passes'.

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	extension used inside container statement before all other substatements

extension contained argument

Code Block

collapse	true

module stores {
    yang-version 1.1;
	...
    extension sync-flag{
        description "This extension allows to tag nodes with a sync flag";
        argument "value";
    }

    typedef year {...}

    container bookstore {
        book-store:sync-flag "on";
		...
        leaf bookstore-name {...}
		list categories {..}
...
}

Image Modified

extension declared after all other substatements of container still passed

2

extension

defined as substatement in the module with argument statement as its substatementextension

used inside a leaf statement (child of a container) before all other substatements

extension contained argument

Code Block

collapse	true

module stores {
    yang-version 1.1;
	...
    extension sync-flag{
        description "This extension allows to tag nodes with a sync flag";
        argument "value";
    }

    typedef year {...}

    container bookstore {
		...
        leaf bookstore-name {
	      book-store:sync-flag "on"; 
		}
		list categories {..}
...
}

Image Modified

Extension declared after type-statement inside leaf statement (child of a container) still passed

3

extension defined as substatement in the module with argument statement as its substatement

extension used inside list statement (child of a container) before all other substatements

extension contained argument

Code Block

collapse	true

module stores {
    yang-version 1.1;
	...
    extension sync-flag{
        description "This extension allows to tag nodes with a sync flag";
        argument "value";
    }

    typedef year {...}

    container bookstore {
		...
        leaf bookstore-name {...}
		list categories {
		 	book-store:sync-flag "on";
			key "code";
			...  
		}
...
}

Image Modified

Extension declared after key-statement inside list statement (child of a container) still passed

4

extension

defined as substatement in the module with argument statement as its substatementextension used inside leaf statement

used inside leaf statement (child of list node from case #3) before all its substatements

extension contained argument

Code Block

collapse	true

module stores {
    yang-version 1.1;
 	...
    extension sync-flag{
        description "This extension allows to tag nodes with a sync flag";
        argument "value";
    }
    typedef year {...}

    container bookstore {
        leaf bookstore-name {...}

    list categories {
        key "code";
        leaf code {
            book-store:sync-flag "on";
            type string;
        }
        leaf name {...}
        list books {...}
...
}

Image Modified

Extension declared after type-statement inside leaf statement (child of list node from case #3) still passed

5

extension

defined as substatement in the module with argument statement as its substatementextension

used inside list node (child of list node from case #4) before key-statement of list

extension contained argument

Code Block

collapse	true

module stores {
    yang-version 1.1;
 	...
    extension sync-flag{
        description "This extension allows to tag nodes with a sync flag";
        argument "value";
    }
    typedef year {...}

    container bookstore {
        leaf bookstore-name {...}

    list categories {
        key "code";
        leaf code {...}
        leaf name {...}
        list books {
		 book-store:sync-flag "on";
		...
		}
...
}

Image Modified

extension declared after key-statement of the list statement still passed

6

extension

defined as substatement in the module with argument statement as its substatementextension

used inside leaf-list node (child of list node from case #5) before all other substatements

extension contained argument

Code Block

collapse	true

module stores {
    yang-version 1.1;
 	...
    extension sync-flag{
        description "This extension allows to tag nodes with a sync flag";
        argument "value";
    }
    typedef year {...}

    container bookstore {
        leaf bookstore-name {...}

    list categories {
        key "code";
        leaf code {...}
        leaf name {...}
        list books {
			leaf-list authors{
			  book-store:sync-flag "on"; 
			}
		}
...
}

Image Modified

extension declared after type-statement of leaf-list still passed

7

extension defined as substatement in the module with argument statement as its substatement

extension used inside module

extension declared before container node

extension contained argument

extension declared has no argument

Code Block

collapse	true

module stores {
    yang-version 1.1;
	...
    extension sync-flag{
        description "This extension allows to tag nodes with a sync flag";
        argument "value";
    }

    typedef year {...}

    book-store:sync-flag "on"; 

    container bookstore {...}
}

Image Modified

data tree still only has one direct child (container node) as with the standard stores model
value of the argument is not seen?

8

scenario the same as case 1 but the extension was used in the container statement without an argument

Code Block

collapse	true

module stores {
    yang-version 1.1;
	...
    extension sync-flag{
        description "This extension allows to tag nodes with a sync flag";
        argument "value";
    }

    typedef year {...}

    container bookstore {
        book-store:sync-flag;
		...
}

Image Modified

same extension declaration/usage fails for:
- - scenarios in all cases 2-7

9

extension defined as substatement in the module without argument statement as its substatement

extension used inside container statement before all other substatements

no argument declared for extension

Code Block

collapse	true

module stores {
    yang-version 1.1;
	...
    extension sync-flag;

    typedef year {...}

    container bookstore {
        book-store:sync-flag;
		...
        leaf bookstore-name {...}
		list categories {..}
...
}

Image Modified

use of the same definition and declaration of the extension on this case for cases #1-7 passes

10

extension

defined as substatement in the module without argument statement as its substatementextension

used twice
- inside container statement before all other substatements
- inside leaf statement (child of container statement)

extension declared has no argument

Code Block

collapse	true

module stores {
    yang-version 1.1;
	...
    extension sync-flag;

    typedef year {...}

    container bookstore {
        book-store:sync-flag;
		...
        leaf bookstore-name {
			book-store:sync-flag;
		}
		list categories {..}
...
}

Image Modified

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	Created schema set the model contained only an extension definition	successfully stored yang resource successfully created a node using the model fragment table did not add the extension argument in attributes
2	Created schema set the model contained an extension definition and the model was used inside a container node	successfully stored yang resource successfully created a node using the model fragment table did not add the extension argument in attributes *the same result acquired for all passed cases on the groovy tests table above
3	Created schema set the model contained only an extension definition extension contains argument yin-element set to true	creating the schema set failed received 500 server error parsing schema set
4	Created schema set the model contained an extension definition and was used inside the container node extension contains argument yin-element set to true	creating the schema set failed received 500 server error parsing schema set

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
- see
  Jira Legacy
  server System Jira
  serverId 4733707d-2057-3a0f-ae5e-4fd8aff50176
  key CPS-866

Versions Compared

Old Version 24

New Version Current

Key

YANG Language

Existing YANG parser in CPS

Testing with groovy

Parsing a original data instance (json) using the extended model

Conclusions

Page Comparison

Versions Compared

Old Version 24

New Version Current

Key

YANG Language

Existing YANG parser in CPS

Testing with groovy

Parsing a original data instance (json) using the extended model

Conclusions