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