[Search] [pdf|bibtex] [Tracker] [Email] [Nits]

Versions: 00                                                            
Network Working Group                                  M. Bjorklund, Ed.
Internet-Draft                                            Tail-f Systems
Intended status: Informational                         February 18, 2008
Expires: August 21, 2008


    YANG's Compliance with Respect to Various Requirements Documents
                  draft-bjorklund-yang-requirements-00

Status of this Memo

   By submitting this Internet-Draft, each author represents that any
   applicable patent or other IPR claims of which he or she is aware
   have been or will be disclosed, and any of which he or she becomes
   aware will be disclosed, in accordance with Section 6 of BCP 79.

   Internet-Drafts are working documents of the Internet Engineering
   Task Force (IETF), its areas, and its working groups.  Note that
   other groups may also distribute working documents as Internet-
   Drafts.

   Internet-Drafts are draft documents valid for a maximum of six months
   and may be updated, replaced, or obsoleted by other documents at any
   time.  It is inappropriate to use Internet-Drafts as reference
   material or to cite them other than as "work in progress."

   The list of current Internet-Drafts can be accessed at
   http://www.ietf.org/ietf/1id-abstracts.txt.

   The list of Internet-Draft Shadow Directories can be accessed at
   http://www.ietf.org/shadow.html.

   This Internet-Draft will expire on August 21, 2008.

Copyright Notice

   Copyright (C) The IETF Trust (2008).














Bjorklund                Expires August 21, 2008                [Page 1]


Internet-Draft                    YANG                     February 2008


Abstract

   This draft addresses requirements for a NETCONF data modeling
   language and how the YANG Modeling Language proposes to fulfill these
   requirements or specifically chooses not to.  Requirements have been
   gathered from multiple documents and each document's requirements are
   handled in a separate section in this draft.

   This draft also explains some of the design choices behind YANG.


Table of Contents

   1.  Introduction . . . . . . . . . . . . . . . . . . . . . . . . .  3
   2.  The case for YANG  . . . . . . . . . . . . . . . . . . . . . .  4
     2.1.  YANG - Wir koennen nicht anders! . . . . . . . . . . . . .  4
     2.2.  YANG - Solving "the configuration problem" . . . . . . . .  5
   3.  Requirements . . . . . . . . . . . . . . . . . . . . . . . . .  8
     3.1.  Requirements from draft-presuhn-rcdml-01 . . . . . . . . .  8
       3.1.1.  Agreed . . . . . . . . . . . . . . . . . . . . . . . .  8
       3.1.2.  "NOT Agreed" with which YANG complies  . . . . . . . . 19
       3.1.3.  "NOT Agreed" with which YANG does not comply (or
               not determined)  . . . . . . . . . . . . . . . . . . . 21
     3.2.  Requirements from RFC 3139 . . . . . . . . . . . . . . . . 22
     3.3.  Requirements from RFC 3216 . . . . . . . . . . . . . . . . 25
       3.3.1.  Accepted objectives  . . . . . . . . . . . . . . . . . 25
       3.3.2.  Nice-to-have objectives  . . . . . . . . . . . . . . . 30
       3.3.3.  Rejected objectives  . . . . . . . . . . . . . . . . . 31
     3.4.  Requirements from
           draft-linowski-netconf-dml-requirements-00 . . . . . . . . 32
   4.  YANG DHCP Module . . . . . . . . . . . . . . . . . . . . . . . 36
   5.  IANA Considerations  . . . . . . . . . . . . . . . . . . . . . 41
   6.  Security Considerations  . . . . . . . . . . . . . . . . . . . 42
   7.  Contributors . . . . . . . . . . . . . . . . . . . . . . . . . 43
   8.  References . . . . . . . . . . . . . . . . . . . . . . . . . . 44
     8.1.  Normative References . . . . . . . . . . . . . . . . . . . 44
     8.2.  Non-Normative References . . . . . . . . . . . . . . . . . 44
   Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 45
   Intellectual Property and Copyright Statements . . . . . . . . . . 46












Bjorklund                Expires August 21, 2008                [Page 2]


Internet-Draft                    YANG                     February 2008


1.  Introduction

   This draft details YANG's [YANG] compliance with respect to a list of
   requirements for a data modeling language for NETCONF.  The
   requirements have been put together from multiple documents that
   represent the IETF's current collected understanding of what a data
   modeling language for NETCONF must be able to do.












































Bjorklund                Expires August 21, 2008                [Page 3]


Internet-Draft                    YANG                     February 2008


2.  The case for YANG

   On the last day of the 68th IETF in Prague, a small band of NETCONF
   veterans assembled over breakfast and talked about the need for a
   simple modeling language for NETCONF.  This was an area where NETCONF
   was failing to make forward progress, putting the future of NETCONF
   at risk.  We compared our experience implementing in-house tools for
   our proprietary NETCONF engines and found that we had all reached
   similar solutions to the problem.  The areas of overlap and
   similarities were immense, and we began work on a proposal that built
   on our experiences, picking the "best of breed" feature from our
   existing solutions, and tailoring them into a consistent language
   that is as powerful as it is simple.

   This document, together with the [YANG] specification, explain the
   needs and benefits of this "second generation" data modeling
   language.

2.1.  YANG - Wir koennen nicht anders!

   YANG is designed specifically for use with NETCONF.  While it might
   be useful for data modeling in other contexts, that is not the focus
   of this work.  Our perception is that there is a very serious problem
   to be solved: we have a protocol ([RFC4741]) for configuration, but
   we have no standardized way to define the models for that which we
   are going to configure, much less models themselves.  Without timely
   forward progress in this area, NETCONF cannot service the needs of
   the network management community, and will quickly move lose what
   momentum remains.  YANG aims to fill that gap by providing NETCONF
   what the SMI ([RFC2578]) gives the SNMP-based framework.

   YANG has a strong heritage.  YANG is based on languages used actively
   for development of NETCONF-based management systems in products
   today.  As such, the design of YANG is based heavily on requirements
   placed upon those languages by their users and the experience of
   writing NETCONF data models in the vendor-specific languages from
   which much of YANG was derived.  Real world usage is the best way to
   understand requirements and YANG takes advantage of years of real
   world usage from these internal tools, building on their requirements
   and their solutions to complex issues in data modeling.

   YANG is designed to give priority to data model readers.  The readers
   and reviewers of data models need insight into the organization,
   constraints, and meaning of its elements.  The reader of a YANG
   module can easily see the high-level view of the data model while
   seeing how the object will be encoded in NETCONF operations.  While
   YANG models the data content, the XML rendering of this content is
   very apparent.



Bjorklund                Expires August 21, 2008                [Page 4]


Internet-Draft                    YANG                     February 2008


   YANG has a history that demonstrates the need for a new language.
   During previous proprietary implementations that were input to YANG,
   developers realized that models written in existing languages
   (specifically XSD, RelaxNG) were very difficult both to read and
   write, so the languages were based on something "home grown" designed
   for the developers who would be writing models and implementing them
   on devices.  Given that experience, YANG's syntax was chosen
   specifically for its readability, since YANG values the time and
   effort of the readers of models above those of modules writers and
   YANG tool-chain developers.  Above all, the users of NETCONF models
   (operators) were given highest priority in YANG's design.

