2 :rfc6020: https://tools.ietf.org/html/rfc6020
3 :lhotka-yang-json: https://tools.ietf.org/html/draft-lhotka-netmod-yang-json-01
6 YANG Tools is set of libraries and tooling providing support for use {rfc6020}[YANG] for Java (or other JVM-based language) projects and applications.
8 YANG Tools provides following features in OpenDaylight:
10 - parsing of YANG sources and
11 semantic inference of relationship across YANG models as defined in
13 - representation of YANG-modeled data in Java
14 ** *Normalized Node* representation - DOM-like tree model, which uses conceptual
15 meta-model more tailored to YANG and OpenDaylight use-cases than a standard XML
17 - serialization / deserialization of YANG-modeled data driven by YANG
19 ** XML - as defined in {rfc6020}[RFC6020]
20 ** JSON - as defined in {rfc6020}[draft-lhotka-netmod-yang-json-01]
21 ** support for third-party generators processing YANG models.
24 YANG Tools project consists of following logical subsystems:
26 - *Commons* - Set of general purpose code, which is not specific to YANG, but
27 is also useful outside YANG Tools implementation.
28 - *YANG Model and Parser* - YANG semantic model and lexical and semantic parser
29 of YANG models, which creates in-memory cross-referenced represenation of
30 YANG models, which is used by other components to determine their behaviour
32 - *YANG Data* - Definition of Normalized Node APIs and Data Tree APIs, reference
33 implementation of these APIs and implementation of XML and JSON codecs for
35 - *YANG Maven Plugin* - Maven plugin which integrates YANG parser into Maven
36 build lifecycle and provides code-generation framework for components, which
37 wants to generate code or other artefacts based on YANG model.
40 Project defines base concepts and helper classes which are project-agnostic and could be used outside of YANG Tools project scope.
46 - yang-data-codec-gson
53 - yang-maven-plugin-it
54 - yang-maven-plugin-spi
62 Class diagram of yang model API
64 image:models/yang-model-api.png[]
68 Yang Statement Parser works on the idea of statement concepts as defined in RFC6020, section 6.3. We come up here with basic ModelStatement and StatementDefinition, following RFC6020 idea of having sequence of statements, where
69 every statement contains keyword and zero or one argument. ModelStatement is extended by DeclaredStatement (as it comes from source, e.g. YANG source)
70 and EffectiveStatement, which contains other substatements and tends to represent result of semantic processing of other statements (uses, augment for YANG).
71 IdentifierNamespace represents common superclass for YANG model namespaces.
73 Input of the Yang Statement Parser is a collection of StatementStreamSource objects.
74 StatementStreamSource interface is used for inference of effective model
75 and is required to emit its statements using supplied StatementWriter.
76 Each source (e.g. YANG source) has to be processed in three steps
77 in order to emit different statements for each step.
78 This package provides support for various namespaces used across statement parser
79 in order to map relations during declaration phase process.
81 Currently, there are two implementations of StatementStreamSource in Yangtools:
83 - YangStatementSourceImpl - intended for yang sources
84 - YinStatementSourceImpl - intended for yin sources
87 Class diagram of yang data API
89 image:models/yang-data-api.png[]
92 Codecs which enable serialization of NormalizedNodes into YANG-modeled data in XML or JSON format and deserialization of YANG-modeled data in XML or JSON format into NormalizedNodes.
94 ==== YANG Maven Plugin
95 Maven plugin which integrates YANG parser into Maven
96 build lifecycle and provides code-generation framework for components, which
97 wants to generate code or other artefacts based on YANG model.
101 === Working with YANG Model
102 First thing you need to do if you want to work with YANG models is to instantiate a SchemaContext object. This object type describes one or more parsed YANG modules.
104 In order to create it you need to utilize YANG statement parser which takes one or more StatementStreamSource objects as input and then produces the SchemaContext object.
106 StatementStreamSource object contains the source file information. It has two implementations, one for YANG sources - YangStatementSourceImpl, and one for YIN sources - YinStatementSourceImpl.
108 Here is an example of creating StatementStreamSource objects for YANG files, providing them to the YANG statement parser and building the SchemaContext:
112 StatementStreamSource yangModuleSource = new YangStatementSourceImpl("/example.yang", false);
113 StatementStreamSource yangModuleSource2 = new YangStatementSourceImpl("/example2.yang", false);
115 CrossSourceStatementReactor.BuildAction reactor = YangInferencePipeline.RFC6020_REACTOR.newBuild();
116 reactor.addSources(yangModuleSource, yangModuleSource2);
118 SchemaContext schemaContext = reactor.buildEffective();
121 First, StatementStreamSource objects with two constructor arguments should be instantiated: path to the yang source file (which is a regular String object) and a boolean which determines if the path is absolute or relative.
123 Next comes the initiation of new yang parsing cycle - which is represented by CrossSourceStatementReactor.BuildAction object. You can get it by calling method newBuild() on CrossSourceStatementReactor object (RFC6020_REACTOR) in YangInferencePipeline class.
125 Then you should feed yang sources to it by calling method addSources() that takes one or more StatementStreamSource objects as arguments.
127 Finally you call the method buildEffective() on the reactor object which returns EffectiveSchemaContext (that is a concrete implementation of SchemaContext). Now you are ready to work with contents of the added yang sources.
129 Let us explain how to work with models contained in the newly created SchemaContext. If you want to get all the modules in the schemaContext, you have to call method getModules() which returns a Set of modules. If you want to get all the data definitions in schemaContext, you need to call method getDataDefinitions, etc.
132 Set<Module> modules = schemaContext.getModules();
133 Set<DataSchemaNodes> dataSchemaNodes = schemaContext.getDataDefinitions();
135 Usually you want to access specific modules. Getting a concrete module from SchemaContext is a matter of calling one of these methods:
137 * findModuleByName(),
138 * findModuleByNamespace(),
139 * findModuleByNamespaceAndRevision().
141 In the first case, you need to provide module name as it is defined in the yang source file and module revision date if it specified in the yang source file (if it is not defined, you can just pass a null value). In order to provide the revision date in proper format, you can use a utility class named SimpleDateFormatUtil.
144 Module exampleModule = schemaContext.findModuleByName("example-module", null);
146 Date revisionDate = SimpleDateFormatUtil.getRevisionFormat().parse("2015-09-02");
147 Module exampleModule = schemaContext.findModuleByName("example-module", revisionDate);
149 In the second case, you have to provide module namespace in form of an URI object.
151 Module exampleModule = schema.findModuleByNamespace(new URI("opendaylight.org/example-module"));
153 In the third case, you provide both module namespace and revision date as arguments.
155 Once you have a Module object, you can access its contents as they are defined in YANG Model API.
156 One way to do this is to use method like getIdentities() or getRpcs() which will give you a Set of objects. Otherwise you can access a DataSchemaNode directly via the method getDataChildByName() which takes a QName object as its only argument. Here are a few examples.
160 Set<AugmentationSchema> augmentationSchemas = exampleModule.getAugmentations();
161 Set<ModuleImport> moduleImports = exampleModule.getImports();
163 ChoiceSchemaNode choiceSchemaNode = (ChoiceSchemaNode) exampleModule.getDataChildByName(QName.create(exampleModule.getQNameModule(), "example-choice"));
165 ContainerSchemaNode containerSchemaNode = (ContainerSchemaNode) exampleModule.getDataChildByName(QName.create(exampleModule.getQNameModule(), "example-container"));
168 The YANG statement parser can work in three modes:
171 * mode with active resolution of if-feature statements
172 * mode with active semantic version processing
174 The default mode is active when you initialize the parsing cycle as usual by calling the method newBuild() without passing any arguments to it. The second and third mode can be activated by invoking the newBuild() with a special argument. You can either activate just one of them or both by passing proper arguments. Let us explain how these modes work.
176 Mode with active resolution of if-features makes yang statements containing an if-feature statement conditional based on the supported features. These features are provided in the form of a QName-based java.util.function.Predicate object. In the example below, only two features are supported: example-feature-1 and example-feature-2. The Predicate which contains this information is passed to the method newBuild() and the mode is activated.
180 Predicate<QName> isFeatureSupported = qName -> {
181 Set<QName> supportedFeatures = new HashSet<>();
182 supportedFeatures.add(QName.create("example-namespace", "2016-08-31", "example-feature-1"));
183 supportedFeatures.add(QName.create("example-namespace", "2016-08-31", "example-feature-2"));
184 return supportedFeatures.contains(qName);
187 CrossSourceStatementReactor.BuildAction reactor = YangInferencePipeline.RFC6020_REACTOR.newBuild(isFeatureSupported);
190 In case when no features should be supported, you should provide a Predicate<QName> object whose test() method just returns false.
194 Predicate<QName> isFeatureSupported = qName -> false;
196 CrossSourceStatementReactor.BuildAction reactor = YangInferencePipeline.RFC6020_REACTOR.newBuild(isFeatureSupported);
199 When this mode is not activated, all features in the processed YANG sources are supported.
201 Mode with active semantic version processing changes the way how YANG import statements work - each module import is processed based on the specified semantic version statement and the revision-date statement is ignored. In order to activate this mode, you have to provide StatementParserMode.SEMVER_MODE enum constant as argument to the method newBuild().
205 CrossSourceStatementReactor.BuildAction reactor = YangInferencePipeline.RFC6020_REACTOR.newBuild(StatementParserMode.SEMVER_MODE);
208 Before you use a semantic version statement in a YANG module, you need to define an extension for it so that the YANG statement parser can recognize it.
212 module semantic-version {
213 namespace "urn:opendaylight:yang:extension:semantic-version";
217 revision 2016-02-02 {
218 description "Initial version";
220 sv:semantic-version "0.0.1";
222 extension semantic-version {
223 argument "semantic-version" {
228 In the example above, you see a YANG module which defines semantic version as an extension. This extension can be imported to other modules in which we want to utilize the semantic versioning concept.
230 Below is a simple example of the semantic versioning usage. With semantic version processing mode being active, the foo module imports the bar module based on its semantic version. Notice how both modules import the module with the semantic-version extension.
239 import semantic-version { prefix sv; revision-date 2016-02-02; sv:semantic-version "0.0.1"; }
240 import bar { prefix bar; sv:semantic-version "0.1.2";}
242 revision "2016-02-01" {
243 description "Initial version";
245 sv:semantic-version "0.1.1";
258 import semantic-version { prefix sv; revision-date 2016-02-02; sv:semantic-version "0.0.1"; }
260 revision "2016-01-01" {
261 description "Initial version";
263 sv:semantic-version "0.1.2";
269 === Working with YANG Data
270 If you want to work with YANG Data you are going to need NormalizedNode objects that are specified in the YANG Data API. NormalizedNode is an interface at the top of the YANG Data hierarchy. It is extended through sub-interfaces which define the behaviour of specific NormalizedNode types like AnyXmlNode, ChoiceNode, LeafNode, ContainerNode, etc. Concrete implemenations of these interfaces are defined in yang-data-impl module. Once you have one or more NormalizedNode instances, you can perform CRUD operations on YANG data tree which is an in-memory database designed to store normalized nodes in a tree-like structure.
272 In some cases it is clear which NormalizedNode type belongs to which yang statement (e.g. AnyXmlNode, ChoiceNode, LeafNode). However, there are some normalized nodes which are named differently from their yang counterparts. They are listed below:
274 * LeafSetNode - leaf-list
275 * OrderedLeafSetNode - leaf-list that is ordered-by user
276 * LeafSetEntryNode - concrete entry in a leaf-list
277 * MapNode - keyed list
278 * OrderedMapNode - keyed list that is ordered-by user
279 * MapEntryNode - concrete entry in a keyed list
280 * UnkeyedListNode - unkeyed list
281 * UnkeyedListEntryNode - concrete entry in an unkeyed list
283 In order to create a concrete NormalizedNode object you can use the utility class Builders or ImmutableNodes. These classes can be found in yang-data-impl module and they provide methods for building each type of normalized node. Here is a simple example of building a normalized node:
288 ContainerNode containerNode = Builders.containerBuilder().withNodeIdentifier(new YangInstanceIdentifier.NodeIdentifier(QName.create(moduleQName, "example-container")).build();
291 ContainerNode containerNode2 = Builders.containerBuilder(containerSchemaNode).build();
293 Both examples produce the same result. NodeIdentifier is one of the four types of YangInstanceIdentifier (these types are described in the javadoc of YangInstanceIdentifier). The purpose of YangInstanceIdentifier is to uniquely identify a particular node in the data tree. In the first example, you have to add NodeIdentifier before building the resulting node. In the second example it is also added using the provided ContainerSchemaNode object.
295 ImmutableNodes class offers similar builder methods and also adds an overloaded method called fromInstanceId() which allows you to create a NormalizedNode object based on YangInstanceIdentifier and SchemaContext. Below is an example which shows the use of this method.
299 YangInstanceIdentifier.NodeIdentifier contId = new YangInstanceIdentifier.NodeIdentifier(QName.create(moduleQName, "example-container");
301 NormalizedNode<?, ?> contNode = ImmutableNodes.fromInstanceId(schemaContext, YangInstanceIdentifier.create(contId));
304 Let us show a more complex example of creating a NormalizedNode. First, consider the following YANG module:
308 module example-module {
309 namespace "opendaylight.org/example-module";
312 container parent-container {
313 container child-container {
314 list parent-ordered-list {
317 key "parent-key-leaf";
319 leaf parent-key-leaf {
323 leaf parent-ordinary-leaf {
327 list child-ordered-list {
330 key "child-key-leaf";
332 leaf child-key-leaf {
336 leaf child-ordinary-leaf {
346 In the following example, two normalized nodes based on the module above are written to and read from the data tree.
350 TipProducingDataTree inMemoryDataTree = InMemoryDataTreeFactory.getInstance().create(TreeType.OPERATIONAL);
351 inMemoryDataTree.setSchemaContext(schemaContext);
353 // first data tree modification
354 MapEntryNode parentOrderedListEntryNode = Builders.mapEntryBuilder().withNodeIdentifier(
355 new YangInstanceIdentifier.NodeIdentifierWithPredicates(
356 parentOrderedListQName, parentKeyLeafQName, "pkval1"))
357 .withChild(Builders.leafBuilder().withNodeIdentifier(
358 new YangInstanceIdentifier.NodeIdentifier(parentOrdinaryLeafQName))
359 .withValue("plfval1").build()).build();
361 OrderedMapNode parentOrderedListNode = Builders.orderedMapBuilder().withNodeIdentifier(
362 new YangInstanceIdentifier.NodeIdentifier(parentOrderedListQName))
363 .withChild(parentOrderedListEntryNode).build();
365 ContainerNode parentContainerNode = Builders.containerBuilder().withNodeIdentifier(
366 new YangInstanceIdentifier.NodeIdentifier(parentContainerQName))
367 .withChild(Builders.containerBuilder().withNodeIdentifier(
368 new NodeIdentifier(childContainerQName)).withChild(parentOrderedListNode).build()).build();
370 YangInstanceIdentifier path1 = YangInstanceIdentifier.of(parentContainerQName);
372 DataTreeModification treeModification = inMemoryDataTree.takeSnapshot().newModification();
373 treeModification.write(path1, parentContainerNode);
375 // second data tree modification
376 MapEntryNode childOrderedListEntryNode = Builders.mapEntryBuilder().withNodeIdentifier(
377 new YangInstanceIdentifier.NodeIdentifierWithPredicates(
378 childOrderedListQName, childKeyLeafQName, "chkval1"))
379 .withChild(Builders.leafBuilder().withNodeIdentifier(
380 new YangInstanceIdentifier.NodeIdentifier(childOrdinaryLeafQName))
381 .withValue("chlfval1").build()).build();
383 OrderedMapNode childOrderedListNode = Builders.orderedMapBuilder().withNodeIdentifier(
384 new YangInstanceIdentifier.NodeIdentifier(childOrderedListQName))
385 .withChild(childOrderedListEntryNode).build();
387 ImmutableMap.Builder<QName, Object> builder = ImmutableMap.builder();
388 ImmutableMap<QName, Object> keys = builder.put(parentKeyLeafQName, "pkval1").build();
390 YangInstanceIdentifier path2 = YangInstanceIdentifier.of(parentContainerQName).node(childContainerQName)
391 .node(parentOrderedListQName).node(new NodeIdentifierWithPredicates(parentOrderedListQName, keys)).node(childOrderedListQName);
393 treeModification.write(path2, childOrderedListNode);
394 treeModification.ready();
395 inMemoryDataTree.validate(treeModification);
396 inMemoryDataTree.commit(inMemoryDataTree.prepare(treeModification));
398 DataTreeSnapshot snapshotAfterCommits = inMemoryDataTree.takeSnapshot();
399 Optional<NormalizedNode<?, ?>> readNode = snapshotAfterCommits.readNode(path1);
400 Optional<NormalizedNode<?, ?>> readNode2 = snapshotAfterCommits.readNode(path2);
402 First comes the creation of in-memory data tree instance. The schema context (containing the model mentioned above) of this tree is set. After that, two normalized nodes are built. The first one consists of a parent container, a child container and a parent ordered list which contains a key leaf and an ordinary leaf. The second normalized node is a child ordered list that also contains a key leaf and an ordinary leaf.
404 In order to add a child node to a node, method withChild() is used. It takes a NormalizedNode as argument. When creating a list entry, YangInstanceIdentifier.NodeIdentifierWithPredicates should be used as its identifier. Its arguments are the QName of the list, QName of the list key and the value of the key. Method withValue() specifies a value for the ordinary leaf in the list.
406 Before writing a node to the data tree, a path (YangInstanceIdentifier) which determines its place in the data tree needs to be defined. The path of the first normalized node starts at the parent container. The path of the second normalized node points to the child ordered list contained in the parent ordered list entry specified by the key value "pkval1".
408 Write operation is performed with both normalized nodes mentioned earlier. It consist of several steps. The first step is to instantiate a DataTreeModification object based on a DataTreeSnapshot. DataTreeSnapshot gives you the current state of the data tree. Then comes the write operation which writes a normalized node at the provided path in the data tree. After doing both write operations, method ready() has to be called, marking the modification as ready for application to the data tree. No further operations within the modification are allowed. The modification is then validated - checked whether it can be applied to the data tree. Finally we commit it to the data tree.
410 Now you can access the written nodes. In order to do this, you have to create a new DataTreeSnapshot instance and call the method readNode() with path argument pointing to a particular node in the tree.
412 === Serialization / deserialization of YANG Data
413 If you want to deserialize YANG-modeled data which have the form of an XML document, you can use the XML parser found in the module yang-data-codec-xml. The parser walks through the XML document containing YANG-modeled data based on the provided SchemaContext and emits node events into a NormalizedNodeStreamWriter. The parser disallows multiple instances of the same element except for leaf-list and list entries. The parser also expects that the YANG-modeled data in the XML source are wrapped in a root element. Otherwise it will not work correctly.
415 Here is an example of using the XML parser.
418 InputStream resourceAsStream = ExampleClass.class.getResourceAsStream("/example-module.yang");
420 XMLInputFactory factory = XMLInputFactory.newInstance();
421 XMLStreamReader reader = factory.createXMLStreamReader(resourceAsStream);
423 NormalizedNodeResult result = new NormalizedNodeResult();
424 NormalizedNodeStreamWriter streamWriter = ImmutableNormalizedNodeStreamWriter.from(result);
426 XmlParserStream xmlParser = XmlParserStream.create(streamWriter, schemaContext);
427 xmlParser.parse(reader);
429 NormalizedNode<?, ?> transformedInput = result.getResult();
431 The XML parser utilizes the javax.xml.stream.XMLStreamReader for parsing an XML document. First, you should create an instance of this reader using XMLInputFactory and then load an XML document (in the form of InputStream object) into it.
433 In order to emit node events while parsing the data you need to instantiate a NormalizedNodeStreamWriter. This writer is actually an interface and therefore you need to use a concrete implementation of it. In this example it is the ImmutableNormalizedNodeStreamWriter, which constructs immutable instances of NormalizedNodes.
435 There are two ways how to create an instance of this writer using the static overloaded method from(). One version of this method takes a NormalizedNodeResult as argument. This object type is a result holder in which the resulting NormalizedNode will be stored. The other version takes a
436 NormalizedNodeContainerBuilder as argument. All created nodes will be written to this builder.
438 Next step is to create an instance of the XML parser. The parser itself is represented by a class named XmlParserStream. You can use one of two versions of the static overloaded method create() to construct this object. One version accepts a NormalizedNodeStreamWriter and a SchemaContext as arguments, the other version takes the same arguments plus a SchemaNode. Node events are emitted to the writer. The SchemaContext is used to check if the YANG data in the XML source comply with the provided YANG model(s). The last argument, a SchemaNode object, describes the node that is the parent of nodes defined in the XML data. If you do not provide this argument, the parser sets the SchemaContext as the parent node.
440 The parser is now ready to walk through the XML. Parsing is initiated by calling the method parse() on the XmlParserStream object with XMLStreamReader as its argument.
442 Finally you can access the result of parsing - a tree of NormalizedNodes containg the data as they are defined in the parsed XML document - by calling the method getResult() on the NormalizedNodeResult object.
444 === Introducing schema source repositories
446 === Writing YANG driven generators
448 === Introducing specific extension support for YANG parser