[Docs] [txt|pdf|xml|html] [Tracker] [Email] [Nits]

Versions: 00

Network Working Group                                         A. Bierman
Internet-Draft                                                 YumaWorks
Intended status: Standards Track                            July 6, 2015
Expires: January 7, 2016


                       The YANG Package Statement
                  draft-bierman-netmod-yang-package-00

Abstract

   This document describes mechanisms for defining a conceptual
   collection of YANG modules and protocol capability URIs, called a
   YANG package.  Typically, modules with high cohesion that are
   designed to be used together to manage a service or product feature
   are included in a YANG package.  The purpose of the package is not
   constrained by this document.  For example, a YANG package may
   describe conformance requirements or simply describe the modules and
   protocol capabilities implemented in a specific platform.

Status of This Memo

   This Internet-Draft is submitted in full conformance with the
   provisions of BCP 78 and BCP 79.

   Internet-Drafts are working documents of the Internet Engineering
   Task Force (IETF).  Note that other groups may also distribute
   working documents as Internet-Drafts.  The list of current Internet-
   Drafts is at http://datatracker.ietf.org/drafts/current/.

   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."

   This Internet-Draft will expire on January 7, 2016.

Copyright Notice

   Copyright (c) 2015 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



Bierman                  Expires January 7, 2016                [Page 1]


Internet-Draft                YANG Packages                    July 2015


   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.

Table of Contents

   1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   3
     1.1.  Terminology . . . . . . . . . . . . . . . . . . . . . . .   4
       1.1.1.  YANG  . . . . . . . . . . . . . . . . . . . . . . . .   4
       1.1.2.  YANG Package  . . . . . . . . . . . . . . . . . . . .   4
     1.2.  Solution Overview . . . . . . . . . . . . . . . . . . . .   5
       1.2.1.  Objectives  . . . . . . . . . . . . . . . . . . . . .   5
       1.2.2.  YANG Package  . . . . . . . . . . . . . . . . . . . .   5
       1.2.3.  YANG Package File . . . . . . . . . . . . . . . . . .   5
       1.2.4.  YANG Package Examples . . . . . . . . . . . . . . . .   6
   2.  YANG Package Statement  . . . . . . . . . . . . . . . . . . .  10
     2.1.  The "package" Statement . . . . . . . . . . . . . . . . .  10
       2.1.1.  The "package" Substatements . . . . . . . . . . . . .  10
     2.2.  The "yang-package-version" Statement  . . . . . . . . . .  11
     2.3.  The "uses-package" Statement  . . . . . . . . . . . . . .  11
       2.3.1.  The "uses-package" Substatements  . . . . . . . . . .  12
     2.4.  The "uses-revision" Statement . . . . . . . . . . . . . .  12
     2.5.  The "imports-module" Statement  . . . . . . . . . . . . .  12
       2.5.1.  The "imports-module" Substatements  . . . . . . . . .  12
     2.6.  The "uses-module" Statement . . . . . . . . . . . . . . .  13
       2.6.1.  The "uses-module" Substatements . . . . . . . . . . .  13
     2.7.  The "uses-feature" Statement  . . . . . . . . . . . . . .  13
       2.7.1.  The "uses-feature" Substatements  . . . . . . . . . .  13
     2.8.  The "uses-capability" Statement . . . . . . . . . . . . .  13
       2.8.1.  The "uses-capability" Substatements . . . . . . . . .  14
     2.9.  The "uses-parameter" Statement  . . . . . . . . . . . . .  14
       2.9.1.  The "uses-parameter" Substatements  . . . . . . . . .  14
     2.10. The "uses-value" Statement  . . . . . . . . . . . . . . .  15
       2.10.1.  The "uses-value" Substatements . . . . . . . . . . .  15
   3.  Updating a YANG Package . . . . . . . . . . . . . . . . . . .  16
   4.  YANG Package Identifier . . . . . . . . . . . . . . . . . . .  16
   5.  YANG Package ABNF . . . . . . . . . . . . . . . . . . . . . .  17
   6.  IANA Considerations . . . . . . . . . . . . . . . . . . . . .  20
   7.  Security Considerations . . . . . . . . . . . . . . . . . . .  20
   8.  References  . . . . . . . . . . . . . . . . . . . . . . . . .  20
     8.1.  Normative References  . . . . . . . . . . . . . . . . . .  20
     8.2.  Informative References  . . . . . . . . . . . . . . . . .  20
   Appendix A.  Change Log . . . . . . . . . . . . . . . . . . . . .  21
     A.1.  bierman-yang-conformance-03 to bierman-yang-package-00  .  21
   Author's Address  . . . . . . . . . . . . . . . . . . . . . . . .  21