2.2.  YANG - Solving "the configuration problem"

   NETCONF and YANG are all about solving "the configuration problem", a
   problem that is not simple.  The history of network management (and
   configuration management in particular) over the last 20 years
   clearly demonstrates the industry's failure to provide interoperable,
   multi-vendor configuration tools.  It is instructive to understand
   some of the factors that make configuration a difficult problem, as
   the modeling language for NETCONF should do all that it can to
   alleviate these difficulties.

   In designing configuration for a complex device, you have a number of
   goals:

   o  Avoid human error: design the configuration to make errors
      detectable in software, and observable in "show" output.

   o  Avoid misunderstanding: If the syntax/semantics of the modeling
      language is not simple enough, operators/readers will definitely
      make mistakes during configuration.  If its complicated it is
      unusable even if it works.

   o  Be flexible: customer deployment scenarios always exceed your
      vision when you design something.  Allowing for these cases is
      both important and painful.

   o  Complexity reduction: if it's complex to configure, it won't get
      deployed.  And even if it does get deployed, the support costs for
      both the customer and the vendor will be high.

   o  Details should be hidden where possible: the user shouldn't need
      to fully understand hardware, software, or protocol issues to
      configure them.

   o  Enhancement/future proofing: this configuration needs to work on
      next year's hardware running next year's software, often running



Bjorklund                Expires August 21, 2008                [Page 5]


Internet-Draft                    YANG                     February 2008


      next year's protocols.

   o  Full feature support: the configuration needs to fully represent
      the available features your hardware and software support.

   o  Be consistent: make it fit inside the rules and conventions of
      your existing syntax.

   o  Holistic view: the configuration should look like a single
      description of a complete system.

   o  Easy to learn: If its complicated, people never learn it.

   In striving for simplification, many of these goals are in conflict
   with one other.  For example, in trying to be flexible, one must
   decide when an odd configuration is an error and when the user is
   just doing something clever (which may be an error, but is an
   intentional one).

   In standardization, the goals are often completely different.
   Expressiveness and accuracy win over simplicity.  A single complex
   method of configuration wins over a dual "common" and "advanced"
   approach.  The model for a standard must be something that can
   support all platforms, which leads to complexity, and the translation
   between the standard's complex model and the unique abilities of
   individual platforms is non-trivial.

   An example is packet filtering, where the device configuration is
   more often dictated by the hardware architecture and the layout of
   that hardware (in terms of where packets can be filtered, what can be
   filtered on, what can be done to them at that layer, and what
   resources are consumed) is often directly visible in the
   configuration in order for the customer to express their desired
   setup.

   A standard, on the other hand, needs a model that is "bigger" than
   one vendor's solution, where any sort of filtering can be done at any
   place with any outcome without concern for resource impact.  No
   vendor will implement such a model, and the translation between the
   model and the device configuration requires understanding the
   performance versus resource utilization tradeoffs that the customer
   is willing to make.

   For example, some functionality may be available in hardware at wire
   rate, other in hardware at lower speed, other in dedicated CPUs, and
   still other in the main CPU.  Choosing the proper filtering point is
   a matter of both the speed and abilities of that point, plus chip
   memory and other contention issues.  And getting a correct assignment



Bjorklund                Expires August 21, 2008                [Page 6]


Internet-Draft                    YANG                     February 2008


   will still be wrong if it's not the assignment the customer wanted.

   This translation must be performed in a way that avoids letting small
   changes in the configuration turn into large configuration changes on
   the device.  This is not an easy problem, but is key to device-
   independent configuration.

   The problem isn't getting a few knobs to configure basic
   functionality, but getting a solution that's complete enough to give
   folks sufficient faith to move toward it.  If it solved 20% of the
   problem, it's worthless.  When it solves 80-90% of the problem, it's
   interesting.

   NETCONF gives us the ability to manipulate configuration in XML,
   which is a good first step.  With YANG, we now have the ability to
   define that XML in a way that allows extensibility and the expression
   of device-specific content, which is a good second step.  The next
   step will be a translation framework that allows robust translation
   between a standard view and a device-specific view.
































Bjorklund                Expires August 21, 2008                [Page 7]


Internet-Draft                    YANG                     February 2008


3.  Requirements

   The following sections address requirements from various internet
   drafts and RFCs.  For each document, the requirements are named by
   section and title (if available) or with a short summary of the
   requirement.  For a full explanation of the requirement, see the
   source document.

   For each requirement, we state:

   o  If YANG is compliant

   o  If so, we identify the mechanism in YANG that fulfills the
      requirement

   o  If not, we explain why YANG is not compliant

3.1.  Requirements from draft-presuhn-rcdml-01

   [PRESUHN], "Requirements for a Configuration Data Modeling Language",
   has the following requirements.  They are listed by section number in
   [PRESUHN] and divided into two lists.  The first list is all of the
   requirements that the requirements design team reached rough
   consensus on.  The second list is those where rough consensus was NOT
   reached.  For both of these lists, YANG states its compliance with
   respect to the requirement and provides additional commentary as
   deemed necessary.  The text explaining the requirements themselves
   are not reproduced here.

   RFC 3139 and RFC 3216 Considerations are handled separately.

3.1.1.  Agreed

   YANG complies with all Agreed requirements.

   o  3.1.1.  Notification Definition (Agreed)

   Supported with the "notification" statement.













Bjorklund                Expires August 21, 2008                [Page 8]


Internet-Draft                    YANG                     February 2008


     notification link-failure {
         description "A link failure has been detected";
         leaf if-index {
             type int32 { range "1 .. max"; }
         }
         leaf if-name {
             type keyref {
                 path "/interfaces/interface/name";
             }
         }
     }

   o  3.1.3.  Locking (Agreed)

   YANG does not impose any restrictions for partial locking.

   o  3.1.4.  All Base Operations (Agreed)

   The YANG specification explicitly details how all <edit-config>
   operations work for the data definition statements.

   All YANG data definition statements define either configuration or
   non-configuration data, supporting the <get-config> and <get>
   operations of NETCONF.

   o  3.1.5.  Define new NETCONF Operations (Agreed)

   New NETCONF operations, vendor-specific or standard, are defined with
   the "rpc" statement.  This statement covers input parameters, the
   result and semantics of the operation.

   rpc activate-software-image {
       description "Activate a new software image "
                 + "(upgrade or downgrade)";
       input {
           leaf image-name {
             description "Local file name of the incoming image";
               type string;
           }
       }
       output {
           leaf status {
               description "Status string returned by the new software";
               type string;
           }
       }
   }




Bjorklund                Expires August 21, 2008                [Page 9]


Internet-Draft                    YANG                     February 2008


   Operations defined in YANG can be extended by vendors with extra
   information with the "augment" statement.

     augment /rpc/activate-software-image/input {
         vend1:custom-flag true;
     }

   o  3.1.6.  Separation of Operations and Payload (Agreed)

   The "rpc" statement is clearly separated from the data definition
   statements in YANG.

   The operation name appears as the argument to the "rpc" statement,
   while the input payload appears in the "input" statement.  Output
   payload appears in the "output" statement.

   o  3.1.7.  Error Annotation (Agreed)

   YANG allows the user to define the error-app-tag and the error-
   message NETCONF elements both for common constraints like range and
   for specific constraints defined using the "must" statement.

  leaf cell-count {
      type uint32;
      must "ifType == 'atm'" {
          error-message "'cell-count' is only valid for ATM interfaces";
          error-app-tag invalid-interface-type;
      }
  }

   NETCONF-specific error information (error-message and error-app-tag)
   can be assigned to statements that put syntactic and semantic
   restrictions on the data model.

   o  3.1.8.  No Mixed Content (Agreed)

   YANG does not provide a mechanism to define mixed XML content.

   o  3.2.1.  Human Readable (Agreed)

   The YANG syntax is similar to that of SMIng [RFC3780] and programming
   languages like C and C++.  This C-like syntax was chosen specifically
   for its readability and conciseness, since YANG values the time and
   effort of the readers of models above those of modules writers and
   YANG tool-chain developers.






