tech-invite   World Map     

IETF     RFCs     Groups     SIP     ABNFs    |    3GPP     Specs     Glossaries     Architecture     IMS     UICC    |    search     info

RFC 6020

 Errata 
Proposed STD
Pages: 173
Top     in Index     Prev     Next
in Group Index     No Prev: Lowest Number in Group     Next in Group     Group: NETMOD

YANG - A Data Modeling Language for the Network Configuration Protocol (NETCONF)

Part 1 of 7, p. 1 to 11
None       Next RFC Part

 


Top       ToC       Page 1 
Internet Engineering Task Force (IETF)                 M. Bjorklund, Ed.
Request for Comments: 6020                                Tail-f Systems
Category: Standards Track                                   October 2010
ISSN: 2070-1721


                  YANG - A Data Modeling Language for
              the Network Configuration Protocol (NETCONF)

Abstract

   YANG is a data modeling language used to model configuration and
   state data manipulated by the Network Configuration Protocol
   (NETCONF), NETCONF remote procedure calls, and NETCONF notifications.

Status of This Memo

   This is an Internet Standards Track document.

   This document is a product of the Internet Engineering Task Force
   (IETF).  It represents the consensus of the IETF community.  It has
   received public review and has been approved for publication by the
   Internet Engineering Steering Group (IESG).  Further information on
   Internet Standards is available in Section 2 of RFC 5741.

   Information about the current status of this document, any errata,
   and how to provide feedback on it may be obtained at
   http://www.rfc-editor.org/info/rfc6020.