Bierman                  Expires January 7, 2016                [Page 2]


Internet-Draft                YANG Packages                    July 2015


1.  Introduction

   The YANG data modelling language [I-D.ietf-netmod-rfc6020bis] is used
   to manage conceptual hierarchical data in a modular fashion.  It is
   highly extensible, and modules from any organization can be defined
   to work together.  Unfortunately, YANG has no way to describe any
   functionality or service which is defined in multiple YANG modules.
   As described in [I-D.bogdanovic-netmod-yang-model-classification],
   vendor-specific YANG modules are expected to co-exist with standard
   modules from multiple standards organizations.  Operators and
   developers need a higher layer of data organization than a list of
   individual YANG modules, in order to more easily manage networks with
   YANG data models.

   There is a need for standard mechanisms to describe a set of YANG
   modules, grouped together for a specific purpose.  The exact purpose
   of such a mechanism may vary by use-case, and is not restricted by
   this document.

   Often YANG modules are designed such that a framework module (e.g.,
   ietf-interfaces module in [RFC7223]) is designed to be augmented by
   many other modules.  There are no machine-readable statements in YANG
   to describe which modules are needed for the implementation of a
   service or product feature.

   YANG features are used to specify a set of optional related
   statements, such as data definition statements.  There are no
   machine-readable statements in YANG to describe which features are
   needed for the implementation of a service or product feature.

   Capability URIs are used in protocols such as NETCONF [RFC6241] and
   RESTCONF [I-D.ietf-netconf-restconf] to identify an optional protocol
   feature.  such as the ":confirmed-commit" capability in NETCONF.
   There are no machine-readable statements in YANG to describe which
   protocol capabilities are needed for the implementation of a service
   or product feature.

   Constrained devices may have limited host and network resources.
   Retrieval of a large list of YANG modules, or sending of a large
   NETCONF <hello> message could significantly impact network
   performance.  It is important to minimize all network management
   traffic in this type of environment.  Advertisement of YANG packages
   instead of a complete list of YANG modules (with revision, features,
   and deviation parameters) could save a significant amount of host and
   network resources.






Bierman                  Expires January 7, 2016                [Page 3]


Internet-Draft                YANG Packages                    July 2015


1.1.  Terminology

   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].

1.1.1.  YANG

   The following terms are defined in [I-D.ietf-netmod-rfc6020bis]: q

   o  data node

   o  feature

   o  module

   o  notification statement

   o  rpc statement

1.1.2.  YANG Package

   The following terms are used within this document:

   o  conditional node: An object that has one or more "if-feature" sub-
      statements associated with it.  Note that objects affected by
      "when" statements are not considered conditional for conformance
      purposes.

   o  macro-data: The reusable YANG statements that are not protocol-
      accessible.  These include the "typedef", "grouping", "feature",
      and "identity" statements.

   o  module base: There is an implied "base" version of the module,
      which includes all statements which are not conditional.  The
      module base may be empty, a subset of all statements, or the
      entire module.  Note that a "deviation" statement is always part
      of the module base since it cannot be conditional.

   o  object: a conceptual data structure represented by a YANG data,
      rpc, or notification statement.

   o  YANG package: A set of YANG modules that provide a particular
      service or product feature.  Also called "package".






Bierman                  Expires January 7, 2016                [Page 4]


Internet-Draft                YANG Packages                    July 2015


1.2.  Solution Overview