Bjorklund                Expires August 21, 2008               [Page 10]


Internet-Draft                    YANG                     February 2008


   o  3.2.2.  Machine Readable (Agreed)

   YANG has a few, simple syntactical rules which are easy to parse for
   tools.  YANG also supports an equivalent XML-based syntax called YIN,
   which can be used to feed into standard XML tools such as XSLT
   script.

   All YANG statements are of the following format:

       stmt -> keyword argument? ( ';' | '{' stmt-list '}' )
       stmt-list -> null | stmt-list stmt

   This simple syntax allows the creation of parsers using a trivial
   state machine, rather than needing traditional compiler tools.

   o  3.2.3.  Textual Representation (Agreed)

   YANG models are represented as text.  They can be built in a normal
   editor, sent via email, saved in cvs or svn repositories, diffed,
   grepped, or handled in any manner used on MIBs.

   YANG supports a string concatenation operator which can be used to
   split long strings into multiple lines, supporting inclusion of YANG
   model in 72 column RFCs.  An example is the IPv4 regular expression:

     pattern
         '(([0-1]?[0-9]?[0-9]|2[0-4][0-9]|25[0-5])\.){3}'
       + '([0-1]?[0-9]?[0-9]|2[0-4][0-9]|25[0-5])'
       + '(%[\p{N}\p{L}]+)?';

   o  3.2.4.  Document Information (Agreed)

   YANG supports the "organization", "contact", "revision",
   "description", and "reference" statements for modules.

















Bjorklund                Expires August 21, 2008               [Page 11]


Internet-Draft                    YANG                     February 2008


     // Contents of "acme-system.yang"
     module acme-system {
         namespace "http://acme.example.com/system";
         prefix "acme";

         organization "ACME Inc.";
         contact "joe@acme.example.com";
         description
             "The module for entities implementing the ACME system.";

         revision 2007-06-09 {
             description "Initial revision.";
         }
         ...
     }

   o  3.2.5.  Ownership and Change Control (Agreed)

   YANG is owned and defined by IETF.  It depends on some W3C
   technologies - XML basics, namespaces - and IEEE data types.

   YANG depends only on a limited set of stable external standards to
   avoid problems with future versions of these specifications e.g.  XSD
   1.1.

   o  3.2.6.  Dependency Risk Reduction (Agreed)

   YANG has minimal dependencies on external standards.  The exact
   revisions of the standards are specified in the YANG specification.

   o  3.2.7.  Diff-Friendly (Agreed)

   Because of its simple syntax, a YANG module is diff- and email-
   friendly.

     @@ -62,10 +62,12 @@
        }

        typedef direction-type {
     +    description "Which direction of traffic is requested?";
          type enumeration {
            enum ingress;
            enum egress;
            enum both;
     +      enum neither;
          }
        }




Bjorklund                Expires August 21, 2008               [Page 12]


Internet-Draft                    YANG                     February 2008


   o  3.2.8.1.  Descriptions using Local Languages (Agreed)

   YANG supports Unicode text in the data model definitions.

   o  3.2.8.2.  UTF-8 Encoding (Agreed)

   YANG supports UTF-8.  YANG modules are written in the UTF-8 [RFC3629]
   character set.

   o  3.2.8.3.  Localization Support (Agreed)

   While many YANG text statements ("description", "reference", etc) are
   targeted at the reader and implementer, not the end user, the reality
   is that these strings are commonly placed before users in generic
   browsers.  Internationalization of these strings can be performed
   using extensions, such as:

       leaf trunk-status {
           type string;
           description "The status of the trunk";
           i18n:description "en_GB:The condition of the boot";
           i18n:description "sv_SE:Trunkens nuvarande tillstaand";
       }

   o  3.2.8.4.  Error String Localization (Agreed)

   YANG explicitly lists the app-tags and messages of generated
   messages, allowing applications to translate between the values sent
   over the wire and catalogs of localized messages.

   o  3.3.1.  Modularity (Agreed)

   YANG supports a flexible modularization mechanism.  YANG structures
   data models into modules and submodules.  A module can import data
   from other external modules, and include data from submodules.  The
   hierarchy can be extended, allowing one module to add data nodes to
   the hierarchy defined in another module.  This augmentation can be
   conditional, with new nodes to appearing only if certain conditions
   are met.

   o  3.3.2.  Reusable Definitions (Agreed)

   YANG supports reusable simple (scalar) types with the "typedef"
   statement, and reusable structures with the "grouping" statement.







Bjorklund                Expires August 21, 2008               [Page 13]


Internet-Draft                    YANG                     February 2008


     typedef percent {
         type uint16 {
             range "0 .. 100";
         }
         description "Percentage";
     }

     leaf completed {
         type percent;
     }

     grouping target {
         leaf address {
             type inet:ip-address;
             description "Target IP address";
         }
         leaf port {
             type inet:port-number;
             description "Target port number";
         }
     }

     container peer {
         container destination {
             uses target;
         }
     }

   o  3.3.3.  Modular extension (Agreed)

   A published YANG module can be extended from another module with the
   "augment" statement.  This statement allows for very flexible
   extensions, where the original module does not have to be explicitly
   designed for specific extensibility.

   With the "augment" statement, YANG fully utilizes the flexible
   extensibility of XML with namespaces.

   A module can extend the data model defined in another module using
   the "augment" statement.  Augmentation allows flexible extensions to
   existing modules without forcing the original module to explicitly
   allow for such extensibility.  Augmented nodes are encoded in the XML
   namespace of the augmenting module, avoiding ambiguity and conflicts.

   o  3.4.1.  Default Values on the Wire (Agreed)

   In YANG modules, leafs can have default values.  YANG supports
   NETCONF protocol extensions such as "with-defaults" which control how



Bjorklund                Expires August 21, 2008               [Page 14]


Internet-Draft                    YANG                     February 2008


   defaults are sent over the wire.

   In YANG modules, leafs can have default values.  Defaults need not be
   transmitted on the wire since both client and server understand the
   impact of such defaults.

   YANG supports NETCONF protocol extensions such as "with-defaults"
   which control how defaults are sent over the wire.

   o  3.4.2.1.  Ordered Lists (Agreed)

   Lists can be declared as "ordered-by user" which specifies that the
   order has semantic significance, or "ordered-by system" which
   specifies that the order of the list entries has no semantic meaning.

   o  3.4.3.1.  Validate Instance Data (Agreed)

   The ABNF grammar and general tokenization rules specifies what a
   valid module looks like on a syntactic level.  The semantic meaning
   is defined in the description of the statements.

   o  3.4.4.  Instance Canonicalization (Agreed)

   This is work to be done.  Canonicalization of the XML follows the
   rules defined in [RFC3076].

   o  3.4.5.  Character Set and Encoding (Agreed)

   YANG supports models defined in UTF-8.

   o  3.5.1.  Human-Readable Semantics (Agreed)

   YANG supports the "description" statement as a way to describe
   additional semantics to a definition.  The "description" statement is
   supported on almost all statements, including individual enumerated
   values and bits (which was a problem in SMI).  Furthermore, the
   statement is supported in YANG extensions.

   o  3.5.2.  Basic Types (Agreed)

   YANG has a set of built-in types, similar to those of many
   programming languages, but with some differences due to special
   requirements from the management information model.  Most built-in
   types have a direct mapping to XSD types.

   o  3.5.3.  Handling Opaque Data (Agreed)

   Non-YANG XML data is supported with the "anyxml" statement.



Bjorklund                Expires August 21, 2008               [Page 15]


