Here you can find answers to some of the most frequently asked questions about YANG that do not seem appropriate for inclusion in the standards documents. If you have a question not answered on this page or in the WG documents, you can ask it on YANG doctors maillist (yang-doctors@…) or on the NETMOD mailing list (netmod@…).
First check if your question is not answered by RFC6020 on “YANG - A Data Modeling Language for the Network Configuration Protocol (NETCONF)” or RFC7950 (YANG 1.1).
If your answer is not in RFC6020 or in RFC6020bis document please review following information:
Additional sources interesting to look at are:
Additional pages in the Internet with information on YANG and its usage are:
After searching the sources above, if you still have questions please write an email to yang-doctors@ietf.org and describe your question with some examples.
YIN is an alternative, equivalent XML syntax for YANG. A YANG module can be translated into YIN syntax without losing any information. The YIN module can then be manipulated by standard XML tools such as XSLT scripts. This can be a convenient way to for example extract documentation strings from a module. If necessary, the transformed YIN module can be translated back into YANG syntax, again without information loss.
It was a design decision to keep things simple. (Balazs)
XML attributes are best used for conveying metadata. YANG was initially only interested in modeling data, and hence left support for metadata out. RFC 7952 adds to YANG an ability to model metadata, which is encoded as XML attributes. (Kent)
xs:list in XSD is a simple type, which can be assigned to elements. For example, if such a list for an element "mibs" contains the values "rmon", "alarm", and "rmon2", it would be encoded in XML as:
<mibs > rmon alarm rmon2 </ mibs >
The problem with this is that XPath expressions cannot be used to check individual elements of the list. This is a problem both in must expressions in the YANG modules themselves, and also when tools like XSLT are used to manipulate NETCONF data.
To illustrate this problem, suppose the element "foo" above contains "alarm" and "rmon2":
< mibs > alarm rmon2< /mibs >
If we write an XPath expression which checks if "rmon" is present:
substring ( mibs, "rmon")
this XPath expression returns true.
This is a well-known problem with xs:list in XML in general, and usually it is recommended to use markup instead.
In YANG, there is a separate keyword leaf-list which is used instead.
YANG supports reusable groupings. Everything that can be done with a complex type, and more, can be done with groupings.
Balazs: not fully true
The alternative here would be to drop leaf-list, and just have leaf, but with instance qualifiers. We believe there is a value in giving different names to different concepts. In this case, the two concepts are simple values and arrays of values.
YANG supports min-elements and max-elements, which give more control than ?, +, and *.
There are two situations when type empty is useful.
The first is instead of type boolean, when the default value is =false=:
leaf foo {
type boolean;
default false;
}
leaf foo {
type empty;
}
It is mainly a matter of taste which type to use in this case.
The second situation is when you want to define an extensible enumeration, as an alternative to the type "enumeration", which is not extensible by other modules. For example if an enumeration is used:
type enumeration {
enum smtp;
enum pop3;
}
}
and we want to add a new protocol 'imap4', it must be done by adding a new enum in the module. But if we use a choice of type empty instead:
container protocol {
choice p {
case smtp { leaf smtp { type empty; } }
case pop3 { leaf pop3 { type empty; } }
}
}
then another module can augment the first:
augment /foo:protocol/p {
case imap4 { leaf imap4 { type empty; } }
}
It means that the default is the value the agent will use to create it. It's not like a config knob, where there might be other choices besides this one. This is extra machine-readable text that says that a state or statistic object has an initial value.
Consider this example:
leaf backupFanSpeed {
type enumeration {
enum off;
enum low;
enum medium;
enum high;
}
config false;
default off;
}
You can only monitor the backup fan speed in this example. The backup fan starts out in the 'off' mode, and does not turn on unless needed. Just like zero-based-counter64, it is good for the manager to know the initial value of a non-config object.
A YANG module can have multiple top-level nodes. If data described by such a model is mapped to XML, there will be multiple XML elements. However, the data described in a model is never mapped to root XML elements. The root XML element is always one of <rpc>
, <rpc-reply>
, or <notification>
. The data described by YANG models end up inside the <data>
or <config>
elements.
Note that the same thing happens if the data store is described by more than one YANG module, even if each YANG module has a single top-level node.
From a pure YANG perspective, if-features are better than deviations. Features should be used when you define "conformance profiles" at model design time. Deviations are used by specific implementations when they fail to implement a specific conformance profile.
ietf-yang-types and iana-if-types are common models used by both the client and server. Should a server advertise and export these models?
With YANG 1.1, the ietf-yang-library handles this case, by requiring a server to list these modules with conformance type 'import'.
With YANG 1, these modules can safely be advertised since they have typedefs only.
It would be useful to have standard "guidelines" (and rationale) for keeping some or all of them in one module or not. Let's not allow various protocols to deviate lacking proper justification.
At this time, no guideline can be provided. Discussions are ongoing regarding how to best model intended configuration, applied configuration, and derived state. For example, please see https://mailarchive.ietf.org/arch/msg/netmod/Dlvg3uyE65FXXp16PvForJKDmyM.
Eventually, the final solution will be published as a draft and additional guidelines may be added to 6087bis. There should be a guideline (a starting point, at least) to keep them in one container or 2 different containers or 3 different containers with rationale. It is not a good idea to leave it open to the yang designers for various protocols/working groups.
It is impossible to set any hard and fast rules, each case should be considered separately. In general, each YANG module should correspond to an identifiable functional block of the device or technology for which the module is being written.
Update rules for YANG modules (see section 11 in draft-ietf-netmod-rfc6020bis are an important factor that should be taken into account. Once a YANG module is published in an RFC, only backward-compatible changes are permitted – other changes require a new module to be started. With a finer granularity of modules, such a change is likely to have less impact on other modules and implementations.
It would be useful provide a guideline (perhaps, with a mandate in this case) to always include the diagram for tree structure with more specifics as shown below:
Module: _foo_organization
Config (intended)
State (derived with or without applied)
Notification
RPC
...
Yes.
Per RFC 7950, module-stmt includes body-stmts, which includes data-def-stmt, which includes leaf-stmt. (Kent)
Yes, section 5.3 in draft-ietf-netmod-rfc6087bis specifies the rules for YANG identifiers. In short: use only lowercase letters, and separate words with a hyphen, e.g., routing-protocol
. Any camel-type names, such as routingProtocol
, should be avoided.
There is no direct support in YANG for doing this. One rather hackish way is to add a dummy if-feature statement to the “unwanted” data nodes by means of the refine statement, and make sure this feature isn't advertised.
When designing groupings, it is therefore advisable to make them reasonably granular so as to allow reusing selected parts in different situations.
A server informs the client that it does not support a particular RPC statement by announcing a deviation for the RPC. See https://tools.ietf.org/html/rfc7950#section-7.20.3. In addition, the server should return a <rpc-error>
with the message 'operation-not-supported' if a client tries to use RPC.
The content of this page was last updated on 2017-08-16. It was migrated from the old Trac wiki on 2022-12-20.