idnits 2.17.1 draft-rwilton-netmod-yang-packages-01.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 is 1 instance of too long lines in the document, the longest one being 2 characters in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 560 has weird spacing: '...mespace ine...' == Line 564 has weird spacing: '...evision yan...' == Line 574 has weird spacing: '...evision yan...' == Line 670 has weird spacing: '...version yan...' == Line 721 has weird spacing: '...mespace ine...' == (7 more instances...) -- The document date (March 10, 2019) is 1867 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) == Unused Reference: 'I-D.ietf-netmod-module-tags' is defined on line 1399, but no explicit reference was found in the text == Unused Reference: 'I-D.ietf-netmod-artwork-folding' is defined on line 1461, but no explicit reference was found in the text == Unused Reference: 'RFC8199' is defined on line 1471, but no explicit reference was found in the text == Outdated reference: A later version (-10) exists of draft-ietf-netmod-module-tags-07 == Outdated reference: A later version (-21) exists of draft-ietf-netmod-yang-instance-file-format-02 ** Downref: Normative reference to an Informational draft: draft-verdt-netmod-yang-versioning-reqs (ref. 'I-D.verdt-netmod-yang-versioning-reqs') ** Obsolete normative reference: RFC 5246 (Obsoleted by RFC 8446) ** Obsolete normative reference: RFC 6536 (Obsoleted by RFC 8341) == Outdated reference: A later version (-12) exists of draft-ietf-netmod-artwork-folding-00 Summary: 4 errors (**), 0 flaws (~~), 13 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group R. Wilton 3 Internet-Draft Cisco Systems, Inc. 4 Intended status: Standards Track March 10, 2019 5 Expires: September 11, 2019 7 YANG Packages 8 draft-rwilton-netmod-yang-packages-01 10 Abstract 12 This document defines YANG packages, an organizational structure 13 holding a set of related YANG modules, that can be used to simplify 14 the conformance and sharing of YANG schema. It describes how YANG 15 instance data documents are used to define YANG packages, and how the 16 YANG library information published by a server can be augmented with 17 additional packaging related information. 19 Status of This Memo 21 This Internet-Draft is submitted in full conformance with the 22 provisions of BCP 78 and BCP 79. 24 Internet-Drafts are working documents of the Internet Engineering 25 Task Force (IETF). Note that other groups may also distribute 26 working documents as Internet-Drafts. The list of current Internet- 27 Drafts is at https://datatracker.ietf.org/drafts/current/. 29 Internet-Drafts are draft documents valid for a maximum of six months 30 and may be updated, replaced, or obsoleted by other documents at any 31 time. It is inappropriate to use Internet-Drafts as reference 32 material or to cite them other than as "work in progress." 34 This Internet-Draft will expire on September 11, 2019. 36 Copyright Notice 38 Copyright (c) 2019 IETF Trust and the persons identified as the 39 document authors. All rights reserved. 41 This document is subject to BCP 78 and the IETF Trust's Legal 42 Provisions Relating to IETF Documents 43 (https://trustee.ietf.org/license-info) in effect on the date of 44 publication of this document. Please review these documents 45 carefully, as they describe your rights and restrictions with respect 46 to this document. Code Components extracted from this document must 47 include Simplified BSD License text as described in Section 4.e of 48 the Trust Legal Provisions and are provided without warranty as 49 described in the Simplified BSD License. 51 Table of Contents 53 1. Terminology and Conventions . . . . . . . . . . . . . . . . . 2 54 2. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 55 3. Background on YANG packaging . . . . . . . . . . . . . . . . 4 56 4. Possible alternative solutions . . . . . . . . . . . . . . . 4 57 4.1. Using module tags . . . . . . . . . . . . . . . . . . . . 4 58 4.2. Using YANG library . . . . . . . . . . . . . . . . . . . 5 59 5. Objectives . . . . . . . . . . . . . . . . . . . . . . . . . 6 60 6. Package description . . . . . . . . . . . . . . . . . . . . . 7 61 6.1. Package definition rules . . . . . . . . . . . . . . . . 7 62 6.2. Package versioning . . . . . . . . . . . . . . . . . . . 8 63 6.3. Client server package conformance . . . . . . . . . . . . 10 64 6.4. Schema referential completeness . . . . . . . . . . . . . 10 65 6.5. Submodules packaging considerations . . . . . . . . . . . 11 66 6.6. Revision history . . . . . . . . . . . . . . . . . . . . 11 67 6.7. Uniqueness of packages and global registry . . . . . . . 11 68 7. YANG Packaging instance data . . . . . . . . . . . . . . . . 12 69 8. YANG Packaging additions to YANG library . . . . . . . . . . 13 70 8.1. Package List . . . . . . . . . . . . . . . . . . . . . . 14 71 8.2. Binding from schema to package . . . . . . . . . . . . . 14 72 8.3. Tree diagram . . . . . . . . . . . . . . . . . . . . . . 15 73 9. YANG Packaging groupings . . . . . . . . . . . . . . . . . . 15 74 10. YANG Modules . . . . . . . . . . . . . . . . . . . . . . . . 17 75 11. Security Considerations . . . . . . . . . . . . . . . . . . . 29 76 12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 30 77 13. Open Questions/Issues . . . . . . . . . . . . . . . . . . . . 31 78 14. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 31 79 15. References . . . . . . . . . . . . . . . . . . . . . . . . . 31 80 15.1. Normative References . . . . . . . . . . . . . . . . . . 31 81 15.2. Informative References . . . . . . . . . . . . . . . . . 32 82 Appendix A. Tree output for ietf-yang-library with package 83 augmentations . . . . . . . . . . . . . . . . . . . 32 84 Appendix B. Examples . . . . . . . . . . . . . . . . . . . . . . 34 85 B.1. Example IETF Network Device YANG package . . . . . . . . 35 86 B.2. Example IETF Basic Routing YANG package . . . . . . . . . 37 87 B.3. Package import conflict resolution example . . . . . . . 40 88 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 43 90 1. Terminology and Conventions 92 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 93 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 94 "OPTIONAL" in this document are to be interpreted as described in BCP 95 14 [RFC2119] [RFC8174] when, and only when, they appear in all 96 capitals, as shown here. 98 This document uses terminology introduced in the YANG versioning 99 requirements draft [I-D.verdt-netmod-yang-versioning-reqs]. 101 This document also makes of the following terminology introduced in 102 the Network Management Datastore Architecture [RFC8342]: 104 o datastore schema 106 In addition, this document makes use of the following terminology: 108 o bc: Used as an abbreviation for a backwards-compatible change. 110 o nbc: Used as an abbreviation for a non-backwards-compatible 111 change. 113 o editorial change: A backwards-compatible change that does not 114 change the YANG module semantics in any way. 116 Note - the bc/nbc/editorial terminology should probably be defined 117 and referenced from the YANG module versioning solution draft. 119 2. Introduction 121 This document defines and describes the YANG [RFC7950] constructs 122 that are used to define and use YANG packages. 124 A YANG package is an organizational structure that groups a set of 125 related YANG modules together into a consistent versioned definition. 126 YANG packages can themselves refer to and reuse other package 127 definitions. 129 The draft consists of the following significant sections: 131 A background section that describes some of the prior work in this 132 area, both within IETF and the wider industry. 134 An overview of the objectives for a YANG packaging solution, and also 135 what work is out of scope for this document. 137 The definition of YANG packages, how package definitions are 138 constructed, and how they are used. 140 How YANG instance data documents 141 [I-D.ietf-netmod-yang-instance-file-format] are used to define 142 particular YANG package instances. 144 Augmentations to the YANG library [I-D.ietf-netconf-rfc7895bis] 145 content published by servers to include YANG packaging related 146 information. 148 YANG modules the provide the definitions for YANG packages. 150 Non-normative examples of YANG package instances are provided in the 151 appendicies. 153 3. Background on YANG packaging 155 It has long been acknowledged within the IETF NETMOD community that 156 network management using YANG requires a unit of organization and 157 conformance that is broader in scope than individual YANG modules. 159 'The YANG Package Statement' [I-D.bierman-netmod-yang-package] 160 proposed a YANG package mechanism based on new YANG language 161 statements, where a YANG package is defined in a file similar to how 162 YANG modules are defined, and would require enhancements to YANG 163 compilers to understand the new statements used to define particular 164 package instances. This document did not progress in the working 165 group, although this may have been due to other higher priority 166 concerns or resource constraints within the working group rather than 167 due to consideration of the technical merits of the proposed 168 approach. 170 OpenConfig [openconfigsemver] describes an approach to versioning 171 'bundle releases' based on git tags. I.e. a set of modules, at 172 particular versions, can be marked with the same release tag to 173 indicate that they are known to interoperate together. 175 The NETMOD WG in general, and the YANG versioning design team in 176 particular, are exploring solutions to the YANG versioning 177 requirements, [I-D.verdt-netmod-yang-versioning-reqs]. Solutions to 178 the versioning requirements can be split into several distinct areas. 179 One draft, TBD (draft-verdt-netmod-yang-semver), has a primary focus 180 on YANG versioning scoped to individual modules. But an overall 181 solution should also consider YANG versioning and conformance scoped 182 to a server's datastore schema. YANG packages may help form part of 183 the solution for versioning at the datastore schema level. 185 4. Possible alternative solutions 187 4.1. Using module tags 189 Module tags have been suggested as an alternative solution, and 190 indeed that can address some of the same requirements as YANG 191 packages but not all of them. 193 Module tags can be used to group or organize YANG modules. However, 194 this raises the question of where this tag information is stored. 195 Module tags either require that the YANG module files themselves are 196 updated with the module tag information (creating another versioning 197 problem), or for the module tag information to be hosted elsewhere, 198 perhaps in a centralize YANG Catalog, or in instance data documents 199 similar to how YANG packages have been defined in this draft. 201 One of the principle aims of YANG packages is to be a versioned 202 object that defines a precise set of YANG modules versions that work 203 together. Module tags cannot meet this aim without an explosion of 204 module tags definitions (i.e. a separate module tag must be defined 205 for each package version). 207 Module tags cannot support the hierachical scheme to construct YANG 208 schema that is proposed in this draft. 210 4.2. Using YANG library 212 Another question is whether it is necessary to define new YANG 213 modules to define YANG packages, and whether YANG library could just 214 be reused in an instance data document. The use of YANG packages is 215 intended to offer several benefits over just using YANG library: 217 1. Packages allow schema to be built in a hierarchical fashion. 218 [I-D.ietf-netconf-rfc7895bis] only allows one layer of hierarchy 219 (using module sets), and there can be no conflicts between module 220 revisions in different module-sets. 222 2. Packages can be made available off the box, with a well defined 223 unique name, avoiding the need for clients to download, and 224 construct/check the entire YANG schema for each device, instead 225 they can rely on the named packages. YANG libraries use of 226 checksums are unique only to the device that generated them. 228 3. Packages are versioned using a semantic versioning scheme, YANG 229 library does not have a schema level semantic version number, 230 although this could potentially be added if required. 232 4. For a YANG library instance data document to contain the 233 necessary information, it needs both YANG library, and probably 234 also various augmentations (e.g. to include each module's 235 semantic version number), unless a new version of YANG library is 236 defined containing this information. A module definition for a 237 YANG package could be defined to contain all of the ncessary 238 information to solve the problem. 240 5. YANG library is designed to publish information about the 241 modules, datastores, and datastore schema used by a server. It 242 is unclear whether exactly the same information is required for 243 an offline schema definition, or whether these definitions might 244 deviate from each other over time. E.g., some thought needs to 245 be given concerning the relationship between datastores and 246 schema. 248 5. Objectives 250 The main goals of YANG package definitions include, but are not 251 restricted to: 253 o To act as a simplified YANG conformance mechanism. Rather than 254 conformance being performed against a set of individual YANG 255 module revisions, conformance could also be more simply stated in 256 terms of YANG packages, with a set modifications (e.g. additional 257 modules, deviations, or features). 259 o To allow YANG datastore schema to be specified in a more concise 260 way rather than having to list all modules and revisions. YANG 261 package definitions can be defined in documents that can be 262 referenced by a URL rather than requiring explicit lists of 263 modules to be shared between client and server. Hence, a YANG 264 package must contain sufficient information to allow a client or 265 server to precisely construct the schema associated with the 266 package. 268 o To provide generic packaging related YANG grouping definitions for 269 use in other YANG modules, as required. 271 o To define a mainly linear versioned history of sets of modules 272 versions that are known to work together. I.e. to help mitigate 273 the problem were a client must manage devices from multiple 274 vendors, and vendor A implements version 1.0.0 of module foo and 275 version 2.0.0 of module bar, and vendor B implements version 2.0.0 276 of module foo and version 1.0.0 of module bar. For a client, 277 trying to interoperate with multiple vendors, and many YANG 278 modules, then finding a consistent lowest common denominator set 279 of YANG module versions may be difficult, or impossible. 281 Protocol mechanisms of how clients could negotiate which packages or 282 package versions are be used for client server communications are 283 outside the scope of this document. However, the design of the YANG 284 library augmentations for YANG packages are intended to keep open the 285 possibility of such extensions in future work. 287 Finally, the package definitions proposed by this document are 288 intended to be relatively basic in their definition and the 289 functionality that they support. As indsutry gains experience using 290 YANG packages, the standard YANG mechanisms of updating, or 291 augmenting, YANG modules could be used to extend the functionality 292 supported by YANG packages. 294 6. Package description 296 This document specifies an approach to defining YANG packages that is 297 different to either of the approaches described in the background. 299 The approach defined here is for a YANG package definition structure 300 to be defined using existing YANG language statements without 301 requiring extensions or new YANG statements. By making use of this 302 structure, particular YANG package instances can be defined as YANG 303 instance data documents [I-D.ietf-netmod-yang-instance-file-format] 304 with well defined names and locations. 306 The YANG sementic versioning scheme, described in draft-verdt-netmod- 307 yang-semver (TBD), is used to version YANG packages using an 308 equivalent scheme to how individual YANG modules version numbers are 309 changed. 311 YANG library is augmented to allow servers to report the packages 312 that they implement and to associate those packages back to 313 particular datastore schema. 315 TODO - It would be helpful if the YANG instance data file format 316 [I-D.ietf-netmod-yang-instance-file-format] could also reference a 317 YANG packages to specify the schema associated with an instance data 318 document. This could either be defined in instance-file-format 319 draft, or as a YANG augmentation as part of this draft. 321 Each version of a YANG package defines: a set of YANG modules that 322 are implemented at particular versions or revisions; a set of YANG 323 modules that are import-only with particular versions or revisions; 324 and a set of mandatory module features that implementations of the 325 package MUST implement or otherwise deviate. 327 6.1. Package definition rules 329 The following rules define how packages are defined: 331 Every YANG package definition MUST be referentially complete. 332 I.e. all import and include statements for all YANG modules 333 included in a package MUST resolve to a module specified in the 334 package itself, or an imported package. 336 For a given package, each separate instance of the package MUST 337 have a unique version number that follows the semantic versioning 338 rules described in Section 6.2. 340 A package MAY have a revision-date. Any package revision-dates 341 MUST be unique for different package versions. 343 For each module implemented by a package, only a single revision/ 344 version MUST be implemented. 346 The version/revision of a module listed in the package module list 347 supercedes any version/revision of the module listed in a imported 348 package module list. This allows a package to resolve any 349 conflicting implemented module versions/revisions in imported 350 packages. 352 The replaces-revision leaf-list in the import-only-module list can 353 be used to exclude duplicate revisions of import-only modules from 354 imported packages. Otherwise, the import-only-modules for a 355 package are the import-only-modules from all imported packages 356 combined with any modules listed in the packages import-only- 357 module list. 359 Modules referenced by a package SHOULD specify the version of the 360 module, both in the package definition and within the module 361 definition itself. 363 Modules referenced by a package MUST specify the revision date of 364 the module, both in the package definition and within the module 365 definition itself. 367 6.2. Package versioning 369 Every YANG package must specify a YANG semantic version field that 370 defines the particular version of the package. 372 The rules for incrementing the YANG package version number are 373 equivalent to the semantic versioning rules used to version 374 individual YANG modules, defined in TBD (draft-verdt-netmod-yang- 375 semver). 377 The semantic versioning rules, as they apply to YANG packages, are 378 defined using the following two step process: 380 The first step is to determined whether the change to the YANG 381 package is classified as a major, minor, or editorial based on the 382 content that has changed in the package relative to the previous 383 version. Where available, the semantic version number of the 384 referenced elements in the package (imported packages or modules) can 385 be used to help determine what type of change is being made. The 386 formal rules are: 388 If any of the referenced elements of the package (imported 389 packages or modules) are changed in an nbc way, or if any imported 390 package, module, or mandatory-feature is removed from the package 391 definition, then the package has been updated in an nbc way. 393 If none of the referenced elements of the package (imported 394 packages, modules) are removed or changed in a nbc way, but some 395 referenced elements are changed in a bc way, or new referenced 396 elements or mandatory-features added, then the package is deemed 397 to be updated in a bc way. 399 If none of the referenced elements of the package (imported 400 packages, modules) are added, removed, or changed in a nbc or bc 401 way, but some referenced elements have editorial changes then the 402 package is deemed to be updated in an editorial way. 404 The second step, after it has been determined what type of version 405 change is being made to the YANG package, is for the YANG semantic 406 versioning rules to be applied to update the YANG package semantic 407 version number. The formal rules are: 409 If the package is being updated in a nbc way, then the package 410 version "X.Y.Z[m|M]" SHOULD be updated to "X+1.0.0" unless that 411 package version has already been defined with different content, 412 in which case the package version "X.Y.Z+1M MUST be used instead. 414 If the package is being updated in a bc way, then the package 415 version "X.Y.Z[m|M]" SHOULD be updated to "X.Y+1.0" unless that 416 package version has already been defined with different content, 417 in which case if the current package version is "X.Y.ZM" then it 418 MUST be updated to "X.Y.Z+1M", or otherwise "X.Y.Z+1m". 420 If the package is being updated in an editorial way, then the 421 package version "X.Y.Z[m|M]" MUST be updated to "X.Y.Z+1[m|M], 422 retaining the 'm|M' character if it is already present in the 423 previous version.". 425 Package YANG semantic version numbers begining with 0, i.e "0.X.Y" 426 are regarded as beta definitions and need not follow the nbc 427 rules, and the minor version number can be incremented instead. 429 In all cases, the 3 number fields that comprise a YANG semantic 430 version number associated with a YANG package MUST uniquely 431 identify the contents of that YANG package. 433 6.3. Client server package conformance 435 The YANG semantic versioning scheme used for YANG packages means that 436 a client can determine the nature of changes between two package 437 revisions. 439 This means that a client is not restricted to working only with 440 servers that advertise exactly the same version of package in YANG 441 libary. Instead, reasonable clients should be able to interoperate 442 with a server that supports a package version that is backwards 443 compatible to what the client is designed for. 445 For example, a client coded to support 'foo' package at version 1.0.0 446 should interoperate with a server implementing 'foo' package at 447 version 1.3.5, because the YANG semantic versioning rules require 448 that package version 1.3.5 is backwards compatible to version 1.0.0. 450 This also has a relevance on servers that are capable of supporting 451 version selection because they need not necessarily support every 452 version of a YANG package to ensure good client compatibility. 453 Choosing suitable minor versions within each major version number 454 should generally be sufficient, particular if they can avoid NBC 455 patch level changes (i.e. 'M' labelled versions). 457 6.4. Schema referential completeness 459 A YANG package may represent a schema that is 'referentially 460 complete', or 'referentially incomplete'. 462 If all import statements in all YANG modules included in the package 463 (either directly, or through imported packages) can be resolved to a 464 module revision defined with the YANG package definition, then the 465 package is classified as referentially complete. Conversely, if one 466 or more import statements cannot be resolved to a module specified as 467 part of the package definition, then the package is classified as 468 referentially incomplete. 470 A package that represents the exact contents of a datastore schema 471 MUST always be referentially complete. 473 Referentially incomplete packages can be used to group sets of 474 logically related modules together, but without requiring a fixed 475 dependency on all imported 'types' modules, instead leaving the 476 choice of specific revisions of 'types' modules to be resolved when 477 the package definition is used. 479 6.5. Submodules packaging considerations 481 As defined in [RFC7950] and draft-verdt-netmod-yang-semver (TBD), 482 YANG conformance and versioning is specified in terms of particular 483 revisions of YANG modules rather than for individual submodules. 485 However, YANG package definitions also include the list of submodules 486 included by a module, primarily to provide a location of where the 487 submodule definition can be obtained from, allowing a YANG schema to 488 be fully constructed from a YANG package instance-data definition. 490 Restructuring how a module uses, or does not use, submodules is 491 treated as an editorial level change in YANG semantic versioning, on 492 the condition that there is no change in the modules sementic 493 behavior due to the restructuring. 495 To ensure that a module and any constituent submodule are tightly 496 related, all 'include' statements in a YANG module SHOULD specify 497 revision-dates of the included submodules. If 'include' statement 498 revision-dates are included in the YANG module then they MUST match 499 the 'revision' field specified for the submodule in the packages's 500 submodules lists. 502 6.6. Revision history 504 YANG packages do not contain a revision history, because a linear 505 revision history does not work well for a versioning object that 506 supports branching. In addition, some packages could have frequent 507 revisions, and a long revision history would bloat the package 508 definition. 510 To mitigate this, the package definition includes a 'previous- 511 version' leaf that indicates the specific version this package 512 definition is based on. By recursively examining the 'previous- 513 version' leaf of a package definition, a full revision history can be 514 dynamically constructed if required. 516 6.7. Uniqueness of packages and global registry 518 The name given to a package SHOULD be globally unique, and it SHOULD 519 include an appropriate organization prefix in the name, equivalent to 520 YANG module naming conventions. 522 Ideally a YANG instance data document defining a particular package 523 version would be publically available at one or more URLs. 525 7. YANG Packaging instance data 527 YANG packages are expected to be defined as YANG instance data 528 documents [I-D.ietf-netmod-yang-instance-file-format] using the YANG 529 schema below to define the pacakge data itself. 531 The instance data document for each version of a YANG package SHOULD 532 be made available at one of more locations accessible via URLs. If 533 one of the listed locations defines a definitive reference 534 implementation for the package definition then it MUST be listed as 535 the first entry in the list. 537 The "ietf-yang-package" YANG module has the following structure: 539 module: ietf-yang-package 540 +--ro yang-package 541 +--ro name yang:yang-identifier 542 +--ro version yang-sem-ver 543 +--ro revision-date? yanglib:revision-identifier 544 +--ro location* inet:uri 545 +--ro description? string 546 +--ro reference? string 547 +--ro previous-version? yang-sem-ver 548 +--ro tag* tags:tag 549 +--ro referentially-complete? boolean 550 +--ro mandatory-feature* string 551 +--ro imported-packages* [name version] 552 | +--ro name yang:yang-identifier 553 | +--ro version yang-sem-ver 554 | +--ro deviated? boolean 555 | +--ro location* inet:uri 556 +--ro module* [name] 557 | +--ro name yang:yang-identifier 558 | +--ro revision? revision-identifier 559 | +--ro version? yang-sem-ver 560 | +--ro namespace inet:uri 561 | +--ro location* inet:uri 562 | +--ro submodule* [name] 563 | +--ro name yang:yang-identifier 564 | +--ro revision yanglib:revision-identifier 565 | +--ro location* inet:uri 566 +--ro import-only-module* [name revision] 567 +--ro name yang:yang-identifier 568 +--ro revision union 569 +--ro version? yang-sem-ver 570 +--ro namespace inet:uri 571 +--ro location* inet:uri 572 +--ro submodule* [name] 573 | +--ro name yang:yang-identifier 574 | +--ro revision yanglib:revision-identifier 575 | +--ro location* inet:uri 576 +--ro replaces-revision* yanglib:revision-identifier 578 8. YANG Packaging additions to YANG library 579 8.1. Package List 581 The main addition is a top level 'yang-library/package' list that 582 lists all package of all versions known to the server. Each package 583 itself is defined using imported packages and module-sets to define 584 the specific set of modules implemented and imported by the package. 585 The use of module-sets allows the module definitions to be shared 586 with the existing YANG library schema definitions. The existing rule 587 of RFC 7995bis related to combining modules-sets also applies here, 588 i.e. The combined set of modules defined by the module-sets MUST NOT 589 contain modules implemented at different revisions. I.e. the module- 590 sets leaf-list is directly equivalent to the explicit module and 591 import-only-module lists in the instance data YANG package 592 definition. 594 The 'yang-library/package' list MAY include multiple versions of a 595 particular package. E.g. if the server is capable of allowing 596 clients to select which package versions should be used by the 597 server. 599 8.2. Binding from schema to package 601 The second augmentation is to allow a server to optionally indicate 602 that a schema definition directly relates to a package. Since YANG 603 packages are available offline, it may be sufficient for a client to 604 only check that a compatible version of the YANG package is being 605 implemented by the server without fetching and comparing the full 606 module list. 608 If a server indicates that its schema maps to a particular package 609 then it MUST support all mandatory-features defined as part of that 610 package, and it MUST NOT have any deviations to the modules defined 611 by the package. A server MAY implement features not specified in the 612 package's mandatory-features list. 614 If a server cannot faithfully implement a package then it can define 615 a new package to accurately report what it does implement. The new 616 package can include the original package as an imported package, and 617 the new package can define additional modules containing deviations 618 to the original package, allowing the new package to accurately 619 describe the server behavior. There is no specific mechanism 620 provided to indicate that a mandatory-feature is not supported on a 621 server, but deviations MAY be used to disable functionality 622 predicated by a mandatory-feature. 624 8.3. Tree diagram 626 The "ietf-yang-library-packages" YANG module has the following 627 structure: 629 module: ietf-yang-library-packages 630 augment /yanglib:yang-library: 631 +--ro package* [name version] 632 +--ro name yang:yang-identifier 633 +--ro version yang-sem-ver 634 +--ro revision-date? yanglib:revision-identifier 635 +--ro location* inet:uri 636 +--ro description? string 637 +--ro reference? string 638 +--ro previous-version? yang-sem-ver 639 +--ro tag* tags:tag 640 +--ro referentially-complete? boolean 641 +--ro mandatory-feature* string 642 +--ro imported-packages* [name version] 643 | +--ro name yang:yang-identifier 644 | +--ro version yang-sem-ver 645 | +--ro deviated? boolean 646 +--ro module-set* 647 -> /yanglib:yang-library/module-set/name 648 augment /yanglib:yang-library/yanglib:schema: 649 +--ro package 650 +--ro name? -> /yanglib:yang-library/package/name 651 +--ro version? leafref 652 augment /yanglib:yang-library/yanglib:module-set/ 653 yanglib:import-only-module: 654 +--ro replaces-revision* yanglib:revision-identifier 656 9. YANG Packaging groupings 658 Groupings for YANG packaging related constructs are provided in a 659 'types' module for use by the instance-data and YANG library 660 constructs described previously. They are also avaiable to be used 661 by other modules that have a need for packaging information. 663 The "ietf-yang-package-types" YANG module has the following 664 structure: 666 module: ietf-yang-package-types 668 grouping yang-pkg-identification-leafs 669 +---- name yang:yang-identifier 670 +---- version yang-sem-ver 671 grouping yang-pkg-common-leafs 672 +---- revision-date? yanglib:revision-identifier 673 +---- location* inet:uri 674 +---- description? string 675 +---- reference? string 676 +---- previous-version? yang-sem-ver 677 +---- tag* tags:tag 678 +---- referentially-complete? boolean 679 +---- mandatory-feature* string 680 +---- imported-packages* [name version] 681 +---- name yang:yang-identifier 682 +---- version yang-sem-ver 683 +---- deviated? boolean 684 grouping yang-pkg-library-definition 685 +---- name yang:yang-identifier 686 +---- version yang-sem-ver 687 +---- revision-date? yanglib:revision-identifier 688 +---- location* inet:uri 689 +---- description? string 690 +---- reference? string 691 +---- previous-version? yang-sem-ver 692 +---- tag* tags:tag 693 +---- referentially-complete? boolean 694 +---- mandatory-feature* string 695 +---- imported-packages* [name version] 696 | +---- name yang:yang-identifier 697 | +---- version yang-sem-ver 698 | +---- deviated? boolean 699 +---- module-set* 700 -> /yanglib:yang-library/module-set/name 701 grouping yang-pkg-file-definition 702 +---- name yang:yang-identifier 703 +---- version yang-sem-ver 704 +---- revision-date? yanglib:revision-identifier 705 +---- location* inet:uri 706 +---- description? string 707 +---- reference? string 708 +---- previous-version? yang-sem-ver 709 +---- tag* tags:tag 710 +---- referentially-complete? boolean 711 +---- mandatory-feature* string 712 +---- imported-packages* [name version] 713 | +---- name yang:yang-identifier 714 | +---- version yang-sem-ver 715 | +---- deviated? boolean 716 | +---- location* inet:uri 717 +---- module* [name] 718 | +---- name yang:yang-identifier 719 | +---- revision? revision-identifier 720 | +---- version? yang-sem-ver 721 | +---- namespace inet:uri 722 | +---- location* inet:uri 723 | +---- submodule* [name] 724 | +---- name? yang:yang-identifier 725 | +---- revision yanglib:revision-identifier 726 | +---- location* inet:uri 727 +---- import-only-module* [name revision] 728 +---- name? yang:yang-identifier 729 +---- revision? union 730 +---- version? yang-sem-ver 731 +---- namespace inet:uri 732 +---- location* inet:uri 733 +---- submodule* [name] 734 | +---- name? yang:yang-identifier 735 | +---- revision yanglib:revision-identifier 736 | +---- location* inet:uri 737 +---- replaces-revision* yanglib:revision-identifier 739 10. YANG Modules 741 The YANG module definitions for the modules described in the previous 742 sections. 744 file "ietf-yang-package-types@2018-11-26.yang" 745 module ietf-yang-package-types { 746 yang-version 1.1; 747 namespace "urn:ietf:params:xml:ns:yang:ietf-yang-package-types"; 748 prefix "pkg-types"; 750 import ietf-yang-types { 751 prefix yang; 752 reference "RFC 6991: Common YANG Data Types."; 753 } 754 import ietf-inet-types { 755 prefix inet; 756 reference "RFC 6991: Common YANG Data Types."; 757 } 758 import ietf-yang-library { 759 prefix yanglib; 760 reference "RFC 7895bis: YANG Library"; 761 } 762 import ietf-module-tags { 763 prefix tags; 764 reference "XXX, (draft-ietf-netmod-module-tags-03): YANG Module Tags"; 765 } 767 organization 768 "IETF NETMOD (Network Modeling) Working Group"; 770 contact 771 "WG Web: 772 WG List: 774 Author: Rob Wilton 775 "; 777 description 778 "This module provides type and grouping definitions for YANG 779 packages. 781 Copyright (c) 2018 IETF Trust and the persons identified as 782 authors of the code. All rights reserved. 784 Redistribution and use in source and binary forms, with or 785 without modification, is permitted pursuant to, and subject 786 to the license terms contained in, the Simplified BSD License 787 set forth in Section 4.c of the IETF Trust's Legal Provisions 788 Relating to IETF Documents 789 (http://trustee.ietf.org/license-info). 791 This version of this YANG module is part of RFC XXXX; see 792 the RFC itself for full legal notices."; 794 // RFC Ed.: update the date below with the date of RFC publication 795 // and remove this note. 796 // RFC Ed.: replace XXXX with actual RFC number and remove this 797 // note. 798 revision 2018-11-26 { 799 description 800 "Initial revision"; 801 reference 802 "RFC XXXX: YANG Schema Versioning."; 803 } 805 /* 806 * Typedefs 807 */ 809 typedef yang-sem-ver { 810 type string { 811 pattern '\d+[.]\d+[.]\d+[mM]?'; 812 } 813 description 814 "Represents a YANG semantic version number."; 815 reference 816 "TODO - Should be defined by YANG versioning types module"; 817 } 819 /* 820 * Groupings 821 */ 823 grouping yang-pkg-identification-leafs { 824 description 825 "Parameters for identifying a specific version of a YANG 826 package"; 828 leaf name { 829 type yang:yang-identifier; 830 mandatory true; 831 description 832 "The YANG package name."; 833 } 835 leaf version { 836 type yang-sem-ver; 837 mandatory true; 838 description 839 "YANG package version. Follows YANG semantic versions rules 840 defined in XXX"; 841 } 842 } 844 grouping yang-pkg-common-leafs { 845 description 846 "Defines definitions common to all YANG package definitions."; 848 leaf revision-date { 849 type yanglib:revision-identifier; 851 description 852 "An optional revision identifier of when this package version 853 was created. This does not need to be unique across all 854 versions of a package."; 855 } 857 leaf-list location { 858 type inet:uri; 859 description 860 "Contains a URL that represents where an instance data file 861 for this YANG package can be found. 863 This leaf will only be present if there is a URL 864 available for retrieval of the schema for this entry. 866 If multiple locations are provided, then the first location 867 in the leaf-list MUST be the definitive location that 868 uniquely identifies this package"; 869 } 871 leaf description { 872 type string; 874 description "Provides a description of the package"; 875 } 877 leaf reference { 878 type string; 880 description "Allows for a reference for the package"; 881 } 883 leaf previous-version { 884 type yang-sem-ver; 885 description 886 "The previous package version that this version has been 887 derived from. This leaf allows a full version history graph 888 to be constructed if required."; 889 } 891 leaf-list tag { 892 type tags:tag; 893 description 894 "Tags associated with a YANG package. Module tags defined in 895 XXX, ietf-netmod-module-tags can be used here but with the 896 modification that the tag applies to the entire package 897 rather than a specific module. See the IANA 'YANG Module Tag 898 Prefix' registry for reserved prefixes and the IANA 'YANG 899 Module IETF Tag' registry for IETF standard tags."; 900 } 902 leaf referentially-complete { 903 type boolean; 904 default true; 905 description 906 "Indicates whether the schema defined by this package is 907 referentially complete. I.e. all module imports can be 908 resolved to a module explcitly defined in this package or one 909 of the imported packages."; 910 } 912 leaf-list mandatory-feature { 913 type string; 914 // TODO - Is there a better type for this? 915 description 916 "List all features from modules included in the package that 917 MUST be supported by any server implementing the package. 918 All other features defined in included packages are OPTIONAL 919 to implement. 921 Features are identified using :"; 922 } 924 list imported-packages { 925 key "name version"; 926 description 927 "An entry in this list represents a package that is imported 928 as part of the package definition. 930 If packages implement different revisions or versions of the 931 same module, then an explicit entry in the module list MUST 932 be provided to select the specific module version 933 'implemented' by this package definition. 935 For import-only modules, the replaces-revision leaf-list can 936 be used to select the specific module versions imported by 937 this package."; 938 reference 939 "XXX"; 941 uses yang-pkg-identification-leafs; 943 leaf deviated { 944 type boolean; 945 default true; 946 description 947 "Set to true if any data nodes in this package are modified 948 in a non backwards compatible way, either through the use 949 of deviations, or because one of the modules has been 950 replaced by an earlier module version."; 951 } 952 } 953 } 954 grouping yang-pkg-file-definition { 955 description 956 "The set of parameters that describe a particular YANG package."; 958 uses yang-pkg-identification-leafs; 960 uses yang-pkg-common-leafs { 961 augment "imported-packages" { 962 description "Add the package location path"; 964 leaf-list location { 965 type inet:uri; 966 description 967 "Contains a URL that represents where an instance data 968 file for this YANG package can be found. 970 This leaf will only be present if there is a URL 971 available for retrieval of the schema for this entry. 973 If multiple locations are provided, then the first 974 location in the leaf-list MUST be the definitive location 975 that uniquely identifies this package"; 976 } 977 } 978 } 980 list module { 981 key "name"; 982 description 983 "An entry in this list represents a module that must be 984 implemented by a server implementing this package, as per 985 RFC 7950 section 5.6.5, with a particular set of supported 986 features and deviations. 988 A entry in this list overrides any module version 989 'implemented' by an imported package"; 990 reference 991 "RFC 7950: The YANG 1.1 Data Modeling Language."; 993 uses yanglib:module-identification-leafs; 995 leaf version { 996 type yang-sem-ver; 997 description 998 "The YANG module or submodule version. If no version 999 statement is present in the YANG module or submodule, this 1000 leaf is not instantiated."; 1001 } 1002 leaf namespace { 1003 type inet:uri; 1004 mandatory true; 1005 description 1006 "The XML namespace identifier for this module."; 1007 } 1008 uses yanglib:location-leaf-list; 1010 list submodule { 1011 key "name"; 1012 description 1013 "Each entry represents one submodule within the 1014 parent module."; 1016 leaf name { 1017 type yang:yang-identifier; 1018 description 1019 "The YANG submodule name."; 1020 } 1021 leaf revision { 1022 type yanglib:revision-identifier; 1023 mandatory true; 1024 description 1025 "The YANG submodule revision date. If the parent module 1026 include statement for this submodule includes a revision 1027 date then it MUST match this leaf's value."; 1028 } 1030 uses yanglib:location-leaf-list; 1031 } 1032 } 1034 list import-only-module { 1035 key "name revision"; 1036 description 1037 "An entry in this list indicates that the server imports 1038 reusable definitions from the specified revision of the 1039 module, but does not implement any protocol accessible 1040 objects from this revision. 1042 Multiple entries for the same module name MAY exist. This 1043 can occur if multiple modules import the same module, but 1044 specify different revision-dates in the import statements."; 1046 leaf name { 1047 type yang:yang-identifier; 1048 description 1049 "The YANG module name."; 1051 } 1052 leaf revision { 1053 type union { 1054 type yanglib:revision-identifier; 1055 type string { 1056 length 0; 1057 } 1058 } 1059 description 1060 "The YANG module revision date. A zero-length string is 1061 used if no revision statement is present in the YANG 1062 module."; 1063 } 1064 leaf version { 1065 type yang-sem-ver; 1066 description 1067 "The YANG module or submodule version. If no version 1068 statement is present in the YANG module or submodule, this 1069 leaf is not instantiated."; 1070 } 1071 leaf namespace { 1072 type inet:uri; 1073 mandatory true; 1074 description 1075 "The XML namespace identifier for this module."; 1076 } 1078 uses yanglib:location-leaf-list; 1080 list submodule { 1081 key "name"; 1082 description 1083 "Each entry represents one submodule within the 1084 parent module."; 1086 leaf name { 1087 type yang:yang-identifier; 1088 description 1089 "The YANG submodule name."; 1090 } 1091 leaf revision { 1092 type yanglib:revision-identifier; 1093 mandatory true; 1094 description 1095 "The YANG submodule revision date. If the parent module 1096 include statement for this submodule includes a revision 1097 date then it MUST match this leaf's value."; 1098 } 1099 uses yanglib:location-leaf-list; 1100 } 1102 leaf-list replaces-revision { 1103 type yanglib:revision-identifier; 1104 description 1105 "Gives the revision of an import-only-module defined in 1106 an imported package that is replaced by this 1107 import-only-module revision."; 1108 } 1109 } 1110 } 1112 grouping yang-pkg-library-definition { 1113 description 1114 "The set of parameters that describe a particular YANG package."; 1116 uses yang-pkg-identification-leafs; 1117 uses yang-pkg-common-leafs; 1119 leaf-list module-set { 1120 type leafref { 1121 path "/yanglib:yang-library/yanglib:module-set/yanglib:name"; 1122 } 1123 description 1124 "Describes any modules in addition to, and replacing, and 1125 modules defined in the imported packages. 1127 If a non import-only module appears in multiple module sets, 1128 then the module revision and the associated features and 1129 deviations must be identical."; 1130 } 1131 } 1132 } 1133 1135 file "ietf-yang-package2018-11-26.yang" 1136 module ietf-yang-package { 1137 yang-version 1.1; 1138 namespace "urn:ietf:params:xml:ns:yang:ietf-yang-package"; 1139 prefix pkg; 1141 import ietf-yang-package-types { 1142 prefix pkg-types; 1143 reference "RFC XXX: YANG Schema Versioning."; 1144 } 1145 organization 1146 "IETF NETMOD (Network Modeling) Working Group"; 1148 contact 1149 "WG Web: 1150 WG List: 1152 Author: Rob Wilton 1153 "; 1155 description 1156 "This module provides a definition of a YANG package, which is 1157 used as the schema for an YANG instance data document specifying 1158 a YANG package. 1160 Copyright (c) 2018 IETF Trust and the persons identified as 1161 authors of the code. All rights reserved. 1163 Redistribution and use in source and binary forms, with or 1164 without modification, is permitted pursuant to, and subject 1165 to the license terms contained in, the Simplified BSD License 1166 set forth in Section 4.c of the IETF Trust's Legal Provisions 1167 Relating to IETF Documents 1168 (http://trustee.ietf.org/license-info). 1170 This version of this YANG module is part of RFC XXXX; see 1171 the RFC itself for full legal notices."; 1173 // RFC Ed.: update the date below with the date of RFC publication 1174 // and remove this note. 1175 // RFC Ed.: replace XXXX with actual RFC number and remove this 1176 // note. 1177 revision 2018-11-26 { 1178 description 1179 "Initial revision"; 1180 reference 1181 "RFC XXXX: YANG Schema Versioning."; 1182 } 1184 /* 1185 * Top-level container 1186 */ 1188 container yang-package { 1189 config false; 1190 description 1191 "Defines a YANG package. 1193 Intended to be used to specify a YANG package as an instance 1194 data document."; 1196 uses pkg-types:yang-pkg-file-definition; 1197 } 1198 } 1199 1201 file "ietf-yang-library-packages@2018-11-26.yang" 1202 module ietf-yang-library-packages { 1203 yang-version 1.1; 1204 namespace 1205 "urn:ietf:params:xml:ns:yang:ietf-yang-library-packages"; 1206 prefix pkg; 1208 import ietf-yang-package-types { 1209 prefix pkg-types; 1210 reference "RFC XXX: YANG Packages."; 1211 } 1212 import ietf-yang-library { 1213 prefix yanglib; 1214 reference "RFC 7895bis: YANG Library"; 1215 } 1217 organization 1218 "IETF NETMOD (Network Modeling) Working Group"; 1220 contact 1221 "WG Web: 1222 WG List: 1224 Author: Rob Wilton 1225 "; 1227 description 1228 "This module provides defined augmentations to YANG library to 1229 allow a server to report YANG package information. 1231 Copyright (c) 2018 IETF Trust and the persons identified as 1232 authors of the code. All rights reserved. 1234 Redistribution and use in source and binary forms, with or 1235 without modification, is permitted pursuant to, and subject 1236 to the license terms contained in, the Simplified BSD License 1237 set forth in Section 4.c of the IETF Trust's Legal Provisions 1238 Relating to IETF Documents 1239 (http://trustee.ietf.org/license-info). 1241 This version of this YANG module is part of RFC XXXX; see 1242 the RFC itself for full legal notices."; 1244 // RFC Ed.: update the date below with the date of RFC publication 1245 // and remove this note. 1246 // RFC Ed.: replace XXXX with actual RFC number and remove this 1247 // note. 1248 revision 2018-11-26 { 1249 description 1250 "Initial revision"; 1251 reference 1252 "RFC XXXX: YANG Schema Versioning."; 1253 } 1255 /* 1256 * Add in the list of packaged into YANG libary. 1257 */ 1258 augment "/yanglib:yang-library" { 1259 description "Add YANG package definitions into YANG library"; 1261 list package { 1262 config "false"; 1263 key "name version"; 1265 description "Defines the packages available on this server."; 1267 uses "pkg-types:yang-pkg-library-definition"; 1268 } 1269 } 1271 /* 1272 * Allow schema to be related to a YANG package. 1273 */ 1274 augment "/yanglib:yang-library/yanglib:schema" { 1275 description 1276 "Allow datastore schema to be related to a YANG package"; 1278 container package { 1279 leaf name { 1280 type leafref { 1281 path "/yanglib:yang-library/package/name"; 1282 } 1283 description 1284 "The name of the package this schema relates to."; 1285 } 1286 leaf version { 1287 type leafref { 1288 path '/yanglib:yang-library/' 1289 + 'package[name = current()/../name]/version'; 1290 } 1292 description 1293 "The version of the package this schema relates to."; 1294 } 1296 description 1297 "Describes which package the schema directly relates to, if 1298 any."; 1299 } 1300 } 1302 /* 1303 * Allow import-only modules to list the versions that they are 1304 * replacing. 1305 */ 1307 augment 1308 "/yanglib:yang-library/yanglib:module-set/" + 1309 "yanglib:import-only-module" { 1311 description 1312 "Add replaces-revision to import-only-module definitions"; 1314 leaf-list replaces-revision { 1315 type yanglib:revision-identifier; 1316 description 1317 "Gives the revision of an import-only-module defined in an 1318 imported package that is replaced by this import-only-module 1319 revision. 1321 Only used for YANG package definitions"; 1322 } 1323 } 1324 } 1325 1327 11. Security Considerations 1329 The YANG modules specified in this document defines a schema for data 1330 that is accessed by network management protocols such as NETCONF 1331 [RFC6241] or RESTCONF [RFC8040]. The lowest NETCONF layer is the 1332 secure transport layer, and the mandatory-to-implement secure 1333 transport is Secure Shell (SSH) [RFC6242]. The lowest RESTCONF layer 1334 is HTTPS, and the mandatory-to-implement secure transport is TLS 1335 [RFC5246]. 1337 The NETCONF access control model [RFC6536] provides the means to 1338 restrict access for particular NETCONF or RESTCONF users to a 1339 preconfigured subset of all available NETCONF or RESTCONF protocol 1340 operations and content. 1342 Similarly to YANG library [I-D.ietf-netconf-rfc7895bis], some of the 1343 readable data nodes in these YANG modules may be considered sensitive 1344 or vulnerable in some network environments. It is thus important to 1345 control read access (e.g., via get, get-config, or notification) to 1346 these data nodes. 1348 One additional key different to YANG library, is that the 'ietf-yang- 1349 package' YANG module defines a schema to allow YANG packages to be 1350 defined in YANG instance data documents, that are outside the 1351 security controls of the network management protocols. Hence, it is 1352 important to also consider controlling access to these package 1353 instance data documents to restrict access to sensitive information. 1355 As per the YANG library security considerations, the module, revision 1356 and version information in YANG packages may help an attacker 1357 identify the server capabilities and server implementations with 1358 known bugs since the set of YANG modules supported by a server may 1359 reveal the kind of device and the manufacturer of the device. Server 1360 vulnerabilities may be specific to particular modules, module 1361 revisions, module features, or even module deviations. For example, 1362 if a particular operation on a particular data node is known to cause 1363 a server to crash or significantly degrade device performance, then 1364 the packaging information will help an attacker identify server 1365 implementations with such a defect, in order to launch a denial-of- 1366 service attack on the device. 1368 12. IANA Considerations 1370 It is expected that a central registry of standard YANG package 1371 definitions is required to support this packaging solution. 1373 It is unclear whether an IANA registry is also required to manage 1374 specific package versions. It is highly desirable to have a specific 1375 canonical location, under IETF control, where the definitive YANG 1376 package versions can be obtained from. 1378 TODO - Add IANA registrations for YANG modules defined in this draft. 1380 13. Open Questions/Issues 1382 All issues, along with the draft text, are currently being tracked at 1383 https://github.com/rgwilton/YANG-Packages-Draft/issues/ 1385 14. Acknowledgements 1387 Feedback helping shape this document has kindly been provided by Andy 1388 Bierman, Ladislav Lhotka, and Jason Sterne. 1390 15. References 1392 15.1. Normative References 1394 [I-D.ietf-netconf-rfc7895bis] 1395 Bierman, A., Bjorklund, M., Schoenwaelder, J., Watsen, K., 1396 and R. Wilton, "YANG Library", draft-ietf-netconf- 1397 rfc7895bis-07 (work in progress), October 2018. 1399 [I-D.ietf-netmod-module-tags] 1400 Hopps, C., Berger, L., and D. Bogdanovic, "YANG Module 1401 Tags", draft-ietf-netmod-module-tags-07 (work in 1402 progress), March 2019. 1404 [I-D.ietf-netmod-yang-instance-file-format] 1405 Lengyel, B. and B. Claise, "YANG Instance Data File 1406 Format", draft-ietf-netmod-yang-instance-file-format-02 1407 (work in progress), February 2019. 1409 [I-D.verdt-netmod-yang-versioning-reqs] 1410 Clarke, J., "YANG Module Versioning Requirements", draft- 1411 verdt-netmod-yang-versioning-reqs-02 (work in progress), 1412 November 2018. 1414 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1415 Requirement Levels", BCP 14, RFC 2119, 1416 DOI 10.17487/RFC2119, March 1997, 1417 . 1419 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 1420 (TLS) Protocol Version 1.2", RFC 5246, 1421 DOI 10.17487/RFC5246, August 2008, 1422 . 1424 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 1425 and A. Bierman, Ed., "Network Configuration Protocol 1426 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 1427 . 1429 [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure 1430 Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011, 1431 . 1433 [RFC6536] Bierman, A. and M. Bjorklund, "Network Configuration 1434 Protocol (NETCONF) Access Control Model", RFC 6536, 1435 DOI 10.17487/RFC6536, March 2012, 1436 . 1438 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 1439 RFC 7950, DOI 10.17487/RFC7950, August 2016, 1440 . 1442 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 1443 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 1444 . 1446 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1447 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1448 May 2017, . 1450 [RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 1451 and R. Wilton, "Network Management Datastore Architecture 1452 (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018, 1453 . 1455 15.2. Informative References 1457 [I-D.bierman-netmod-yang-package] 1458 Bierman, A., "The YANG Package Statement", draft-bierman- 1459 netmod-yang-package-00 (work in progress), July 2015. 1461 [I-D.ietf-netmod-artwork-folding] 1462 Watsen, K., Wu, Q., Farrel, A., and B. Claise, "Handling 1463 Long Lines in Artwork in Internet-Drafts and RFCs", draft- 1464 ietf-netmod-artwork-folding-00 (work in progress), 1465 November 2018. 1467 [openconfigsemver] 1468 "Semantic Versioning for Openconfig Models", 1469 . 1471 [RFC8199] Bogdanovic, D., Claise, B., and C. Moberg, "YANG Module 1472 Classification", RFC 8199, DOI 10.17487/RFC8199, July 1473 2017, . 1475 Appendix A. Tree output for ietf-yang-library with package 1476 augmentations 1478 Complete tree output for ietf-yang-library with package 1479 augmentations. 1481 module: ietf-yang-library 1482 +--ro yang-library 1483 | +--ro module-set* [name] 1484 | | +--ro name string 1485 | | +--ro module* [name] 1486 | | | +--ro name yang:yang-identifier 1487 | | | +--ro revision? revision-identifier 1488 | | | +--ro namespace inet:uri 1489 | | | +--ro location* inet:uri 1490 | | | +--ro submodule* [name] 1491 | | | | +--ro name yang:yang-identifier 1492 | | | | +--ro revision? revision-identifier 1493 | | | | +--ro location* inet:uri 1494 | | | +--ro feature* yang:yang-identifier 1495 | | | +--ro deviation* -> ../../module/name 1496 | | +--ro import-only-module* [name revision] 1497 | | +--ro name yang:yang-identifier 1498 | | +--ro revision union 1499 | | +--ro namespace inet:uri 1500 | | +--ro location* inet:uri 1501 | | +--ro submodule* [name] 1502 | | | +--ro name yang:yang-identifier 1503 | | | +--ro revision? revision-identifier 1504 | | | +--ro location* inet:uri 1505 | | +--ro pkg:replaces-revision* 1506 | | yanglib:revision-identifier 1507 | +--ro schema* [name] 1508 | | +--ro name string 1509 | | +--ro module-set* -> ../../module-set/name 1510 | | +--ro pkg:package 1511 | | +--ro pkg:name? 1512 | | | -> /yanglib:yang-library/package/name 1513 | | +--ro pkg:version? leafref 1514 | +--ro datastore* [name] 1515 | | +--ro name ds:datastore-ref 1516 | | +--ro schema -> ../../schema/name 1517 | +--ro content-id string 1518 | +--ro pkg:package* [name version] 1519 | +--ro pkg:name yang:yang-identifier 1520 | +--ro pkg:version yang-sem-ver 1521 | +--ro pkg:revision-date? 1522 | | yanglib:revision-identifier 1523 | +--ro pkg:location* inet:uri 1524 | +--ro pkg:description? string 1525 | +--ro pkg:reference? string 1526 | +--ro pkg:previous-version? yang-sem-ver 1527 | +--ro pkg:tag* tags:tag 1528 | +--ro pkg:referentially-complete? boolean 1529 | +--ro pkg:mandatory-feature* string 1530 | +--ro pkg:imported-packages* [name version] 1531 | | +--ro pkg:name yang:yang-identifier 1532 | | +--ro pkg:version yang-sem-ver 1533 | | +--ro pkg:deviated? boolean 1534 | +--ro pkg:module-set* 1535 | -> /yanglib:yang-library/module-set/name 1536 x--ro modules-state 1537 x--ro module-set-id string 1538 x--ro module* [name revision] 1539 x--ro name yang:yang-identifier 1540 x--ro revision union 1541 +--ro schema? inet:uri 1542 x--ro namespace inet:uri 1543 x--ro feature* yang:yang-identifier 1544 x--ro deviation* [name revision] 1545 | x--ro name yang:yang-identifier 1546 | x--ro revision union 1547 x--ro conformance-type enumeration 1548 x--ro submodule* [name revision] 1549 x--ro name yang:yang-identifier 1550 x--ro revision union 1551 +--ro schema? inet:uri 1553 notifications: 1554 +---n yang-library-update 1555 | +--ro content-id -> /yang-library/content-id 1556 x---n yang-library-change 1557 x--ro module-set-id -> /modules-state/module-set-id 1559 Appendix B. Examples 1561 This section provides various examples of YANG packages, and as such 1562 this text is non-normative. The purpose of the examples is to only 1563 illustrate the file format of YANG packages, and how package 1564 dependencies work. It does not imply that such packages will be 1565 defined by IETF, or which modules would be included in those packages 1566 even if they were defined. 1568 B.1. Example IETF Network Device YANG package 1570 This section provides an instance data document example of an IETF 1571 Network Device YANG package formatted in JSON. 1573 This example package is intended to represent the standard set of 1574 YANG modules, with import dependencies, to implement a basic network 1575 device without any dynamic routing or layer 2 services. E.g., it 1576 includes functionality such as system information, interface and 1577 basic IP configuration. 1579 As for all YANG packages, all import dependencies are fully resolved. 1580 Because this example uses YANG modules that have been standardized 1581 before YANG semantic versioning, they modules are referenced by 1582 revision date rather than version number. 1584 file "example-ietf-network-device-pkg.json" 1585 ========= NOTE: '\\' line wrapping per BCP XX (RFC XXXX) =========== 1587 { 1588 "ietf-yang-instance-data:instance-data-set": { 1589 "name": "example-ietf-network-device-pkg", 1590 "target-ptr": "TBD", 1591 "timestamp": "2018-12-13T17:00:00Z", 1592 "description": "Example IETF network device YANG package definit\ 1593 \ion", 1594 "content-data": { 1595 "ietf-yang-package:yang-package": { 1596 "name": "example-ietf-network-device", 1597 "version": "1.1.2", 1598 "namespace": "urn:ietf:params:xml:ns:yang-pkg:ietf-network-d\ 1599 \evice", 1600 "location": "file://example.org/yang/packages/ietf-network-d\ 1601 \evice@v1.1.2.json", 1602 "description": "This package defines a small sample set of Y\ 1603 \ANG modules that could represent the basic set of modules that a st\ 1604 \andard network device might be expected to support.", 1605 "reference": "XXX, draft-rwilton-netmod-yang-packages", 1606 "revision-date": "2018-11-26", 1607 "module": [ 1608 { 1609 "name": "iana-crypt-hash", 1610 "revision": "2014-08-06", 1611 "namespace": "urn:ietf:params:xml:ns:yang:iana-crypt-has\ 1612 \h", 1613 "location": "https://raw.githubusercontent.com/YangModel\ 1614 \s/yang/master/standard/ietf/RFC/iana-crypt-hash%402014-08-06.yang" 1615 }, 1616 { 1617 "name": "ietf-system", 1618 "revision": "2014-08-06", 1619 "namespace": "urn:ietf:params:xml:ns:yang:ietf-system", 1620 "location": "https://raw.githubusercontent.com/YangModel\ 1621 \s/yang/master/standard/ietf/RFC/ietf-system%402014-08-06.yang" 1622 }, 1623 { 1624 "name": "ietf-interfaces", 1625 "revision": "2018-02-20", 1626 "namespace": "urn:ietf:params:xml:ns:yang:ietf-interface\ 1627 \s", 1628 "location": "https://raw.githubusercontent.com/YangModel\ 1629 \s/yang/master/standard/ietf/RFC/ietf-interfaces%402018-02-20.yang" 1630 }, 1631 { 1632 "name": "ietf-netconf-acm", 1633 "revision": "2018-02-14", 1634 "namespace": "urn:ietf:params:xml:ns:yang:ietf-netconf-a\ 1635 \cm", 1636 "location": "https://raw.githubusercontent.com/YangModel\ 1637 \s/yang/master/standard/ietf/RFC/ietf-netconf-acm%402018-02-14.yang" 1638 }, 1639 { 1640 "name": "ietf-key-chain", 1641 "revision": "2017-06-15", 1642 "namespace": "urn:ietf:params:xml:ns:yang:ietf-key-chain\ 1643 \", 1644 "location": "https://raw.githubusercontent.com/YangModel\ 1645 \s/yang/master/standard/ietf/RFC/ietf-key-chain@2017-06-15.yang" 1646 }, 1647 { 1648 "name": "ietf-ip", 1649 "revision": "2018-02-22", 1650 "namespace": "urn:ietf:params:xml:ns:yang:ietf-ip", 1651 "location": "https://raw.githubusercontent.com/YangModel\ 1652 \s/yang/master/standard/ietf/RFC/ietf-ip%402018-02-22.yang" 1653 } 1654 ], 1655 "import-only-module": [ 1656 { 1657 "name": "ietf-yang-types", 1658 "revision": "2013-07-15", 1659 "namespace": "urn:ietf:params:xml:ns:yang:ietf-yang-type\ 1660 \s", 1661 "location": "https://raw.githubusercontent.com/YangModel\ 1662 \s/yang/master/standard/ietf/RFC/ietf-yang-types%402013-07-15.yang" 1663 }, 1664 { 1665 "name": "ietf-inet-types", 1666 "revision": "2013-07-15", 1667 "namespace": "urn:ietf:params:xml:ns:yang:ietf-inet-type\ 1668 \s", 1669 "location": "https://raw.githubusercontent.com/YangModel\ 1670 \s/yang/master/standard/ietf/RFC/ietf-inet-types%402013-07-15.yang" 1671 } 1672 ] 1673 } 1674 } 1675 } 1676 } 1677 1679 B.2. Example IETF Basic Routing YANG package 1681 This section provides an instance data document example of a basic 1682 IETF Routing YANG package formatted in JSON. 1684 This example package is intended to represent the standard set of 1685 YANG modules, with import dependencies, that builds upon the example- 1686 ietf-network-device YANG package to add support for basic dynamic 1687 routing and ACLs. 1689 As for all YANG packages, all import dependencies are fully resolved. 1690 Because this example uses YANG modules that have been standardized 1691 before YANG semantic versioning, they modules are referenced by 1692 revision date rather than version number. Locations have been 1693 excluded where they are not currently known, e.g., for YANG modules 1694 defined in IETF drafts. In a normal YANG package, locations would be 1695 expected to be provided for all YANG modules. 1697 file "example-ietf-routing-pkg.json" 1698 ========== NOTE: '\\' line wrapping per BCP XX (RFC XXXX) =========== 1700 { 1701 "ietf-yang-instance-data:instance-data-set": { 1702 "name": "example-ietf-routing-pkg", 1703 "target-ptr": "TBD", 1704 "timestamp": "2018-12-13T17:00:00Z", 1705 "description": "Example IETF routing YANG package definition", 1706 "content-data": { 1707 "ietf-yang-package:yang-package": { 1708 "name": "example-ietf-routing", 1709 "version": "1.3.1", 1710 "namespace": "urn:ietf:params:xml:ns:yang-pkg:ietf-routing", 1711 "location": "file://example.org/yang/packages/ietf-routing@v\ 1712 \1.3.1.json", 1713 "description": "This package defines a small sample set of I\ 1714 \ETF routing YANG modules that could represent the set of IETF routi\ 1715 \ng functionality that a basic IP network device might be expected t\ 1716 \o support.", 1717 "reference": "XXX, draft-rwilton-netmod-yang-packages", 1718 "revision-date": "2018-11-26", 1719 "imported-packages": [ 1720 { 1721 "name": "ietf-network-device", 1722 "version": "1.1.2", 1723 "location": [ 1724 "http://example.org/yang/packages/ietf-network-device@\ 1725 \v1.1.2.json" 1726 ] 1727 } 1728 ], 1729 "module": [ 1730 { 1731 "name": "ietf-routing", 1732 "revision": "2018-03-13", 1733 "namespace": "urn:ietf:params:xml:ns:yang:ietf-routing", 1734 "location": [ 1735 "https://raw.githubusercontent.com/YangModels/yang/mas\ 1736 \ter/standard/ietf/RFC/ietf-routing@2018-03-13.yang" 1737 ] 1738 }, 1739 { 1740 "name": "ietf-ipv4-unicast-routing", 1741 "revision": "2018-03-13", 1742 "namespace": "urn:ietf:params:xml:ns:yang:ietf-ipv4-unca\ 1743 \st-routing", 1744 "location": [ 1745 "https://raw.githubusercontent.com/YangModels/yang/mas\ 1746 \ter/standard/ietf/RFC/ietf-ipv4-unicast-routing@2018-03-13.yang" 1747 ] 1748 }, 1749 { 1750 "name": "ietf-ipv6-unicast-routing", 1751 "revision": "2018-03-13", 1752 "namespace": "urn:ietf:params:xml:ns:yang:ietf-ipv6-unca\ 1753 \st-routing", 1754 "location": [ 1755 "https://raw.githubusercontent.com/YangModels/yang/mas\ 1756 \ter/standard/ietf/RFC/ietf-ipv6-unicast-routing@2018-03-13.yang" 1757 ] 1758 }, 1759 { 1760 "name": "ietf-isis", 1761 "revision": "2018-12-11", 1762 "namespace": "urn:ietf:params:xml:ns:yang:ietf-isis" 1763 }, 1764 { 1765 "name": "ietf-interfaces-common", 1766 "revision": "2018-07-02", 1767 "namespace": "urn:ietf:params:xml:ns:yang:ietf-interface\ 1768 \s-common" 1769 }, 1770 { 1771 "name": "ietf-if-l3-vlan", 1772 "revision": "2017-10-30", 1773 "namespace": "urn:ietf:params:xml:ns:yang:ietf-if-l3-vla\ 1774 \n" 1775 }, 1776 { 1777 "name": "ietf-routing-policy", 1778 "revision": "2018-10-19", 1779 "namespace": "urn:ietf:params:xml:ns:yang:ietf-routing-p\ 1780 \olicy" 1781 }, 1782 { 1783 "name": "ietf-bgp", 1784 "revision": "2018-05-09", 1785 "namespace": "urn:ietf:params:xml:ns:yang:ietf-bgp" 1786 }, 1787 { 1788 "name": "ietf-access-control-list", 1789 "revision": "2018-11-06", 1790 "namespace": "urn:ietf:params:xml:ns:yang:ietf-access-co\ 1791 \ntrol-list" 1792 } 1793 ], 1794 "import-only-module": [ 1795 { 1796 "name": "ietf-routing-types", 1797 "revision": "2017-12-04", 1798 "namespace": "urn:ietf:params:xml:ns:yang:ietf-routing-t\ 1799 \ypes", 1800 "location": [ 1801 "https://raw.githubusercontent.com/YangModels/yang/mas\ 1802 \ter/standard/ietf/RFC/ietf-routing-types@2017-12-04.yang" 1803 ] 1804 }, 1805 { 1806 "name": "iana-routing-types", 1807 "revision": "2017-12-04", 1808 "namespace": "urn:ietf:params:xml:ns:yang:iana-routing-t\ 1809 \ypes", 1810 "location": [ 1811 "https://raw.githubusercontent.com/YangModels/yang/mas\ 1812 \ter/standard/ietf/RFC/iana-routing-types@2017-12-04.yang" 1813 ] 1814 }, 1815 { 1816 "name": "ietf-bgp-types", 1817 "revision": "2018-05-09", 1818 "namespace": "urn:ietf:params:xml:ns:yang:ietf-bgp-types" 1819 }, 1820 { 1821 "name": "ietf-packet-fields", 1822 "revision": "2018-11-06", 1823 "namespace": "urn:ietf:params:xml:ns:yang:ietf-packet-fi\ 1824 \elds" 1825 }, 1826 { 1827 "name": "ietf-ethertypes", 1828 "revision": "2018-11-06", 1829 "namespace": "urn:ietf:params:xml:ns:yang:ietf-ethertype\ 1830 \s" 1831 } 1832 ] 1833 } 1834 } 1835 } 1836 } 1837 1839 B.3. Package import conflict resolution example 1841 This section provides an example of how a package can resolve 1842 conflicting module versions from imported packages. 1844 In this example, YANG package 'example-3-pkg' imports both 'example- 1845 import-1' and 'example-import-2' packages. However, the two imported 1846 packages implement different versions of 'example-module-A' so the 1847 'example-3-pkg' package selects version '1.2.3' to resolve the 1848 conflict. Similarly, for import-only modules, the 'example-3-pkg' 1849 package does not require both versions of example-types-module-C to 1850 be imported, so it indicates that it only imports revision 1851 '2018-11-26' and not '2018-01-01'. 1853 { 1854 "ietf-yang-instance-data:instance-data-set": { 1855 "name": "example-import-1-pkg", 1856 "description": "First imported example package", 1857 "content-data": { 1858 "ietf-yang-package:yang-package": { 1859 "name": "example-import-1", 1860 "version": "1.0.0", 1861 "reference": "XXX, draft-rwilton-netmod-yang-packages", 1862 "revision-date": "2018-01-01", 1863 "module": [ 1864 { 1865 "name": "example-module-A", 1866 "version": "1.0.0" 1867 }, 1868 { 1869 "name": "example-module-B", 1870 "version": "1.0.0" 1871 } 1872 ], 1873 "import-only-module": [ 1874 { 1875 "name": "example-types-module-C", 1876 "revision": "2018-01-01" 1877 }, 1878 { 1879 "name": "example-types-module-D", 1880 "revision": "2018-01-01" 1881 } 1882 ] 1883 } 1884 } 1885 } 1886 } 1888 { 1889 "ietf-yang-instance-data:instance-data-set": { 1890 "name": "example-import-2-pkg", 1891 "description": "Second imported example package", 1892 "content-data": { 1893 "ietf-yang-package:yang-package": { 1894 "name": "example-import-2", 1895 "version": "2.0.0", 1896 "reference": "XXX, draft-rwilton-netmod-yang-packages", 1897 "revision-date": "2018-11-26", 1898 "module": [ 1899 { 1900 "name": "example-module-A", 1901 "version": "1.2.3" 1902 }, 1903 { 1904 "name": "example-module-E", 1905 "version": "1.1.0" 1906 } 1907 ], 1908 "import-only-module": [ 1909 { 1910 "name": "example-types-module-C", 1911 "revision": "2018-11-26" 1912 }, 1913 { 1914 "name": "example-types-module-D", 1915 "revision": "2018-11-26" 1916 } 1917 ] 1918 } 1919 } 1920 } 1921 } 1923 { 1924 "ietf-yang-instance-data:instance-data-set": { 1925 "name": "example-3-pkg", 1926 "description": "Importing example package", 1927 "content-data": { 1928 "ietf-yang-package:yang-package": { 1929 "name": "example-3", 1930 "version": "1.0.0", 1931 "reference": "XXX, draft-rwilton-netmod-yang-packages", 1932 "revision-date": "2018-11-26", 1933 "imported-packages": [ 1934 { 1935 "name": "example-import-1", 1936 "version": "1.0.0" 1937 }, 1938 { 1939 "name": "example-import-2", 1940 "version": "2.0.0" 1941 } 1942 ], 1943 "module": [ 1944 { 1945 "name": "example-module-A", 1946 "version": "1.2.3" 1947 } 1948 ], 1949 "import-only-module": [ 1950 { 1951 "name": "example-types-module-C", 1952 "revision": "2018-11-26", 1953 "replaces-revision": [ "2018-01-01 "] 1954 } 1955 ] 1956 } 1957 } 1958 } 1959 } 1961 Author's Address 1963 Robert Wilton 1964 Cisco Systems, Inc. 1966 Email: rwilton@cisco.com