Internet-Draft                    YANG                     February 2008


   anyxml contents {
       description "Contains the unfiltered contents of some XML thing";
   }

   o  3.5.4.1.  Define Keys (Agreed)

   A list used for configuration data must have keys in YANG.

       list user {
           key "name";
           leaf name {
               type string;
           }
           leaf full-name {
               type string;
           }
           leaf class {
               type string;
           }
       }

   o  3.5.5.1.  Simple Relationships (Agreed)

   The "keyref" statement is used to formally define 1:1 and 1:n
   relationships in YANG models.  These formal machine readable
   relationships can cross module boundaries.

     notification link-failure {
         description "A link failure has been detected";
         leaf if-index {
             type int32 { range "1 .. max"; }
         }
         leaf if-name {
             type keyref {
                 path "/interfaces/interface/name";
             }
         }
     }

   o  3.5.6.  Hierarchical Data

   YANG supports the definition of hierarchical data.

   o  3.5.8.  Characterize Data (Agreed)

   Each data object in a YANG module is either defined as configuration
   or non-configuration, with the "config" statement.




Bjorklund                Expires August 21, 2008               [Page 16]


Internet-Draft                    YANG                     February 2008


         leaf observed-speed {
             type uint32;
             config false;
         }

   o  3.5.10.1.  Formal Description of Constraints (Agreed)

   Constraints local to scalar objects are supported with restrictions
   on the type.  YANG supports "range", "length" and "pattern"
   restrictions.

      type union {
         type int {
             range 0..15;
         }
         type string {
             length 5..10;
             pattern "full.*";
         }
     }

   Uniqueness is controlled with the "unique" statement, as discussed in
   the next section.

   o  3.5.10.3.  Non-Key Uniqueness (Agreed)

   A common type of constraint is uniqueness constraints, i.e. the
   ability to specify that within some context, the values of some
   objects must be unique across all instances.

   YANG supports this with the "unique" statement.

     list server {
         key "name";
         unique "ip port";
         leaf name {
             type string;
         }
         leaf ip {
             type inet:ip-address;
         }
         leaf port {
             type inet:port-number;
         }
     }






Bjorklund                Expires August 21, 2008               [Page 17]


Internet-Draft                    YANG                     February 2008


   o  3.5.11.  Units (Agreed)

   YANG supports associating units with values or derived types with the
   "units" statement.

     leaf max-lease-time {
         type uint32;
         units seconds;
     }

   o  3.6.1.1.  Language Versioning (Agreed)

   The YANG language is versioned with the "yang-version" statement.

     yang-version 1;

   o  3.6.2.1.  Model Version Identification (Agreed)

   A YANG module has a revision, and the revision number is reported as
   part of the schema discovery process.

     revision "2007-06-09" {
         description "Initial revision.";
     }

   o  3.6.2.4.  Obsolete Portions of a Model (Agreed)

   YANG uses the well-known STATUS clause from SMI, with the "status"
   statement.  The meaning is the same as in the SMI.

     status deprecated;

   o  3.6.3.3.  Backwards Compatibility (Agreed)

   YANG supports module revisions while allowing backwards
   compatibility.  The rules controlling such changes remains work to be
   done.

   o  3.7.2.  Conformance to a Model (Agreed)

   In the current version of YANG, conformance is on the module level.

   Support for finer-grained conformance is work to be done.  In
   designing this feature, it is important to learn from the experience
   with AGENT-CAPABILITIES in SMIv2.






Bjorklund                Expires August 21, 2008               [Page 18]


Internet-Draft                    YANG                     February 2008


   o  3.7.2.2.  Server Conformance to Schema (Agreed)

   Since the conformance in YANG is on module level, a server that
   claims conformance to a module must implement the entire module.

   o  3.8.2.  Translate Models to Other Forms (Agreed)

   YANG models can be translated to XSD or RelaxNG, if needed.  The XSD
   translation is implemented in one open source tool.  Since a YANG
   module contains much more information than the XML grammar supported
   by these languages, the transformation to standard XSD or RelaxNG
   will be lossy.  As a simple example, the information if an object
   represents configuration can not be expressed in standard XSD and
   RelaxNG.  Since both these languages support user-defined
   annotations, the missing information can be encoded in non-standard
   user-defined annotations.

3.1.2.  "NOT Agreed" with which YANG complies

   YANG complies with the following "NOT Agreed" requirements.

   o  3.4.3.2.  Tools to Validate Instance Data (NOT Agreed)

   There is currently one open-source tool available to validate YANG
   modules, and at least two more open-source tools are being worked
   upon.

   o  3.5.9.1.  Default Values (NOT Agreed)

   YANG supports default values.  Any leaf node can specify a static
   default using the "default" statement.

     default 1024;

   o  3.5.10.2.  Multi-element Constraints (NOT Agreed)

   We believe that there is a value in having formal descriptions of
   integrity constraints.  One reason is that with formal descriptions,
   interoperability is easier to achieve.  Another reason is that tools
   can reduce the implementation effort of data models.  We also believe
   that there is a balance between the expressiveness and usefulness of
   formal descriptions - if the formal definition of a constraint is too
   complex to read, a textual description might be more appropriate.

   YANG supports XPath based constraints.  XPath is a fairly simple
   language (in its expressiveness), but covers many common use cases.
   More complex constraints are defined in description clauses.




Bjorklund                Expires August 21, 2008               [Page 19]


Internet-Draft                    YANG                     February 2008


         must "ifType != ethernet or " +
              "(ifType = ethernet and ifMTU = 1500)" {
             error-message "An ethernet MTU must be 1500";
         }

   o  3.5.7.1.  Referential Integrity (NOT Agreed)

   YANG supports formal referential integrity constraints with the
   "keyref" statement.

     leaf mgmt-interface {
         type keyref {
             path "../interface/name";
         }
     }

   o  3.6.1.2.  User Extensions (NOT Agreed)

   YANG supports user-defined extensions to the language itself.

   To define an extension:

     module my-extensions {
       ...

       extension c-define {
         description
           "Takes as argument a name string.
           Makes the code generator use the given name in the
           #define.";
         argument "name";
       }
     }

   To use the extension:

     module my-interfaces {
       ...
       import my-extensions {
         prefix "myext";
       }
       ...
       container interfaces {
         ...
         myext:c-define "MY_INTERFACES";
       }
     }




Bjorklund                Expires August 21, 2008               [Page 20]


Internet-Draft                    YANG                     February 2008


   o  3.6.1.3.  Mandatory Extensions (NOT Agreed)

   We believe that this is a bad idea, since it will break backwards
   compatibility.  Marking an extension as "must-understand" would be
   necessary when the existing semantics of a definition has been
   altered in a backwards incompatible way.  We believe it is a feature
   to not allow extensions that modifies the semantics in such a way.

   o  3.6.3.5.  Must-Understand Model Extensions (NOT Agreed)

   See above.

   o  3.8.3.  Minimize SMI Translation Pain (NOT Agreed)

   To the extent possible, YANG maintains compatibility with SNMP's
   SMIv2 (Structure of Management Information version 2 [RFC2578],
   [RFC2579]).  SMIv2-based MIB modules can be automatically translated
   into YANG modules for read-only access.  However YANG is not
   concerned with reverse translation from YANG to SMIv2.

