idnits 2.17.1 draft-lhotka-netmod-yang-markup-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (March 09, 2017) is 2598 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Possible downref: Non-RFC (?) normative reference: ref. 'IANA-MEDIA-TYPES' Summary: 0 errors (**), 0 flaws (~~), 1 warning (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 NETMOD Working Group L. Lhotka 3 Internet-Draft CZ.NIC 4 Intended status: Standards Track March 09, 2017 5 Expires: September 10, 2017 7 Using Markup in YANG Text Arguments 8 draft-lhotka-netmod-yang-markup-00 10 Abstract 12 This document defines a YANG extension that allows for specifying a 13 media type for text in the arguments of these YANG statements: 14 "contact", "description", "error-message", "organization" and 15 "reference." 17 Status of This Memo 19 This Internet-Draft is submitted in full conformance with the 20 provisions of BCP 78 and BCP 79. 22 Internet-Drafts are working documents of the Internet Engineering 23 Task Force (IETF). Note that other groups may also distribute 24 working documents as Internet-Drafts. The list of current Internet- 25 Drafts is at http://datatracker.ietf.org/drafts/current/. 27 Internet-Drafts are draft documents valid for a maximum of six months 28 and may be updated, replaced, or obsoleted by other documents at any 29 time. It is inappropriate to use Internet-Drafts as reference 30 material or to cite them other than as "work in progress." 32 This Internet-Draft will expire on September 10, 2017. 34 Copyright Notice 36 Copyright (c) 2017 IETF Trust and the persons identified as the 37 document authors. All rights reserved. 39 This document is subject to BCP 78 and the IETF Trust's Legal 40 Provisions Relating to IETF Documents 41 (http://trustee.ietf.org/license-info) in effect on the date of 42 publication of this document. Please review these documents 43 carefully, as they describe your rights and restrictions with respect 44 to this document. Code Components extracted from this document must 45 include Simplified BSD License text as described in Section 4.e of 46 the Trust Legal Provisions and are provided without warranty as 47 described in the Simplified BSD License. 49 Table of Contents 51 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 52 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 53 3. Declaring the Media Type of Text Arguments . . . . . . . . . 3 54 4. YANG Module . . . . . . . . . . . . . . . . . . . . . . . . . 4 55 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 6 56 6. Security Considerations . . . . . . . . . . . . . . . . . . . 7 57 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 7 58 7.1. Normative References . . . . . . . . . . . . . . . . . . 7 59 7.2. Informative References . . . . . . . . . . . . . . . . . 7 60 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 8 62 1. Introduction 64 Descriptions play an important role in YANG data models. They may 65 specify normative semantic constraints that cannot be expressed 66 formally, instructions for implementors of the data model, and other 67 vital information. That is why descriptions often comprise several 68 paragraphs of text and sometimes also other structures such all 69 numbered or bulleted lists. 71 So far, YANG modules have mostly used only plain text in the argument 72 of the "description" statement, i.e., formatted text structures using 73 just whitespace. This is generally sufficient for human readers and 74 also for including YANG modules in RFC documents, but less so for 75 tools that are designed to process or use YANG modules in other ways, 76 for example: 78 o converting YANG compact syntax to other formats (YIN, HTML) 80 o including YANG modules in standards and other documents whose 81 source form in not plain text 83 o including description text in user interface elements. 85 The above considerations also apply, albeit to a lesser extent, to 86 other YANG statements with more structured arguments: "contact", 87 "error-message", "organization" and "reference". 89 In principle, it is possible to use any kind of markup such as 90 markdown [RFC7764] but doing so would not be not very effective and 91 tool-friendly unless the markup format is either standardized or 92 declared in the module source. 94 This document defines a YANG extension statement, "text-media-type", 95 that can be placed as a substatement of the "module" or "submodule" 96 statement to indicate the media type that is used throughout the 97 (sub)module for markup in the arguments of the five YANG statements 98 mentioned above. 100 2. Terminology 102 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 103 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 104 document are to be interpreted as described in [RFC2119]. 106 3. Declaring the Media Type of Text Arguments 108 Section 4 below contains the "ietf-yang-text-media-type" module that 109 defines a YANG language extension: "text-media-type". Its purpose is 110 to declare media type that is used for markup in the arguments of the 111 following YANG statements: 113 o contact 115 o description 117 o error-message 119 o organization 121 o reference 123 The common characteristic of these five statements is that their 124 argument is represented as the element in YIN format 125 (Section 13 of [RFC7950]). 127 The "text-media-type" extension is intended to be used at the top 128 level of a YANG module or submodule, i.e., as a substatement of 129 either "module" or "submodule" statement. The declared media type 130 applies to arguments of the above YANG statements throughout the 131 module or submodule. 133 The "text-media-type" extension MAY be ignored, and a module in which 134 it appears MUST be valid YANG. 136 The argument of the "text-media-type" extension is a string 137 specifying the media type in the format defined in [RFC6838]. The 138 media type SHOULD be registered by IANA in the "text" registry 139 [IANA-MEDIA-TYPES]. Media type parameters MAY be used. 141 It is RECOMMENDED to use only media types representing "lightweight" 142 markup that is easy to read even in the unprocessed source form, such 143 as "text/markdown". 145 YANG modules have to be use the UTF-8 character encoding, see 146 Section 6 of [RFC7950]. This implies the following rules: 148 o Whenever the "charset" parameter is present, its value MUST be 149 "UTF-8". 151 o If no default value is defined for the "charset" parameter of a 152 given media type, or if a default value is defined but is 153 different from "UTF-8", then the "charset" parameter MUST be 154 present with the value of "UTF-8". 156 Even if the "text-media-type" extension statement is present and 157 markup used in text arguments, all YANG and YIN syntax rules still 158 apply. 160 The "ietf-yang-text-media-type" module not only defines but also uses 161 the "text-media-type" extension statement, which illustrates its 162 typical use. 164 4. YANG Module 166 RFC Editor: In this section, replace all occurrences of 'XXXX' with 167 the actual RFC number and all occurrences of the revision date below 168 with the date of RFC publication (and remove this note). 170 file "ietf-yang-text-media-type@2017-03-09.yang" 172 module ietf-yang-text-media-type { 174 namespace "urn:ietf:params:xml:ns:yang:ietf-yang-text-media-type"; 176 prefix ymt; 178 ymt:text-media-type "text/markdown; charset=UTF-8"; 180 organization 181 "IETF NETMOD (NETCONF Data Modeling Language) Working Group"; 183 contact 184 "WG Web: 185 WG List: 187 WG Chair: Lou Berger 188 190 WG Chair: Kent Watsen 191 193 Editor: Ladislav Lhotka 194 "; 196 description 197 "This module defines the *text-media-type* extension that allows 198 for specifying media-type for markup that is used in arguments 199 of these YANG statements: contact, description, error-message, 200 organization, and reference. 202 Copyright (c) 2016 IETF Trust and the persons identified as 203 authors of the code. All rights reserved. 205 Redistribution and use in source and binary forms, with or 206 without modification, is permitted pursuant to, and subject to 207 the license terms contained in, the Simplified BSD License set 208 forth in Section 4.c of the IETF Trust's Legal Provisions 209 Relating to IETF Documents 210 (https://trustee.ietf.org/license-info). 212 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL 213 NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'MAY', and 214 'OPTIONAL' in the module text are to be interpreted as described 215 in RFC 2119 (https://tools.ietf.org/html/rfc2119). 217 This version of this YANG module is part of RFC XXXX 218 (https://tools.ietf.org/html/rfcXXXX); see the RFC itself for 219 full legal notices."; 221 revision 2017-03-09 { 222 description 223 "Initial revision."; 224 reference 225 "RFC XXXX: Using Markup in YANG Text Arguments"; 226 } 228 extension text-media-type { 229 argument type; 230 description 231 "This extension allows for specifying a media type that is used 232 for markup in the arguments of the following YANG statements: 234 - contact 236 - description 238 - error-message 240 - organization 241 - reference 243 The *text-media-type* extension statement MAY be used at the 244 top level of a module or submodule, i.e., as a substatement of 245 *module* or *submodule*, and no more than once. The declared 246 media type applies throughout the module or submodule. 248 The argument SHOULD be a media type registered by IANA in the 249 *text* registry. Media type parameters MAY be present. 251 This YANG extension is only indicative and optional to 252 implement. Tools MAY ignore it completely or support just a 253 subset of markup directives that are available for a given 254 media type."; 255 reference 256 "- IANA: Media Types, 2016-12-21. Available [online] 257 (http://www.iana.org/assignments/media-types/media-types.xhtml) 259 - [RFC 6838](https://tools.ietf.org/html/rfc6838): Media Type 260 Specifications and Registration Procedures"; 261 } 262 } 264 266 5. IANA Considerations 268 RFC Editor: In this section, replace all occurrences of 'XXXX' with 269 the actual RFC number and all occurrences of the revision date below 270 with the date of RFC publication (and remove this note). 272 This document registers the following namespace URI in the "IETF XML 273 registry" [RFC3688]: 275 URI: urn:ietf:params:xml:ns:yang:ietf-yang-text-media-type 276 Registrant Contact: The IESG. 277 XML: N/A, the requested URI is an XML namespace. 279 This document registers the following YANG module in the "YANG Module 280 Names" registry [RFC6020]: 282 Name: ietf-yang-text-media-type 283 Namespace: urn:ietf:params:xml:ns:yang:ietf-yang-text-media-type 284 Prefix: ymt 285 Reference: RFC XXXX 287 6. Security Considerations 289 The "text-media-type" extension defined in this document provides 290 information that is completely optional. YANG modules and submodules 291 in which it is present have to satisfy all rules of the YANG 292 language. The extension therefore doen't introduce any new threats. 294 7. References 296 7.1. Normative References 298 [IANA-MEDIA-TYPES] 299 Internet Assigned Numbers Authority, "Media Types", 12 300 2016. 302 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 303 Requirement Levels", BCP 14, RFC 2119, 304 DOI 10.17487/RFC2119, March 1997, 305 . 307 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 308 DOI 10.17487/RFC3688, January 2004, 309 . 311 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 312 the Network Configuration Protocol (NETCONF)", RFC 6020, 313 DOI 10.17487/RFC6020, October 2010, 314 . 316 [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type 317 Specifications and Registration Procedures", BCP 13, 318 RFC 6838, DOI 10.17487/RFC6838, January 2013, 319 . 321 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 322 RFC 7950, DOI 10.17487/RFC7950, August 2016, 323 . 325 7.2. Informative References 327 [RFC7764] Leonard, S., "Guidance on Markdown: Design Philosophies, 328 Stability Strategies, and Select Registrations", RFC 7764, 329 DOI 10.17487/RFC7764, March 2016, 330 . 332 Author's Address 334 Ladislav Lhotka 335 CZ.NIC 337 Email: lhotka@nic.cz