1.2.1.  Objectives

   The solution in this document attempts to achieve the following
   objectives:

   o  Provide simple documentation mechanisms that are readable and easy
      to understand, and can be maintained over time.

   o  Provide simple mechanisms that can scale in usage from one module
      to thousands of modules.

   o  Describe the usage relationship between an augmented module and
      the augmenting module.

   o  Describe the usage relationship between modules that represent
      parts of the same conceptual high-level service.

1.2.2.  YANG Package

   A YANG package is a conceptual set of YANG modules describing some
   service or product feature.  Typically, modules with high cohesion
   that are designed to be used together to manage a service or device
   feature are included in a YANG package.  The purpose of the package
   is not constrained by this document.  A YANG package may describe
   conformance requirements or simply describe the modules implemented
   in a specific platform.

   YANG packages are specified using a text file similar to YANG
   modules, however they are separate from YANG modules, since the
   purpose of a YANG package is to describe a set of YANG modules.
   Unlike YANG modules, YANG package definitions cannot represent YANG
   data nodes that would appear in a protocol message.

   A YANG package is identified with a module-qualified name similar to
   a YANG module.  YANG modules and YANG packages share the same YANG
   identifier namespace, so the same naming conventions apply to YANG
   packages as YANG modules.

1.2.3.  YANG Package File

   A YANG package file consists of UTF-8 characters.  The syntax is
   exactly the same as for YANG modules.  Several YANG statements are
   "imported" from the YANG ABNF, and some new statements are defined.
   Specifically, YANG package syntax is the same as
   [I-D.ietf-netmod-rfc6020bis], sections 6, 6.1, 6.2, and 6.3.




Bierman                  Expires January 7, 2016                [Page 5]


Internet-Draft                YANG Packages                    July 2015


   At least one revision statement MUST be present in a YANG package
   file.  A new revision MUST be added each time the YANG package file
   is published.  This requirement is more strict than RFC 6020 to
   ensure that package revisions can be properly identified without
   ambiguity.

   A YANG package has a lifecycle status, based on the YANG "status"
   statement.

1.2.4.  YANG Package Examples

   In this example, a package named "example-routing-pkg" is defined to
   describe the routing modules supported by a particular vendor name
   Example, Inc.





































Bierman                  Expires January 7, 2016                [Page 6]


Internet-Draft                YANG Packages                    July 2015


     package example-routing-pkg {

       organization "Example, Inc.";
       contact "support at example.com";
       description
         "This package describes the routing modules required to
          support Example, Inc. base routing service.";

       revision 2015-07-01 {
         description "First revision";
         reference "TBD";
       }

       imports-module ietf-inet-types {
         uses-revision 2013-07-15;
       }

       imports-module ietf-yang-types {
         uses-revision 2013-07-15;
       }

       uses-module ietf-routing {
         uses-revision 2015-05-25;
         uses-feature multiple-ribs;
         uses-feature router-id;
       }

       uses-module ietf-interfaces {
         uses-revision 2014-05-08;
         uses-feature pre-provisioning;
       }

       uses-module ietf-ipv4-unicast-routing {
         uses-revision 2014-05-25;
       }

       uses-module ietf-ipv6-unicast-routing {
         uses-revision 2014-05-25;
       }

       uses-module example-routing-extensions {
         uses-revision 2015-06-24;
       }
     }

   In this example, a package named "example-routing-bgp-pkg" is defined
   to describe the BGP modules supported by a particular vendor name
   Example, Inc.



Bierman                  Expires January 7, 2016                [Page 7]


