Guidelines for Authors and Reviewers of YANG Data Model Documents
RFC 6087

Internet Engineering Task Force (IETF)                        A. Bierman
Request for Comments: 6087                                       Brocade
Category: Informational                                     January 2011
ISSN: 2070-1721

   Guidelines for Authors and Reviewers of YANG Data Model Documents

Abstract

   This memo provides guidelines for authors and reviewers of Standards
   Track specifications containing YANG data model modules.  Applicable
   portions may be used as a basis for reviews of other YANG data model
   documents.  Recommendations and procedures are defined, which are
   intended to increase interoperability and usability of Network
   Configuration Protocol (NETCONF) implementations that utilize YANG
   data model modules.

Status of This Memo

   This document is not an Internet Standards Track specification; it is
   published for informational purposes.

   This document is a product of the Internet Engineering Task Force
   (IETF).  It represents the consensus of the IETF community.  It has
   received public review and has been approved for publication by the
   Internet Engineering Steering Group (IESG).  Not all documents
   approved by the IESG are a candidate for any level of Internet
   Standard; see Section 2 of RFC 5741.

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

Copyright Notice

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

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

Bierman                       Informational                     [Page 1]
RFC 6087              Guidelines for YANG Documents         January 2011

Table of Contents

   1.  Introduction . . . . . . . . . . . . . . . . . . . . . . . . .  3
   2.  Terminology  . . . . . . . . . . . . . . . . . . . . . . . . .  3
     2.1.  Requirements Notation  . . . . . . . . . . . . . . . . . .  3
     2.2.  NETCONF Terms  . . . . . . . . . . . . . . . . . . . . . .  4
     2.3.  YANG Terms . . . . . . . . . . . . . . . . . . . . . . . .  4
     2.4.  Terms  . . . . . . . . . . . . . . . . . . . . . . . . . .  4
   3.  General Documentation Guidelines . . . . . . . . . . . . . . .  5
     3.1.  Module Copyright . . . . . . . . . . . . . . . . . . . . .  5
     3.2.  Narrative Sections . . . . . . . . . . . . . . . . . . . .  6
     3.3.  Definitions Section  . . . . . . . . . . . . . . . . . . .  6
     3.4.  Security Considerations Section  . . . . . . . . . . . . .  6
     3.5.  IANA Considerations Section  . . . . . . . . . . . . . . .  7
       3.5.1.  Documents that Create a New Namespace  . . . . . . . .  7
       3.5.2.  Documents that Extend an Existing Namespace  . . . . .  8
     3.6.  Reference Sections . . . . . . . . . . . . . . . . . . . .  8
   4.  YANG Usage Guidelines  . . . . . . . . . . . . . . . . . . . .  8
     4.1.  Module Naming Conventions  . . . . . . . . . . . . . . . .  8
     4.2.  Identifiers  . . . . . . . . . . . . . . . . . . . . . . .  9
     4.3.  Defaults . . . . . . . . . . . . . . . . . . . . . . . . .  9
     4.4.  Conditional Statements . . . . . . . . . . . . . . . . . . 10
     4.5.  XPath Usage  . . . . . . . . . . . . . . . . . . . . . . . 10
     4.6.  Lifecycle Management . . . . . . . . . . . . . . . . . . . 11
     4.7.  Module Header, Meta, and Revision Statements . . . . . . . 12
     4.8.  Namespace Assignments  . . . . . . . . . . . . . . . . . . 13
     4.9.  Top-Level Data Definitions . . . . . . . . . . . . . . . . 14
     4.10. Data Types . . . . . . . . . . . . . . . . . . . . . . . . 14
     4.11. Reusable Type Definitions  . . . . . . . . . . . . . . . . 15
     4.12. Data Definitions . . . . . . . . . . . . . . . . . . . . . 15
     4.13. Operation Definitions  . . . . . . . . . . . . . . . . . . 17
     4.14. Notification Definitions . . . . . . . . . . . . . . . . . 17
   5.  IANA Considerations  . . . . . . . . . . . . . . . . . . . . . 17
   6.  Security Considerations  . . . . . . . . . . . . . . . . . . . 18
     6.1.  Security Considerations Section Template . . . . . . . . . 19
   7.  Acknowledgments  . . . . . . . . . . . . . . . . . . . . . . . 20
   8.  References . . . . . . . . . . . . . . . . . . . . . . . . . . 20