3.1.3.  "NOT Agreed" with which YANG does not comply (or not determined)

   This section lists those "NOT Agreed" requirements with which YANG
   either does not comply or no determination of compliance has yet been
   made.

   o  3.1.2.  Notification Get (NOT Agreed)

   o  3.2.8.5.  Tag Names and Strings in Local Languages (NOT agreed)

   o  3.4.2.2.  Order within Containers (NOT Agreed)

   o  3.4.2.3.  Interleaving (NOT Agreed)

   o  3.4.6.  Model Instance Localization (NOT Agreed)

   o  3.5.4.2.  Deep Keys (NOT Agreed)

   o  3.5.5.2.  Many-to-Many Relationships (NOT Agreed)

   o  3.5.5.3.  Retrieve Relationships instance (NOT Agreed)

   o  3.5.5.4.  Retrieve Relationships - qualified (NOT Agreed)

   o  3.5.7.2.  Extended Referential Integrity (NOT Agreed)

   o  3.5.7.3.  Referential Integrity Robustness (NOT Agreed)




Bjorklund                Expires August 21, 2008               [Page 21]


Internet-Draft                    YANG                     February 2008


   o  3.5.9.2.  Dynamic Defaults (NOT Agreed)

   o  3.5.12.  Define Actions (NOT Agreed)

   o  3.6.2.2.  Interaction with defaults (NOT Agreed)

   o  3.6.2.3.  Conformance Interference (NOT Agreed)

   o  3.6.3.1.  Schema Version of Instance (NOT Agreed)

   o  3.6.3.2.  Interaction with default Values (NOT Agreed)

   o  3.6.3.4.  Forwards Compatibility (NOT Agreed)

   o  3.7.1.  Conformance to the Modeling Language (NOT Agreed)

   o  3.7.2.1.  Conditional Conformance (NOT Agreed)

   o  3.7.2.3.  Client Conformance To Schema (NOT Agreed)

   o  3.7.2.4.  Versioned Conformance (NOT Agreed)

   o  3.8.1.  Standard Technology (NOT Agreed)

   o  3.8.4.  Generate Models from Other Forms (NOT Agreed)

   o  3.8.5.  Isolate Models from Protocol (NOT Agreed)

   o  3.8.6.  Library Support (NOT Agreed)

3.2.  Requirements from RFC 3139

   [RFC3139], "Requirements for Configuration Management of IP-based
   Networks", lists requirements in Section 3.0, "Requirements for an
   IP-based Configuration Management System".  In this document, only
   the number in that section and a brief summary are reproduced.

   o  1): higher level of abstraction

   Network-wide configuration is very difficult to achieve.  Many system
   components beyond the data modeling language impact the design of
   such an application.  YANG provides a consistent and interoperable
   definition of NETCONF content independent of any one device, which is
   an important component of a network-wide configuration management
   system.






Bjorklund                Expires August 21, 2008               [Page 22]


Internet-Draft                    YANG                     February 2008


   o  2): translating network-wide configurations into device-local
      configuration

   YANG supports language extensions, which can be added by an
   application to data model files to identify conceptual data
   definitions which vary in implementation on specific platforms.  YANG
   will soon support NETCONF capabilities, which can be used to
   partition data model definitions in device-specific ways.  YANG can
   also be translated to YIN, and then manipulated with XSLT scripts, to
   construct device-specific variants of network-wide configurations.

   o  3): interpret device-local configuration

   This is an application requirement, not related to the data modeling
   language.  YANG does not have any specific constructs that
   differentiate between network-wide and device-specific
   configurations.

   o  4): provisioning complete or partial configuration data to network
      devices simultaneously or in a synchronized fashion

   This is a protocol requirement, not related to the data modeling
   language.  Transfer of configuration data in this manner is supported
   by the NETCONF protocol.

   o  4a): provision multiple device-local configurations

   This is a protocol requirement, not related to the data modeling
   language.  Transfer of configuration data in this manner is supported
   by the NETCONF protocol.

   o  5): means by which network devices can send feedback

   This is a protocol requirement, supported by the NETCONF protocol.

   o  6): provisioning complete or partial configuration data to network
      devices dynamically

   This is an application requirement, supported by the NETCONF
   protocol.

   o  7): efficient and reliable means to provision large amounts of
      configuration data

   This is a protocol requirement, supported by the NETCONF protocol.






Bjorklund                Expires August 21, 2008               [Page 23]


Internet-Draft                    YANG                     February 2008


   o  8): secure means to provision configuration data

   This is a transport requirement, supported by the NETCONF protocol
   stack.

   o  9): provide expiration time and effective time capabilities to
      configuration data

   This is a protocol and possibly data model requirement.  NETCONF does
   not support configuration expire times.

   o  10): provide error detection and failure recovery mechanisms

   NETCONF provides extensive error information, which can include
   content-layer specific fields.  YANG supports the definition of data-
   model specific error information, which an agent can return in these
   fields.

   o  11): eliminate the potential for mis-configuration occurring
      through concurrent shared write access

   This is a protocol requirement, supported by the NETCONF protocol.

   o  12): help in tracing back configuration changes

   This is a protocol and possibly data model requirement.  NETCONF does
   not support configuration change history traceback explicitly, but
   the mechanisms exist in the protocol to support this feature.

   o  13): allow for the use of redundant components

   This is a platform-specific feature, not related to the data modeling
   language.

   o  14): be flexible and extensible to accommodate future needs

   YANG supports language extensions, language versioning, and
   augmentation of data models defined in existing documents.

   o  15): leverage knowledge of the existing SNMP management
      infrastructure

   YANG is based in part on SMIng and SMIv2, and includes as many
   familiar concepts from SNMP data modeling as possible.  YANG is
   designed to extend SMIv2, not throw it out and start over.






Bjorklund                Expires August 21, 2008               [Page 24]


Internet-Draft                    YANG                     February 2008


3.3.  Requirements from RFC 3216

   [RFC3216], "SMIng Objectives", divides its objectives into three
   categories: accepted, nice-to-have, and rejected.

3.3.1.  Accepted objectives

   o  4.1.1 The Set of Specification Documents

   YANG is specified in one document.

   o  4.1.2 Textual Representation

   YANG uses a textual representation.

   o  4.1.3 Human Readability

   It is easy for humans to read and write YANG modules.  Many features,
   such as string formatting, string concatenation, and small set of
   language tokens, are included for ease-of-use.

   o  4.1.4 Rigorously Defined Syntax

   The YANG language is fully specified using ABNF.

   o  4.1.5 Accessibility

   Protocol accessibility is built into certain YANG constructs, such as
   'rpc' or 'notification'.  NETCONF data access is controlled with
   several language constructs, such as the 'config' and 'mandatory'
   statements.

   o  4.1.6 Language Extensibility

   YANG supports language extensions.

   o  4.1.7 Special Characters in Text

   YANG provides full support of UTF-8 strings and many special
   characters can be inserted in strings.

   o  4.1.8 Naming

   YANG supports complete instance naming using the Xpath language.
   Indexed lists are supported as well.






Bjorklund                Expires August 21, 2008               [Page 25]