Internet-Draft                YANG Packages                    July 2015


     package example-routing-bgp-pkg {

       organization "Example, Inc.";
       contact "support at example.com";
       description
         "This package describes the routing modules required to
          support Example, Inc. BGP routing service.";

       revision 2015-07-01 {
         description "First revision";
         reference "TBD";
       }

       uses-package example-routing-pkg {
         uses-revision 2015-07-01;
       }

       uses-module example-routing-bgp {
         uses-revision 2014-04-17;
       }
     }

   In this example, the YANG package described the NETCONF server
   features that the Example, Inc NMS platform requires to function.

     package example-netconf-pkg {

       organization "Example, Inc.";
       contact "support at example.com";
       description
         "This package describes the NETCONF functionality required to
          support Example, Inc. NMS platforms.";

       revision 2015-07-01 {
         description "First revision";
       }

       imports-module ietf-inet-types {
         uses-revision 2013-07-15;
       }

       imports-module ietf-yang-types {
         uses-revision 2013-07-15;
       }

       uses-module ietf-netconf {
         uses-revision 2011-06-01;
         uses-feature candidate;



Bierman                  Expires January 7, 2016                [Page 8]


Internet-Draft                YANG Packages                    July 2015


         uses-feature confirmed-commit;
       }

       uses-capability
         "urn:ietf:params:netconf:capability:notification:1.0" {
         description
           "Notification delivery support is required.";
          reference "RFC 5277, section 3.1";
       }

       uses-capability
         "urn:ietf:params:netconf:capability:interleave:1.0" {
         description
           "Interleave of commands is required while notification
            delivery is active .";
         reference "RFC 5277, section 6";
       }

       uses-module ietf-netconf-with-defaults {
         uses-revision 2011-06-01;
         description
           "Support for <with-defaults> RPC parameter is required.";
            reference "RFC 6243, section 5";
       }

       uses-module ietf-netconf-acm {
         uses-revision 2012-02-22;
         description
           "Base module implementation of NACM is required.";
         reference "RFC 6536, section 3.5.2";
       }

       uses-module ietf-netconf-monitoring {
         uses-revision 2010-10-04;
         description
           "Implementation of NETCONF monitoring is required.";
         reference "RFC 6022, section 5";
       }

       uses-module ietf-netconf-notifications {
         uses-revision 2012-02-06;
         reference "RFC 6470, section 2.2";
       }
     }







Bierman                  Expires January 7, 2016                [Page 9]


Internet-Draft                YANG Packages                    July 2015


2.  YANG Package Statement

2.1.  The "package" Statement

   The "package" statement defines the YANG package's name, and contains
   all YANG package statements.  The "package" statement's argument is
   the name of the YANG package, followed by a block of substatements
   that hold detailed package information.  The package name follows the
   rules for identifiers in RFC 6020bis, section 6.2.

   A YANG package name is defined in the same conceptual namespace as
   YANG module names.  The same rules for selecting non-conflicting
   names apply as defined in RFC 6020bis, section 7.1.

   If standard YANG packages are defined by the IETF, then an IANA
   registry for YANG package names will be needed, similar to mechanism
   described in RFC 6020bis, section 15.

   A YANG package includes a status statement to indicate the package
   lifecycle status.  The YANG "status" statement is used for this
   purpose.  The default status is "current".  A current YANG package
   SHOULD NOT use any package, module, feature, or capability that is
   deprecated.  A current YANG package MUST NOT use any package, module,
   feature, or capability that is obsolete.

   Only current YANG packages SHOULD be used in a server.  A deprecated
   package MAY be used with the understanding that support for the
   package may be removed at any time in the future.  An obsolete
   package MUST NOT be used.

2.1.1.  The "package" Substatements




















Bierman                  Expires January 7, 2016               [Page 10]


Internet-Draft                YANG Packages                    July 2015


       +----------------------+---------------------+-------------+
       | Substatement         | Reference           | Cardinality |
       +----------------------+---------------------+-------------+
       | contact              | RFC 6020bis, 7.1.8  | 0..1        |
       | description          | RFC 6020bis, 7.19.3 | 0..1        |
       | imports-module       | 2.5                 | 0..n        |
       | organization         | RFC 6020bis, 7.1.7  | 0..1        |
       | reference            | RFC 6020bis, 7.19.4 | 0..1        |
       | revision             | RFC 6020bis, 7.1.9  | 1..n        |
       | status               | RFC 6020bis, 7.19.2 | 0..1        |
       | uses-capability      | 2.8                 | 0..n        |
       | uses-module          | 2.6                 | 0..n        |
       | uses-package         | 2.3                 | 0..n        |
       | yang-package-version | 2.2                 | 0..1        |
       +----------------------+---------------------+-------------+

                           package Substatements

