Internet Architecture Board (IAB) K. Watsen Internet-Draft Juniper Networks Updates: 7991 (if approved) April 18, 2018 Intended status: Informational Expires: October 20, 2018 Automation for Source Code in Drafts draft-yd-iab-sourcecode-automation-00 Abstract This draft updates the "xml2rfc" vocabulary defined in RFC 7991 in order to support automatic validation of supported content and automatic generation of derived views for supported content. 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 October 20, 2018. Copyright Notice Copyright (c) 2018 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. Watsen Expires October 20, 2018 [Page 1] Internet-Draft Automation for Source Code in Drafts April 2018 Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 2. Requirements Language . . . . . . . . . . . . . . . . . . . . 3 3. Updates to RFC 7991 . . . . . . . . . . . . . . . . . . . . . 3 3.1. The Element . . . . . . . . . . . . . . . . . . 3 3.2. The Element . . . . . . . . . . . . . . . . 3 4. Relation to Previous Work . . . . . . . . . . . . . . . . . . 3 4.1. Previous Work . . . . . . . . . . . . . . . . . . . . . . 3 4.2. Relation . . . . . . . . . . . . . . . . . . . . . . . . 4 5. YANG Doctor Automation . . . . . . . . . . . . . . . . . . . 4 5.1. Validating Tree Diagrams . . . . . . . . . . . . . . . . 4 5.2. Validating YANG Modules . . . . . . . . . . . . . . . . . 5 5.3. Validating Examples Conform to Schema . . . . . . . . . . 5 6. Solution . . . . . . . . . . . . . . . . . . . . . . . . . . 6 6.1. The Element . . . . . . . . . . . . . . . . . . 6 6.2. The Element . . . . . . . . . . . . . . . . 6 6.3. Rendering Long Lines . . . . . . . . . . . . . . . . . . 7 7. Security Considerations . . . . . . . . . . . . . . . . . . . 7 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 7 9. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 7 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 7 10.1. Normative References . . . . . . . . . . . . . . . . . . 7 10.2. Informative References . . . . . . . . . . . . . . . . . 8 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 9 1. Introduction This draft updates the "xml2rfc" vocabulary defined in [RFC7991] in order to support automatic validation of supported content and automatic generation of derived views for supported content. The driving motivation for this update is to automate, as much as possible, a review performed by a YANG Doctor [yang-doctors], but the solution is intended to be extendable to technologies other than YANG [RFC6020] [RFC7950], such as ASN.1 [ITU.X690.2015] and ABNF [RFC5234] [RFC7405]. While the solution presented in this document facilitates "doctor" reviews (MIB, YANG, etc.), experience shows that doctor reviews are often out of synch with the document submitted for publication, some times by several draft revisions. Thusly, it is currently common practice for the draft's shepherd to make some attempt at verifying the correctness of artwork containing structured code. And, of course, as the document progresses in the publication process, it may be subsequently updated by IESG and/or RFC Editor reviews. By Watsen Expires October 20, 2018 [Page 2] Internet-Draft Automation for Source Code in Drafts April 2018 enabling the verification to be automated, correctness can be more assured thoughout the publication process. 2. Requirements Language The key words "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] [RFC8174] when, and only when, they appear in all capitals, as shown here. 3. Updates to RFC 7991 3.1. The Element This document modifies the element defined in Section 2.5 of [RFC7991] by: o introducing some new optional attributes o adding a new "preferred value" for the "type" attribute. 3.2. The Element This document modifies the element defined in Section 2.48 of [RFC7991] by: o introducing some new optional attributes All updates to [RFC7991] are described in Section 6 of this document. 4. Relation to Previous Work 4.1. Previous Work Previous work includes: o Section 3.2 of [I-D.ietf-netmod-rfc6087bis] states that normative YANG modules and submodules contained within Internet-Drafts and RFCs must be bracketed by "" and "" markers. o The "xym" utility [xym] has been developed to extract said YANG modules from Internet-Drafts and RFCs. o The RFC Submit [rfc-submit] tool has been modified to test YANG modules contained within I-Ds, and the resulting document page in Datatracker [datatracker] displays a new "Yang Validation" field Watsen Expires October 20, 2018 [Page 3] Internet-Draft Automation for Source Code in Drafts April 2018 containing a varying color yin-yang symbol (green if no errors, red if errors) along with counts. 4.2. Relation The solution described in this document overlaps with Datatracker's ability to validate YANG modules. However, it does so with the following benefits: o The solution could be built into a utility (e.g., xml2rfc) and thus be available outside of the RFC Submit process. o The solution enables the validation of more than just YANG modules; it additionally supports validating tree-diagrams and instance examples. The solution described in this document overlaps with the "" and "" markers. However, it does so with the following benefits: o The solution eliminates the need for authors to have to put these markers into their documents directly. o Since tooling generates the "" marker, ensuring consistency of the "file " value would no longer be a manual effort. 5. YANG Doctor Automation The parts of a YANG Doctor review that can be automated are discussed in this section. Other parts of a YANG Doctor review cannot be automated, but at least time isn't wasted ensuring what's contained in the I-D is valid. 5.1. Validating Tree Diagrams Reviewing the tree diagrams [RFC8340] for the modules contained in the draft is a common first step, as the tree diagrams offer a high- level view of a module as a whole, which is very helpful to understand prior to examining the module in detail. Typically, drafts containing YANG modules already contain tree diagrams, as is recommended by Section 3.4 of [I-D.ietf-netmod-rfc6087bis], but there is no assurance that the tree diagrams are current, and sometimes, more often than should be the case, they are not. Watsen Expires October 20, 2018 [Page 4] Internet-Draft Automation for Source Code in Drafts April 2018 Thus, in order to trust any provided tree diagrams provided entails first validating that they are correct and, since there is no way to "validate" a tree diagram, typically new diagrams are generated and compared against what was provided. Generating the tree diagrams may require guesswork to ascertain which set of commandline parameters were used to generate each particular diagram. The need to reverse engineer the commands introduces further delay. 5.2. Validating YANG Modules Validating the YANG modules contained in a document is a common first step, one that likely occurs while generating fresh tree diagrams to review (see previous section). The YANG Doctor typically extracts the YANG modules using the "xym" utility. Sometimes this step fails due to an incorrect line, thus the YANG Doctor also needs to verify that such lines are set correctly as well. YANG module validations often require access to all imported, potentially recursively imported, modules that may come from other I-Ds and/or RFCs. Thus, it is often necessary for the YANG Doctor to also track down and extract the YANG module from the RFC or I-D referenced by 'import' statements, introduction further delay. 5.3. Validating Examples Conform to Schema Validating the examples of YANG module usage contained in a document is an important step, as many times the examples are the best way to see how things work. Validating examples requires the YANG doctor to have to manually extract the examples, because "xym" doesn't, and determine the correct commandline parameters needed to validate each example, which can introduce delay. Sometimes extracting examples is additionally complicated by needed to reconstitute the original documents, before having been modified to fit the line-length requirements. E.g., a trailing '\' character on a line might signal the need to remove the following CRLF character(s). In order to validate some examples, it is neccessary to supply additional instance documents to, for instance, to provide the target of a leafref. Sometimes these instance documents need to be Watsen Expires October 20, 2018 [Page 5] Internet-Draft Automation for Source Code in Drafts April 2018 generated out of thin-air, as they are otherwise not published in any draft. Doing this is both error-prone and introduces delay. 6. Solution This section details the proposed changes to RFC 7991 [RFC7991]. 6.1. The Element Modifications to existing attributes: o Section 2.5.7 of RFC 7991 defines the "type" attribute along with "preferred values": ascii-art, binary-art, call-flow, hex-dump, and svg. This document adds one more preferred value called "yang-tree-diagram". Introduction of new attributes: gen: The "gen" (for "generate") attribute indicates that the given artwork may be programmatically generated using a provided command. For example, the following does not use inline content or the "src" attribute: [ '\' added for formatting reasons ] . [RFC7991] Hoffman, P., "The "xml2rfc" Version 3 Vocabulary", RFC 7991, DOI 10.17487/RFC7991, December 2016, . Watsen Expires October 20, 2018 [Page 7] Internet-Draft Automation for Source Code in Drafts April 2018 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017, . 10.2. Informative References [datatracker] "Datatracker Documents", . [I-D.ietf-netmod-rfc6087bis] Bierman, A., "Guidelines for Authors and Reviewers of YANG Data Model Documents", draft-ietf-netmod-rfc6087bis-20 (work in progress), March 2018. [ITU.X690.2015] International Telecommunication Union, "Information Technology - ASN.1 encoding rules: Specification of Basic Encoding Rules (BER), Canonical Encoding Rules (CER) and Distinguished Encoding Rules (DER)", ITU-T Recommendation X.690, ISO/IEC 8825-1, August 2015, . [rfc-submit] "Internet-Draft submission", . [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax Specifications: ABNF", STD 68, RFC 5234, DOI 10.17487/RFC5234, January 2008, . [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for the Network Configuration Protocol (NETCONF)", RFC 6020, DOI 10.17487/RFC6020, October 2010, . [RFC7405] Kyzivat, P., "Case-Sensitive String Support in ABNF", RFC 7405, DOI 10.17487/RFC7405, December 2014, . [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", RFC 7950, DOI 10.17487/RFC7950, August 2016, . [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, . Watsen Expires October 20, 2018 [Page 8] Internet-Draft Automation for Source Code in Drafts April 2018 [xym] "YANG Module Extraction Tool", . [yang-doctors] "YANG Doctors", . Author's Address Kent Watsen Juniper Networks EMail: kwatsen@juniper.net Watsen Expires October 20, 2018 [Page 9]