Copyright Notice

   Copyright (c) 2010 IETF Trust and the persons identified as the
   document authors.  All rights reserved.

   This document is subject to BCP 78 and the IETF Trust's Legal
   Provisions Relating to IETF Documents
   (http://trustee.ietf.org/license-info) in effect on the date of
   publication of this document.  Please review these documents
   carefully, as they describe your rights and restrictions with respect
   to this document.  Code Components extracted from this document must
   include Simplified BSD License text as described in Section 4.e of
   the Trust Legal Provisions and are provided without warranty as
   described in the Simplified BSD License.

Page 2 
   This document may contain material from IETF Documents or IETF
   Contributions published or made publicly available before November
   10, 2008.  The person(s) controlling the copyright in some of this
   material may not have granted the IETF Trust the right to allow
   modifications of such material outside the IETF Standards Process.
   Without obtaining an adequate license from the person(s) controlling
   the copyright in such materials, this document may not be modified
   outside the IETF Standards Process, and derivative works of it may
   not be created outside the IETF Standards Process, except to format
   it for publication as an RFC or to translate it into languages other
   than English.

Table of Contents

   1. Introduction ....................................................8
   2. Keywords ........................................................8
   3. Terminology .....................................................8
      3.1. Mandatory Nodes ...........................................10
   4. YANG Overview ..................................................11
      4.1. Functional Overview .......................................11
      4.2. Language Overview .........................................13
           4.2.1. Modules and Submodules .............................13
           4.2.2. Data Modeling Basics ...............................13
           4.2.3. State Data .........................................18
           4.2.4. Built-In Types .....................................18
           4.2.5. Derived Types (typedef) ............................19
           4.2.6. Reusable Node Groups (grouping) ....................20
           4.2.7. Choices ............................................21
           4.2.8. Extending Data Models (augment) ....................22
           4.2.9. RPC Definitions ....................................23
           4.2.10. Notification Definitions ..........................24
   5. Language Concepts ..............................................25
      5.1. Modules and Submodules ....................................25
           5.1.1. Import and Include by Revision .....................26
           5.1.2. Module Hierarchies .................................27
      5.2. File Layout ...............................................28
      5.3. XML Namespaces ............................................29
           5.3.1. YANG XML Namespace .................................29
      5.4. Resolving Grouping, Type, and Identity Names ..............29
      5.5. Nested Typedefs and Groupings .............................29
      5.6. Conformance ...............................................30
           5.6.1. Basic Behavior .....................................31
           5.6.2. Optional Features ..................................31
           5.6.3. Deviations .........................................31
           5.6.4. Announcing Conformance Information in the
                  <hello> Message ....................................32
      5.7. Data Store Modification ...................................34
   6. YANG Syntax ....................................................34

Top      ToC       Page 3 
      6.1. Lexical Tokenization ......................................34
           6.1.1. Comments ...........................................34
           6.1.2. Tokens .............................................34
           6.1.3. Quoting ............................................35
      6.2. Identifiers ...............................................36
           6.2.1. Identifiers and Their Namespaces ...................36
      6.3. Statements ................................................37
           6.3.1. Language Extensions ................................37
      6.4. XPath Evaluations .........................................38
           6.4.1. XPath Context ......................................38
      6.5. Schema Node Identifier ....................................39
   7. YANG Statements ................................................39
      7.1. The module Statement ......................................39
           7.1.1. The module's Substatements .........................41
           7.1.2. The yang-version Statement .........................41
           7.1.3. The namespace Statement ............................42
           7.1.4. The prefix Statement ...............................42
           7.1.5. The import Statement ...............................42
           7.1.6. The include Statement ..............................43
           7.1.7. The organization Statement .........................44
           7.1.8. The contact Statement ..............................44
           7.1.9. The revision Statement .............................44
           7.1.10. Usage Example .....................................45
      7.2. The submodule Statement ...................................46
           7.2.1. The submodule's Substatements ......................48
           7.2.2. The belongs-to Statement ...........................48
           7.2.3. Usage Example ......................................49
      7.3. The typedef Statement .....................................49
           7.3.1. The typedef's Substatements ........................50
           7.3.2. The typedef's type Statement .......................50
           7.3.3. The units Statement ................................50
           7.3.4. The typedef's default Statement ....................50
           7.3.5. Usage Example ......................................51
      7.4. The type Statement ........................................51
           7.4.1. The type's Substatements ...........................51
      7.5. The container Statement ...................................51
           7.5.1. Containers with Presence ...........................52
           7.5.2. The container's Substatements ......................53
           7.5.3. The must Statement .................................53
           7.5.4. The must's Substatements ...........................55
           7.5.5. The presence Statement .............................56
           7.5.6. The container's Child Node Statements ..............56
           7.5.7. XML Mapping Rules ..................................56
           7.5.8. NETCONF <edit-config> Operations ...................56
           7.5.9. Usage Example ......................................57
      7.6. The leaf Statement ........................................58
           7.6.1. The leaf's default value ...........................58
           7.6.2. The leaf's Substatements ...........................59

Top      ToC       Page 4 
           7.6.3. The leaf's type Statement ..........................59
           7.6.4. The leaf's default Statement .......................59
           7.6.5. The leaf's mandatory Statement .....................60
           7.6.6. XML Mapping Rules ..................................60
           7.6.7. NETCONF <edit-config> Operations ...................60
           7.6.8. Usage Example ......................................61
      7.7. The leaf-list Statement ...................................62
           7.7.1. Ordering ...........................................62
           7.7.2. The leaf-list's Substatements ......................63
           7.7.3. The min-elements Statement .........................63
           7.7.4. The max-elements Statement .........................63
           7.7.5. The ordered-by Statement ...........................64
           7.7.6. XML Mapping Rules ..................................64
           7.7.7. NETCONF <edit-config> Operations ...................65
           7.7.8. Usage Example ......................................66
      7.8. The list Statement ........................................67
           7.8.1. The list's Substatements ...........................68
           7.8.2. The list's key Statement ...........................68
           7.8.3. The list's unique Statement ........................69
           7.8.4. The list's Child Node Statements ...................70
           7.8.5. XML Mapping Rules ..................................70
           7.8.6. NETCONF <edit-config> Operations ...................71
           7.8.7. Usage Example ......................................72
      7.9. The choice Statement ......................................75
           7.9.1. The choice's Substatements .........................76
           7.9.2. The choice's case Statement ........................76
           7.9.3. The choice's default Statement .....................77
           7.9.4. The choice's mandatory Statement ...................79
           7.9.5. XML Mapping Rules ..................................79
           7.9.6. NETCONF <edit-config> Operations ...................79
           7.9.7. Usage Example ......................................79
      7.10. The anyxml Statement .....................................80
           7.10.1. The anyxml's Substatements ........................81
           7.10.2. XML Mapping Rules .................................81
           7.10.3. NETCONF <edit-config> Operations ..................81
           7.10.4. Usage Example .....................................82
      7.11. The grouping Statement ...................................82
           7.11.1. The grouping's Substatements ......................83
           7.11.2. Usage Example .....................................84
      7.12. The uses Statement .......................................84
           7.12.1. The uses's Substatements ..........................85
           7.12.2. The refine Statement ..............................85
           7.12.3. XML Mapping Rules .................................86
           7.12.4. Usage Example .....................................86
      7.13. The rpc Statement ........................................87
           7.13.1. The rpc's Substatements ...........................88
           7.13.2. The input Statement ...............................88
           7.13.3. The output Statement ..............................89

Top      ToC       Page 5 
           7.13.4. XML Mapping Rules .................................90
           7.13.5. Usage Example .....................................91
      7.14. The notification Statement ...............................91
           7.14.1. The notification's Substatements ..................92
           7.14.2. XML Mapping Rules .................................92
           7.14.3. Usage Example .....................................93
      7.15. The augment Statement ....................................93
           7.15.1. The augment's Substatements .......................94
           7.15.2. XML Mapping Rules .................................94
           7.15.3. Usage Example .....................................95
      7.16. The identity Statement ...................................97
           7.16.1. The identity's Substatements ......................97
           7.16.2. The base Statement ................................97
           7.16.3. Usage Example .....................................98
      7.17. The extension Statement ..................................98
           7.17.1. The extension's Substatements .....................99
           7.17.2. The argument Statement ............................99
           7.17.3. Usage Example ....................................100
      7.18. Conformance-Related Statements ..........................100
           7.18.1. The feature Statement ............................100
           7.18.2. The if-feature Statement .........................102
           7.18.3. The deviation Statement ..........................102
      7.19. Common Statements .......................................105
           7.19.1. The config Statement .............................105
           7.19.2. The status Statement .............................105
           7.19.3. The description Statement ........................106
           7.19.4. The reference Statement ..........................106
           7.19.5. The when Statement ...............................107
   8. Constraints ...................................................108
      8.1. Constraints on Data ......................................108
      8.2. Hierarchy of Constraints .................................109
      8.3. Constraint Enforcement Model .............................109
           8.3.1. Payload Parsing ...................................109
           8.3.2. NETCONF <edit-config> Processing ..................110
           8.3.3. Validation ........................................111
   9. Built-In Types ................................................111
      9.1. Canonical Representation .................................112
      9.2. The Integer Built-In Types ...............................112
           9.2.1. Lexical Representation ............................113
           9.2.2. Canonical Form ....................................114
           9.2.3. Restrictions ......................................114
           9.2.4. The range Statement ...............................114
           9.2.5. Usage Example .....................................115
      9.3. The decimal64 Built-In Type ..............................115
           9.3.1. Lexical Representation ............................115
           9.3.2. Canonical Form ....................................115
           9.3.3. Restrictions ......................................116
           9.3.4. The fraction-digits Statement .....................116

Top      ToC       Page 6 
           9.3.5. Usage Example .....................................117
      9.4. The string Built-In Type .................................117
           9.4.1. Lexical Representation ............................117
           9.4.2. Canonical Form ....................................117
           9.4.3. Restrictions ......................................117
           9.4.4. The length Statement ..............................117
           9.4.5. Usage Example .....................................118
           9.4.6. The pattern Statement .............................119
           9.4.7. Usage Example .....................................119
      9.5. The boolean Built-In Type ................................120
           9.5.1. Lexical Representation ............................120
           9.5.2. Canonical Form ....................................120
           9.5.3. Restrictions ......................................120
      9.6. The enumeration Built-In Type ............................120
           9.6.1. Lexical Representation ............................120
           9.6.2. Canonical Form ....................................120
           9.6.3. Restrictions ......................................120
           9.6.4. The enum Statement ................................120
           9.6.5. Usage Example .....................................121
      9.7. The bits Built-In Type ...................................122
           9.7.1. Restrictions ......................................122
           9.7.2. Lexical Representation ............................122
           9.7.3. Canonical Form ....................................122
           9.7.4. The bit Statement .................................122
           9.7.5. Usage Example .....................................123
      9.8. The binary Built-In Type .................................123
           9.8.1. Restrictions ......................................124
           9.8.2. Lexical Representation ............................124
           9.8.3. Canonical Form ....................................124
      9.9. The leafref Built-In Type ................................124
           9.9.1. Restrictions ......................................124
           9.9.2. The path Statement ................................124
           9.9.3. Lexical Representation ............................125
           9.9.4. Canonical Form ....................................125
           9.9.5. Usage Example .....................................126
      9.10. The identityref Built-In Type ...........................129
           9.10.1. Restrictions .....................................129
           9.10.2. The identityref's base Statement .................129
           9.10.3. Lexical Representation ...........................130
           9.10.4. Canonical Form ...................................130
           9.10.5. Usage Example ....................................130
      9.11. The empty Built-In Type .................................131
           9.11.1. Restrictions .....................................131
           9.11.2. Lexical Representation ...........................131
           9.11.3. Canonical Form ...................................131
           9.11.4. Usage Example ....................................131
      9.12. The union Built-In Type .................................132
           9.12.1. Restrictions .....................................132

Top      ToC       Page 7 
           9.12.2. Lexical Representation ...........................132
           9.12.3. Canonical Form ...................................133
      9.13. The instance-identifier Built-In Type ...................133
           9.13.1. Restrictions .....................................134
           9.13.2. The require-instance Statement ...................134
           9.13.3. Lexical Representation ...........................134
           9.13.4. Canonical Form ...................................134
           9.13.5. Usage Example ....................................134
   10. Updating a Module ............................................135
   11. YIN ..........................................................137
      11.1. Formal YIN Definition ...................................137
           11.1.1. Usage Example ....................................141
   12. YANG ABNF Grammar ............................................143
   13. Error Responses for YANG Related Errors ......................165
      13.1. Error Message for Data That Violates a unique
            Statement ...............................................165
      13.2. Error Message for Data That Violates a
            max-elements Statement ..................................165
      13.3. Error Message for Data That Violates a
            min-elements Statement ..................................165
      13.4. Error Message for Data That Violates a must Statement ...166
      13.5. Error Message for Data That Violates a
            require-instance Statement ..............................166
      13.6. Error Message for Data That Does Not Match a
            leafref Type ............................................166
      13.7. Error Message for Data That Violates a mandatory
            choice Statement ........................................166
      13.8. Error Message for the "insert" Operation ................167
   14. IANA Considerations ..........................................167
      14.1. Media type application/yang .............................168
      14.2. Media type application/yin+xml ..........................169
   15. Security Considerations ......................................170
   16. Contributors .................................................171
   17. Acknowledgements .............................................171
   18. References ...................................................171
      18.1. Normative References ....................................171
      18.2. Informative References ..................................172

Top      ToC       Page 8 
1.  Introduction

   YANG is a data modeling language used to model configuration and
   state data manipulated by the Network Configuration Protocol
   (NETCONF), NETCONF remote procedure calls, and NETCONF notifications.
   YANG is used to model the operations and content layers of NETCONF
   (see the NETCONF Configuration Protocol [RFC4741], Section 1.1).

   This document describes the syntax and semantics of the YANG
   language, how the data model defined in a YANG module is represented
   in the Extensible Markup Language (XML), and how NETCONF operations
   are used to manipulate the data.

2.  Keywords

   The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
   "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
   "OPTIONAL" in this document are to be interpreted as described in BCP
   14, [RFC2119].

3.  Terminology

   o  anyxml: A data node that can contain an unknown chunk of XML data.

   o  augment: Adds new schema nodes to a previously defined schema
      node.

   o  base type: The type from which a derived type was derived, which
      may be either a built-in type or another derived type.

   o  built-in type: A YANG data type defined in the YANG language, such
      as uint32 or string.

   o  choice: A schema node where only one of a number of identified
      alternatives is valid.

   o  configuration data: The set of writable data that is required to
      transform a system from its initial default state into its current
      state [RFC4741].

   o  conformance: A measure of how accurately a device follows a data
      model.

   o  container: An interior data node that exists in at most one
      instance in the data tree.  A container has no value, but rather a
      set of child nodes.

Top      ToC       Page 9 
   o  data definition statement: A statement that defines new data
      nodes.  One of container, leaf, leaf-list, list, choice, case,
      augment, uses, and anyxml.

   o  data model: A data model describes how data is represented and
      accessed.

   o  data node: A node in the schema tree that can be instantiated in a
      data tree.  One of container, leaf, leaf-list, list, and anyxml.

   o  data tree: The instantiated tree of configuration and state data
      on a device.

   o  derived type: A type that is derived from a built-in type (such as
      uint32), or another derived type.

   o  device deviation: A failure of the device to implement the module
      faithfully.

   o  extension: An extension attaches non-YANG semantics to statements.
      The extension statement defines new statements to express these
      semantics.

   o  feature: A mechanism for marking a portion of the model as
      optional.  Definitions can be tagged with a feature name and are
      only valid on devices that support that feature.

   o  grouping: A reusable set of schema nodes, which may be used
      locally in the module, in modules that include it, and by other
      modules that import from it.  The grouping statement is not a data
      definition statement and, as such, does not define any nodes in
      the schema tree.

   o  identifier: Used to identify different kinds of YANG items by
      name.

   o  instance identifier: A mechanism for identifying a particular node
      in a data tree.

   o  interior node: Nodes within a hierarchy that are not leaf nodes.

   o  leaf: A data node that exists in at most one instance in the data
      tree.  A leaf has a value but no child nodes.

   o  leaf-list: Like the leaf node but defines a set of uniquely
      identifiable nodes rather than a single node.  Each node has a
      value but no child nodes.

Top      ToC       Page 10 
   o  list: An interior data node that may exist in multiple instances
      in the data tree.  A list has no value, but rather a set of child
      nodes.

   o  module: A YANG module defines a hierarchy of nodes that can be
      used for NETCONF-based operations.  With its definitions and the
      definitions it imports or includes from elsewhere, a module is
      self-contained and "compilable".

   o  RPC: A Remote Procedure Call, as used within the NETCONF protocol.

   o  RPC operation: A specific Remote Procedure Call, as used within
      the NETCONF protocol.  It is also called a protocol operation.

   o  schema node: A node in the schema tree.  One of container, leaf,
      leaf-list, list, choice, case, rpc, input, output, notification,
      and anyxml.

   o  schema node identifier: A mechanism for identifying a particular
      node in the schema tree.

   o  schema tree: The definition hierarchy specified within a module.

   o  state data: The additional data on a system that is not
      configuration data such as read-only status information and
      collected statistics [RFC4741].

   o  submodule: A partial module definition that contributes derived
      types, groupings, data nodes, RPCs, and notifications to a module.
      A YANG module can be constructed from a number of submodules.

   o  top-level data node: A data node where there is no other data node
      between it and a module or submodule statement.

   o  uses: The "uses" statement is used to instantiate the set of
      schema nodes defined in a grouping statement.  The instantiated
      nodes may be refined and augmented to tailor them to any specific
      needs.

3.1.  Mandatory Nodes

   A mandatory node is one of:

   o  A leaf, choice, or anyxml node with a "mandatory" statement with
      the value "true".

   o  A list or leaf-list node with a "min-elements" statement with a
      value greater than zero.

Top      ToC       Page 11 
   o  A container node without a "presence" statement, which has at
      least one mandatory node as a child.



(page 11 continued on part 2)

Next RFC Part