2.2.  The "yang-package-version" Statement

   The optional "yang-package-version" statement specifies which version
   of the YANG Package specification language was used in developing the
   module.  The statement's argument is a string.  If present, it MUST
   contain the value "1", which is the current YANG Package language
   version and the default value.

   Handling of the "yang-package-version" statement for versions other
   than "1" (the version defined here) is out of scope for this
   specification.  Any document that defines a higher version will need
   to define the backward compatibility of such a higher version.

2.3.  The "uses-package" Statement

   The "uses-package" statement is used to indicate that support for an
   another YANG package.  It takes as an argument the name of the YANG
   package to use, followed by a block of substatements that hold
   detailed server support requirements.

   A "uses-package" statement MUST NOT specify any YANG package name
   that would create a dependency loop, such that the package containing
   the "uses-package" statement would be required to use itself.

   The "uses-revision" sub-statement is required, and identifies the
   revision of the package used.







Bierman                  Expires January 7, 2016               [Page 11]


Internet-Draft                YANG Packages                    July 2015


2.3.1.  The "uses-package" Substatements

           +---------------+---------------------+-------------+
           | Substatement  | Reference           | Cardinality |
           +---------------+---------------------+-------------+
           | description   | RFC 6020bis, 7.19.3 | 0..1        |
           | reference     | RFC 6020bis, 7.19.4 | 0..1        |
           | uses-revision | 2.4                 | 1           |
           +---------------+---------------------+-------------+

                        uses-package Substatements

2.4.  The "uses-revision" Statement

   The "uses-revision" statement is a mandatory statement used to
   identify the revision date for the parent package or module statement
   uses in the YANG package.  It takes as argument a date string in the
   form "YYYY-MM-DD" where "YYYY" is the year, "MM" is the month, and
   "DD" is the day.  The "uses-revision" statement has no substatements.

2.5.  The "imports-module" Statement

   The "imports-module" statement is used to indicate that the macro-
   data from the specified module is used.  It takes as an argument the
   name of the module to import, followed by a block of substatements
   that describe detailed module import usage information.

   The "uses-revision" sub-statement is required, and identifies at
   least one revision of the module imported.  YANG permits the macro-
   data from more than one revision of a module to be used within a
   server (i.e., import using a revision-date), so multiple
   "uses-revision" statements are permitted.

2.5.1.  The "imports-module" Substatements

           +---------------+---------------------+-------------+
           | Substatement  | Reference           | Cardinality |
           +---------------+---------------------+-------------+
           | description   | RFC 6020bis, 7.19.3 | 0..1        |
           | reference     | RFC 6020bis, 7.19.4 | 0..1        |
           | uses-revision | 2.4                 | 1..n        |
           +---------------+---------------------+-------------+

                       imports-module Substatements







Bierman                  Expires January 7, 2016               [Page 12]


Internet-Draft                YANG Packages                    July 2015


2.6.  The "uses-module" Statement

   The "uses-module" statement is used to indicate support for the
   protocol accessible objects in the specified base module.  It takes
   as an argument the name of the module to use, followed by a block of
   substatements that describe detailed module usage information.

   The "uses-revision" sub-statement is required, and identifies the
   revision of the module used.

2.6.1.  The "uses-module" Substatements

           +---------------+---------------------+-------------+
           | Substatement  | Reference           | Cardinality |
           +---------------+---------------------+-------------+
           | description   | RFC 6020bis, 7.19.3 | 0..1        |
           | reference     | RFC 6020bis, 7.19.4 | 0..1        |
           | uses-revision | 2.4                 | 1           |
           | uses-feature  | 2.7                 | 0..n        |
           +---------------+---------------------+-------------+

                         uses-module Substatements

2.7.  The "uses-feature" Statement

   The "uses-feature" statement is used to indicate that the specified
   YANG feature is used in the YANG package.  It takes as argument the
   name of the YANG feature that is required, and is followed by a block
   of substatements that describe the YANG feature usage within the YANG
   package.

