idnits 2.17.1 draft-clacla-netmod-model-catalog-03.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 : ---------------------------------------------------------------------------- ** There are 139 instances of too long lines in the document, the longest one being 65 characters in excess of 72. ** The document seems to lack a both a reference to RFC 2119 and the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. RFC 2119 keyword, line 438: '..."maturity-level" MUST be "not-applicab...' RFC 2119 keyword, line 447: '...expire, the "expired" leaf MUST be set...' RFC 2119 keyword, line 1152: '... prefix string MAY be used to refer ...' RFC 2119 keyword, line 1176: '...of interoperability, it is RECOMMENDED...' RFC 2119 keyword, line 1358: '... modules, so the same entry MAY appear...' (3 more instances...) Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 202 has weird spacing: '...evision uni...' == Line 218 has weird spacing: '...version str...' == Line 226 has weird spacing: '...evision uni...' == Line 256 has weird spacing: '...evision uni...' == Line 293 has weird spacing: '...ication enu...' == (6 more instances...) -- The document date (April 3, 2018) is 2213 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) -- Looks like a reference, but probably isn't: '1' on line 1632 -- Looks like a reference, but probably isn't: '2' on line 1634 ** Obsolete normative reference: RFC 7895 (Obsoleted by RFC 8525) ** Downref: Normative reference to an Informational RFC: RFC 8199 Summary: 4 errors (**), 0 flaws (~~), 7 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group J. Clarke 3 Internet-Draft B. Claise 4 Intended status: Standards Track Cisco Systems, Inc. 5 Expires: October 5, 2018 April 3, 2018 7 YANG module for yangcatalog.org 8 draft-clacla-netmod-model-catalog-03 10 Abstract 12 This document specifies a YANG module that contains metadata related 13 to YANG modules and vendor implementations of those YANG modules. 15 Status of This Memo 17 This Internet-Draft is submitted in full conformance with the 18 provisions of BCP 78 and BCP 79. 20 Internet-Drafts are working documents of the Internet Engineering 21 Task Force (IETF). Note that other groups may also distribute 22 working documents as Internet-Drafts. The list of current Internet- 23 Drafts is at https://datatracker.ietf.org/drafts/current/. 25 Internet-Drafts are draft documents valid for a maximum of six months 26 and may be updated, replaced, or obsoleted by other documents at any 27 time. It is inappropriate to use Internet-Drafts as reference 28 material or to cite them other than as "work in progress." 30 This Internet-Draft will expire on October 5, 2018. 32 Copyright Notice 34 Copyright (c) 2018 IETF Trust and the persons identified as the 35 document authors. All rights reserved. 37 This document is subject to BCP 78 and the IETF Trust's Legal 38 Provisions Relating to IETF Documents 39 (https://trustee.ietf.org/license-info) in effect on the date of 40 publication of this document. Please review these documents 41 carefully, as they describe your rights and restrictions with respect 42 to this document. Code Components extracted from this document must 43 include Simplified BSD License text as described in Section 4.e of 44 the Trust Legal Provisions and are provided without warranty as 45 described in the Simplified BSD License. 47 Table of Contents 49 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 50 1.1. Status of Work and Open Issues . . . . . . . . . . . . . 3 51 2. Learning from Experience . . . . . . . . . . . . . . . . . . 3 52 2.1. YANG Module Library . . . . . . . . . . . . . . . . . . . 4 53 2.2. YANG Catalog Data Model . . . . . . . . . . . . . . . . . 4 54 2.3. Module Sub-Tree . . . . . . . . . . . . . . . . . . . . . 6 55 2.4. Compilation Information . . . . . . . . . . . . . . . . . 8 56 2.5. Maturity Level . . . . . . . . . . . . . . . . . . . . . 10 57 2.6. Generated From . . . . . . . . . . . . . . . . . . . . . 11 58 2.7. Implementation . . . . . . . . . . . . . . . . . . . . . 11 59 2.8. Vendor Sub-Tree . . . . . . . . . . . . . . . . . . . . . 12 60 2.9. Regex Expression Differences . . . . . . . . . . . . . . 13 61 3. YANG Catalog Use Cases . . . . . . . . . . . . . . . . . . . 14 62 3.1. YANG Search Metadata . . . . . . . . . . . . . . . . . . 14 63 3.2. Identify YANG Module Support in Devices . . . . . . . . . 14 64 3.3. Identify The Backward Compatibility between YANG Module 65 Revisions . . . . . . . . . . . . . . . . . . . . . . . . 14 66 4. YANG Catalog YANG module . . . . . . . . . . . . . . . . . . 17 67 5. Security Considerations . . . . . . . . . . . . . . . . . . . 35 68 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 35 69 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 35 70 7.1. Normative References . . . . . . . . . . . . . . . . . . 35 71 7.2. Informative References . . . . . . . . . . . . . . . . . 36 72 7.3. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 36 73 Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . . 36 74 Appendix B. Changes From Previous Revisions . . . . . . . . . . 37 75 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 38 77 1. Introduction 79 YANG [RFC6020] [RFC7950] became the standard data modeling language 80 of choice. Not only is it used by the IETF for specifying models, 81 but also in many Standard Development Organizations (SDOs), 82 consortia, and open-source projects: the IEEE, the Broadband Forum 83 (BFF), DMTF, MEF, ITU, OpenDaylight, Open ROADM, Openconfig, sysrepo, 84 and more. 86 With the rise of data model-driven management and the success of YANG 87 as a key piece comes a challenge: the entire industry develops YANG 88 models. In order for operators to automate coherent services, the 89 industry must ensure the following: 91 1. Data models must work together 93 2. There exists a toolchain to help one search and understand models 94 3. Metadata is present to further describe model attributes 96 The site (and the YANG catalog that it 97 provides) is an attempt to address these key tenants. From a high 98 level point of view, the goal of this catalog is to become a 99 reference for all YANG modules available in the industry, for both 100 YANG developers (to search on what exists already) and for operators 101 (to discover the more mature YANG models to automate services). This 102 YANG catalog should not only contain pointers to the YANG modules 103 themselves, but also contain metadata related to those YANG modules: 104 What is the module type (service model or not?); what is the maturity 105 level? (e.g., for the IETF: is this an RFC, a working group document 106 or an individual draft?); is this module implemented?; who is the 107 contact?; is there open-source code available? And we expect many 108 more in the future. The industry has begun to understand that the 109 metadata related to YANG models become equally important as the YANG 110 models themselves. 112 This document defines a YANG [RFC7950] module called yang- 113 catalog.yang that contains the metadata definitions that are 114 complementary to the related YANG modules themselves. The design for 115 this module is based on experience and real code. As such, it's 116 expected that this YANG module will be a living document. 117 Furthermore, new use cases, which require new metadata in this YANG 118 module, are discovered on a regular basis. 120 The yangcatalog.org instantiation of the catalog provides a means for 121 module authors and vendors implementing modules to upload their 122 metadata, which is then searchable via an API, as well as using a 123 variety of web-based tools. The instructions for contributing and 124 searching for metadata can be found at . 127 1.1. Status of Work and Open Issues 129 The top open issues are: 131 1. Obtain feedback from vendors and SDOs 133 2. Socialize module at the IETF and incorporate feedback 135 3. Provide module bundle support 137 2. Learning from Experience 139 While implementing the catalog and tools at yangcatalog.org, we 140 initially looked at the "Catalog and registry for YANG models" 141 [I-D.openconfig-netmod-model-catalog] as a starting point but we 142 quickly realized that the objectives are different. As a 143 consequence, even if some of the information is similar, this YANG 144 module started to diverge. Below are the justifications for the 145 divergence, our observations, and our learning experience as we have 146 been developing and getting feedback. 148 2.1. YANG Module Library 150 In order for the YANG catalog to become a complete inventory of which 151 models are supported on the different platforms, content such as the 152 support of the YANG module/deviation/feature/etc. should be easy to 153 import and update. An easy way to populate this information is to 154 have a similar structure as the YANG Module Library [RFC7895]. That 155 way, querying the YANG Module Library from a platform provides, 156 directly in the right format, the input for the YANG catalog 157 inventory. 159 There are some similar entries between the YANG Module Library and 160 the Openconfig catalog. For example, the Openconfig catalog model 161 defines a "uri" leaf which is similar to "schema" from [RFC7895]). 162 And this adds to the overall confusion. 164 2.2. YANG Catalog Data Model 166 The structure of the yang-catalog.yang module described in this 167 document is found below. The meaning of the symbols in this and 168 seubsequent tree diagrams in this document is explained in 169 [I-D.ietf-netmod-yang-tree-diagrams]: 171 module: yang-catalog 172 +--rw catalog 173 +--rw modules 174 | +--rw module* [name revision organization] 175 | +--rw name yang:yang-identifier 176 | +--rw revision union 177 | +--rw organization string 178 | +--rw ietf 179 | | +--rw ietf-wg? string 180 | +--rw namespace inet:uri 181 | +--rw schema? inet:uri 182 | +--rw generated-from? enumeration 183 | +--rw maturity-level? enumeration 184 | +--rw document-name? string 185 | +--rw author-email? yc:email-address 186 | +--rw reference? inet:uri 187 | +--rw module-classification enumeration 188 | +--rw compilation-status? enumeration 189 | +--rw compilation-result? inet:uri 190 | +--rw prefix? string 191 | +--rw yang-version? enumeration 192 | +--rw description? string 193 | +--rw contact? string 194 | +--rw module-type? enumeration 195 | +--rw belongs-to? yang:yang-identifier 196 | +--rw tree-type? enumeration 197 | +--rw yang-tree? inet:uri 198 | +--rw expires? yang:date-and-time 199 | +--rw expired? union 200 | +--rw submodule* [name revision] 201 | | +--rw name yang:yang-identifier 202 | | +--rw revision union 203 | | +--rw schema? inet:uri 204 | +--rw dependencies* [name] 205 | | +--rw name yang:yang-identifier 206 | | +--rw revision? union 207 | | +--rw schema? inet:uri 208 | +--rw dependents* [name] 209 | | +--rw name yang:yang-identifier 210 | | +--rw revision? union 211 | | +--rw schema? inet:uri 212 | +--rw semantic-version? yc:semver 213 | +--rw derived-semantic-version? yc:semver 214 | +--rw implementations 215 | +--rw implementation* [vendor platform software-version software-flavor] 216 | +--rw vendor string 217 | +--rw platform string 218 | +--rw software-version string 219 | +--rw software-flavor string 220 | +--rw os-version? string 221 | +--rw feature-set? string 222 | +--rw os-type? string 223 | +--rw feature* yang:yang-identifier 224 | +--rw deviation* [name revision] 225 | | +--rw name yang:yang-identifier 226 | | +--rw revision union 227 | +--rw conformance-type? enumeration 228 +--rw vendors 229 +--rw vendor* [name] 230 +--rw name string 231 +--rw platforms 232 +--rw platform* [name] 233 +--rw name string 234 +--rw software-versions 235 +--rw software-version* [name] 236 +--rw name string 237 +--rw software-flavors 238 +--rw software-flavor* [name] 239 +--rw name string 240 +--rw protocols 241 | +--rw protocol* [name] 242 | +--rw name identityref 243 | +--rw protocol-version* string 244 | +--rw capabilities* string 245 +--rw modules 246 +--rw module* [name revision organization] 247 +--rw name -> /catalog/modules/module/name 248 +--rw revision -> deref(../name)/../revision 249 +--rw organization -> deref(../revision)/../organization 250 +--rw os-version? string 251 +--rw feature-set? string 252 +--rw os-type? string 253 +--rw feature* yang:yang-identifier 254 +--rw deviation* [name revision] 255 | +--rw name yang:yang-identifier 256 | +--rw revision union 257 +--rw conformance-type? enumeration 259 Various elements of this module tree will be discussed in the 260 subsequent sections. 262 2.3. Module Sub-Tree 264 Each module in the YANG Catalog is enumerated by its metadata and by 265 various vendor implementations. While initially each module used the 266 "module-list" grouping from the YANG Library [RFC7895], it was found 267 that some of the nodes within that grouping such as "conformance- 268 type", "feature", and "deviation" are only valid when a module is 269 implemented by a server. As pure YANG data (which the Catalog is) it 270 is not possible to provide meaningful values for those nodes. As 271 such, common leafs were extracted from the YANG Library's "module- 272 list" for use in the module sub-tree of yang-catalog. Those server- 273 specific nodes are moved under the implementation sub-tree. The 274 yang-catalog module then augments these common nodes to add metadata 275 elements that aid module developers and module consumers alike in 276 understanding the relative maturity, compilation status, and the 277 support contact(s) of each YANG module. 279 +--rw modules 280 | +--rw module* [name revision organization] 281 | +--rw name yang:yang-identifier 282 | +--rw revision union 283 | +--rw organization string 284 | +--rw ietf 285 | | +--rw ietf-wg? string 286 | +--rw namespace inet:uri 287 | +--rw schema? inet:uri 288 | +--rw generated-from? enumeration 289 | +--rw maturity-level? enumeration 290 | +--rw document-name? string 291 | +--rw author-email? yc:email-address 292 | +--rw reference? inet:uri 293 | +--rw module-classification enumeration 294 | +--rw compilation-status? enumeration 295 | +--rw compilation-result? inet:uri 296 | +--rw prefix? string 297 | +--rw yang-version? enumeration 298 | +--rw description? string 299 | +--rw contact? string 300 | +--rw module-type? enumeration 301 | +--rw belongs-to? yang:yang-identifier 302 | +--rw tree-type? enumeration 303 | +--rw yang-tree? inet:uri 304 | +--rw expires? yang:date-and-time 305 | +--rw expired? union 306 | +--rw submodule* [name revision] 307 | | +--rw name yang:yang-identifier 308 | | +--rw revision union 309 | | +--rw schema? inet:uri 310 | +--rw dependencies* [name] 311 | | +--rw name yang:yang-identifier 312 | | +--rw revision? union 313 | | +--rw schema? inet:uri 314 | +--rw dependents* [name] 315 | | +--rw name yang:yang-identifier 316 | | +--rw revision? union 317 | | +--rw schema? inet:uri 318 | +--rw implementations 319 | +--rw implementation* 320 | [vendor platform software-version software-flavor] 321 | +--rw vendor string 322 | +--rw platform string 323 | +--rw software-version string 324 | +--rw software-flavor string 325 | +--rw os-version? string 326 | +--rw feature-set? string 327 | +--rw os-type? string 328 | +--rw feature* yang:yang-identifier 329 | +--rw deviation* [name revision] 330 | | +--rw name yang:yang-identifier 331 | | +--rw revision union 332 | +--rw conformance-type? enumeration 334 Many of these additional metadata fields are self-explanatory, 335 especially given their descriptions in the module itself and the fact 336 that many elements translate directly to YANG schema elements. 337 However, those requiring additional explanation or context as to why 338 they are needed are described in the subsequent sections. 340 2.4. Compilation Information 342 For the inventory to be complete, YANG modules at different stages of 343 their lifecyle should be taken into account, including YANG modules 344 that are clearly works-in-progress (i.e., that do not validate 345 correctly either because of faulty YANG constructs, because of a 346 faulty imported YANG module, or simply because of warnings). The 347 results of compilation testing are denoted in the "compilation- 348 status" leaf with links to the output of the tests stored in the 349 "compilation-result" leaf. Note that some warnings seen in 350 "compilation-result" are not always show-stoppers from a code 351 generation point of view (see the Generated From section). 352 Nonetheless, the compilation or validation status, along with the 353 compilation output, provide a clear indication of a given YANG 354 module's development phase and stability. The current set of 355 validator is pyang, confdc, yangdump-pro, and yanglint. 357 leaf compilation-status { 358 type enumeration { 359 enum passed { 360 description 361 "All compilers were able to compile this YANG module without 362 any errors or warnings."; 363 } 364 enum passed-with-warnings { 365 description 366 "All compilers were able to compile this YANG module without 367 any errors, but at least one of them caught a warning."; 368 } 369 enum failed { 370 description 371 "At least one of compilers found an error while 372 compiling this YANG module."; 373 } 374 enum pending { 375 description 376 "The module was just added to the catalog and compilation testing is still 377 in progress."; 378 } 379 enum unknown { 380 description 381 "There is not sufficient information about compilation status. This Could 382 mean compilation crashed causing it not to complete fully."; 383 } 384 } 385 description 386 "Status of the module, whether it was possible to compile this YANG module or 387 there are still some errors/warnings."; 388 } 389 leaf compilation-result { 390 type string; 391 description 392 "Result of the compilation explaining specifically what error or warning occurred. 393 This is not existing if compilation status is PASSED."; 394 } 396 The current instantiation of the YANG Catalog at 397 uses a number of different YANG 398 compilers for testing. The wrapper that handles validation attempts 399 to use metadata from the catalog to determine which tests to perform 400 on a given module. For example, if the module is authored by the 401 IETF, IETF-specific tests will be conducted to provide the most 402 accurate and complete set of tests possible. 404 2.5. Maturity Level 406 Models also have inherent maturity levels from their respective 407 Standards Development Organizations (SDOs). These maturity levels 408 help module consumers understand how complete, tested, etc. a module 409 is. 411 leaf maturity-level { 412 type enumeration { 413 enum ratified { 414 description 415 "Maturity of a module that is fully approved (e.g., a standard)."; 416 } 417 enum adopted { 418 description 419 "Maturity of a module that is actively being developed by a organization towards ratification."; 420 } 421 enum initial { 422 description 423 "Maturity of a module that has been initially created, but has no official 424 organization-level status."; 425 } 426 enum not-applicable { 427 description 428 "The maturity level is not used for vendor-supplied models, and thus all vendor 429 modules will have a maturity of not-applicable"; 430 } 431 } 432 description 433 "The current maturity of the module with respect to the body that created it. 434 This allows one to understand where the module is in its overall life cycle."; 435 } 437 This enumeration mapping has been implemented for the YANG modules 438 from IETF and BBF. The "maturity-level" MUST be "not-applicable" for 439 all vendor-authored modules. 441 In addition to a module's maturity, modules that are part of works- 442 in-progress (e.g., IETF internet drafts) may expire if work ceases on 443 the related document. To track that, the catalog has two module 444 leafs: "expires" and "expired". The "expires" leaf indicates a date 445 and time when the module is expected to expire whereas the "expired" 446 leaf indicates whether or not the module has already expired. For 447 those modules that will never expire, the "expired" leaf MUST be set 448 to "not-applicable". 450 2.6. Generated From 452 While many models are written by hand (i.e., authored by humans) 453 others are generated from things such as vendor code or CLI 454 constructs or from SMI-based MIB modules. These "generated" modules 455 do not necessarily require the same stringent validity checking that 456 hand-written modules require. As such, these modules have a 457 generated-from value that is designed to inform validators how much 458 checking to do. 460 leaf generated-from { 461 type enumeration { 462 enum "mib" { 463 description 464 "Module generated from Structure of Management Information (SMI) 465 MIB per RFC6643."; 466 } 467 enum "not-applicable" { 468 description 469 "Module was not generated but it was authored manually."; 470 } 471 enum "native" { 472 description 473 "Module generated from platform internal, 474 proprietary structure, or code."; 475 } 476 } 477 default "not-applicable"; 478 description 479 "This statement defines weather the module was generated or not. 480 Default value is set to not-applicable, which means that module 481 was created manualy and not generated."; 482 } 484 2.7. Implementation 486 As of version 02 of openconfig-model-catalog.yang 487 [I-D.openconfig-netmod-model-catalog] it is not possible to identify 488 the implementations of one specific module. Instead modules are 489 grouped into feature-bundle, and feature-bundles are implemented by 490 devices. Because of this, we added our own implementation sub-tree 491 under each module to yang-catalog.yang. Our implementation sub-tree 492 is: 494 +--rw implementation* [vendor platform software-version software-flavor] 495 +--rw vendor string 496 +--rw platform string 497 +--rw software-version string 498 +--rw software-flavor string 499 +--rw os-version? string 500 +--rw feature-set? string 501 +--rw os-type? string 502 +--rw feature* yang:yang-identifier 503 +--rw deviation* [name revision] 504 | +--rw name yang:yang-identifier 505 | +--rw revision union 506 +--rw conformance-type? enumeration 508 The keys in this sub-tree can be used in the "vendor" sub-tree 509 defined below to walk through each vendor, platform, and software 510 release to get a full list of supported YANG modules for that 511 release. 513 The "software-flavor" key leaf identifies a variation of a specific 514 version where YANG model support may be different. Depending on the 515 vendor, this could be a license, additional software component, or a 516 feature set. 518 The other non-key leaves in the implementation sub-tree represent 519 optional elements of a software release that some vendors may choose 520 to use for informational purposes. These leafs are duplicated under 521 the vendor sub-tree. 523 2.8. Vendor Sub-Tree 525 The vendor sub-tree provides a way, especially for module consumers, 526 to walk through a specific device and software release to find a list 527 of modules supported therein. This sub-tree turns the 528 "implementation" sub-tree on its head to provide an optimized index 529 for one wanting to go from a platform to a full list of modules. 531 In addition to the module list, the vendor sub-tree lists the YANG- 532 based protocols (e.g., NETCONF or RESTCONF) that the platforms 533 support. 535 +--rw vendors 536 +--rw vendor* [name] 537 +--rw name string 538 +--rw platforms 539 +--rw platform* [name] 540 +--rw name string 541 +--rw software-versions 542 +--rw software-version* [name] 543 +--rw name string 544 +--rw software-flavors 545 +--rw software-flavor* [name] 546 +--rw name string 547 +--rw protocols 548 | +--rw protocol* [name] 549 | +--rw name identityref 550 | +--rw protocol-version* string 551 | +--rw capabilities* string 552 +--rw modules 553 +--rw module* 554 [name revision organization] 555 +--rw name leafref 556 +--rw revision leafref 557 +--rw organization leafref 558 +--rw os-version? string 559 +--rw feature-set? string 560 +--rw os-type? string 561 +--rw feature* 562 | yang:yang-identifier 563 +--rw deviation* [name revision] 564 | +--rw name 565 | | yang:yang-identifier 566 | +--rw revision union 567 +--rw conformance-type? enumeration 569 This sub-tree structure also enables one to look for YANG modules for 570 a class of platforms (e.g., list of modules for Cisco, or list of 571 modules for Cisco ASR9K routers) instead of only being able to look 572 for YANG modules for a specific platform and software release. 574 2.9. Regex Expression Differences 576 Another challenge encountered when trying to using 577 [I-D.openconfig-netmod-model-catalog] as the canonical catalog is the 578 regular expression syntax it uses. The Openconfig module uses a 579 POSIX-compliant regular expression syntax whereas YANG-based protocol 580 implementations like ConfD [1] expect the IETF-chosen W3C syntax. In 581 order to load the Openconfig catalog in such engines, changes to the 582 regular expression syntax had to be done, and these one-off changes 583 are not supportable. 585 3. YANG Catalog Use Cases 587 The YANG Catalog module is currently targeted to address the 588 following use cases. 590 3.1. YANG Search Metadata 592 The yangcatalog.org toolchain provides a service for searching [2] 593 for YANG modules based on keywords. The resulting search data 594 currently stores the module and node metadata in a proprietary format 595 along with the search index data. By populating the yang-catalog 596 module, this search service can instead pull the metadata from the 597 implementation of the module. Populating this instance of the yang- 598 catalog module will be using an API that is still under development, 599 but will ultimately allow SDOs and vendors to provide metadata and 600 ensure the search service has the most up-to-date data for all 601 available modules. 603 3.2. Identify YANG Module Support in Devices 605 By organizing the yang-catalog module so that one can either find all 606 implementations for a given module, or find all modules supported by 607 a vendor platform and software release, the catalog will provide a 608 straight-forward way for one to understand the extent of YANG module 609 support in participating vendors' software releases. Eventually a 610 web-based graphical interface will be connected to this on 611 yangcatalog.org to make it easier for consumers to leverage the 612 instance of the yang-catalog module for this use case. 614 3.3. Identify The Backward Compatibility between YANG Module Revisions 616 The YANG catalog contains not only the most up-to-date YANG module 617 revision of a given module, but keeps all previous revisions as well. 618 With APIs in mind, it's important to understand whether different 619 YANG module revisions are backward compatible (this is specifically 620 imported for native YANG modules, i.e. the ones where generated-from 621 = native). This document uses the following semver.org semantic 622 [semver] to compare the YANG module backwards (in)compatibility: 624 MAJOR is incremented when the new version of the specification is 625 incompatible with previous versions. 627 MINOR is incremented when new functionality is added in a manner 628 that is backward-compatible with previous versions. 630 PATCH is incremented when bug fixes are made in a backward- 631 compatible manner. 633 Two distinct leaves in the YANG module contains this semver semantic: 635 the semantic-version leaf contains the value reported as metadata 636 by a specific YANG module. 638 the derived-semantic-version leaf is established by examining the 639 the YANG module themselves. As such, only the YANG syntax, as 640 opposed to the implementation changes that lead some some semantic 641 changes. 643 Typically, an Openconfig YANG module would contain an extension, 644 which is mapped to the semantic-version leaf. 646 // extension statements 647 extension openconfig-version { 648 argument "semver" { 649 yin-element false; 650 } 651 description 652 "The OpenConfig version number for the module. This is 653 expressed as a semantic version number of the form: 654 x.y.z 655 where: 656 * x corresponds to the major version, 657 * y corresponds to a minor version, 658 * z corresponds to a patch version. 659 This version corresponds to the model file within which it is 660 defined, and does not cover the whole set of OpenConfig models. 661 Where several modules are used to build up a single block of 662 functionality, the same module version is specified across each 663 file that makes up the module. 665 A major version number of 0 indicates that this model is still 666 in development (whether within OpenConfig or with industry 667 partners), and is potentially subject to change. 669 Following a release of major version 1, all modules will 670 increment major revision number where backwards incompatible 671 changes to the model are made. 673 The minor version is changed when features are added to the 674 model that do not impact current clients use of the model. 676 The patch-level version is incremented when non-feature changes 677 (such as bugfixes or clarifications to human-readable 678 descriptions that do not impact model functionality) are made 679 that maintain backwards compatibility. 681 The version number is stored in the module meta-data."; 682 } 684 Note that the absolute numbers in the semantic-version and derived- 685 semantic-version are actually meaningless: the difference between two 686 YANG module semver fields should be looked at. 688 In addition to the semantic versions, the yang-tree field points to 689 the respective module's simplified graphical representation of its 690 model as described by [I-D.ietf-netmod-yang-tree-diagrams]. This 691 diagram can be compared between two revisions of the same module to 692 visually determine any structural differences when MAJOR or MINOR 693 semantic versions differ. 695 4. YANG Catalog YANG module 697 The structure of the model defined in this document is described by 698 the YANG module below. 700 file "yang-catalog@2018-04-03.yang" 701 module yang-catalog { 702 yang-version 1.1; 703 namespace "urn:ietf:params:xml:ns:yang:yang-catalog"; 704 prefix yc; 706 import ietf-yang-types { 707 prefix yang; 708 } 709 import ietf-yang-library { 710 prefix yanglib; 711 } 712 import ietf-inet-types { 713 prefix inet; 714 } 716 organization 717 "yangcatalog.org"; 718 contact 719 "Benoit Claise 721 Joe Clarke "; 722 description 723 "This module contains metadata pertinent to each YANG module, as 724 well as a list of vendor implementations for each module. The 725 structure is laid out in such a way as to make it possible to 726 locate metadata and vendor implementation on a per-module basis 727 as well as obtain a list of available modules for a given 728 vendor's platform and specific software release."; 730 revision 2018-04-03 { 731 description 732 "Bump the YANG version number to 1.1 for the deref XPath 733 function."; 734 reference "YANG Catalog "; 735 } 736 revision 2018-01-23 { 737 description 738 "* Add leafs to track expire modules 739 * Correct a bug with leafref dereferencing"; 740 reference "YANG Catalog "; 741 } 742 revision 2017-09-26 { 743 description 744 "* Add leafs for tracking dependencies and dependents 745 * Simplify the generated-from enumerated values 746 * Refine the type for compilation-result to be an inet:uri 747 * Add leafs for semantic versioning"; 748 reference "YANG Catalog "; 749 } 750 revision 2017-08-18 { 751 description 752 "* Reorder organization to be with the other module keys 753 * Add a belongs-to leaf to track a submodule's parent"; 754 reference "YANG Catalog "; 755 } 756 revision 2017-07-28 { 757 description 758 "* Revert config false nodes as we need to be able to set these via 760 * Make conformance-type optional as not all vendors implement yang-library 762 * Re-add the path typedef"; 763 reference "YANG Catalog "; 764 } 765 revision 2017-07-26 { 766 description 767 "A number of improvements based on YANG Doctor review: 769 * Remove references to 'server' in leafs describing YANG data 770 * Fold the augmentation module leafs directly under /catalog/modules/module 771 * Use identities for protocols instead of an emumeration 772 * Make some extractable fields 'config false' 773 * Fix various types 774 * Normalize enums to be lowercase 775 * Add a leaf for module-classification 776 * Change yang-version to be an enum 777 * Add module conformance, deviation and feature leafs under the implementation branches"; 778 reference "YANG Catalog "; 779 } 780 revision 2017-07-14 { 781 description 782 "Modularize some of the leafs and create typedefs so they 783 can be shared between the API input modules."; 784 reference "YANG Catalog "; 785 } 786 revision 2017-07-03 { 787 description 788 "Initial revision."; 789 reference 790 " 791 YANG Catalog "; 792 } 794 /* 795 * Identities 796 */ 798 identity protocol { 799 description 800 "Abstract base identity for a YANG-based protocol."; 801 } 803 identity netconf { 804 base protocol; 805 description 806 "Protocol identity for NETCONF as described in RFC 6241."; 807 } 809 identity restconf { 810 base protocol; 811 description 812 "Protocol identity for RESTCONF as described in RFC 8040."; 813 } 815 typedef email-address { 816 type string { 817 pattern "[a-zA-Z0-9.!#$%&'*+/=?^_`{|}~-]+@[a-zA-Z0-9-]+([.][a-zA-Z0-9-]+)*"; 818 } 819 description 820 "This type represents a string with an email address."; 821 } 823 /* 824 * Typedefs 825 */ 827 typedef path { 828 type string { 829 pattern '([A-Za-z]:|[\w-]+(\.[\w-]+)*)?(([/\\][\w@.-]+)+)'; 830 } 831 description 832 "This type represents a string with path to the file."; 833 } 835 typedef semver { 836 type string { 837 pattern '[0-9]+\.[0-9]+\.[0-9]+'; 838 } 839 description 840 "A semantic version in the format of x.y.z, where: 842 x = the major version number 843 y = the minor version number 844 z = the patch version number 846 Changes to the major version number denote backwards-incompatible 847 changes between two revisions of the same module. 849 Changes to the minor version number indicate there have been new 850 backwards-compatible features introduced in the later version of 851 a module. 853 Changes to the patch version indicate bug fixes between two 854 versions of a module."; 855 reference "Semantic Versioning 2.0.0 "; 856 } 858 container catalog { 859 description 860 "Root container of yang-catalog holding two main branches - 861 modules and vendors. The modules sub-tree contains all the modules in 862 the catalog and all of their metadata with their implementations. 863 The vendor sub-tree holds modules for specific vendors, platforms, 864 software-versions, and software-flavors. It contains reference to a 865 name and revision of the module in order to reference the module's full 866 set of metadata."; 867 container modules { 868 description 869 "Container holding the list of modules"; 870 list module { 871 key "name revision organization"; 872 description 873 "Each entry represents one revision of one module 874 for one organization."; 875 uses yang-lib-common-leafs; 876 leaf organization { 877 type string; 878 description 879 "This statement defines the party responsible for this 880 module. The argument is a string that is used to specify a textual 881 description of the organization(s) under whose auspices this module 882 was developed."; 883 } 884 uses organization-specific-metadata; 885 leaf namespace { 886 type inet:uri; 887 mandatory true; 888 description 889 "The XML namespace identifier for this module."; 890 } 891 uses yang-lib-schema-leaf; 892 uses catalog-module-metadata; 893 list submodule { 894 key "name revision"; 895 description 896 "Each entry represents one submodule within the 897 parent module."; 898 uses yang-lib-common-leafs; 899 uses yang-lib-schema-leaf; 900 } 901 list dependencies { 902 key "name"; 903 description 904 "Each entry represents one dependency."; 905 uses yang-lib-common-leafs; 906 uses yang-lib-schema-leaf; 907 } 908 list dependents { 909 key "name"; 910 description 911 "Each entry represents one dependent."; 912 uses yang-lib-common-leafs; 913 uses yang-lib-schema-leaf; 914 } 915 leaf semantic-version { 916 type yc:semver; 917 description 918 "The formal semantic version of a module as provided by the module 919 itself. If the module does not provide a semantic version, this leaf 920 will not be specified."; 921 } 922 leaf derived-semantic-version { 923 type yc:semver; 924 description 925 "The semantic version of a module as compared to other revisions of 926 the same module. This value is computed algorithmically by ordering 927 all revisions of a given module and comparing them to look for backwards 928 incompatible changes."; 929 } 930 container implementations { 931 description 932 "Container holding lists of per-module implementation details."; 933 list implementation { 934 key "vendor platform software-version software-flavor"; 935 description 936 "List of module implementations."; 937 leaf vendor { 938 type string; 939 description 940 "Organization that implements this module."; 941 } 942 leaf platform { 943 type string; 944 description 945 "Platform on which this module is implemented."; 946 } 947 leaf software-version { 948 type string; 949 description 950 "Name of the version of software. With respect to most network device appliances, 951 this will be the operating system version. But for other YANG module 952 implementation, this would be a version of appliance software. Ultimately, 953 this should correspond to a version string that will be recognizable by 954 the consumers of the platform."; 955 } 956 leaf software-flavor { 957 type string; 958 description 959 "A variation of a specific version where 960 YANG model support may be different. Depending on the vendor, this could 961 be a license, additional software component, or a feature set."; 962 } 963 uses shared-implementation-leafs; 964 uses yang-lib-implementation-leafs; 965 } 966 } 967 } 968 } 969 container vendors { 970 description 971 "Container holding lists of organizations that publish YANG modules."; 972 list vendor { 973 key "name"; 974 description 975 "List of organizations publishing YANG modules."; 976 leaf name { 977 type string; 978 description 979 "Name of the maintaining organization -- the name should be 980 supplied in the official format used by the organization. 981 Standards Body examples: 982 IETF, IEEE, MEF, ONF, etc. 984 Commercial entity examples: 985 AT&T, Facebook, 986 Name of industry forum examples: 987 OpenConfig, OpenDaylight, ON.Lab"; 988 } 989 container platforms { 990 description 991 "Container holding list of platforms."; 992 list platform { 993 key "name"; 994 description 995 "List of platforms under specific vendor"; 996 leaf name { 997 type string; 998 description 999 "Name of the platform"; 1000 } 1001 container software-versions { 1002 description 1003 "Container holding list of versions of software versions."; 1004 list software-version { 1005 key "name"; 1006 description 1007 "List of version of software versions under specific vendor, platform."; 1008 leaf name { 1009 type string; 1010 description 1011 "Name of the version of software. With respect to most network device appliances, 1012 this will be the operating system version. But for other YANG module 1013 implementation, this would be a version of appliance software. Ultimately, 1014 this should correspond to a version string that will be recognizable by 1015 the consumers of the platform."; 1016 } 1017 container software-flavors { 1018 description 1019 "Container holding list of software flavors."; 1020 list software-flavor { 1021 key "name"; 1022 description 1023 "List of software flavors under specific vendor, platform, software-version."; 1024 leaf name { 1025 type string; 1026 description 1027 "A variation of a specific version where 1028 YANG model support may be different. Depending on the vendor, this could 1029 be a license, additional software component, or a feature set."; 1030 } 1031 container protocols { 1032 description 1033 "List of the protocols"; 1034 list protocol { 1035 key "name"; 1036 description 1037 "YANG-based protocol that is used on the device. New identities 1038 are expected to be added to address other YANG-based protocols."; 1039 leaf name { 1040 type identityref { 1041 base yc:protocol; 1042 } 1043 description 1044 "Identity of the YANG-based protocol that is supported."; 1045 } 1046 leaf-list protocol-version { 1047 type string; 1048 description 1049 "Version of the specific protocol."; 1050 } 1051 leaf-list capabilities { 1052 type string; 1053 description 1054 "Listed name of capabilities that are 1055 supported by the specific device."; 1056 } 1057 } 1058 } 1059 container modules { 1060 description 1061 "Container holding list of modules."; 1062 list module { 1063 key "name revision organization"; 1064 description 1065 "List of references to YANG modules under specific vendor, platform, software-version, 1066 software-flavor. Using these references, the complete set of metadata can be 1067 retrieved for each module."; 1068 leaf name { 1069 type leafref { 1070 path "/catalog/modules/module/name"; 1071 } 1072 description 1073 "Reference to a name of the module that is contained in specific vendor, platform, 1074 software-version, software-flavor."; 1075 } 1076 leaf revision { 1077 type leafref { 1078 path "deref(../name)/../revision"; 1079 } 1080 description 1081 "Reference to a revision of the module that is contained in specific vendor, 1082 platform, software-version, software-flavor."; 1083 } 1084 leaf organization { 1085 type leafref { 1086 path "deref(../revision)/../organization"; 1087 } 1088 description 1089 "Reference to the authoring organization of the module for the implemented 1090 module."; 1091 } 1092 uses shared-implementation-leafs; 1093 uses yang-lib-implementation-leafs; 1094 } 1095 } 1096 } 1097 } 1098 } 1099 } 1100 } 1101 } 1102 } 1103 } 1104 } 1106 grouping catalog-module-metadata { 1107 uses shared-module-leafs; 1108 leaf compilation-status { 1109 type enumeration { 1110 enum passed { 1111 description 1112 "All compilers were able to compile this YANG module without 1113 any errors or warnings."; 1114 } 1115 enum passed-with-warnings { 1116 description 1117 "All compilers were able to compile this YANG module without 1118 any errors, but at least one of them caught a warning."; 1119 } 1120 enum failed { 1121 description 1122 "At least one of compilers found an error while 1123 compiling this YANG module."; 1124 } 1125 enum pending { 1126 description 1127 "The module was just added to the catalog and compilation testing is still 1128 in progress."; 1129 } 1130 enum unknown { 1131 description 1132 "There is not sufficient information about compilation status. This Could 1133 mean compilation crashed causing it not to complete fully."; 1134 } 1135 } 1136 description 1137 "Status of the module, whether it was possible to compile this YANG module or 1138 there are still some errors/warnings."; 1139 } 1140 leaf compilation-result { 1141 type inet:uri; 1142 description 1143 "Link to the result of the compilation explaining specifically what error or 1144 warning occurred. This is not existing if compilation status is PASSED."; 1145 } 1146 leaf prefix { 1147 type string; 1148 description 1149 "Statement of yang that is used to define the prefix associated with 1150 the module and its namespace. The prefix statement's argument is 1151 the prefix string that is used as a prefix to access a module. The 1152 prefix string MAY be used to refer to definitions contained in the 1153 module, e.g., if:ifName."; 1154 } 1155 leaf yang-version { 1156 type enumeration { 1157 enum 1.0 { 1158 description 1159 "YANG version 1.0 as defined in RFC 6020."; 1160 } 1161 enum 1.1 { 1162 description 1163 "YANG version 1.1 as defined in RFC 7950."; 1164 } 1165 } 1166 description 1167 "The optional yang-version statement specifies which version of the 1168 YANG language was used in developing the module."; 1169 } 1170 leaf description { 1171 type string; 1172 description 1173 "This statement takes as an argument a string that 1174 contains a human-readable textual description of this definition. 1175 The text is provided in a language (or languages) chosen by the 1176 module developer; for the sake of interoperability, it is RECOMMENDED 1177 to choose a language that is widely understood among the community of 1178 network administrators who will use the module."; 1179 } 1180 leaf contact { 1181 type string; 1182 description 1183 "This statement provides contact information for the module. 1184 The argument is a string that is used to specify contact information 1185 for the person or persons to whom technical queries concerning this 1186 module should be sent, such as their name, postal address, telephone 1187 number, and electronic mail address."; 1188 } 1189 leaf module-type { 1190 type enumeration { 1191 enum module { 1192 description 1193 "If YANG file contains module."; 1194 } 1195 enum submodule { 1196 description 1197 "If YANG file contains sub-module."; 1198 } 1199 } 1200 description 1201 "Whether a file contains a YANG module or sub-module."; 1202 } 1203 leaf belongs-to { 1204 when "../module-type = 'submodule'" { 1205 description 1206 "Include the module's parent when it is a submodule."; 1207 } 1208 type yang:yang-identifier; 1209 description 1210 "Name of the module that includes this submodule."; 1211 } 1212 leaf tree-type { 1213 type enumeration { 1214 enum split { 1215 description 1216 "This module uses a split config/operational state layout."; 1217 } 1218 enum nmda-compatible { 1219 description 1220 "This module is compatible with the Network Management Datastores 1221 Architecture (NMDA) and combines config and operational state nodes."; 1222 } 1223 enum transitional-extra { 1224 description 1225 "This module is derived as a '-state' module to allow for transitioning 1226 to a full NMDA-compliant tree structure."; 1227 } 1228 enum openconfig { 1229 description 1230 "This module uses the Openconfig data element layout."; 1231 } 1232 enum unclassified { 1233 description 1234 "This module does not belong to any category or can't be determined."; 1235 } 1236 enum not-applicable { 1237 description 1238 "This module is not applicable. For example, because the YANG module only contains typedefs, groupings, or is a submodule"; 1239 } 1240 } 1241 description 1242 "The type of data element tree used by the module as it relates to the 1243 Network Management Datastores Architecture."; 1244 reference "draft-dsdt-nmda-guidelines Guidelines for YANG Module Authors (NMDA)"; 1245 } 1246 leaf yang-tree { 1247 when "../module-type = 'module'"; 1248 type inet:uri; 1249 description 1250 "This leaf provides a URI that points to the ASCII tree format of the module in 1251 draft-ietf-netmod-yang-tree-diagrams format."; 1252 reference "See draft-ietf-netmod-yang-tree-diagrams."; 1253 } 1254 leaf expires { 1255 type yang:date-and-time; 1256 description 1257 "Date and time of when this module expires (if it expires). This will typically be used for 1258 modules that have not been fully ratified."; 1259 } 1260 leaf expired { 1261 type union { 1262 type boolean; 1263 type enumeration { 1264 enum not-applicable { 1265 description 1266 "This module is not and will not be expired."; 1267 } 1268 } 1269 } 1270 default "false"; 1271 description 1272 "Whether or not this module has expired. If the current date is beyond the expires date, then expired 1273 should be true."; 1274 } 1275 description 1276 "Grouping of YANG module metadata that extends the common list defined in the YANG 1277 Module Library (RFC 7895)."; 1278 } 1280 grouping organization-specific-metadata { 1281 container ietf { 1282 when "../organization = 'ietf'" { 1283 description 1284 "Include this container specific metadata of the IETF."; 1285 } 1286 leaf ietf-wg { 1287 type string; 1288 description 1289 "Working group that authored the document containing this module."; 1290 } 1291 description 1292 "Include this container for the IETF-specific organization metadata."; 1293 } 1294 description 1295 "Any organization that has some specific metadata of the yang module and want them add to the 1296 yang-catalog, should augment this grouping. This grouping is for any metadata that can`t be used for 1297 every yang module."; 1298 } 1300 grouping yang-lib-common-leafs { 1301 leaf name { 1302 type yang:yang-identifier; 1303 description 1304 "The YANG module or submodule name."; 1305 } 1306 leaf revision { 1307 type union { 1308 type yanglib:revision-identifier; 1309 type string { 1310 length "0"; 1311 } 1312 } 1313 description 1314 "The YANG module or submodule revision date. 1315 A zero-length string is used if no revision statement 1316 is present in the YANG module or submodule."; 1317 } 1318 description 1319 "The YANG module or submodule revision date. 1321 A zero-length string is used if no revision statement 1322 is present in the YANG module or submodule."; 1323 reference "RFC7895 YANG Module Library : common-leafs grouping"; 1324 } 1326 grouping yang-lib-schema-leaf { 1327 leaf schema { 1328 type inet:uri; 1329 description 1330 "Contains a URL that represents the YANG schema 1331 resource for this module or submodule. 1332 This leaf will only be present if there is a URL 1333 available for retrieval of the schema for this entry."; 1334 } 1335 description 1336 "These are a subset of leafs from the yang-library (RFC 7895) that provide some 1337 extractable fields for catalog modules. The module-list grouping cannot be 1338 used from yang-library as modules themselves cannot have conformance without 1339 a server."; 1340 reference "RFC7895 YANG Module Library : schema-leaf grouping"; 1341 } 1343 grouping yang-lib-implementation-leafs { 1344 leaf-list feature { 1345 type yang:yang-identifier; 1346 description 1347 "List of YANG feature names from this module that are 1348 supported by the server, regardless of whether they are 1349 defined in the module or any included submodule."; 1350 } 1351 list deviation { 1352 key "name revision"; 1353 description 1354 "List of YANG deviation module names and revisions 1355 used by this server to modify the conformance of 1356 the module associated with this entry. Note that 1357 the same module can be used for deviations for 1358 multiple modules, so the same entry MAY appear 1359 within multiple 'module' entries. 1360 The deviation module MUST be present in the 'module' 1361 list, with the same name and revision values. 1362 The 'conformance-type' value will be 'implement' for 1363 the deviation module."; 1364 uses yang-lib-common-leafs; 1365 } 1366 leaf conformance-type { 1367 type enumeration { 1368 enum implement { 1369 description 1370 "Indicates that the server implements one or more 1371 protocol-accessible objects defined in the YANG module 1372 identified in this entry. This includes deviation 1373 statements defined in the module. 1374 For YANG version 1.1 modules, there is at most one 1375 module entry with conformance type 'implement' for a 1376 particular module name, since YANG 1.1 requires that, 1377 at most, one revision of a module is implemented. 1378 For YANG version 1 modules, there SHOULD NOT be more 1379 than one module entry for a particular module name."; 1380 } 1381 enum import { 1382 description 1383 "Indicates that the server imports reusable definitions 1384 from the specified revision of the module but does 1385 not implement any protocol-accessible objects from 1386 this revision. 1387 Multiple module entries for the same module name MAY 1388 exist. This can occur if multiple modules import the 1389 same module but specify different revision dates in 1390 the import statements."; 1391 } 1392 } 1393 // Removing the mandatory true for now as not all vendors may have 1394 // this information if they do not implement yang-library. 1395 //mandatory true; 1396 description 1397 "Indicates the type of conformance the server is claiming 1398 for the YANG module identified by this entry."; 1399 } 1400 description 1401 "This is a set of leafs extracted from the yang-library that are 1402 specific to server implementations."; 1403 reference "RFC7895 YANG Module Library : module-list grouping"; 1404 } 1406 grouping shared-implementation-leafs { 1407 leaf os-version { 1408 type string; 1409 description 1410 "Version of the operating system using this module. This is primarily useful if 1411 the software implementing the module is an application that requires a specific 1412 operating system."; 1413 } 1414 leaf feature-set { 1415 type string; 1416 description 1417 "An optional feature of the software that is required in order to implement this 1418 module. Some form of this must be incorporated in software-version or 1419 software-flavor, but can be broken out here for additional clarity."; 1420 } 1421 leaf os-type { 1422 type string; 1423 description 1424 "Type of the operating system using this module. This is primarily useful if 1425 the software implementing the module is an application that requires a 1426 specific operating system."; 1427 } 1428 description 1429 "Grouping of non-key leafs to be used in the module and vendor sub-trees."; 1430 } 1432 grouping shared-module-leafs { 1433 leaf generated-from { 1434 type enumeration { 1435 enum mib { 1436 description 1437 "Module generated from Structure of Management Information (SMI) 1438 MIB per RFC6643."; 1439 } 1440 enum not-applicable { 1441 description 1442 "Module was not generated but it was authored manually."; 1443 } 1444 enum native { 1445 description 1446 "Module generated from platform internal, 1447 proprietary structure, or code."; 1448 } 1449 } 1450 default "not-applicable"; 1451 description 1452 "This statement defines weather the module was generated or not. 1453 Default value is set to not-applicable, which means that module 1454 was created manualy and not generated."; 1455 } 1456 leaf maturity-level { 1457 type enumeration { 1458 enum ratified { 1459 description 1460 "Maturity of a module that is fully approved (e.g., a standard)."; 1461 } 1462 enum adopted { 1463 description 1464 "Maturity of a module that is actively being developed by a organization towards ratification."; 1466 } 1467 enum initial { 1468 description 1469 "Maturity of a module that has been initially created, but has no official 1470 organization-level status."; 1471 } 1472 enum not-applicable { 1473 description 1474 "The maturity level is not used for vendor-supplied models, and thus all vendor 1475 modules will have a maturity of not-applicable"; 1476 } 1477 } 1478 description 1479 "The current maturity of the module with respect to the body that created it. 1480 This allows one to understand where the module is in its overall life cycle."; 1481 } 1482 leaf document-name { 1483 type string; 1484 description 1485 "The name of the document from which the module was extracted or taken; 1486 or that provides additional context about the module."; 1487 } 1488 leaf author-email { 1489 type yc:email-address; 1490 description 1491 "Contact email of the author who is responsible for this module."; 1492 } 1493 leaf reference { 1494 type inet:uri; 1495 description 1496 "A string that is used to specify a textual cross-reference to an external document, either 1497 another module that defines related management information, or a document that provides 1498 additional information relevant to this definition."; 1499 } 1500 leaf module-classification { 1501 type enumeration { 1502 enum network-service { 1503 description 1504 "Network Service YANG Module that describes the configuration, state 1505 data, operations, and notifications of abstract representations of 1506 services implemented on one or multiple network elements."; 1507 } 1508 enum network-element { 1509 description 1510 "Network Element YANG Module that describes the configuration, state 1511 data, operations, and notifications of specific device-centric 1512 technologies or features."; 1513 } 1514 enum unknown { 1515 description 1516 "In case that there is not sufficient information about how to classify the module."; 1517 } 1518 enum not-applicable { 1519 description 1520 "The YANG module abstraction type is neither a Network Service YANG Module 1521 nor a Network Element YANG Module."; 1522 } 1523 } 1524 mandatory true; 1525 description 1526 "The high-level classification of the given YANG module."; 1527 reference "RFC8199 YANG Module Classification"; 1528 } 1529 description 1530 "These leafs are shared among the yang-catalog and its API."; 1531 } 1533 grouping online-source-file { 1534 leaf owner { 1535 type string; 1536 mandatory true; 1537 description 1538 "Username or ID of the owner of the version control system repository."; 1539 } 1540 leaf repository { 1541 type string; 1542 mandatory true; 1543 description 1544 "The name of the repository."; 1545 } 1546 leaf path { 1547 type yc:path; 1548 mandatory true; 1549 description 1550 "Location within the repository of the module file."; 1551 } 1552 leaf branch { 1553 type string; 1554 description 1555 "Revision control system branch or tag to use to find the module. If this is not 1556 specified, the head of the repository is used."; 1557 } 1558 description 1559 "Networked version control system location of the module file."; 1560 } 1561 } 1563 1565 5. Security Considerations 1567 The goal of the YANG Catalog module and yangcatalog.org is to 1568 document a large library of YANG modules and their implementations. 1569 Already, we have seen some SDOs hestitant to provide modules that 1570 have not reached a "ratified" maturity level because of intellectual 1571 property leakage concerns or simply organization process that 1572 mandates only fully ratified modules can be published. Care must be 1573 paid that through private automated testing and validation of such 1574 modules that their metadata does not leak before the publishing 1575 organization approves the release of such data. 1577 Similarly, from a vendor implementation standpoint, data that is 1578 exposed to the catalog before the vendor has fully vetted it could 1579 cause confusion amongst that vendor's customers or reveal product 1580 releases to the market before they have been officially announced. 1582 Ultimately, there is a balance to be struck with respect to providing 1583 a rich library of YANG module metadata, and doing so at the right 1584 time to avoid information leakage. 1586 6. IANA Considerations 1588 No IANA action is requested. 1590 7. References 1592 7.1. Normative References 1594 [I-D.ietf-netmod-yang-tree-diagrams] 1595 Bjorklund, M. and L. Berger, "YANG Tree Diagrams", draft- 1596 ietf-netmod-yang-tree-diagrams-06 (work in progress), 1597 February 2018. 1599 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 1600 the Network Configuration Protocol (NETCONF)", RFC 6020, 1601 DOI 10.17487/RFC6020, October 2010, 1602 . 1604 [RFC7895] Bierman, A., Bjorklund, M., and K. Watsen, "YANG Module 1605 Library", RFC 7895, DOI 10.17487/RFC7895, June 2016, 1606 . 1608 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 1609 RFC 7950, DOI 10.17487/RFC7950, August 2016, 1610 . 1612 [RFC8199] Bogdanovic, D., Claise, B., and C. Moberg, "YANG Module 1613 Classification", RFC 8199, DOI 10.17487/RFC8199, July 1614 2017, . 1616 [semver] "Semantic Versioning 2.0.0", . 1618 7.2. Informative References 1620 [I-D.openconfig-netmod-model-catalog] 1621 Shaikh, A., Shakir, R., and K. D'Souza, "Catalog and 1622 registry for YANG models", draft-openconfig-netmod-model- 1623 catalog-02 (work in progress), March 2017. 1625 [RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 1626 and R. Wilton, "Network Management Datastore Architecture 1627 (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018, 1628 . 1630 7.3. URIs 1632 [1] https://developer.cisco.com/site/confD/index.gsp 1634 [2] https://www.yangcatalog.org/yang-search 1636 Appendix A. Acknowledgments 1638 The authors would like to thanks Miroslav Kovac for this help on this 1639 YANG module and the yangcatalog.org implementation. We would also 1640 like to thank Radek Krejci for his extensive review and suggestions 1641 for improvement. 1643 The RFC text was produced using Marshall Rose's xml2rfc tool. 1645 Appendix B. Changes From Previous Revisions 1647 RFC Editor to remove this section prior to publication. 1649 Draft -00 to -01: 1651 o Redesign of module sub-tree based on review. 1653 o Modularize some leafs and create typedefs to share with API YANG 1654 modules. 1656 o Add module conformance-type, deviation and feature leafs under the 1657 implementation branch. 1659 o Change yang-version to be an enum. 1661 o Add a leaf for module-classification based on [RFC8199]. 1663 o Normalize enums to be lowercase. 1665 o Use identities for protocols instead of an enumeration. 1667 o Make conformance-type optional as not all vendors implement 1668 [RFC7895]. 1670 o Add a leaf for tree-type based on [RFC8342]. 1672 o Add a reference to contributing to the YANG Catalog at 1673 yangcatalog.org. 1675 o Various wording and style changes to the document text. 1677 Draft -01 to -02: 1679 o Add a belongs-to leaf to track parent modules. 1681 o Add leafs to track dependents and dependencies for a given module. 1683 o Simplify the generated-from enumerated values. 1685 o Refine the type for compilation-result to be an inet:uri. 1687 o Add leafs for semantic versioning. 1689 o Reorder the organization leaf to be with other module keys. 1691 o Add text to describe generated-from and semantic versioning. 1693 Draft -02 to -03: 1695 o Change YANG ref to RFC7950 as the catalog module now needs YANG 1696 1.1. 1698 o Add a reference to I-D.ietf-netmod-yang-tree-diagrams. 1700 o Document the new yang-tree node in the catalog. 1702 o Document the new expires and expired leafs and their relation to 1703 maturity. 1705 o Updtae NMDA reference to point to new RFC number. 1707 Authors' Addresses 1709 Joe Clarke 1710 Cisco Systems, Inc. 1711 7200-12 Kit Creek Rd 1712 Research Triangle Park, North Carolina 1713 United States of America 1715 Phone: +1-919-392-2867 1716 Email: jclarke@cisco.com 1718 Benoit Claise 1719 Cisco Systems, Inc. 1720 De Kleetlaan 6a b1 1721 1831 Diegem 1722 Belgium 1724 Phone: +32 2 704 5622 1725 Email: bclaise@cisco.com