Internet-Draft                    YANG                     February 2008


   o  4.1.9 Namespace Control

   YANG allows full control of XML namespace usage within a data model.

   o  4.1.10 Modules

   YANG supports modular definitions, and self-consistent sub-modules as
   well.

   o  4.1.11 Module Conformance

   YANG only supports full module conformance at this time.  Work is
   under-way to add NETCONF capability based conformance and other
   mechanisms to support partial module conformance.

   o  4.1.12 Arbitrary Unambiguous Identities

   YANG includes the 'instance-identifier' built-in data-type, which can
   be used for XML the way an OBJECT IDENTIFIER is used in SNMP.

   o  4.1.13 Protocol Independence

   YANG is not protocol independent.  It is designed to fully support
   definition of the NETCONF content layer, allowing interoperable
   manipulation of network configuration data.  YANG does not support
   SNMP or COPS-PR.

   o  4.1.14 Protocol Mapping

   YANG does not provide mechanisms to manually map data model
   constructs to arbitrary protocols.  Experience gained in the SMING WG
   suggests that it is too difficult to maintain separate data model
   files, or sections within a file, in order to split definitions into
   a protocol independent section and 1 or more protocol-dependent
   sections,

   YANG builds complete NETCONF protocol support into the language,
   increasing human ease-of-use, and reducing the chance of errors
   introduced by additional complicated language constructs to define
   protocol mappings.

   The YANG specification defines NETCONF / XML Encoding Rules in
   separate sections, which allows a possible later mapping to other
   protocols.

   o  4.1.15 Translation to Other Data Definition Languages

   YANG can be translated to XSD or RelaxNG.  It cannot be translated to



Bjorklund                Expires August 21, 2008               [Page 26]


Internet-Draft                    YANG                     February 2008


   SMIv2 or SPPI, without loss of semantics.

   o  4.1.16 Base Data Types

   YANG supports all of the listed data types.  All are built into the
   language, except OID, which is a derived type.

   o  4.1.17 Enumerations

   SMIv2 style enumerations are fully supported in YANG.

   o  4.1.18 Discriminated Unions

   YANG includes the 'union' data type, which is a non-discriminated
   union.  It is trivial to construct a discriminated union with data
   modeling constructs (i.e, container with a leaf as the discriminator,
   plus a union leaf.)

   o  4.1.19 Instance Pointers

   YANG supports instance pointers with the 'instance-identifier
   built-in data type.  A well-established and industry accepted method
   is used to identify NETCONF data model objects, and named instances
   of those objects.

   o  4.1.20 Row Pointers

   The YANG instance-identifier is used to identify all conceptual data
   model nodes, including conceptual rows in YANG lists.

   o  4.1.21 Constraints on Pointers

   YANG supports constraints on object instances with the 'keyref'
   built-in data type.  This data type uses an Xpath expression to
   identify specific object(s) or object instances that are valid for a
   particular object.

   o  4.1.22 Base Type Set

   YANG supports a fixed type set, and does not include and extensible
   numeric base types.  These data types are named similar to SMIv2 data
   types, starting with the kind of numeric type, followed by the number
   of bits in the data type (int8, uint8, int16, uint16, int32, uint32,
   int64, uint64, float32, and float64).

   o  4.1.23 Extended Data Types

   YANG fully supports derived types for leafs and leaf-lists, which can



Bjorklund                Expires August 21, 2008               [Page 27]


Internet-Draft                    YANG                     February 2008


   be based on a built-in type or another derived type.  YANG supports
   global derived types which can be exported, and nested in-line local
   derived types which are private, and limited to a local (private)
   inline scope,

   o  4.1.24 Units, Formats, and Default Values of Defined Types and
      Attributes

   YANG contains a 'units' clause which is equivalent to the SMIv2 UNITS
   clause.  Default values are mandatory-to-implement, and can be
   applied to a derived type or a leaf definition.  The DISPLAY-HINT
   construct is supported with a language extension, and used by the
   smidump program to convert SMIv2 modules to SMIv2 files.

   o  4.1.25 Table Existence Relationships

   YANG supports an INDEX clause (key), AUGMENTS clause (augment), but
   not the SPPI table EXTENDS mechanism.  YANG also SPARSE-AUGMENTS with
   an Xpath expression (when clause), and arbitrarily complex table
   relationship expressions (must clause).  Non-key tuple uniqueness is
   also provided (unique clause).

   o  4.1.26 Table Existence Relationships (2)

   The SPPI EXPAND and REORDERS mechanisms are not supported by YANG.
   They are needed in SPPI for protocol mappings, which are not required
   in YANG.

   o  4.1.27 Attribute Groups

   YANG has powerful groupings that can be reused, and refined for each
   use.

   o  4.1.28 Containment

   Groupings, data definitions, and augmentation of data can be mixed in
   arbitrarily complex ways.  Unlimited nesting of any complex data
   construct (container, list, choice, uses, augment) is allowed.

   o  4.1.29 Single Inheritance

   Although YANG is not object-oriented, a simple form of single
   inheritance can be modeled with a grouping that extends an existing
   grouping.

   o  4.1.30 Reusable vs. Final Attribute Groups

   YANG does not currently support a 'final' attribute.  All typedef and



Bjorklund                Expires August 21, 2008               [Page 28]


Internet-Draft                    YANG                     February 2008


   grouping definitions can be refined.

   o  4.1.31 Events

   YANG provides full support of NETCONF notification content
   definition.

   o  4.1.32 Creation/Deletion

   YANG fully supports the create and delete operations in the NETCONF
   protocol, and includes additional support for user-controlled list or
   leaf-list insertion.

   o  4.1.33 Range and Size Constraints

   The YANG range (and length) clauses are almost identical to the SMIv2
   SIZE clause, except it is better.  In addition to the usual syntax,
   e.g., (1..10) or (1 | 3 5..10), the 'min' and 'max' keywords are
   allowed to indicate that the range boundary is derived from the
   parent, in the chain of derived types.  In addition, float32 and
   float64 range definitions can contain the4 '-INF' and 'INF' keywords,
   which are synonyms for 'min' and 'max', traditionally used for
   floating point numbers.

   o  4.1.34 Uniqueness

   The YANG 'unique' clause supports uniqueness constraint
   specification.

   o  4.1.35 Extension Rules

   YANG defines rules for extending and updating modules in a compatible
   way (work to be done).  The YANG "augment" statement allows extending
   a data model with the contents of a new module in a compatible way.

   o  4.1.36 Deprecate Use of IMPLIED Keyword

   This requirement is not applicable to NETCONF.

   o  4.1.37 No Redundancy

   YANG is designed with minimal data entry redundancy in mind.  No data
   ever needs to be entered in multiple places, within a module, in
   order to define any construct.

   o  4.1.38 Compliance and Conformance

   YANG does not have any partial module conformance.  Only full module



Bjorklund                Expires August 21, 2008               [Page 29]


Internet-Draft                    YANG                     February 2008


   conformance is supported at this time.  Could be added, if needed.

   o  4.1.39 Allow Refinement of All Definitions in Conformance
      Statements

   This feature could be supported in YANG, if some sort of module
   variance mechanism is added.

   o  4.1.40 Categories

   YANG does not contain explicit support for SPPI subject categories.
   This could be achieved with a language extension, if needed in
   NETCONF.

   o  4.1.41 Core Language Keywords vs. Defined Identifiers

   YANG is similar to SPPI, in that no language keywords are ever
   imported, or built-in data types.  Only user-defined identifiers are
   imported or included in YANG.

   o  4.1.42 Instance Naming

   SPPI and SMIv2 instance naming is not relevant to NETCONF.

   o  4.1.43 Length of Identifiers

   YANG defines a minimum value that all implementations must support as
   their maximum identifier length (63 characters).  A hard-wired
   maximum identifier length is not used.

   o  4.1.44 Assign OIDs in the Protocol Mappings

   COPS-PR protocol mapping is not relevant to NETCONF.

3.3.2.  Nice-to-have objectives

   o  4.2.1 Methods

   YANG and NETCONF support methods with a remote procedure call
   construct.  This is not the same as an object-oriented method, but
   YANG fully supports the mechanisms with NETCONF for this purpose.

   o  4.2.2 Unions

   YANG contains the 'union' built-in data type, which can contain an
   arbitrary mix of types, including other unions.





Bjorklund                Expires August 21, 2008               [Page 30]