2.7.1.  The "uses-feature" Substatements

           +--------------+---------------------+-------------+
           | Substatement | Reference           | Cardinality |
           +--------------+---------------------+-------------+
           | description  | RFC 6020bis, 7.19.3 | 0..1        |
           | reference    | RFC 6020bis, 7.19.4 | 0..1        |
           +--------------+---------------------+-------------+

                        uses-feature Substatements

2.8.  The "uses-capability" Statement

   The "uses-capability" statement is used to indicate that the
   specified protocol capability URI is used in the YANG package.  It
   takes as argument a URI string identifying the protocol capability




Bierman                  Expires January 7, 2016               [Page 13]


Internet-Draft                YANG Packages                    July 2015


   that is used, and is followed by a block of substatements that
   describe the protocol capability usage within the YANG package.

2.8.1.  The "uses-capability" Substatements

          +----------------+---------------------+-------------+
          | Substatement   | Reference           | Cardinality |
          +----------------+---------------------+-------------+
          | description    | RFC 6020bis, 7.19.3 | 0..1        |
          | reference      | RFC 6020bis, 7.19.4 | 0..1        |
          | uses-parameter | 2.9                 | 0..n        |
          +----------------+---------------------+-------------+

                       uses-capability Substatements

2.9.  The "uses-parameter" Statement

   The "uses-parameter" statement is used to indicate that the specified
   URI parameter for the parent "uses-capability" statement is used in
   the YANG package.

   It takes as argument a string identifying the parameter name that is
   used, and MAY be followed by a block of substatements that describe
   the protocol parameter usage within the YANG package.

   If this parameter appears more than once within a "uses-capability"
   statement then all the specified parameters are used in the YANG
   package.

2.9.1.  The "uses-parameter" Substatements

           +--------------+---------------------+-------------+
           | Substatement | Reference           | Cardinality |
           +--------------+---------------------+-------------+
           | description  | RFC 6020bis, 7.19.3 | 0..1        |
           | reference    | RFC 6020bis, 7.19.4 | 0..1        |
           | uses-value   | 2.10                | 0..n        |
           +--------------+---------------------+-------------+

                       uses-parameter Substatements

   Usage Example:









Bierman                  Expires January 7, 2016               [Page 14]


Internet-Draft                YANG Packages                    July 2015


     package example-url {
       description
          "A package for requiring that the scheme parameter
           be present in the :url capability. Any value is
           allowed.";
       uses-capability
          "urn:ietf:params:netconf:capability:url:1.0" {
          description
            "Support for the :url capability is required.";
          reference "RFC 6241, section 8.8";
          uses-parameter scheme {
            description
              "Support for the scheme parameter is required.";
            reference "RFC 6241, section 8.8.3";
          }
       }
     }

2.10.  The "uses-value" Statement

   The "uses-value" statement is used to indicate a parameter value used
   in the parent "uses-capability" statement.

   It takes as argument a string identifying a parameter value that is
   used, and MAY be followed by a block of substatements that describe
   the protocol parameter value usage within the YANG package.

2.10.1.  The "uses-value" Substatements

           +--------------+---------------------+-------------+
           | Substatement | Reference           | Cardinality |
           +--------------+---------------------+-------------+
           | description  | RFC 6020bis, 7.19.3 | 0..1        |
           | reference    | RFC 6020bis, 7.19.4 | 0..1        |
           +--------------+---------------------+-------------+

                         uses-value Substatements

   Usage Example












Bierman                  Expires January 7, 2016               [Page 15]


Internet-Draft                YANG Packages                    July 2015


     package example-url-ftp {
       description
         "A profile for requiring FTP support for the 'url'
          capability.";
       uses-capability
         "urn:ietf:params:netconf:capability:url:1.0" {
         description
           "Support for the :url capability is required.";
         reference "RFC 6241, section 8.8";
         uses-parameter scheme {
           description
             "Support for the 'scheme' parameter is required.";
           reference "RFC 6241, section 8.8.3";
           uses-value ftp {
             description
               "Support for 'ftp' transfer is required.";
           }
         }
       }
     }

3.  Updating a YANG Package

   If a YANG package is modified then a new "revision" statement MUST be
   added identifying the new revision date.  There are no other YANG
   package update restrictions.

