Overview

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

References:

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

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

YANG language defines models with modules and submodules
Takes one argument (module name) which is the identifier
Groups all statements that belong to the module
This module example contains the following statements for header information:

see examples from Lines 2-16

- - yang-version statement
  - namespace statement prefix statement
  - revision statements

typedef Statement

see example from Line 12

a statement that allows a new type to be defined based on a base type which is a YANG built-in type

container Statement

see example from Line 18

defines interior (container node) in the schema tree
only contains child nodes, has no value
- - child nodes can be a leaf, lists, containers and leaf-lists

leaf Statement

see example from Line 27

defines a leaf node in the schema tree
its only one argument is the identifier
has no child nodes, has one value of a particular type
'type statement' is mandatory
See optional substatements available in (Section 7.6 https://www.hjp.at/doc/rfc/rfc6020.html#sec_1)

list Statement

see example from Line 35

defines an interior data node (list node) in the schema tree
its only one argument is the identifier
follows a block of substatements:
mandatory substatements:
- - 'key statement'

leaf-list Statement

see example from Line 41

array of leaf nodes
one value of a particular type per leaf
its only one argument is the identifier

Figure 1.1 Schema tree of module 'stores'

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 stores {
…
prefix book-store;
…
   extension sampleExtension{
     description
           “This is a sample extension statement description“
      argument name {
          yin-element true;
     }
   }
container bookstore { 
        leaf bookstore-name {
            type string;
        }
….
}

example-module2 model

module example-module2{
…
     import stores {
       prefix book-store;
     }

     book-store:sampleExtension locations {
       list address {
         key "state";
         leaf state {
           type string;
           description "State name"{
               book-store:sampleExtension-b "b-sample-name";
           }
         }
         leaf city {
           type string;
           description "City name"{
               book-store:sampleExtension-c "c-sample-name";
           }
….
   }

extension Statement

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

Syntax

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

Usage

see example from Lines

<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 Lines on stores model

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

example-model2 model (YIN version)

<?xml version="1.0" encoding="UTF-8"?>
<module name="example-module2"
        xmlns="urn:ietf:params:xml:ns:yang:yin:1"
        xmlns:em="org:onap:ccsdk:sample2"
        xmlns:book-store="org:onap:ccsdk:sample">
  <yang-version value="1.1"/>
  <namespace uri="org:onap:ccsdk:sample2"/>
  <prefix value="em"/>
  <import module="stores">
    <prefix value="book-store"/>
  </import>
  <book-store:sampleExtension>
    <book-store:name>locations</book-store:name>
    <list name="address">
      <key value="state"/>
      <leaf name="state">
        <type name="string"/>
        <description>
          <text>State name</text>
          <book-store:sampleExtension-b name="b-sample-name"/>
        </description>
      </leaf>
      <leaf name="city">
        <type name="string"/>
        <description>
          <text>City name</text>
          <book-store:sampleExtension-c>
            <book-store:name>c-sample-name</book-store:name>
          </book-store:sampleExtension-c>
        </description>
      </leaf>
    </list>
  </book-store:sampleExtension>
</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

Line

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

Expected tree diagram for example-module based on RFC8340 (https://datatracker.ietf.org/doc/html/rfc8340):

Schema tree for sampleExtension

sampleExtension locations:
     +-- address* [state]
        +-- state string
        +-- city? string

Existing YANG parser in CPS

(Please see https://wiki.onap.org/display/DW/Existing+Yang+Parser)

OpenDayLight Yang tools recognises 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();
}

Implementing Class
- - Class

CPS-735 Spike: Support for Yang Language Extension