Existing Yang Parser

WORK IN PROGRESS

This page documents the existing Yang Parser used in ONAP and OpenDayLight and will investigate if they can be used for the C&PS.

Resources

_{*Although this documentation link is to the latest ODL doc revision, it is very outdated and the code examples need significant updates, see findings in Mini-PoC below (bug reported: https://jira.opendaylight.org/browse/DOCS-126)}

Overview

The Yang parser used in ONAP (CCSDK / SDNC) was developed (and still is) a OpenDayLight Library.

There are 2 different usage patterns within CCSDK, though.

Most of CCSDK/SDNC is using Yang primarily to define their northbound interfaces. In that context, there’s a maven plugin (org.opendaylight.yangtools:yang-maven-plugin) that is used to generate source code from the Yang model. Our application code in that case doesn’t really do anything directly with the Yang, since all of the that is handled for us by the generated code.

In ccsdk/sli/plugins, there is a plugin called restconf-client which was contributed by Huawei. That code uses the yangtool parser more directly so that it can interpret the results being returned when it calls a restconf interface.

Mini-PoC

To help this evaluation I will create a small sample project with the goal to pare a yang file using the ODL Yang Tools. I will report my findings here

Maven dependency

The documentation mentioned above lists many modules but the code examples do not clarify which exactly are needed to parse a Yang file in java code.

To be able to use yangtools teh project needs to use the mdsal 'binding-parent' pom
The module yang-parser-impl contains all code required to parse yang files
SLF4J has been added as the implementation requires a logger enabled

pom.xml

   <properties>
		<maven.compiler.version>3.8.1</maven.compiler.version>
		<maven.compiler.release>11</maven.compiler.release>
		<org.opendaylight.yangtools.version>5.0.3</org.opendaylight.yangtools.version>
	</properties>
	
	<build>
		<plugins>
			<plugin>
				<groupId>org.apache.maven.plugins</groupId>
				<artifactId>maven-compiler-plugin</artifactId>
				<version>${maven.compiler.version}</version>
				<configuration>
					<release>${maven.compiler.release}</release>
				</configuration>
			</plugin>
		</plugins>
	</build>

	<dependencies>
		<dependency>
			<groupId>org.opendaylight.yangtools</groupId>
			<artifactId>yang-parser-api</artifactId>
			<version>${org.opendaylight.yangtools.version}</version>
		</dependency>

		<dependency>
			<groupId>org.opendaylight.yangtools</groupId>
			<artifactId>yang-parser-impl</artifactId>
			<version>${org.opendaylight.yangtools.version}</version>
		</dependency>

		<dependency>
			<groupId>org.opendaylight.yangtools</groupId>
			<artifactId>yang-model-util</artifactId>
			<version>${org.opendaylight.yangtools.version}</version>
		</dependency>

		<dependency>
			<groupId>org.opendaylight.yangtools</groupId>
			<artifactId>yang-data-codec-xml</artifactId>
			<version>${org.opendaylight.yangtools.version}</version>
		</dependency>

		<dependency>
			<groupId>org.slf4j</groupId>
			<artifactId>slf4j-api</artifactId>
			<version>1.6.1</version>
		</dependency>

		<dependency>
			<groupId>org.slf4j</groupId>
			<artifactId>slf4j-log4j12</artifactId>
			<version>1.6.1</version>
		</dependency>
	</dependencies>

Documentation Code Updates

The sample code provided in the documentation is faulty (using == for assigning?!) and is using some long deprecated and even removed classes and methods.

Bug reported: https://jira.opendaylight.org/browse/DOCS-126

Corrected Code

    static YangParserFactory PARSER_FACTORY;

    static {
        final Iterator<YangParserFactory> it = ServiceLoader.load(YangParserFactory.class).iterator();
        if (!it.hasNext()) {
            throw new IllegalStateException("No YangParserFactory found");
        }
        PARSER_FACTORY = it.next();
    }

    ...

        File file = new File(ClassLoader.getSystemClassLoader().getResource("example.yang").getFile());
        YangTextSchemaSource source = YangTextSchemaSource.forFile(file);
        
        final YangParser yangParser = PARSER_FACTORY.createParser(StatementParserMode.DEFAULT_MODE);
        yangParser.addSource(source);
        SchemaContext schemaContext = yangParser.buildEffectiveModel();

        schemaContext.getModules()

This is the kind of object (module) that gets created:

Generated Java Object Structures per Yang concept

Object Structure

The SchemaContext object generated by the Yang Parser in java has the following possible structures (java collections)

ChildNodes are implemented as a Map <QName, DataSchemaNode>

The Class DataSchemaNode can represent a Yang Leaf, List or Container

Main data types

The package org.opendaylight.yangtools.yang.model.util.type contains classes for all the possible data types including:

BaseBinaryType
BaseBitsType
BaseBooleanType
BaseDecimalType
BaseEnumerationType
BaseInt8Type
BaseInt16Type
BaseInt32Type
BaseInt64Type
BaseStringType
BaseUint8Type
BaseUint16Type
BaseUint32Type
BaseUint64Type

There are also some special data types such as:

BaseEmptyType
BaseIdentityrefType
BaseInstanceIdentifierType
BaseLeafrefType
BaseUnionType

Description	Yang	Notes
Datatypes and basic constraints
Basic String	`leaf response-code {` `type string;` `}`
Mandatory Basic String	`leaf response-code {` `type string;` `mandatory "true";` `}`
Limited String	`leaf pnf-name {` `type string {` `length "0..256";` `}`	Specialized class to hold length limitation
typedef (String) with pattern	`typedef dotted-quad {` `type string {` `pattern` `'(([0-9] ...';` `}` `}` `leaf address {` `type dotted-quad;` `mandatory "true";` `}`
Limited unint64	`leaf cid {` `type string {` `length "0..52";` `}`
boolean with default value	`leaf blacklisted {` `type boolean;` `default 1;` `}`
Unique
Unique	`list server {` `key "name";` `unique "ip port";` `leaf name {` `type string;` `}` `leaf ip {` `type dotted-quad;` `}` `leaf port {` `type uint32;` `}}`
Choice
Choice	`choice transfer-method {` `leaf transfer-interval {` `type uint64 {` `range "15..2880";` `}` `units minutes;` `}` `leaf transfer-on-commit {` `type empty;` `}}`
Must
Must	`leaf ifType {` `type enumeration {` `enum ethernet;` `enum atm;}}` `leaf ifMTU {` `type uint32;}` `must "ifType != 'ethernet' or "` `+ "(ifType = 'ethernet' and ifMTU = 1500)" {error-message 466px"An ethernet MTU must be 1500";}`
When
When	leaf a { type boolean; } leaf b { type string; when "../a = 'true'"; }
Extension
Extension declaration	`extension store-state-ext {` `argument duration;` `description "An extension to enable state-storage for any attribute. Use duration to specify how long: nnn h\|d\|y";` `}`
Extension usage	`leaf attribute-with-temporal-storage {` `type string;` `cm-notify-api:store-state-ext "3 d"; // store state 3 days` `}`	extension is stored as 'UnknownNode' and refers back to the extension declaration
Augmentation
	`augment "server" {` `when "port = '8787'";` `leaf enable-debug {` `type boolean;` `}` `}`
RPC
rpc	rpc nbrlist-change-notification { description "RAN Neighbor List change notification to configure RuntimeDB"; input { : } output { : } }
rpc input	input { leaf fap-service-number-of-entries-changed { type uint64; description "Number of cells for which neighbor list has changed"; } list fap-service { key "alias"; leaf alias { type string { length "1..64"; } } leaf cid { type string { length "0..52"; } } uses x-0005b9-lte-g; leaf lte-cell-number-of-entries { type uint64; description "Number of cells in a neighbor list that was changed"; } list lte-ran-neighbor-list-in-use-lte-cell-changed { key "plmnid cid"; uses lte-ran-neighbor-list-in-use-lte-cell-g; description "Changed/Modified List of cells in a neighbor list for this fap service"; } } }
rpc output	output { uses cm-notification-response; }