4.  YANG Package Identifier

   The YANG Package Identifier is a URI, used to identify a YANG package
   within a protocol capability URI.  This document does not specify any
   protocol procedures for advertisement of a YANG Package Identifier.

   The YANG Package Identifier MUST match the rule for a "pkg-uri":

      pkg-uri             = yang-pkg-uri parameter-list
      parameter-list      = "?" pkg-parameter "&" rev-parameter
      pkg-parameter       = "name=" package-name
      rev-parameter       = "rev=" revision-date

   Where:

   o  "yang-pkg-uri" is the IANA-assigned URI to identify a YANG package

   o  "package-name" is the name of the YANG package

   o  "revision-date" is the revision date of the YANG package




Bierman                  Expires January 7, 2016               [Page 16]


Internet-Draft                YANG Packages                    July 2015


   Both parameters MUST be present in the YANG Package Identifier.

   Example: (wrapped for display purposes only)

     urn:ietf:params:xml:ns:yang:pkg?name=example-routing-pkg
        &rev=2015-07-01

5.  YANG Package ABNF

   The following ABNF grammar is defined in accordance with [RFC5234]
   and [RFC7405].

   Within the ABNF grammar, unordered statements are marked with
   comments.

   This grammar assumes that the scanner replaces YANG comments with a
   single space character.

    <CODE BEGINS> file "yang-package.abnf"

        package-stmt     = optsep package-keyword sep identifier-arg-str
                           optsep
                           "{" stmtsep
                               [yang-package-version-stmt]
                               meta-stmts
                               [status-stmt stmtsep]
                               req-revision-stmts
                               package-body-stmts
                           "}" optsep

        yang-package-version-stmt   = yang-package-version-keyword sep
                                  yang-package-version-arg-str
                                  optsep stmtend

        yang-package-version-arg-str = < a string that matches the rule
                                   yang-package-version-arg >

        yang-package-version-arg    = "1"

        req-revision-stmts = 1*(revision-stmt stmtsep)

        uses-revision-stmt = revision-keyword sep date-arg-str stmtend

        package-body-stmts  = *((uses-package-stmt /
                                 uses-module-stmt /
                                 imports-module-stmt /
                                 uses-capability-stmt) stmtsep)




Bierman                  Expires January 7, 2016               [Page 17]


Internet-Draft                YANG Packages                    July 2015


        uses-package-stmt = uses-package-keyword sep
                          identifier-arg-str optsep
                          (";" /
                           "{" stmtsep
                               ;; these stmts can appear in any order
                               uses-revision-stmt stmtsep
                               [description-stmt stmtsep]
                               [reference-stmt stmtsep]
                           "}")

        uses-module-stmt = uses-module-keyword sep
                          identifier-arg-str optsep
                          (";" /
                           "{" stmtsep
                               ;; these stmts can appear in any order
                               uses-revision-stmt stmtsep
                               [description-stmt stmtsep]
                               [reference-stmt stmtsep]
                               *(uses-feature-stmt stmtsep)
                           "}")

        uses-feature-stmt = uses-feature-keyword sep
                          identifier-arg-str optsep
                          (";" /
                           "{" stmtsep
                               ;; these stmts can appear in any order
                               [description-stmt stmtsep]
                               [reference-stmt stmtsep]
                           "}")

        imports-module-stmt = imports-module-keyword sep
                          identifier-arg-str optsep
                          (";" /
                           "{" stmtsep
                               ;; these stmts can appear in any order
                               uses-revision-stmt stmtsep
                               [description-stmt stmtsep]
                               [reference-stmt stmtsep]
                           "}")

        uses-capability-stmt = uses-capability-keyword sep
                        uri-str optsep
                        (";" /
                         "{" stmtsep
                             ;; these stmts can appear in any order
                             [description-stmt stmtsep]
                             [reference-stmt stmtsep]
                             *(uses-parameter-stmt stmtsep)



Bierman                  Expires January 7, 2016               [Page 18]


Internet-Draft                YANG Packages                    July 2015


                         "}")

        uses-parameter-stmt = uses-parameter-keyword sep
                          identifier-arg-str optsep
                          (";" /
                           "{" stmtsep
                               ;; these stmts can appear in any order
                               [description-stmt stmtsep]
                               [reference-stmt stmtsep]
                               *(uses-value-stmt stmtsep)
                           "}")

        uses-value-stmt = uses-value-keyword sep
                          value-arg-str optsep
                          (";" /
                           "{" stmtsep
                               ;; these stmts can appear in any order
                               [description-stmt stmtsep]
                               [reference-stmt stmtsep]
                           "}")

        value-arg-str = <string containing parameter value>


        ;; new keywords
        imports-module-keyword   = 'imports-module'
        package-keyword          = 'package'
        uses-revision-keyword    = 'uses-revision'
        uses-capability-keyword  = 'uses-capability'
        uses-feature-keyword     = 'uses-feature'
        uses-module-keyword      = 'uses-module'
        uses-parameter-keyword   = 'uses-parameter'
        uses-package-keyword     = 'uses-package'
        uses-value-keyword       = 'uses-value'
        yang-package-version-keyword = 'yang-package-version'

        ;; the following rules are defined in RFC 6020bis, section 12
        description-stmt
        identifier-arg-str
        meta-stmts
        opt-set
        reference-stmt
        revision-keyword
        revision-stmt
        status-stmt
        stmtsep
        uri-str