Internet-Draft                    YANG                     February 2008


   o  4.2.3 Float Data Types

   YANG supports IEEE floating point math with the 'float32' and
   'float64' built-in data types.  A range or default clause for these
   types can be specified in IEEE floating point syntax. [ed.
   reference].

   o  4.2.4 Comments

   YANG supports single line C++ style comments '// ...EOLN' as well as
   C-style multi-line comments (/* ... */).

   o  4.2.5 Referencing Tagged Rows

   SPPI instance tagging is not relevant to NETCONF.

   o  4.2.6 Arrays

   YANG supports variable-length, multi-valued objects with the 'choice'
   construct, which provides extensible cases and some NETCONF protocol
   control (mandatory, default) for this type of flexible object
   definition.

   o  4.2.7 Internationalization

   Internationalization is possible in YANG.  See bullets 3.2.8.2-
   3.2.8.4 in chapter Section 3.1.1.

   o  4.2.8 Separate Data Modelling from Management Protocol Mapping

   Almost all NETCONF protocol details are hidden by YANG, allowing data
   modelers to focus on the domain-specific aspects of the data model,
   and not the language syntax.  YANG clauses have a very flexible
   syntax, loose ordering, and relatively few language constructs, to
   allow users to concentrate on writing data definitions, not fixing
   MIB compiler errors.

3.3.3.  Rejected objectives

   YANG supports some of the rejected requirements from SMING.  Support
   is described below specifically if present in YANG.

   o  4.3.1 Incomplete Translations

   o  4.3.2 Attribute Value Constraints

   Supported with the "must" statement.




Bjorklund                Expires August 21, 2008               [Page 31]


Internet-Draft                    YANG                     February 2008


   o  4.3.3 Attribute Transaction Constraints

   o  4.3.4 Method Constraints

   o  4.3.5 Agent Capabilities

   o  4.3.6 Relationships

   Partly supported with the "must" statement and the keyref built-in
   type.

   o  4.3.7 Procedures

   Supported with the "rpc" statement.

   o  4.3.8 Associations

   Supported with the "keyref" built-in type.

   o  4.3.9 Association Cardinalities

   The "keyref" built-in type is used to formally define 1:1 and 1:n
   associations/relationships in YANG models.

   o  4.3.10 Categories of Modules

   o  4.3.11 Mapping Modules to Files

   YANG provides a recommendation for mapping to files.

   o  4.3.12 Simple Grammar

   o  4.3.13 Place of Module Information

   Supported.

   o  4.3.14 Module Namespace

   o  4.3.15 Hyphens in Identifiers

   Supported.

3.4.  Requirements from draft-linowski-netconf-dml-requirements-00

   [LINOWSKI], "NETCONF Data Modeling Language Requirements", has the
   following requirements:





Bjorklund                Expires August 21, 2008               [Page 32]


Internet-Draft                    YANG                     February 2008


   o  4.1.1.  Base Data Types

   Compliant.

   o  4.1.2.  Default Values of Defined Types and Attributes

   Compliant.

   o  4.1.3.  Language Extensibility

   Compliant.  YANG supports extensions to the language in a compatible
   way.

   o  4.1.4.  Model Modularity

   Compliant, using the "module" and "submodule" statements.

   o  4.1.5.  Protocol Independence

   Compliant, see bullets 4.1.13 and 4.1.14 in Section 3.3.1.

   o  4.1.6.  Translation to Other Data Definition Languages

   Compliant.  See bullet 3.8.2 in Section 3.1.1.

   o  4.1.7.  Module Conformance

   Compliant, see bullet 4.1.11 in Section 3.3.1.

   o  4.2.1.  Model Element Identifiers

   Partly compliant.  YANG identifiers are case sensitive, and hyphens,
   dots and leading underscores are allowed as well.

   o  4.2.2.  Model Element Documentation Text

   Compliant.  YANG provides a number of documentation and information
   elements that support UTF-8 characters.

   o  4.2.3.  Model Element Presentation Name

   Compliant.  For localization/internationalization see bullet 3.2.8.1
   through 3.2.8.4 in Section 3.1.1.

   o  4.3.1.  Release Support

   Compliant.  See bullet 3.6.2.1. in Section 3.1.1.




Bjorklund                Expires August 21, 2008               [Page 33]


Internet-Draft                    YANG                     February 2008


   o  4.3.2.  Multiple sub-module revisions in one model

   Not compliant, disagree with the requirement.  Handling multiple
   possibly incompatible versions of a model in one document would be
   confusing to the user.  Keep the (sub)modules side by side, don't
   merge them.  Incompatible versions of the (sub)modules must have
   different names as in SMI.

   o  4.4.1.  Concrete Classes

   Not compliant.  YANG is not object oriented.  Groupings can be used
   as a proxy to classes.  A grouping can define all attributes of a
   class.

   o  4.4.2.  Abstract Classes

   Not compliant.

   o  4.4.3.  Single Class Inheritance

   Partly compliant.  Although YANG is not object-oriented, a simple
   form of single inheritance can be modeled with a grouping that
   extends an existing grouping.

   o  4.4.4.  Attributes

   Partly compliant.  Classes and attribute groups can be modeled using
   the "grouping" statement.

   o  4.4.5.  Attribute Groups

   Compliant using the "grouping" statement.

   o  4.4.6.  Reference Relationships

   Partly compliant.  The keyref built-in type can be used to describe
   references.

   o  4.4.7.  Containment Relationships

   Compliant using the "container" or the "list" and the augment
   statement.

   o  4.4.8 Calculated Relationships

   Compliant, based on a leaf-list of the keyref built-in type.  Adding
   relationships without altering the source- or target-end class is
   possible with a keyref list stored externally to both ends of the



Bjorklund                Expires August 21, 2008               [Page 34]


Internet-Draft                    YANG                     February 2008


   relationship.

   o  4.4.9.  Simple Attribute Constraints

   Compliant, but all constraints are combined with the AND operator
   that is all constraints must be met simultaneously.

   o  4.5.1.  Typed Annotations

   Partly compliant based on the "extension" statement.  The type, the
   placement and the optionality of an extension is intentionally not
   defined.  If it is an extension then by definition it should allow
   free usage; most tools will anyway not understand it - will ignore
   it.





































Bjorklund                Expires August 21, 2008               [Page 35]


Internet-Draft                    YANG                     February 2008


