Overview

The following study describes extending YANG language statements to allow customization of models.

References:

• CPS-735 - Getting 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

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

* 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

Basic YANG statements

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

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

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

module extended-stores {
    yang-version 1.1;
	...
    import stores{
	    prefix book-store;
	}

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

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

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

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

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

** 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 Interface

  package 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.

Key

**Green cell for case number indicates that groovy test in YangTextSchemaSourceSetSpec.groovy 'Building a valid YangTextSchemaSourceSet using #filenameCase filename) passes

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 books {..}
...
}

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 books {..}
...
}