Bierman                  Expires January 7, 2016               [Page 19]


Internet-Draft                YANG Packages                    July 2015


      <CODE ENDS>

6.  IANA Considerations

   TODO: The YANG Package Identifier URI needs to be registered

7.  Security Considerations

   No security threats are introduced by this document.  This document
   describes mechanisms for specifying collections of YANG modules and
   protocol capabilities.  It does not describe any protocol
   interactions or conceptual interface, such as a YANG module.

   However, if the YANG package list supported by a device is advertised
   by a server, it may help an attacker identify the server capabilities
   and server implementations with known bugs.  Server vulnerabilities
   may be specific to particular modules, module revisions, or module
   features.  This information may be included in a YANG package
   instance document.

8.  References

8.1.  Normative References

   [I-D.ietf-netmod-rfc6020bis]
              Bjorklund, M., "YANG - A Data Modeling Language for the
              Network Configuration Protocol (NETCONF)", draft-ietf-
              netmod-rfc6020bis-06 (work in progress), July 2015.

   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
              Requirement Levels", BCP 14, RFC 2119, March 1997.

   [RFC5234]  Crocker, D. and P. Overell, "Augmented BNF for Syntax
              Specifications: ABNF", STD 68, RFC 5234, January 2008.

   [RFC7405]  Kyzivat, P., "Case-Sensitive String Support in ABNF", RFC
              7405, December 2014.

8.2.  Informative References

   [I-D.bogdanovic-netmod-yang-model-classification]
              Bogdanovic, D., Claise, B., and C. Moberg, "YANG model
              classification", draft-bogdanovic-netmod-yang-model-
              classification-03 (work in progress), June 2015.







Bierman                  Expires January 7, 2016               [Page 20]


Internet-Draft                YANG Packages                    July 2015


   [I-D.ietf-netconf-restconf]
              Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF
              Protocol", draft-ietf-netconf-restconf-06 (work in
              progress), June 2015.

   [RFC6241]  Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed.,
              and A. Bierman, Ed., "Network Configuration Protocol
              (NETCONF)", RFC 6241, June 2011.

   [RFC7223]  Bjorklund, M., "A YANG Data Model for Interface
              Management", RFC 7223, May 2014.

Appendix A.  Change Log

       -- RFC Ed.: remove this section before publication.

A.1.  bierman-yang-conformance-03 to bierman-yang-package-00

   o  removed all mention of YANG conformance since YANG packages do not
      specify new YANG conformance mechanisms.

Author's Address

   Andy Bierman
   YumaWorks

   Email: andy@yumaworks.com
























Bierman                  Expires January 7, 2016               [Page 21]


Html markup produced by rfcmarkup 1.129c, available from https://tools.ietf.org/tools/rfcmarkup/