4.  YANG DHCP Module

   The BOF proposal for the CANMOD BOF at the seventy-first IETF states:
   "Design teams have also prepared annotated examples of instance
   documents to illustrate many of the requirements."  The example
   instance document is in Appendix C of [PRESUHN].  This section shows
   the YANG modules written for that instance document.

   module dhcp {
     namespace "http://example.com/ns/dhcp";
     prefix dhcp;

     import yang-types { prefix yang; }
     import inet-types { prefix inet; }
     import ieee-types { prefix ieee; }
     import interfaces { prefix if; }

     organization
       "yang-central.org";
     description
       "Partial data model for DHCP, based on the config of
        the ISC DHCP reference implementation.";

     container dhcp {
       description
         "configuration and operational parameters for a DHCP server.";

       leaf max-lease-time {
         type uint32;
         units seconds;
         default 7200;
       }

       leaf default-lease-time {
         type uint32;
         units seconds;
         must '$this <= ../max-lease-time' {
           error-message
             "The default-lease-time must be less than max-lease-time";
         }
         default 600;
       }

       uses subnet-list;

       container shared-networks {
         list shared-network {
           key name;



Bjorklund                Expires August 21, 2008               [Page 36]


Internet-Draft                    YANG                     February 2008


           leaf name {
             type string;
           }
           uses subnet-list;
         }
       }
     }

     grouping subnet-list {
       description "A reusable list of subnets";
       list subnet {
         key "network prefix-length";
         leaf network {
           type inet:ip-address;
         }
         leaf prefix-length {
           type uint8 {
             range "0..128";
           }
         }
         container range {
           presence "enables dynamic address assignment";
           leaf dynamic-bootp {
             type empty;
             description
               "Allows BOOTP clients to get addresses in this range";
           }
           leaf low {
             type inet:ip-address;
             mandatory true;
           }
           leaf high {
             type inet:ip-address;
             mandatory true;
           }
         }

         container dhcp-options {
           description "Options in the DHCP protocol";
           container router-list {
             leaf-list router {
               type inet:host;
               ordered-by user;
               reference "RFC 2132, sec. 3.8";
             }
           }
           container domain-list {
             leaf-list domain-name {



Bjorklund                Expires August 21, 2008               [Page 37]


Internet-Draft                    YANG                     February 2008


               type inet:domain-name;
               reference "RFC 2132, sec. 3.17";
             }
           }
           list custom {
             key option;
             leaf option {
               type uint32;
             }
             choice type {
               leaf ipv4-address {
                 type inet:ipv4-address;
               }
               leaf string {
                 type string;
               }
             }
           }
         }

         leaf max-lease-time {
           type uint32;
           units seconds;
           default 7200;
         }

         container leases {
           config false;
           description
             "Contains status information about active leases.";
           list lease {
             key address;

             leaf address {
               type inet:ip-address;
             }
             leaf starts {
               type yang:date-and-time;
             }
             leaf ends {
               type yang:date-and-time;
             }
             leaf mac-address {
               type yang:phys-address;
             }
           }
         }




Bjorklund                Expires August 21, 2008               [Page 38]


Internet-Draft                    YANG                     February 2008


         container interface-filter {
           description
             "The DHCP server will only respond to requests for this
              subnet when they come from one of these interfaces";
           leaf-list interface {
             type keyref {
               path "/if:interfaces/if:interface/if:ifName";
             }
           }
         }
       }
     }
   }

   The next module is an example of a YANG module that augments the
   existing dhcp module.

   module calendar {

     namespace "http://example.com/ns/cal";
     prefix cal;

     import dhcp { prefix dhcp; }

     augment "/dhcp:dhcp/dhcp:subnet/dhcp:dhcp-options" {
       leaf timezone {
         type string;
       }
     }

     // more data definitions added here...

   }

   The interface module is an incomplete stub module for the keyref in
   dhcp.yang.















Bjorklund                Expires August 21, 2008               [Page 39]


Internet-Draft                    YANG                     February 2008


   module interfaces {
     namespace "http://example.com/ns/int";
     prefix if;

     // This is a stub module to make sure the keyref in
     // dhcp module points to a real list.

     container interfaces {
       list interface {
         key ifName;
         leaf ifName {
           type string;
         }
       }
     }
   }



































Bjorklund                Expires August 21, 2008               [Page 40]


Internet-Draft                    YANG                     February 2008


5.  IANA Considerations

   This document has no actions for IANA.
















































Bjorklund                Expires August 21, 2008               [Page 41]


Internet-Draft                    YANG                     February 2008


6.  Security Considerations

   This document is only a statement of compliance to a set of
   requirements.  It does not itself define any protocol or information
   content so security considerations are not applicable.














































Bjorklund                Expires August 21, 2008               [Page 42]


Internet-Draft                    YANG                     February 2008


7.  Contributors

   The following people all contributed significantly to this document:

    - Andy Bierman (andybierman.com)
    - Balazs Lengyel (Ericsson)
    - David Partain (Ericsson)
    - Juergen Schoenwaelder (Jacobs University Bremen)
    - Phil Shafer (Juniper Networks)










































Bjorklund                Expires August 21, 2008               [Page 43]


Internet-Draft                    YANG                     February 2008


8.  References

8.1.  Normative References

   [LINOWSKI]
              Linowski, B., "NETCONF Data Modeling Language
              Requirements", draft-linowski-netconf-dml-requirements-01
              (work in progress), February 2008.

   [PRESUHN]  Presuhn, R., "Requirements for a Configuration Data
              Modeling Language", draft-presuhn-rcdml-03 (work in
              progress), February 2008.

   [RFC3076]  Boyer, J., "Canonical XML Version 1.0", RFC 3076,
              March 2001.

   [RFC3139]  Sanchez, L., McCloghrie, K., and J. Saperia, "Requirements
              for Configuration Management of IP-based Networks",
              RFC 3139, June 2001.

   [RFC3216]  Elliott, C., Harrington, D., Jason, J., Schoenwaelder, J.,
              and W. Weiss, "SMIng Objectives", RFC 3216, December 2001.

   [RFC3629]  Yergeau, F., "UTF-8, a transformation format of ISO
              10646", STD 63, RFC 3629, November 2003.

   [RFC4741]  Enns, R., "NETCONF Configuration Protocol", RFC 4741,
              December 2006.

   [YANG]     Bjorklund, M., "YANG - A data modeling language for
              NETCONF", draft-bjorklund-netconf-yang-02 (work in
              progress), February 2008.

8.2.  Non-Normative References

   [RFC2578]  McCloghrie, K., Ed., Perkins, D., Ed., and J.
              Schoenwaelder, Ed., "Structure of Management Information
              Version 2 (SMIv2)", STD 58, RFC 2578, April 1999.

   [RFC2579]  McCloghrie, K., Ed., Perkins, D., Ed., and J.
              Schoenwaelder, Ed., "Textual Conventions for SMIv2",
              STD 58, RFC 2579, April 1999.

   [RFC3780]  Strauss, F. and J. Schoenwaelder, "SMIng - Next Generation
              Structure of Management Information", RFC 3780, May 2004.






Bjorklund                Expires August 21, 2008               [Page 44]


Internet-Draft                    YANG                     February 2008


Author's Address

   Martin Bjorklund (editor)
   Tail-f Systems

   Email: mbj@tail-f.com













































Bjorklund                Expires August 21, 2008               [Page 45]


Internet-Draft                    YANG                     February 2008


Full Copyright Statement

   Copyright (C) The IETF Trust (2008).

   This document is subject to the rights, licenses and restrictions
   contained in BCP 78, and except as set forth therein, the authors
   retain all their rights.

   This document and the information contained herein are provided on an
   "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
   OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND
   THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS
   OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF
   THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
   WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.


Intellectual Property

   The IETF takes no position regarding the validity or scope of any
   Intellectual Property Rights or other rights that might be claimed to
   pertain to the implementation or use of the technology described in
   this document or the extent to which any license under such rights
   might or might not be available; nor does it represent that it has
   made any independent effort to identify any such rights.  Information
   on the procedures with respect to rights in RFC documents can be
   found in BCP 78 and BCP 79.

   Copies of IPR disclosures made to the IETF Secretariat and any
   assurances of licenses to be made available, or the result of an
   attempt made to obtain a general license or permission for the use of
   such proprietary rights by implementers or users of this
   specification can be obtained from the IETF on-line IPR repository at
   http://www.ietf.org/ipr.

   The IETF invites any interested party to bring to its attention any
   copyrights, patents or patent applications, or other proprietary
   rights that may cover technology that may be required to implement
   this standard.  Please address the information to the IETF at
   ietf-ipr@ietf.org.


Acknowledgment

   Funding for the RFC Editor function is provided by the IETF
   Administrative Support Activity (IASA).





Bjorklund                Expires August 21, 2008               [Page 46]