idnits 2.17.1 draft-rwilton-netmod-yang-packages-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 : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 662 has weird spacing: '...evision rev...' == Line 674 has weird spacing: '...evision rev...' == Line 792 has weird spacing: '...version rev...' == Line 2080 has weird spacing: '...mespace ine...' == Line 2143 has weird spacing: '...-set-id str...' == (3 more instances...) -- The document date (October 23, 2019) is 1637 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-artwork-folding' is defined on line 2053, but no explicit reference was found in the text == Unused Reference: 'RFC8199' is defined on line 2063, but no explicit reference was found in the text == Outdated reference: A later version (-10) exists of draft-ietf-netmod-module-tags-09 == Outdated reference: A later version (-05) exists of draft-ietf-netmod-yang-data-ext-04 == Outdated reference: A later version (-21) exists of draft-ietf-netmod-yang-instance-file-format-04 == Outdated reference: A later version (-03) exists of draft-verdt-netmod-yang-solutions-01 ** Downref: Normative reference to an Informational draft: draft-verdt-netmod-yang-solutions (ref. 'I-D.verdt-netmod-yang-solutions') ** Downref: Normative reference to an Informational draft: draft-verdt-netmod-yang-versioning-reqs (ref. 'I-D.verdt-netmod-yang-versioning-reqs') == Outdated reference: A later version (-02) exists of draft-wilton-netmod-yang-ver-selection-00 ** 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-10 Summary: 4 errors (**), 0 flaws (~~), 15 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 October 23, 2019 5 Expires: April 25, 2020 7 YANG Packages 8 draft-rwilton-netmod-yang-packages-02 10 Abstract 12 This document defines YANG packages, a versioned organizational 13 structure holding a set of related YANG modules, that collectively 14 define a YANG schema. It describes how YANG instance data documents 15 are used to define YANG packages, and how the YANG library 16 information published by a server can be augmented with packages 17 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 April 25, 2020. 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 . . . . . . . . . . . . . . . . . 3 54 2. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 55 3. Background on YANG packages . . . . . . . . . . . . . . . . . 4 56 4. Objectives . . . . . . . . . . . . . . . . . . . . . . . . . 5 57 5. YANG Package Definition . . . . . . . . . . . . . . . . . . . 6 58 5.1. Package definition rules . . . . . . . . . . . . . . . . 7 59 5.2. Package versioning . . . . . . . . . . . . . . . . . . . 7 60 5.2.1. Updating a package with a new version . . . . . . . . 8 61 5.2.1.1. Non-Backwards-compatible changes . . . . . . . . 8 62 5.2.1.2. Backwards-compatible changes . . . . . . . . . . 8 63 5.2.1.3. Editorial changes . . . . . . . . . . . . . . . . 9 64 5.2.2. YANG Semantic Versioning for packages . . . . . . . . 9 65 5.2.3. Revision history . . . . . . . . . . . . . . . . . . 10 66 5.3. Package conformance . . . . . . . . . . . . . . . . . . . 10 67 5.3.1. Use of YANG semantic versioning . . . . . . . . . . . 10 68 5.3.2. Package checksums . . . . . . . . . . . . . . . . . . 11 69 5.4. Schema referential completeness . . . . . . . . . . . . . 11 70 5.5. Package name scoping and uniqueness . . . . . . . . . . . 12 71 5.5.1. Globally scoped packages . . . . . . . . . . . . . . 12 72 5.5.2. Server scoped packages . . . . . . . . . . . . . . . 12 73 5.6. Submodules packages considerations . . . . . . . . . . . 13 74 5.7. Package tags . . . . . . . . . . . . . . . . . . . . . . 13 75 6. YANG Packages instance data . . . . . . . . . . . . . . . . . 13 76 7. YANG Packages additions to YANG library . . . . . . . . . . . 15 77 7.1. Package List . . . . . . . . . . . . . . . . . . . . . . 15 78 7.2. Binding from schema to package . . . . . . . . . . . . . 15 79 7.3. Tree diagram . . . . . . . . . . . . . . . . . . . . . . 16 80 8. YANG Packages Groupings . . . . . . . . . . . . . . . . . . . 18 81 9. YANG packages as schema for YANG instance data document . . . 18 82 10. YANG Modules . . . . . . . . . . . . . . . . . . . . . . . . 19 83 11. Security Considerations . . . . . . . . . . . . . . . . . . . 40 84 12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 41 85 13. Open Questions/Issues . . . . . . . . . . . . . . . . . . . . 42 86 14. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 42 87 15. References . . . . . . . . . . . . . . . . . . . . . . . . . 42 88 15.1. Normative References . . . . . . . . . . . . . . . . . . 42 89 15.2. Informative References . . . . . . . . . . . . . . . . . 44 90 Appendix A. Tree output for ietf-yang-library with package 91 augmentations . . . . . . . . . . . . . . . . . . . 45 92 Appendix B. Examples . . . . . . . . . . . . . . . . . . . . . . 47 93 B.1. Example IETF Network Device YANG package . . . . . . . . 47 94 B.2. Example IETF Basic Routing YANG package . . . . . . . . . 50 95 B.3. Package import conflict resolution example . . . . . . . 53 97 Appendix C. Possible alternative solutions . . . . . . . . . . . 56 98 C.1. Using module tags . . . . . . . . . . . . . . . . . . . . 56 99 C.2. Using YANG library . . . . . . . . . . . . . . . . . . . 56 100 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 57 102 1. Terminology and Conventions 104 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 105 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 106 "OPTIONAL" in this document are to be interpreted as described in BCP 107 14 [RFC2119] [RFC8174] when, and only when, they appear in all 108 capitals, as shown here. 110 This document uses terminology introduced in the YANG versioning 111 requirements draft [I-D.verdt-netmod-yang-versioning-reqs]. 113 This document also makes of the following terminology introduced in 114 the Network Management Datastore Architecture [RFC8342]: 116 o datastore schema 118 This document also makes of the following terminology introduced in 119 the YANG 1.1 Data Modeling Language [RFC7950]: 121 o data node 123 In addition, this document defines the following terminology: 125 o YANG schema: A datastore schema, not bound to any particular 126 datastore. 128 o YANG package: An organizational structure holding a collection of 129 YANG modules related by some common purpose, normally defined in a 130 YANG instance data file. A YANG package defines a YANG schema by 131 specifying a set of YANG modules revisions, package versions, 132 mandatory features, and deviations. YANG packages are defined in 133 Section 5. 135 o backwards-compatible (BC) change: When used in the context of a 136 YANG module, it follows the definition in Section 3.1.1 of 137 [I-D.verdt-netmod-yang-module-versioning]. When used in the 138 context of a YANG package, it follows the definition in 139 Section 5.2.1.2. 141 o non-backwards-compatible (NBC) change: When used in the context of 142 a YANG module, it follows the definition in Section 3.1.2 of 143 [I-D.verdt-netmod-yang-module-versioning]. When used in the 144 context of a YANG package, it follows the definition in 145 Section 5.2.1.2. 147 o editorial change: When used in the context of a YANG module, it 148 follows the definition of an 'editorial change' in 3.2 of 149 [I-D.verdt-netmod-yang-semver]. When used in the context of a 150 YANG package, it follows the definition in Section 5.2.1.3. 152 2. Introduction 154 This document defines and describes the YANG [RFC7950] constructs 155 that are used to define and use YANG packages. 157 A YANG package is an organizational structure that groups a set of 158 YANG modules together into a consistent versioned definition to serve 159 a common purpose. For example, a YANG package could define the set 160 of YANG modules required to implement an L2VPN service on a network 161 device. YANG packages can themselves refer to, and reuse, other 162 package definitions. 164 Non-normative examples of YANG packages are provided in the 165 appendices. 167 3. Background on YANG packages 169 It has long been acknowledged within the YANG community that network 170 management using YANG requires a unit of organization and conformance 171 that is broader in scope than individual YANG modules. 173 'The YANG Package Statement' [I-D.bierman-netmod-yang-package] 174 proposed a YANG package mechanism based on new YANG language 175 statements, where a YANG package is defined in a file similar to how 176 YANG modules are defined, and would require enhancements to YANG 177 compilers to understand the new statements used to define packages. 179 OpenConfig [openconfigsemver] describes an approach to versioning 180 'bundle releases' based on git tags. I.e. a set of modules, at 181 particular versions, can be marked with the same release tag to 182 indicate that they are known to interoperate together. 184 The NETMOD WG in general, and the YANG versioning design team in 185 particular, are exploring solutions [I-D.verdt-netmod-yang-solutions] 186 to the YANG versioning requirements, 187 [I-D.verdt-netmod-yang-versioning-reqs]. Solutions to the versioning 188 requirements can be split into several distinct areas. 189 [I-D.verdt-netmod-yang-module-versioning] is focused on YANG 190 versioning scoped to individual modules. The overall solution must 191 also consider YANG versioning and conformance scoped to YANG schema. 193 YANG packages provide part of the solution for versioning YANG 194 schema. 196 4. Objectives 198 The main goals of YANG package definitions include, but are not 199 restricted to: 201 o To provide an alternative, simplified, YANG conformance mechanism. 202 Rather than conformance being performed against a set of 203 individual YANG module revisions, features, and deviations, 204 conformance can be more simply stated in terms of YANG packages, 205 with a set of modifications (e.g. additional modules, deviations, 206 or features). 208 o To allow YANG schema to be specified in a concise way rather than 209 having each server explicitly list all modules, revisions, and 210 features. YANG package definitions can be defined in documents 211 that are available offline, and accessible via a URL, rather than 212 requiring explicit lists of modules to be shared between client 213 and server. Hence, a YANG package must contain sufficient 214 information to allow a client or server to precisely construct the 215 schema associated with the package. 217 o To define a mainly linear versioned history of sets of modules 218 versions that are known to work together. I.e. to help mitigate 219 the problem where a client must manage devices from multiple 220 vendors, and vendor A implements version 1.0.0 of module foo and 221 version 2.0.0 of module bar, and vendor B implements version 2.0.0 222 of module foo and version 1.0.0 of module bar. For a client, 223 trying to interoperate with multiple vendors, and many YANG 224 modules, finding a consistent lowest common denominator set of 225 YANG module versions may be difficult, if not impossible. 227 Protocol mechanisms of how clients can negotiate which packages or 228 package versions are to be used for NETCONF/RESTCONF communications 229 are outside the scope of this document, and are defined in 230 [I-D.wilton-netmod-yang-ver-selection]. 232 Finally, the package definitions proposed by this document are 233 intended to be relatively basic in their definition and the 234 functionality that they support. As industry gains experience using 235 YANG packages, the standard YANG mechanisms of updating, or 236 augmenting, YANG modules could also be used to extend the 237 functionality supported by YANG packages, if required. 239 5. YANG Package Definition 241 This document specifies an approach to defining YANG packages that is 242 different to either of the approaches described in the background. 244 A YANG package is a versioned organizational structure defining a set 245 of related YANG modules, packages, features, and deviations. A YANG 246 package collectively defines a YANG schema. 248 Each YANG package has a name that SHOULD end with the suffix "-pkg". 249 Package names are normally expected to be globally unique, but in 250 some cases the package name may be locally scoped to a server or 251 device, as described in Section 5.5. 253 YANG packages are versioned using the same approaches described in 254 [I-D.verdt-netmod-yang-module-versioning] and 255 [I-D.verdt-netmod-yang-semver]. This is described in further detail 256 in Section 5.2. 258 Each YANG package version, defines: 260 some metadata about the package, e.g., description, tags, scoping, 261 referential completeness, location information. 263 a set of YANG modules, at particular revisions, that are 264 implemented by servers that implement the package. The modules 265 may contain deviations. 267 a set of import-only YANG modules, at particular revisions, that 268 are used 'import-only' by the servers that implement the package. 270 a set of included YANG packages, at particular revisions, that are 271 also implemented by servers that implement the package. 273 a set of YANG module features that must be supported by servers 274 that implement the package. 276 The structure for YANG package definitions uses existing YANG 277 language statements, YANG Data Structure Extensions 278 [I-D.ietf-netmod-yang-data-ext], and YANG Instance Data File Format 279 [I-D.ietf-netmod-yang-instance-file-format]. 281 YANG package definitions are available offline in YANG Instance Data 282 Documents. Client applications can be designed to support particular 283 package versions that they expect to interoperate with. 285 YANG package definitions are available from the server, via 286 augmentations to YANG Library [RFC8525]. Rather than client 287 applications downloading the entire contents of YANG library to 288 confirm that the server schema is compatible with the client, they 289 can check, or download, a much shorter YANG package definition, and 290 validate that it conforms to the expected schema. 292 YANG package definitions can also be used to define the schema 293 associated with YANG instance data documents holding other, e.g., non 294 packages related, instance data. 296 5.1. Package definition rules 298 The following rules define how packages are defined: 300 A YANG package MAY represent a complete YANG schema or only part 301 of a YANG schema with some module import dependencies missing, as 302 described in Section 5.4. 304 Packages definitions are hierarchical. A package can include 305 other packages. Only a single version of a package can be 306 included, and conflicting package includes (e.g. from descendant 307 package includes) MUST be explicitly resolved by indicating which 308 version takes precedence, and which versions are being replaced. 310 For each module implemented by a package, only a single revision 311 of that module MUST be implemented. Multiple revisions of a 312 module MAY be listed as import-only dependencies. 314 The revision of a module listed in the package 'module' list 315 supersedes any 'implemented' revision of the module listed in an 316 included package module list. The 'replaces-revision' leaf-list 317 is used to indicate which 'implemented' or 'import-only' module 318 revisions are replaces by this module revision. This allows a 319 package to explicitly resolve conflicts between implemented module 320 revisions in included packages. 322 The 'replaces-revision' leaf-list in the 'import-only-module' list 323 can be used to exclude duplicate revisions of import-only modules 324 from included packages. Otherwise, the import-only-modules for a 325 package are the import-only-modules from all included packages 326 combined with any modules listed in the packages import-only- 327 module list. 329 5.2. Package versioning 331 Individual versions of a YANG package are versioned using the 332 "revision-label" scheme defined in section 3.3 of 333 [I-D.verdt-netmod-yang-module-versioning]. 335 5.2.1. Updating a package with a new version 337 Package compatibility is fundamentally defined by how the YANG schema 338 between two package versions has changed. 340 When a package definition is updated, the version associated with the 341 package MUST be updated appropriately, taking into consideration the 342 scope of the changes as defined by the rules below. 344 A package definition SHOULD define the previous version of the 345 package in the 'previous-version' leaf unless it is the initial 346 version of the package. If the 'previous-version' leaf is provided 347 then the package definition MUST set the 'nbc-changes' leaf if the 348 new version is non-backwards-compatible with respect to the package 349 version defined in the 'previous-version' leaf. 351 5.2.1.1. Non-Backwards-compatible changes 353 The following changes classify as NBC changes to a package 354 definition: 356 Changing an 'included-package' list entry to select a package 357 version that is non-backwards-compatible to the prior package 358 version, or removing a previously included package. 360 Changing a 'module' or 'import-only-module' list entry to select a 361 module revision that is non-backwards-compatible to the prior 362 module revision, or removing a previously implemented module. 364 Removing a feature from the 'mandatory-feature' leaf-list. 366 Adding, changing, or removing a deviation that is considered a 367 non-backwards-compatible change to the affected data node in the 368 schema associated with the prior package version. 370 5.2.1.2. Backwards-compatible changes 372 The following changes classify as BC changes to a package definition: 374 Changing an 'included-package' list entry to select a package 375 version that is backwards-compatible to the prior package version, 376 or including a new package that does not conflict with any 377 existing included package or module. 379 Changing a 'module' or 'import-only-module' list entry to select a 380 module revision that is backwards-compatible to the prior module 381 revision, or including a new module to the package definition. 383 Adding a feature to the 'mandatory-feature' leaf-list. 385 Adding, changing, or removing a deviation that is considered a 386 backwards-compatible change to the affected data node in the 387 schema associated with the prior package version. 389 5.2.1.3. Editorial changes 391 The following changes classify as editorial changes to a package 392 definition: 394 Changing a 'included-package' list entry to select a package 395 version that is classified as an editorial change relative to the 396 prior package version. 398 Changing a 'module' or 'import-only-module' list entry to select a 399 module revision that is classified as an editorial change relative 400 to the prior module revision. 402 Any change to any metadata associated with a package definition 403 that causes it to have a different checksum value. 405 5.2.2. YANG Semantic Versioning for packages 407 YANG Semantic Versioning [I-D.verdt-netmod-yang-semver] MAY be used 408 as an appropriate type of revision-label for the package version 409 leaf. 411 If the format of the leaf matches the 'yangver:version' type 412 specified in ietf-yang-semver.yang, then the package version leaf 413 MUST be interpreted as a YANG semantic version number. 415 For YANG packages defined by the IETF, YANG semantic version numbers 416 MUST be used as the version scheme for YANG packages. 418 The rules for incrementing the YANG package version number are 419 equivalent to the semantic versioning rules used to version 420 individual YANG modules, defined in section 3.2 of 421 [I-D.verdt-netmod-yang-semver], but use the rules defined previously 422 in Section 5.2.1 to determine whether a change is classified as non- 423 backwards-compatible, backwards-compatible, or editorial. Where 424 available, the semantic version number of the referenced elements in 425 the package (included packages or modules) can be used to help 426 determine the scope of changes being made. 428 5.2.3. Revision history 430 YANG packages do not contain a revision history. This is because 431 packages may have many revisions and a long revision history would 432 bloat the package definition. By recursively examining the 433 'previous-version' leaf of a package definition, a full revision 434 history (including where non-backwards-compatible changes have 435 occurred) can be dynamically constructed, if all package versions are 436 available. 438 5.3. Package conformance 440 YANG packages allows for conformance to be checked at a package level 441 rather than requiring a client to download all modules, revisions, 442 and deviations from the server to ensure that the datastore schema 443 used by the server is compatible with the client. 445 YANG package conformance is analogous to how YANG [RFC7950] requires 446 that servers either implement a module faithfully, or otherwise use 447 deviations to indicate areas of non-conformance. 449 For a top level package representing a datastore schema, servers MUST 450 implement the package definition faithfully, including all mandatory 451 features. 453 Package definitions MAY modify the schema for directly or 454 hierarchically included packages through the use of different module 455 revisions or module deviations. If the schema of any included 456 package is modified in a non-backwards-compatible way then it MUST be 457 indicated by setting the 'nbc-modified' leaf to true. 459 5.3.1. Use of YANG semantic versioning 461 Using the YANG semantic versioning scheme for package version numbers 462 and module revision labels can help with conformance. In the general 463 case, clients should be able to determine the nature of changes 464 between two package versions by comparing the version number. 466 This usually means that a client does not have to be restricted to 467 working only with servers that advertise exactly the same version of 468 a package in YANG library. Instead, reasonable clients should be 469 able to interoperate with any server that supports a package version 470 that is backwards compatible to version that the client is designed 471 for, assuming that the client is designed to ignore operational 472 values for unknown data nodes. 474 For example, a client coded to support 'foo' package at version 1.0.0 475 should interoperate with a server implementing 'foo' package at 476 version 1.3.5, because the YANG semantic versioning rules require 477 that package version 1.3.5 is backwards compatible to version 1.0.0. 479 This also has a relevance on servers that are capable of supporting 480 version selection because they need not support every version of a 481 YANG package to ensure good client compatibility. Choosing suitable 482 minor versions within each major version number should generally be 483 sufficient, particular if they can avoid NBC patch level changes 484 (i.e. 'M' labeled versions). 486 5.3.2. Package checksums 488 Each YANG package definition may have a checksum associated with it 489 to allow a client to validate that the package definition of the 490 server matches the expected package definition without downloading 491 the full package definition from the server. 493 The checksum for a package is calculated using the SHA-256 hash (XXX, 494 reference) of the full file contents of the YANG package instance 495 data file. This means that the checksum includes all whitespace and 496 formatting, encoding, and all meta-data fields associated with the 497 package and the instance data document). 499 The checksum for a module is calculated using the SHA-256 hash of the 500 YANG module file definition. This means that the checksum includes 501 all whitespace, formatting, and comments within the YANG module. 503 Packages that are locally scoped to a server may not have an offline 504 instance data document available, and hence MAY not have a checksum. 506 The package definition allows URLs and checksums to be specified for 507 all included packages, modules and submodules within the package 508 definition. Checksums SHOULD be included in package definitions to 509 validate the full integrity of the package. 511 On a server, package checksums SHOULD also be provided for the top 512 level packages associated with the datastore schema. 514 5.4. Schema referential completeness 516 A YANG package may represent a schema that is 'referentially 517 complete', or 'referentially incomplete', indicated in the package 518 definition by the 'complete' flag. 520 If all import statements in all YANG modules included in the package 521 (either directly, or through included packages) can be resolved to a 522 module revision defined with the YANG package definition, then the 523 package is classified as referentially complete. Conversely, if one 524 or more import statements cannot be resolved to a module specified as 525 part of the package definition, then the package is classified as 526 referentially incomplete. 528 A package that represents the exact contents of a datastore schema 529 MUST always be referentially complete. 531 Referentially incomplete packages can be used, along with locally 532 scoped packages, to represent an update to a device's datastore 533 schema as part of an optional software hot fix. E.g., the base 534 software is made available as a complete globally scoped package. 535 The hot fix is made available as an incomplete globally scoped 536 package. A device's datastore schema can define a local package that 537 implements the base software package updated with the hot fix 538 package. 540 Referentially incomplete packages could also be used to group sets of 541 logically related modules together, but without requiring a fixed 542 dependency on all imported 'types' modules (e.g., iana-if- 543 types.yang), instead leaving the choice of specific revisions of 544 'types' modules to be resolved when the package definition is used. 546 5.5. Package name scoping and uniqueness 548 YANG package names can be globally unique, or locally scoped to a 549 particular server or device. 551 5.5.1. Globally scoped packages 553 The name given to a package MUST be globally unique, and it MUST 554 include an appropriate organization prefix in the name, equivalent to 555 YANG module naming conventions. 557 Ideally a YANG instance data document defining a particular package 558 version would be publicly available at one or more URLs. 560 5.5.2. Server scoped packages 562 Package definitions may be scoped to a particular server by setting 563 the 'is-local' leaf to true in the package definition. 565 Locally scoped packages MAY have a package name that is not globally 566 unique. 568 Locally scoped packages MAY have a definition that is not available 569 offline from the server in a YANG instance data document. 571 5.6. Submodules packages considerations 573 As defined in [RFC7950] and [I-D.verdt-netmod-yang-semver], YANG 574 conformance and versioning is specified in terms of particular 575 revisions of YANG modules rather than for individual submodules. 577 However, YANG package definitions also include the list of submodules 578 included by a module, primarily to provide a location of where the 579 submodule definition can be obtained from, allowing a YANG schema to 580 be fully constructed from a YANG package instance-data file 581 definition. 583 5.7. Package tags 585 [I-D.ietf-netmod-module-tags] defines YANG module tags as a mechanism 586 to annotate a module definition with additional metadata. Tags MAY 587 also be associated to a package definition via the 'tags' leaf-list. 588 The tags use the same registry and definitions used by YANG module 589 tags. 591 6. YANG Packages instance data 593 YANG packages SHOULD be defined as YANG instance data documents 594 [I-D.ietf-netmod-yang-instance-file-format] using the YANG schema 595 below to define the package data itself. 597 The format of the YANG package instance file MUST follow the 598 following rules: 600 The file SHOULD be encoded in JSON. 602 The name of the file SHOULD follow the format "@.json". 605 The package name MUST be specified in both the instance-data-set 606 'name' and package 'name' leafs. 608 The 'description' field of the instance-data-set SHOULD be "YANG 609 package definition". 611 The 'timestamp', "organization', 'contact' fields are defined in 612 both the instance-data-set metadata and the YANG package metadata. 613 Package definitions SHOULD only define these fields as part of the 614 package definition. If any of these fields are populated in the 615 instance-data-set metadata then they MUST contain the same value 616 as the corresponding leaves in the package definition. 618 The 'revision' list in the instance data document SHOULD NOT be 619 used, since versioning is handled by the package definition. 621 The instance data document for each version of a YANG package 622 SHOULD be made available at one of more locations accessible via 623 URLs. If one of the listed locations defines a definitive 624 reference implementation for the package definition then it MUST 625 be listed as the first entry in the list. 627 The "ietf-yang-package" YANG module has the following structure: 629 module: ietf-yang-package 631 structure package: 632 +-- name pkg-identifier 633 +-- version rev:revision-label 634 +-- timestamp? yang:date-and-time 635 +-- organization? string 636 +-- contact? string 637 +-- description? string 638 +-- reference? string 639 +-- location* inet:uri 640 +-- complete? boolean 641 +-- local? boolean 642 +-- previous-version? rev:revision-label 643 +-- nbc-changes? boolean 644 +-- tag* tags:tag 645 +-- mandatory-feature* scoped-feature 646 +-- included-package* [name version] 647 | +-- name pkg-identifier 648 | +-- version rev:revision-label 649 | +-- replaces-version* rev:revision-label 650 | +-- nbc-modified? boolean 651 | +-- location* inet:uri 652 | +-- checksum? pkg-types:sha-256-hash 653 +-- module* [name] 654 | +-- name yang:yang-identifier 655 | +-- revision? rev:revision-date-or-label 656 | +-- replaces-revision* rev:revision-date-or-label 657 | +-- namespace? inet:uri 658 | +-- location* inet:uri 659 | +-- checksum? pkg-types:sha-256-hash 660 | +-- submodule* [name] 661 | +-- name yang:yang-identifier 662 | +-- revision rev:revision-identifier 663 | +-- location* inet:uri 664 | +-- checksum? pkg-types:sha-256-hash 665 +-- import-only-module* [name revision] 666 +-- name yang:yang-identifier 667 +-- revision rev:revision-date-or-label 668 +-- replaces-revision* rev:revision-date-or-label 669 +-- namespace? inet:uri 670 +-- location* inet:uri 671 +-- checksum? pkg-types:sha-256-hash 672 +-- submodule* [name] 673 +-- name yang:yang-identifier 674 +-- revision rev:revision-identifier 675 +-- location* inet:uri 676 +-- checksum? pkg-types:sha-256-hash 678 7. YANG Packages additions to YANG library 680 7.1. Package List 682 The main addition is a top level 'yang-library/package' list that 683 lists all versions of all packages known to the server. Each package 684 defines a potentially incomplete YANG schema, built from included 685 packages and module-sets. The use of module-sets allows the module 686 definitions to be shared with the existing YANG library schema 687 definitions. The existing rule of RFC 7995bis related to combining 688 modules-sets also applies here, i.e. The combined set of modules 689 defined by the module-sets MUST NOT contain modules implemented at 690 different revisions. I.e. the module-sets leaf-list is directly 691 equivalent to the explicit module and import-only-module lists in the 692 instance data YANG package definition. 694 The 'yang-library/package' list MAY include multiple versions of a 695 particular package. E.g. if the server is capable of allowing 696 clients to select which package versions should be used by the 697 server. 699 7.2. Binding from schema to package 701 The second augmentation is to allow a server to optionally indicate 702 that a schema definition directly relates to a package. Since YANG 703 packages are available offline, it may be sufficient for a client to 704 only check that a compatible version of the YANG package is being 705 implemented by the server without fetching and comparing the full 706 module list. 708 If a server indicates that its schema maps to a particular package 709 then it MUST support all features listed in the mandatory-feature 710 list defined as part of that package, and it MUST NOT have any non- 711 backwards-compatible deviations to the modules defined by the 712 package. A server MAY implement features not specified in the 713 package's mandatory-feature list. 715 If a server cannot faithfully implement a package then it can define 716 a new package to accurately report what it does implement. The new 717 package can include the original package as an included package, and 718 the new package can define additional modules containing deviations 719 to the modules in the original package, allowing the new package to 720 accurately describe the server behavior. There is no specific 721 mechanism provided to indicate that a mandatory-feature is not 722 supported on a server, but deviations MAY be used to disable 723 functionality predicated by an if-feature statement. 725 7.3. Tree diagram 727 The "ietf-yang-library-packages" YANG module has the following 728 structure: 730 module: ietf-yl-packages 731 augment /yanglib:yang-library: 732 +--ro package* [name version] 733 +--ro name pkg-identifier 734 +--ro version rev:revision-label 735 +--ro timestamp? yang:date-and-time 736 +--ro organization? string 737 +--ro contact? string 738 +--ro description? string 739 +--ro reference? string 740 +--ro location* inet:uri 741 +--ro complete? boolean 742 +--ro local? boolean 743 +--ro previous-version? rev:revision-label 744 +--ro nbc-changes? boolean 745 +--ro tag* tags:tag 746 +--ro mandatory-feature* scoped-feature 747 +--ro included-package* [name version] 748 | +--ro name pkg-identifier 749 | +--ro version rev:revision-label 750 | +--ro replaces-version* rev:revision-label 751 | +--ro nbc-modified? boolean 752 | +--ro location* inet:uri 753 | +--ro checksum? pkg-types:sha-256-hash 754 +--ro module-set* 755 | -> /yanglib:yang-library/module-set/name 756 +--ro checksum? pkg-types:sha-256-hash 757 augment /yanglib:yang-library/yanglib:schema: 758 +--ro package 759 +--ro name? 760 | -> /yanglib:yang-library/package/name 761 +--ro version? leafref 762 +--ro checksum? pkg-types:sha-256-hash 763 +--ro supported-optional-feature* pkg-types:scoped-feature 764 augment /yanglib:yang-library/yanglib:module-set/yanglib:module: 765 +--ro replaces-revision* rev:revision-date-or-label 766 +--ro checksum? pkg-types:sha-256-hash 767 augment /yanglib:yang-library/yanglib:module-set/yanglib:module 768 /yanglib:submodule: 769 +--ro checksum? pkg-types:sha-256-hash 770 augment /yanglib:yang-library/yanglib:module-set 771 /yanglib:import-only-module: 772 +--ro replaces-revision* rev:revision-date-or-label 773 +--ro checksum? pkg-types:sha-256-hash 774 augment /yanglib:yang-library/yanglib:module-set 775 /yanglib:import-only-module/yanglib:submodule: 776 +--ro checksum? pkg-types:sha-256-hash 778 8. YANG Packages Groupings 780 Groupings for YANG packages related constructs are provided in a 781 'types' module for use by the instance-data and YANG library 782 constructs described previously. They are also available to be used 783 by other modules that have a need for YANG packages information. 785 The "ietf-yang-package-types" YANG module has the following 786 structure: 788 module: ietf-yang-package-types 790 grouping yang-pkg-identification-leafs 791 +-- name pkg-identifier 792 +-- version rev:revision-label 793 grouping yang-pkg-common-leafs 794 +-- timestamp? yang:date-and-time 795 +-- organization? string 796 +-- contact? string 797 +-- description? string 798 +-- reference? string 799 +-- location* inet:uri 800 +-- complete? boolean 801 +-- local? boolean 802 +-- previous-version? rev:revision-label 803 +-- nbc-changes? boolean 804 +-- tag* tags:tag 805 +-- mandatory-feature* scoped-feature 806 +-- included-package* [name version] 807 +-- name pkg-identifier 808 +-- version rev:revision-label 809 +-- replaces-version* rev:revision-label 810 +-- nbc-modified? boolean 811 +-- location* inet:uri 812 +-- checksum? pkg-types:sha-256-hash 814 9. YANG packages as schema for YANG instance data document 816 YANG package definitions can be used as the schema definition for 817 YANG instance data documents. When using a package schema, the name 818 of the package MUST be specified, a package checksum and/or URL to 819 the package definition MAY also be provided. 821 The "ietf-yang-inst-data-pkg" YANG module has the following 822 structure: 824 module: ietf-yang-inst-data-pkg 826 augment-structure /yid:instance-data-set/yid:content-schema-spec: 827 +--:(pkg-schema) 828 +-- pkg-schema 829 +-- package pkg-types:pkg-identifier 830 +-- location* inet:uri 831 +-- checksum? pkg-types:sha-256-hash 833 10. YANG Modules 835 The YANG module definitions for the modules described in the previous 836 sections. 838 file "ietf-yang-package-types@2019-09-11.yang" 839 module ietf-yang-package-types { 840 yang-version 1.1; 841 namespace "urn:ietf:params:xml:ns:yang:ietf-yang-package-types"; 842 prefix "pkg-types"; 844 import ietf-yang-revisions { 845 prefix rev; 846 reference "XXXX: Updated YANG Module Revision Handling"; 847 } 849 import ietf-yang-types { 850 prefix yang; 851 rev:revision-or-derived 2013-07-15; 852 reference "RFC 6991: Common YANG Data Types."; 853 } 855 import ietf-inet-types { 856 prefix inet; 857 reference "RFC 6991: Common YANG Data Types."; 858 } 860 import ietf-module-tags { 861 prefix tags; 862 reference "RFC XXX: YANG Module Tags."; 863 } 865 organization 866 "IETF NETMOD (Network Modeling) Working Group"; 868 contact 869 "WG Web: 870 WG List: 872 Author: Rob Wilton 873 "; 875 description 876 "This module provides type and grouping definitions for YANG 877 packages. 879 Copyright (c) 2019 IETF Trust and the persons identified as 880 authors of the code. All rights reserved. 882 Redistribution and use in source and binary forms, with or 883 without modification, is permitted pursuant to, and subject 884 to the license terms contained in, the Simplified BSD License 885 set forth in Section 4.c of the IETF Trust's Legal Provisions 886 Relating to IETF Documents 887 (http://trustee.ietf.org/license-info). 889 This version of this YANG module is part of RFC XXXX; see 890 the RFC itself for full legal notices. 892 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL 893 NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'NOT RECOMMENDED', 894 'MAY', and 'OPTIONAL' in this document are to be interpreted as 895 described in BCP 14 (RFC 2119) (RFC 8174) when, and only when, 896 they appear in all capitals, as shown here."; 898 // RFC Ed.: update the date below with the date of RFC publication 899 // and remove this note. 900 // RFC Ed.: replace XXXX with actual RFC number and remove this 901 // note. 902 revision 2019-09-11 { 903 rev:revision-label 0.1.0; 904 description 905 "Initial revision"; 906 reference 907 "RFC XXXX: YANG Packages"; 908 } 910 /* 911 * Typedefs 912 */ 914 typedef pkg-identifier { 915 type yang:yang-identifier; 916 description 917 "Package identifiers are typed as YANG identifiers."; 918 } 920 typedef scoped-feature { 921 type string { 922 pattern '[a-zA-Z_][a-zA-Z0-9\-_.]*:[a-zA-Z_][a-zA-Z0-9\-_.]*'; 923 } 924 description 925 "Represents a feature name scoped to a particular module, 926 identified as the ':', where both 927 and are YANG identifier strings, 928 as defiend by Section 12 or RFC 6020."; 929 reference 930 "RFC XXXX, YANG Packages."; 931 } 933 typedef sha-256-hash { 934 type string { 935 length "64"; 936 pattern "[0-9a-fA-F]*"; 937 } 938 description 939 "A SHA-256 hash represented as a hexadecimal string. 941 Used as the checksum for modules, submodules and packages in a 942 YANG package definition. 944 For modules and submodules the SHA-256 hash is calculated on 945 the contents of the YANG file defining the module/submodule. 947 For packages the SHA-256 hash is calculated on the file 948 containing the YANG instance data document holding the package 949 definition"; 950 } 952 /* 953 * Groupings 954 */ 956 grouping yang-pkg-identification-leafs { 957 description 958 "Parameters for identifying a specific version of a YANG 959 package"; 961 leaf name { 962 type pkg-identifier; 963 mandatory true; 964 description 965 "The YANG package name."; 966 } 968 leaf version { 969 type rev:revision-label; 970 mandatory true; 971 description 972 "Uniquely identies a particular version of a YANG package. 974 Follows the definition for revision labels defined in 975 draft-verdt-nemod-yang-module-versioning, section XXX"; 976 } 977 } 979 grouping yang-pkg-common-leafs { 980 description 981 "Defines definitions common to all YANG package definitions."; 983 leaf timestamp { 984 type yang:date-and-time; 986 description 987 "An optional timestamp for when this package was created. 988 This does not need to be unique across all versions of a 989 package."; 990 } 992 leaf organization { 993 type string; 995 description "Organization responsible for this package"; 996 } 998 leaf contact { 999 type string; 1001 description 1002 "Contact information for the person or organization to whom 1003 queries concerning this package should be sent."; 1004 } 1006 leaf description { 1007 type string; 1008 description "Provides a description of the package"; 1009 } 1011 leaf reference { 1012 type string; 1014 description "Allows for a reference for the package"; 1015 } 1017 leaf-list location { 1018 type inet:uri; 1019 description 1020 "Contains a URL that represents where an instance data file 1021 for this YANG package can be found. 1023 This leaf will only be present if there is a URL 1024 available for retrieval of the schema for this entry. 1026 If multiple locations are provided, then the first location 1027 in the leaf-list MUST be the definitive location that 1028 uniquely identifies this package"; 1029 } 1031 leaf complete { 1032 type boolean; 1033 default true; 1034 description 1035 "Indicates whether the schema defined by this package is 1036 referentially complete. I.e. all module imports can be 1037 resolved to a module explicitly defined in this package or 1038 one of the included packages."; 1039 } 1041 leaf local { 1042 type boolean; 1043 default false; 1044 description 1045 "Defines that the package definition is local to the server, 1046 and the name of the package MAY not be unique, and the 1047 package definition MAY not be available in an offline file. 1049 Local packages can be used when the schema for the device 1050 can be changed at runtime through the addition or removal of 1051 software packages, or hot fixes."; 1052 } 1054 leaf previous-version { 1055 type rev:revision-label; 1056 description 1057 "The previous package version that this version has been 1058 derived from. This leaf allows a full version history graph 1059 to be constructed if required."; 1060 } 1062 leaf nbc-changes { 1063 type boolean; 1064 default false; 1065 description 1066 "Indicates whether the defined package version contains 1067 non-backwards-compatible changes relative to the package 1068 version defined in the 'previous-version' leaf."; 1069 } 1071 leaf-list tag { 1072 type tags:tag; 1073 description 1074 "Tags associated with a YANG package. Module tags defined in 1075 XXX, ietf-netmod-module-tags can be used here but with the 1076 modification that the tag applies to the entire package 1077 rather than a specific module. See the IANA 'YANG Module 1078 Tag Prefix' registry for reserved prefixes and the IANA 1079 'YANG Module IETF Tag' registry for IETF standard tags."; 1080 } 1082 leaf-list mandatory-feature { 1083 type scoped-feature; 1084 description 1085 "Lists features from any modules included in the package that 1086 MUST be supported by any server implementing the package. 1088 Features already specified in a 'mandatory-feature' list of 1089 any included package MUST also be supported by server 1090 implementations and do not need to be repeated in this list. 1092 All other features defined in modules included in the 1093 package are OPTIONAL to implement. 1095 Features are identified using :"; 1096 } 1098 list included-package { 1099 key "name version"; 1100 description 1101 "An entry in this list represents a package that is included 1102 as part of the package definition, or an indirectly included 1103 package that is changed in a non backwards compatible way. 1105 It can be used to resolve inclusion of conflicting package 1106 versions by explicitly specifying which package version is 1107 used. 1109 If included packages implement different revisions or 1110 versions of the same module, then an explicit entry in the 1111 module list MUST be provided to select the specific module 1112 version 'implemented' by this package definition. 1114 If the schema for any packages that are included, either 1115 directly or indirectly via another package include, are 1116 changed in any non-backwards-compatible way then they MUST 1117 be explicitly listed in the included-packages list with the 1118 'nbc-modified' leaf set to true. 1120 For import-only modules, the 'replaces-revision' leaf-list 1121 can be used to select the specific module versions used 1122 by this package."; 1123 reference 1124 "XXX"; 1126 uses yang-pkg-identification-leafs; 1128 leaf-list replaces-version { 1129 type rev:revision-label; 1130 description 1131 "Gives the version of an included package version that 1132 is replaced by this included package revision."; 1133 } 1135 leaf nbc-modified { 1136 type boolean; 1137 default false; 1138 description 1139 "Set to true if any data nodes in this package are modified 1140 in a non backwards compatible way, either through the use 1141 of deviations, or because one of the modules has been 1142 replaced by an incompatible revision. This could also 1143 occur if a module's revision was replaced by an earlier 1144 revision that had the effect of removing some data 1145 nodes."; 1146 } 1148 leaf-list location { 1149 type inet:uri; 1150 description 1151 "Contains a URL that represents where an instance data file 1152 for this YANG package can be found. 1154 This leaf will only be present if there is a URL available 1155 for retrieval of the schema for this entry. 1157 If multiple locations are provided, then the first 1158 location in the leaf-list MUST be the definitive location 1159 that uniquely identifies this package"; 1160 } 1162 leaf checksum { 1163 type pkg-types:sha-256-hash; 1164 description 1165 "The SHA-256 hash calculated on the textual package 1166 definition, represented as a hexadecimal string."; 1167 } 1168 } 1169 } 1170 } 1171 1173 file "ietf-yang-package@2019-09-11.yang" 1174 module ietf-yang-package { 1175 yang-version 1.1; 1176 namespace "urn:ietf:params:xml:ns:yang:ietf-yang-package"; 1177 prefix pkg; 1179 import ietf-yang-revisions { 1180 prefix rev; 1181 reference "XXXX: Updated YANG Module Revision Handling"; 1182 } 1184 import ietf-yang-package-types { 1185 prefix pkg-types; 1186 rev:revision-or-derived 0.1.0; 1187 reference "RFC XXX: YANG Schema Versioning."; 1188 } 1190 import ietf-yang-structure-ext { 1191 prefix sx; 1192 reference "RFC XXX: YANG Data Structure Extensions."; 1193 } 1195 import ietf-yang-types { 1196 prefix yang; 1197 rev:revision-or-derived 2013-07-15; 1198 reference "RFC 6991: Common YANG Data Types."; 1199 } 1200 import ietf-inet-types { 1201 prefix inet; 1202 reference "RFC 6991: Common YANG Data Types."; 1203 } 1205 organization 1206 "IETF NETMOD (Network Modeling) Working Group"; 1208 contact 1209 "WG Web: 1210 WG List: 1212 Author: Rob Wilton 1213 "; 1215 description 1216 "This module provides a definition of a YANG package, which is 1217 used as the schema for an YANG instance data document specifying 1218 a YANG package. 1220 Copyright (c) 2019 IETF Trust and the persons identified as 1221 authors of the code. All rights reserved. 1223 Redistribution and use in source and binary forms, with or 1224 without modification, is permitted pursuant to, and subject 1225 to the license terms contained in, the Simplified BSD License 1226 set forth in Section 4.c of the IETF Trust's Legal Provisions 1227 Relating to IETF Documents 1228 (http://trustee.ietf.org/license-info). 1230 This version of this YANG module is part of RFC XXXX; see 1231 the RFC itself for full legal notices. 1233 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL 1234 NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'NOT RECOMMENDED', 1235 'MAY', and 'OPTIONAL' in this document are to be interpreted as 1236 described in BCP 14 (RFC 2119) (RFC 8174) when, and only when, 1237 they appear in all capitals, as shown here."; 1239 // RFC Ed.: update the date below with the date of RFC publication 1240 // and remove this note. 1241 // RFC Ed.: replace XXXX with actual RFC number and remove this 1242 // note. 1243 revision 2019-09-11 { 1244 rev:revision-label 0.1.0; 1245 description 1246 "Initial revision"; 1247 reference 1248 "RFC XXXX: YANG Packages"; 1249 } 1251 /* 1252 * Top-level structure 1253 */ 1255 sx:structure package { 1256 description 1257 "Defines a YANG package. 1259 Intended to be used to specify YANG package within an instance 1260 data document."; 1262 uses pkg-types:yang-pkg-identification-leafs; 1263 uses pkg-types:yang-pkg-common-leafs; 1265 list module { 1266 key "name"; 1267 description 1268 "An entry in this list represents a module that must be 1269 implemented by a server implementing this package, as per 1270 RFC 7950 section 5.6.5, with a particular set of supported 1271 features and deviations. 1273 A entry in this list overrides any module revision 1274 'implemented' by an included package. Any replaced module 1275 revision SHOULD also be listed in the 'replaces-revision' 1276 list."; 1277 reference 1278 "RFC 7950: The YANG 1.1 Data Modeling Language."; 1280 leaf name { 1281 type yang:yang-identifier; 1282 mandatory true; 1283 description 1284 "The YANG module name."; 1285 } 1287 leaf revision { 1288 type rev:revision-date-or-label; 1289 description 1290 "The YANG module revision date or revision-label. 1292 If no revision statement is present in the YANG module, 1293 this leaf is not instantiated."; 1294 } 1295 leaf-list replaces-revision { 1296 type rev:revision-date-or-label; 1297 description 1298 "Gives the revision of an module (implemented or 1299 import-only) defined in an included package that is 1300 replaced by this implemented module revision."; 1301 } 1303 leaf namespace { 1304 type inet:uri; 1305 description 1306 "The XML namespace identifier for this module."; 1307 } 1309 leaf-list location { 1310 type inet:uri; 1311 description 1312 "Contains a URL that represents the YANG schema resource 1313 for this module. 1315 This leaf will only be present if there is a URL available 1316 for retrieval of the schema for this entry."; 1317 } 1319 leaf checksum { 1320 type pkg-types:sha-256-hash; 1321 description 1322 "The SHA-256 hash calculated on the textual module 1323 definition, represented as a hexadecimal string."; 1324 } 1326 list submodule { 1327 key "name"; 1328 description 1329 "Each entry represents one submodule within the 1330 parent module."; 1332 leaf name { 1333 type yang:yang-identifier; 1334 description 1335 "The YANG submodule name."; 1336 } 1338 leaf revision { 1339 type rev:revision-identifier; 1340 mandatory true; 1341 description 1342 "The YANG submodule revision date. If the parent module 1343 include statement for this submodule includes a revision 1344 date then it MUST match this leaf's value."; 1345 } 1347 leaf-list location { 1348 type inet:uri; 1349 description 1350 "Contains a URL that represents the YANG schema resource 1351 for this submodule. 1353 This leaf will only be present if there is a URL 1354 available for retrieval of the schema for this entry."; 1355 } 1357 leaf checksum { 1358 type pkg-types:sha-256-hash; 1359 description 1360 "The SHA-256 hash calculated on the textual submodule 1361 definition, represented as a hexadecimal string."; 1362 } 1363 } 1364 } 1366 list import-only-module { 1367 key "name revision"; 1368 description 1369 "An entry in this list indicates that the server imports 1370 reusable definitions from the specified revision of the 1371 module, but does not implement any protocol accessible 1372 objects from this revision. 1374 Multiple entries for the same module name MAY exist. This 1375 can occur if multiple modules import the same module, but 1376 specify different revision-dates in the import statements."; 1378 leaf name { 1379 type yang:yang-identifier; 1380 description 1381 "The YANG module name."; 1382 } 1384 leaf revision { 1385 type rev:revision-date-or-label; 1386 description 1387 "The YANG module revision date or revision-label. 1389 If no revision statement is present in the YANG module, 1390 this leaf is not instantiated."; 1392 } 1394 leaf-list replaces-revision { 1395 type rev:revision-date-or-label; 1396 description 1397 "Gives the revision of an import-only-module defined in an 1398 included package that is replaced by this 1399 import-only-module revision."; 1400 } 1402 leaf namespace { 1403 type inet:uri; 1404 description 1405 "The XML namespace identifier for this module."; 1406 } 1408 leaf-list location { 1409 type inet:uri; 1410 description 1411 "Contains a URL that represents the YANG schema resource 1412 for this module. 1414 This leaf will only be present if there is a URL available 1415 for retrieval of the schema for this entry."; 1416 } 1418 leaf checksum { 1419 type pkg-types:sha-256-hash; 1420 description 1421 "The SHA-256 hash calculated on the textual submodule 1422 definition, represented as a hexadecimal string."; 1423 } 1425 list submodule { 1426 key "name"; 1427 description 1428 "Each entry represents one submodule within the 1429 parent module."; 1431 leaf name { 1432 type yang:yang-identifier; 1433 description 1434 "The YANG submodule name."; 1435 } 1437 leaf revision { 1438 type rev:revision-identifier; 1439 mandatory true; 1440 description 1441 "The YANG submodule revision date. If the parent module 1442 include statement for this submodule includes a revision 1443 date then it MUST match this leaf's value."; 1444 } 1446 leaf-list location { 1447 type inet:uri; 1448 description 1449 "Contains a URL that represents the YANG schema resource 1450 for this submodule. 1452 This leaf will only be present if there is a URL 1453 available for retrieval of the schema for this entry."; 1454 } 1456 leaf checksum { 1457 type pkg-types:sha-256-hash; 1458 description 1459 "The SHA-256 hash calculated on the textual submodule 1460 definition, represented as a hexadecimal string."; 1461 } 1462 } 1463 } 1464 } 1465 } 1466 1468 file "ietf-yl-packages@2019-09-11.yang" 1469 module ietf-yl-packages { 1470 yang-version 1.1; 1471 namespace "urn:ietf:params:xml:ns:yang:ietf-yl-packages"; 1472 prefix yl-pkg; 1474 import ietf-yang-revisions { 1475 prefix rev; 1476 reference "XXXX: Updated YANG Module Revision Handling"; 1477 } 1479 import ietf-yang-package-types { 1480 prefix pkg-types; 1481 reference "RFC XXX: YANG Packages."; 1482 } 1484 import ietf-yang-library { 1485 prefix yanglib; 1486 reference "RFC 7895bis: YANG Library"; 1487 } 1489 organization 1490 "IETF NETMOD (Network Modeling) Working Group"; 1492 contact 1493 "WG Web: 1494 WG List: 1496 Author: Rob Wilton 1497 "; 1499 description 1500 "This module provides defined augmentations to YANG library to 1501 allow a server to report YANG package information. 1503 Copyright (c) 2018 IETF Trust and the persons identified as 1504 authors of the code. All rights reserved. 1506 Redistribution and use in source and binary forms, with or 1507 without modification, is permitted pursuant to, and subject 1508 to the license terms contained in, the Simplified BSD License 1509 set forth in Section 4.c of the IETF Trust's Legal Provisions 1510 Relating to IETF Documents 1511 (http://trustee.ietf.org/license-info). 1513 This version of this YANG module is part of RFC XXXX; see 1514 the RFC itself for full legal notices. 1516 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL 1517 NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'NOT RECOMMENDED', 1518 'MAY', and 'OPTIONAL' in this document are to be interpreted as 1519 described in BCP 14 (RFC 2119) (RFC 8174) when, and only when, 1520 they appear in all capitals, as shown here."; 1522 // RFC Ed.: update the date below with the date of RFC publication 1523 // and remove this note. 1524 // RFC Ed.: replace XXXX with actual RFC number and remove this 1525 // note. 1526 revision 2019-09-11 { 1527 rev:revision-label 0.1.0; 1528 description 1529 "Initial revision"; 1530 reference 1531 "RFC XXXX: YANG Packages"; 1532 } 1533 /* 1534 * Augmentations 1535 */ 1537 augment "/yanglib:yang-library" { 1538 description "Add YANG package definitions into YANG library"; 1540 list package { 1541 key "name version"; 1542 config "false"; 1544 description 1545 "Defines the package available on this server."; 1547 uses pkg-types:yang-pkg-identification-leafs; 1548 uses pkg-types:yang-pkg-common-leafs; 1550 leaf-list module-set { 1551 type leafref { 1552 path "/yanglib:yang-library/yanglib:module-set/" + 1553 "yanglib:name"; 1554 } 1555 description 1556 "Describes any modules in addition to, and replacing, and 1557 modules defined in the included packages. 1559 If a non import-only module appears in multiple module 1560 sets, then the module revision and the associated features 1561 and deviations MUST be identical."; 1562 } 1564 leaf checksum { 1565 type pkg-types:sha-256-hash; 1566 description 1567 "The SHA-256 hash calculated on the textual package 1568 definition, represented as a hexadecimal string."; 1569 } 1570 } 1571 } 1573 augment "/yanglib:yang-library/yanglib:schema" { 1574 description 1575 "Allow datastore schema to be related to a YANG package"; 1577 container package { 1578 leaf name { 1579 type leafref { 1580 path "/yanglib:yang-library/package/name"; 1582 } 1583 description 1584 "The name of the package this schema relates to. 1586 The referenced package MUST represent a referentially 1587 complete schema"; 1588 } 1590 leaf version { 1591 type leafref { 1592 path '/yanglib:yang-library/' 1593 + 'package[name = current()/../name]/version'; 1594 } 1596 description 1597 "The version number of the package this schema relates 1598 to."; 1599 } 1601 leaf checksum { 1602 type pkg-types:sha-256-hash; 1603 description 1604 "The checksum of the package this schema relates to, 1605 calculated on the 'YANG instance data file' package 1606 definition. 1608 This leaf MAY be omitted if the referenced package is 1609 locally scoped without an associated checksum."; 1610 } 1612 leaf-list supported-optional-feature { 1613 type pkg-types:scoped-feature; 1614 description 1615 "Lists all optional module features that are also 1616 supported by the server when implementing the package. 1618 This list SHOULD exclude any features in the 1619 'mandatory-feature' list for the package, or any included 1620 package. 1622 The full set of features supported by the server for this 1623 schema is the union of this list and all 1624 'mandatory-feature' lists for the package and all 1625 included packages. This is equivalent to the information 1626 provided via the 'feature' leaf list in YANG library. 1628 Features are identified using 1629 ':'"; 1631 } 1633 description 1634 "Describes which package the schema directly relates to, if 1635 any."; 1636 } 1637 } 1639 augment "/yanglib:yang-library/yanglib:module-set/yanglib:module" { 1641 description 1642 "Add 'replaced-revision' and 'checksum' to implemented module 1643 definitions."; 1645 leaf-list replaces-revision { 1646 type rev:revision-date-or-label; 1647 description 1648 "Gives the revision of an module (implemented or import-only) 1649 defined in an included package that is replaced by this 1650 implemented module revision. 1652 Only used for YANG package definitions"; 1653 } 1655 leaf checksum { 1656 type pkg-types:sha-256-hash; 1657 description 1658 "The SHA-256 hash calculated on the textual module 1659 definition, represented as a hexadecimal string."; 1660 } 1661 } 1663 augment 1664 "/yanglib:yang-library/yanglib:module-set/" + 1665 "yanglib:module/yanglib:submodule" { 1667 description 1668 "Add 'checksum' to implemented modules' submodule 1669 definitions."; 1671 leaf checksum { 1672 type pkg-types:sha-256-hash; 1673 description 1674 "The SHA-256 hash calculated on the textual submodule 1675 definition, represented as a hexadecimal string."; 1676 } 1677 } 1678 augment "/yanglib:yang-library/yanglib:module-set/" + 1679 "yanglib:import-only-module" { 1681 description 1682 "Add 'replaces-revision' and 'checksum' to import-only-module 1683 definitions"; 1685 leaf-list replaces-revision { 1686 type rev:revision-date-or-label; 1687 description 1688 "Gives the revision of an import-only-module defined in an 1689 imported package that is replaced by this import-only-module 1690 revision. 1692 Only used for YANG package definitions"; 1693 } 1695 leaf checksum { 1696 type pkg-types:sha-256-hash; 1697 description 1698 "The SHA-256 hash calculated on the textual module 1699 definition, represented as a hexadecimal string."; 1700 } 1701 } 1703 augment "/yanglib:yang-library/yanglib:module-set/" + 1704 "yanglib:import-only-module/yanglib:submodule" { 1706 description 1707 "Add 'checksum' to import-only-modules' submodule 1708 definitions."; 1710 leaf checksum { 1711 type pkg-types:sha-256-hash; 1712 description 1713 "The SHA-256 hash calculated on the textual submodule 1714 definition, represented as a hexadecimal string."; 1715 } 1716 } 1717 } 1718 1720 file "ietf-yang-inst-data-pkg@2019-09-11.yang" 1721 module ietf-yang-inst-data-pkg { 1722 yang-version 1.1; 1723 namespace "urn:ietf:params:xml:ns:yang:ietf-yang-inst-data-pkg"; 1724 prefix yid-pkg; 1726 import ietf-yang-revisions { 1727 prefix rev; 1728 reference "XXXX: Updated YANG Module Revision Handling"; 1729 } 1731 import ietf-yang-package-types { 1732 prefix pkg-types; 1733 rev:revision-or-derived 0.1.0; 1734 reference "RFC XXX: YANG Schema Versioning."; 1735 } 1737 import ietf-yang-structure-ext { 1738 prefix sx; 1739 reference "RFC XXX: YANG Data Structure Extensions."; 1740 } 1742 import ietf-yang-instance-data { 1743 prefix yid; 1744 reference "RFC XXX: YANG Instance Data File Format."; 1745 } 1747 import ietf-inet-types { 1748 prefix inet; 1749 reference "RFC 6991: Common YANG Data Types."; 1750 } 1752 organization 1753 "IETF NETMOD (Network Modeling) Working Group"; 1755 contact 1756 "WG Web: 1757 WG List: 1759 Author: Rob Wilton 1760 "; 1762 description 1763 "The module augments ietf-yang-instance-data to allow package 1764 definitions to be used to define schema in YANG instance data 1765 documents. 1767 Copyright (c) 2019 IETF Trust and the persons identified as 1768 authors of the code. All rights reserved. 1770 Redistribution and use in source and binary forms, with or 1771 without modification, is permitted pursuant to, and subject 1772 to the license terms contained in, the Simplified BSD License 1773 set forth in Section 4.c of the IETF Trust's Legal Provisions 1774 Relating to IETF Documents 1775 (http://trustee.ietf.org/license-info). 1777 This version of this YANG module is part of RFC XXXX; see 1778 the RFC itself for full legal notices. 1780 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL 1781 NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'NOT RECOMMENDED', 1782 'MAY', and 'OPTIONAL' in this document are to be interpreted as 1783 described in BCP 14 (RFC 2119) (RFC 8174) when, and only when, 1784 they appear in all capitals, as shown here."; 1786 // RFC Ed.: update the date below with the date of RFC publication 1787 // and remove this note. 1788 // RFC Ed.: replace XXXX with actual RFC number and remove this 1789 // note. 1790 revision 2019-09-11 { 1791 rev:revision-label 0.1.0; 1792 description 1793 "Initial revision"; 1794 reference 1795 "RFC XXXX: YANG Packages"; 1796 } 1798 /* 1799 * Augmentations 1800 */ 1802 sx:augment-structure 1803 "/yid:instance-data-set/yid:content-schema-spec" { 1804 description 1805 "Add package reference to instance data set schema 1806 specification"; 1807 case pkg-schema { 1808 container pkg-schema { 1809 leaf pkg-schema { 1810 type pkg-types:pkg-identifier; 1811 mandatory true; 1812 description 1813 "The package definition that defines the schema for this 1814 file."; 1815 } 1816 leaf checksum { 1817 type pkg-types:sha-256-hash; 1818 description 1819 "The SHA-256 hash of the package, calculated on 1820 the textual package definition, represented as a 1821 hexadecimal string."; 1822 } 1823 leaf-list location { 1824 type inet:uri; 1825 description 1826 "Contains a URL that represents where an instance data 1827 file for this YANG package can be found. 1829 This leaf will only be present if there is a URL 1830 available for retrieval of the schema for this entry. 1832 If multiple locations are provided, then the first 1833 location in the leaf-list MUST be the definitive 1834 location that uniquely identifies this package"; 1835 } 1836 } 1837 } 1838 } 1839 } 1840 1842 11. Security Considerations 1844 The YANG modules specified in this document defines a schema for data 1845 that is accessed by network management protocols such as NETCONF 1846 [RFC6241] or RESTCONF [RFC8040]. The lowest NETCONF layer is the 1847 secure transport layer, and the mandatory-to-implement secure 1848 transport is Secure Shell (SSH) [RFC6242]. The lowest RESTCONF layer 1849 is HTTPS, and the mandatory-to-implement secure transport is TLS 1850 [RFC5246]. 1852 The NETCONF access control model [RFC6536] provides the means to 1853 restrict access for particular NETCONF or RESTCONF users to a 1854 preconfigured subset of all available NETCONF or RESTCONF protocol 1855 operations and content. 1857 Similarly to YANG library [I-D.ietf-netconf-rfc7895bis], some of the 1858 readable data nodes in these YANG modules may be considered sensitive 1859 or vulnerable in some network environments. It is thus important to 1860 control read access (e.g., via get, get-config, or notification) to 1861 these data nodes. 1863 One additional key different to YANG library, is that the 'ietf-yang- 1864 package' YANG module defines a schema to allow YANG packages to be 1865 defined in YANG instance data documents, that are outside the 1866 security controls of the network management protocols. Hence, it is 1867 important to also consider controlling access to these package 1868 instance data documents to restrict access to sensitive information. 1869 SHA-256 checksums are used to ensure the integrity of YANG package 1870 definitions, imported modules, and sub-modules. 1872 As per the YANG library security considerations, the module, revision 1873 and version information in YANG packages may help an attacker 1874 identify the server capabilities and server implementations with 1875 known bugs since the set of YANG modules supported by a server may 1876 reveal the kind of device and the manufacturer of the device. Server 1877 vulnerabilities may be specific to particular modules, module 1878 revisions, module features, or even module deviations. For example, 1879 if a particular operation on a particular data node is known to cause 1880 a server to crash or significantly degrade device performance, then 1881 the YANG packages information will help an attacker identify server 1882 implementations with such a defect, in order to launch a denial-of- 1883 service attack on the device. 1885 12. IANA Considerations 1887 It is expected that a central registry of standard YANG package 1888 definitions is required to support this solution. 1890 It is unclear whether an IANA registry is also required to manage 1891 specific package versions. It is highly desirable to have a specific 1892 canonical location, under IETF control, where the definitive YANG 1893 package versions can be obtained from. 1895 This document requests IANA to registers a URI in the "IETF XML 1896 Registry" [RFC3688]. Following the format in RFC 3688, the following 1897 registrations are requested. 1899 URI: urn:ietf:params:xml:ns:yang:ietf-yang-package-types.yang 1900 Registrant Contact: The IESG. 1901 XML: N/A, the requested URI is an XML namespace. 1903 URI: urn:ietf:params:xml:ns:yang:ietf-yang-package.yang 1904 Registrant Contact: The IESG. 1905 XML: N/A, the requested URI is an XML namespace. 1907 URI: urn:ietf:params:xml:ns:yang:ietf-yl-packages.yang 1908 Registrant Contact: The IESG. 1909 XML: N/A, the requested URI is an XML namespace. 1911 This document requests that the following YANG modules are added in 1912 the "YANG Module Names" registry [RFC6020]: 1914 Name: ietf-yang-package-types.yang 1915 Namespace: urn:ietf:params:xml:ns:yang:ietf-yang-package- 1916 types.yang 1917 Prefix: pkg-types 1918 Reference: RFC XXXX 1920 Name: ietf-yang-package.yang 1921 Namespace: urn:ietf:params:xml:ns:yang:ietf-yang-package.yang 1922 Prefix: pkg 1923 Reference: RFC XXXX 1925 Name: ietf-yl-packages.yang 1926 Namespace: urn:ietf:params:xml:ns:yang:ietf-yl-packages.yang 1927 Prefix: yl-pkg 1928 Reference: RFC XXXX 1930 13. Open Questions/Issues 1932 All issues, along with the draft text, are currently being tracked at 1933 https://github.com/rgwilton/YANG-Packages-Draft/issues/ 1935 14. Acknowledgements 1937 Feedback helping shape this document has kindly been provided by Andy 1938 Bierman, Joe Clarke, James Cumming, Mahesh Jethanandani, Balazs 1939 Lengyel, Ladislav Lhotka, Jason Sterne, and Reshad Rahman. 1941 15. References 1943 15.1. Normative References 1945 [I-D.ietf-netconf-rfc7895bis] 1946 Bierman, A., Bjorklund, M., Schoenwaelder, J., Watsen, K., 1947 and R. Wilton, "YANG Library", draft-ietf-netconf- 1948 rfc7895bis-07 (work in progress), October 2018. 1950 [I-D.ietf-netmod-module-tags] 1951 Hopps, C., Berger, L., and D. Bogdanovic, "YANG Module 1952 Tags", draft-ietf-netmod-module-tags-09 (work in 1953 progress), September 2019. 1955 [I-D.ietf-netmod-yang-data-ext] 1956 Bierman, A., Bjorklund, M., and K. Watsen, "YANG Data 1957 Structure Extensions", draft-ietf-netmod-yang-data-ext-04 1958 (work in progress), July 2019. 1960 [I-D.ietf-netmod-yang-instance-file-format] 1961 Lengyel, B. and B. Claise, "YANG Instance Data File 1962 Format", draft-ietf-netmod-yang-instance-file-format-04 1963 (work in progress), August 2019. 1965 [I-D.verdt-netmod-yang-module-versioning] 1966 Claise, B., Clarke, J., Rahman, R., Wilton, R., Lengyel, 1967 B., Sterne, J., and K. D'Souza, "Updated YANG Module 1968 Revision Handling", draft-verdt-netmod-yang-module- 1969 versioning-01 (work in progress), October 2019. 1971 [I-D.verdt-netmod-yang-semver] 1972 Claise, B., Clarke, J., Rahman, R., Wilton, R., Lengyel, 1973 B., Sterne, J., and K. D'Souza, "YANG Semantic 1974 Versioning", draft-verdt-netmod-yang-semver-01 (work in 1975 progress), October 2019. 1977 [I-D.verdt-netmod-yang-solutions] 1978 Wilton, R., "YANG Versioning Solution Overview", draft- 1979 verdt-netmod-yang-solutions-01 (work in progress), July 1980 2019. 1982 [I-D.verdt-netmod-yang-versioning-reqs] 1983 Clarke, J., "YANG Module Versioning Requirements", draft- 1984 verdt-netmod-yang-versioning-reqs-02 (work in progress), 1985 November 2018. 1987 [I-D.wilton-netmod-yang-ver-selection] 1988 Wilton, R. and R. Rahman, "YANG Schema Version Selection", 1989 draft-wilton-netmod-yang-ver-selection-00 (work in 1990 progress), March 2019. 1992 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1993 Requirement Levels", BCP 14, RFC 2119, 1994 DOI 10.17487/RFC2119, March 1997, 1995 . 1997 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 1998 DOI 10.17487/RFC3688, January 2004, 1999 . 2001 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 2002 (TLS) Protocol Version 1.2", RFC 5246, 2003 DOI 10.17487/RFC5246, August 2008, 2004 . 2006 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 2007 the Network Configuration Protocol (NETCONF)", RFC 6020, 2008 DOI 10.17487/RFC6020, October 2010, 2009 . 2011 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 2012 and A. Bierman, Ed., "Network Configuration Protocol 2013 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 2014 . 2016 [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure 2017 Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011, 2018 . 2020 [RFC6536] Bierman, A. and M. Bjorklund, "Network Configuration 2021 Protocol (NETCONF) Access Control Model", RFC 6536, 2022 DOI 10.17487/RFC6536, March 2012, 2023 . 2025 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 2026 RFC 7950, DOI 10.17487/RFC7950, August 2016, 2027 . 2029 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 2030 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 2031 . 2033 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2034 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 2035 May 2017, . 2037 [RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 2038 and R. Wilton, "Network Management Datastore Architecture 2039 (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018, 2040 . 2042 [RFC8525] Bierman, A., Bjorklund, M., Schoenwaelder, J., Watsen, K., 2043 and R. Wilton, "YANG Library", RFC 8525, 2044 DOI 10.17487/RFC8525, March 2019, 2045 . 2047 15.2. Informative References 2049 [I-D.bierman-netmod-yang-package] 2050 Bierman, A., "The YANG Package Statement", draft-bierman- 2051 netmod-yang-package-00 (work in progress), July 2015. 2053 [I-D.ietf-netmod-artwork-folding] 2054 Watsen, K., Farrel, A., and Q. WU, "Handling Long Lines in 2055 Inclusions in Internet-Drafts and RFCs", draft-ietf- 2056 netmod-artwork-folding-10 (work in progress), September 2057 2019. 2059 [openconfigsemver] 2060 "Semantic Versioning for OpenConfig Models", 2061 . 2063 [RFC8199] Bogdanovic, D., Claise, B., and C. Moberg, "YANG Module 2064 Classification", RFC 8199, DOI 10.17487/RFC8199, July 2065 2017, . 2067 Appendix A. Tree output for ietf-yang-library with package 2068 augmentations 2070 Complete tree output for ietf-yang-library with package 2071 augmentations. 2073 module: ietf-yang-library 2074 +--ro yang-library 2075 | +--ro module-set* [name] 2076 | | +--ro name string 2077 | | +--ro module* [name] 2078 | | | +--ro name yang:yang-identifier 2079 | | | +--ro revision? revision-identifier 2080 | | | +--ro namespace inet:uri 2081 | | | +--ro location* inet:uri 2082 | | | +--ro submodule* [name] 2083 | | | | +--ro name yang:yang-identifier 2084 | | | | +--ro revision? revision-identifier 2085 | | | | +--ro location* inet:uri 2086 | | | | +--ro yl-pkg:checksum? pkg-types:sha-256-hash 2087 | | | +--ro feature* yang:yang-identifier 2088 | | | +--ro deviation* -> ../../module/name 2089 | | | +--ro yl-pkg:replaces-revision* 2090 | | | | yanglib:revision-identifier 2091 | | | +--ro yl-pkg:checksum? pkg-types:sha-256-hash 2092 | | +--ro import-only-module* [name revision] 2093 | | +--ro name yang:yang-identifier 2094 | | +--ro revision union 2095 | | +--ro namespace inet:uri 2096 | | +--ro location* inet:uri 2097 | | +--ro submodule* [name] 2098 | | | +--ro name yang:yang-identifier 2099 | | | +--ro revision? revision-identifier 2100 | | | +--ro location* inet:uri 2101 | | | +--ro pkg:checksum? pkg-types:sha-256-hash 2102 | | +--ro yl-pkg:replaces-revision* 2103 | | | yanglib:revision-identifier 2104 | | +--ro yl-pkg:checksum? pkg-types:sha-256-hash 2105 | +--ro schema* [name] 2106 | | +--ro name string 2107 | | +--ro module-set* -> ../../module-set/name 2108 | | +--ro yl-pkg:package 2109 | | +--ro yl-pkg:name? 2110 | | | -> /yanglib:yang-library/package/name 2111 | | +--ro yl-pkg:version? leafref 2112 | | +--ro yl-pkg:supported-feature* pkg-types:scoped-feature 2113 | +--ro datastore* [name] 2114 | | +--ro name ds:datastore-ref 2115 | | +--ro schema -> ../../schema/name 2116 | +--ro content-id string 2117 | +--ro yl-pkg:package* [name version] 2118 | +--ro yl-pkg:name yang:yang-identifier 2119 | +--ro yl-pkg:version rev:revision-label 2120 | +--ro yl-pkg:timestamp? yang:date-and-time 2121 | +--ro yl-pkg:organization? string 2122 | +--ro yl-pkg:contact? string 2123 | +--ro yl-pkg:description? string 2124 | +--ro yl-pkg:reference? string 2125 | +--ro yl-pkg:complete? boolean 2126 | +--ro yl-pkg:location* inet:uri 2127 | +--ro yl-pkg:local? boolean 2128 | +--ro yl-pkg:previous-version? yang-sem-ver 2129 | +--ro yl-pkg:nbc-changes? boolean 2130 | +--ro yl-pkg:tag* tags:tag 2131 | +--ro yl-pkg:mandatory-feature* string 2132 | +--ro yl-pkg:included-package* [name version] 2133 | | +--ro yl-pkg:name yang:yang-identifier 2134 | | +--ro yl-pkg:version rev:revision-label 2135 | | +--ro yl-pkg:replaces-version* rev:revision-label 2136 | | +--ro yl-pkg:nbc-modified? boolean 2137 | | +--ro yl-pkg:location* inet:uri 2138 | | +--ro yl-pkg:checksum? string 2139 | +--ro yl-pkg:module-set* 2140 | | -> /yanglib:yang-library/module-set/name 2141 | +--ro yl-pkg:checksum? pkg-types:sha-256-hash 2142 x--ro modules-state 2143 x--ro module-set-id string 2144 x--ro module* [name revision] 2145 x--ro name yang:yang-identifier 2146 x--ro revision union 2147 +--ro schema? inet:uri 2148 x--ro namespace inet:uri 2149 x--ro feature* yang:yang-identifier 2150 x--ro deviation* [name revision] 2151 | x--ro name yang:yang-identifier 2152 | x--ro revision union 2153 x--ro conformance-type enumeration 2154 x--ro submodule* [name revision] 2155 x--ro name yang:yang-identifier 2156 x--ro revision union 2157 +--ro schema? inet:uri 2159 notifications: 2160 +---n yang-library-update 2161 | +--ro content-id -> /yang-library/content-id 2162 x---n yang-library-change 2163 x--ro module-set-id -> /modules-state/module-set-id 2165 Appendix B. Examples 2167 This section provides various examples of YANG packages, and as such 2168 this text is non-normative. The purpose of the examples is to only 2169 illustrate the file format of YANG packages, and how package 2170 dependencies work. It does not imply that such packages will be 2171 defined by IETF, or which modules would be included in those packages 2172 even if they were defined. For brevity, the examples exclude 2173 namespace declarations, and use a shortened URL of "tiny.cc/ietf- 2174 yang" as a replacement for 2175 "https://raw.githubusercontent.com/YangModels/yang/master/standard/ 2176 ietf/RFC". 2178 B.1. Example IETF Network Device YANG package 2180 This section provides an instance data document example of an IETF 2181 Network Device YANG package formatted in JSON. 2183 This example package is intended to represent the standard set of 2184 YANG modules, with import dependencies, to implement a basic network 2185 device without any dynamic routing or layer 2 services. E.g., it 2186 includes functionality such as system information, interface and 2187 basic IP configuration. 2189 As for all YANG packages, all import dependencies are fully resolved. 2190 Because this example uses YANG modules that have been standardized 2191 before YANG semantic versioning, they modules are referenced by 2192 revision date rather than version number. 2194 file "example-ietf-network-device-pkg.json" 2195 ========= NOTE: '\' line wrapping per BCP XX (RFC XXXX) =========== 2197 { 2198 "ietf-yang-instance-data:instance-data-set": { 2199 "name": "example-ietf-network-device-pkg", 2200 "pkg-schema": { 2201 package: "ietf-yang-package-defn-pkg@0.1.0.json" 2202 }, 2203 "description": "YANG package definition", 2204 "content-data": { 2205 "ietf-yang-package:yang-package": { 2206 "name": "example-ietf-network-device-pkg", 2207 "version": "1.1.2", 2208 "timestamp": "2018-12-13T17:00:00Z", 2209 "organization": "IETF NETMOD Working Group", 2210 "contact" : "WG Web: , \ 2211 WG List: ", 2212 "description": "Example IETF network device YANG package.\ 2213 \ 2214 This package defines a small sample set of \ 2215 YANG modules that could represent the basic set of \ 2216 modules that a standard network device might be expected \ 2217 to support.", 2218 "reference": "XXX, draft-rwilton-netmod-yang-packages", 2219 "location": [ "file://example.org/yang/packages/\ 2220 ietf-network-device@v1.1.2.json" ], 2221 "module": [ 2222 { 2223 "name": "iana-crypt-hash", 2224 "revision": "2014-08-06", 2225 "location": [ "https://tiny.cc/ietf-yang/\ 2226 iana-crypt-hash%402014-08-06.yang" ], 2227 "checksum": "fa9fde408ddec2c16bf2c6b9e4c2f80b\ 2228 813a2f9e48c127016f3fa96da346e02d" 2229 }, 2230 { 2231 "name": "ietf-system", 2232 "revision": "2014-08-06", 2233 "location": [ "https://tiny.cc/ietf-yang/\ 2234 ietf-system%402014-08-06.yang" ], 2235 "checksum": "8a692ee2521b4ffe87a88303a61a1038\ 2236 79ee26bff050c1b05a2027ae23205d3f" 2237 }, 2238 { 2239 "name": "ietf-interfaces", 2240 "revision": "2018-02-20", 2241 "location": [ "https://tiny.cc/ietf-yang/\ 2242 ietf-interfaces%402018-02-20.yang" ], 2243 "checksum": "f6faea9938f0341ed48fda93dba9a69a\ 2244 a32ee7142c463342efec3d38f4eb3621" 2245 }, 2246 { 2247 "name": "ietf-netconf-acm", 2248 "revision": "2018-02-14", 2249 "location": [ "https://tiny.cc/ietf-yang/\ 2250 ietf-netconf-acm%402018-02-14.yang" ], 2251 "checksum": "e03f91317f9538a89296e99df3ff0c40\ 2252 03cdfea70bf517407643b3ec13c1ed25" 2253 }, 2254 { 2255 "name": "ietf-key-chain", 2256 "revision": "2017-06-15", 2257 "location": [ "https://tiny.cc/ietf-yang/\ 2258 ietf-key-chain@2017-06-15.yang" ], 2259 "checksum": "6250705f59fc9ad786e8d74172ce90d5\ 2260 8deec437982cbca7922af40b3ae8107c" 2261 }, 2262 { 2263 "name": "ietf-ip", 2264 "revision": "2018-02-22", 2265 "location": [ "https://tiny.cc/ietf-yang/\ 2266 ietf-ip%402018-02-22.yang" ], 2267 "checksum": "b624c84a66c128ae69ab107a5179ca8e\ 2268 20e693fb57dbe5cb56c3db2ebb18c894" 2269 } 2270 ], 2271 "import-only-module": [ 2272 { 2273 "name": "ietf-yang-types", 2274 "revision": "2013-07-15", 2275 "location": [ "https://tiny.cc/ietf-yang/\ 2276 ietf-yang-types%402013-07-15.yang" ], 2277 "checksum": "a04cdcc875764a76e89b7a0200c6b9d8\ 2278 00b10713978093acda7840c7c2907c3f" 2279 }, 2280 { 2281 "name": "ietf-inet-types", 2282 "revision": "2013-07-15", 2283 "location": [ "https://tiny.cc/ietf-yang/\ 2284 ietf-inet-types%402013-07-15.yang" ], 2285 "checksum": "12d98b0143a5ca5095b36420f9ebc1ff\ 2286 a61cfd2eaa850080244cadf01b86ddf9" 2287 } 2288 ] 2289 } 2291 } 2292 } 2293 } 2294 2296 B.2. Example IETF Basic Routing YANG package 2298 This section provides an instance data document example of a basic 2299 IETF Routing YANG package formatted in JSON. 2301 This example package is intended to represent the standard set of 2302 YANG modules, with import dependencies, that builds upon the example- 2303 ietf-network-device YANG package to add support for basic dynamic 2304 routing and ACLs. 2306 As for all YANG packages, all import dependencies are fully resolved. 2307 Because this example uses YANG modules that have been standardized 2308 before YANG semantic versioning, they modules are referenced by 2309 revision date rather than version number. Locations have been 2310 excluded where they are not currently known, e.g., for YANG modules 2311 defined in IETF drafts. In a normal YANG package, locations would be 2312 expected to be provided for all YANG modules. 2314 file "example-ietf-routing-pkg.json" 2315 ========== NOTE: '\' line wrapping per BCP XX (RFC XXXX) =========== 2317 { 2318 "ietf-yang-instance-data:instance-data-set": { 2319 "name": "example-ietf-routing-pkg", 2320 "module": [ "ietf-yang-package@2019-09-11.yang" ], 2321 "description": "YANG package definition", 2322 "content-data": { 2323 "ietf-yang-package:yang-package": { 2324 "name": "example-ietf-routing", 2325 "version": "1.3.1", 2326 "timestamp": "2018-12-13T17:00:00Z", 2327 "description": "This package defines a small sample set of \ 2328 IETF routing YANG modules that could represent the set of \ 2329 IETF routing functionality that a basic IP network device \ 2330 might be expected to support.", 2331 "reference": "XXX, draft-rwilton-netmod-yang-packages", 2332 "imported-packages": [ 2333 { 2334 "name": "ietf-network-device", 2335 "version": "1.1.2", 2336 "location": [ "http://example.org/yang/packages/\ 2337 ietf-network-device@v1.1.2.json" ], 2338 "checksum": "" 2339 } 2340 ], 2341 "module": [ 2342 { 2343 "name": "ietf-routing", 2344 "revision": "2018-03-13", 2345 "location": [ "https://tiny.cc/ietf-yang/\ 2346 ietf-routing@2018-03-13.yang" ], 2347 "checksum": "" 2348 }, 2349 { 2350 "name": "ietf-ipv4-unicast-routing", 2351 "revision": "2018-03-13", 2352 "location": [ "https://tiny.cc/ietf-yang/\ 2353 ietf-ipv4-unicast-routing@2018-03-13.yang" ], 2354 "checksum": "" 2355 }, 2356 { 2357 "name": "ietf-ipv6-unicast-routing", 2358 "revision": "2018-03-13", 2359 "location": [ "https://tiny.cc/ietf-yang/\ 2360 ietf-ipv6-unicast-routing@2018-03-13.yang" ], 2361 "checksum": "" 2362 }, 2363 { 2364 "name": "ietf-isis", 2365 "revision": "2018-12-11", 2366 "location": [ "https://tiny.cc/ietf-yang/\ 2367 " ], 2368 "checksum": "" 2369 }, 2370 { 2371 "name": "ietf-interfaces-common", 2372 "revision": "2018-07-02", 2373 "location": [ "https://tiny.cc/ietf-yang/\ 2374 " ], 2375 "checksum": "" 2376 }, 2377 { 2378 "name": "ietf-if-l3-vlan", 2379 "revision": "2017-10-30", 2380 "location": [ "https://tiny.cc/ietf-yang/\ 2381 " ], 2382 "checksum": "" 2383 }, 2384 { 2385 "name": "ietf-routing-policy", 2386 "revision": "2018-10-19", 2387 "location": [ "https://tiny.cc/ietf-yang/\ 2388 " ], 2389 "checksum": "" 2390 }, 2391 { 2392 "name": "ietf-bgp", 2393 "revision": "2018-05-09", 2394 "location": [ "https://tiny.cc/ietf-yang/\ 2395 " ], 2396 "checksum": "" 2397 }, 2398 { 2399 "name": "ietf-access-control-list", 2400 "revision": "2018-11-06", 2401 "location": [ "https://tiny.cc/ietf-yang/\ 2402 " ], 2403 "checksum": "" 2404 } 2405 ], 2406 "import-only-module": [ 2407 { 2408 "name": "ietf-routing-types", 2409 "revision": "2017-12-04", 2410 "location": [ "https://tiny.cc/ietf-yang/\ 2411 ietf-routing-types@2017-12-04.yang" ], 2412 "checksum": "" 2413 }, 2414 { 2415 "name": "iana-routing-types", 2416 "revision": "2017-12-04", 2417 "location": [ "https://tiny.cc/ietf-yang/\ 2418 iana-routing-types@2017-12-04.yang" ], 2419 "checksum": "" 2420 }, 2421 { 2422 "name": "ietf-bgp-types", 2423 "revision": "2018-05-09", 2424 "location": [ "https://tiny.cc/ietf-yang/\ 2425 " ], 2426 "checksum": "" 2427 }, 2428 { 2429 "name": "ietf-packet-fields", 2430 "revision": "2018-11-06", 2431 "location": [ "https://tiny.cc/ietf-yang/\ 2432 " ], 2434 "checksum": "" 2435 }, 2436 { 2437 "name": "ietf-ethertypes", 2438 "revision": "2018-11-06", 2439 "location": [ "https://tiny.cc/ietf-yang/\ 2440 " ], 2441 "checksum": "" 2442 } 2443 ] 2444 } 2445 } 2446 } 2447 } 2448 2450 B.3. Package import conflict resolution example 2452 This section provides an example of how a package can resolve 2453 conflicting module versions from imported packages. 2455 In this example, YANG package 'example-3-pkg' imports both 'example- 2456 import-1' and 'example-import-2' packages. However, the two imported 2457 packages implement different versions of 'example-module-A' so the 2458 'example-3-pkg' package selects version '1.2.3' to resolve the 2459 conflict. Similarly, for import-only modules, the 'example-3-pkg' 2460 package does not require both versions of example-types-module-C to 2461 be imported, so it indicates that it only imports revision 2462 '2018-11-26' and not '2018-01-01'. 2464 { 2465 "ietf-yang-instance-data:instance-data-set": { 2466 "name": "example-import-1-pkg", 2467 "description": "First imported example package", 2468 "content-data": { 2469 "ietf-yang-package:yang-package": { 2470 "name": "example-import-1", 2471 "version": "1.0.0", 2472 "reference": "XXX, draft-rwilton-netmod-yang-packages", 2473 "revision-date": "2018-01-01", 2474 "module": [ 2475 { 2476 "name": "example-module-A", 2477 "version": "1.0.0" 2478 }, 2479 { 2480 "name": "example-module-B", 2481 "version": "1.0.0" 2482 } 2483 ], 2484 "import-only-module": [ 2485 { 2486 "name": "example-types-module-C", 2487 "revision": "2018-01-01" 2488 }, 2489 { 2490 "name": "example-types-module-D", 2491 "revision": "2018-01-01" 2492 } 2493 ] 2494 } 2495 } 2496 } 2497 } 2499 { 2500 "ietf-yang-instance-data:instance-data-set": { 2501 "name": "example-import-2-pkg", 2502 "description": "Second imported example package", 2503 "content-data": { 2504 "ietf-yang-package:yang-package": { 2505 "name": "example-import-2", 2506 "version": "2.0.0", 2507 "reference": "XXX, draft-rwilton-netmod-yang-packages", 2508 "revision-date": "2018-11-26", 2509 "module": [ 2510 { 2511 "name": "example-module-A", 2512 "version": "1.2.3" 2513 }, 2514 { 2515 "name": "example-module-E", 2516 "version": "1.1.0" 2517 } 2518 ], 2519 "import-only-module": [ 2520 { 2521 "name": "example-types-module-C", 2522 "revision": "2018-11-26" 2523 }, 2524 { 2525 "name": "example-types-module-D", 2526 "revision": "2018-11-26" 2527 } 2529 ] 2530 } 2531 } 2532 } 2533 } 2535 { 2536 "ietf-yang-instance-data:instance-data-set": { 2537 "name": "example-3-pkg", 2538 "description": "Importing example package", 2539 "content-data": { 2540 "ietf-yang-package:yang-package": { 2541 "name": "example-3", 2542 "version": "1.0.0", 2543 "reference": "XXX, draft-rwilton-netmod-yang-packages", 2544 "revision-date": "2018-11-26", 2545 "included-package": [ 2546 { 2547 "name": "example-import-1", 2548 "version": "1.0.0" 2549 }, 2550 { 2551 "name": "example-import-2", 2552 "version": "2.0.0" 2553 } 2554 ], 2555 "module": [ 2556 { 2557 "name": "example-module-A", 2558 "version": "1.2.3" 2559 } 2560 ], 2561 "import-only-module": [ 2562 { 2563 "name": "example-types-module-C", 2564 "revision": "2018-11-26", 2565 "replaces-revision": [ "2018-01-01 "] 2566 } 2567 ] 2568 } 2569 } 2570 } 2571 } 2573 Appendix C. Possible alternative solutions 2575 This section briefly describes some alternative solutions. It can be 2576 removed if this document is adopted as a WG draft. 2578 C.1. Using module tags 2580 Module tags have been suggested as an alternative solution, and 2581 indeed that can address some of the same requirements as YANG 2582 packages but not all of them. 2584 Module tags can be used to group or organize YANG modules. However, 2585 this raises the question of where this tag information is stored. 2586 Module tags either require that the YANG module files themselves are 2587 updated with the module tag information (creating another versioning 2588 problem), or for the module tag information to be hosted elsewhere, 2589 perhaps in a centralize YANG Catalog, or in instance data documents 2590 similar to how YANG packages have been defined in this draft. 2592 One of the principle aims of YANG packages is to be a versioned 2593 object that defines a precise set of YANG modules versions that work 2594 together. Module tags cannot meet this aim without an explosion of 2595 module tags definitions (i.e. a separate module tag must be defined 2596 for each package version). 2598 Module tags cannot support the hierachical scheme to construct YANG 2599 schema that is proposed in this draft. 2601 C.2. Using YANG library 2603 Another question is whether it is necessary to define new YANG 2604 modules to define YANG packages, and whether YANG library could just 2605 be reused in an instance data document. The use of YANG packages 2606 offers several benefits over just using YANG library: 2608 1. Packages allow schema to be built in a hierarchical fashion. 2609 [I-D.ietf-netconf-rfc7895bis] only allows one layer of hierarchy 2610 (using module sets), and there must be no conflicts between 2611 module revisions in different module-sets. 2613 2. Packages can be made available off the box, with a well defined 2614 unique name, avoiding the need for clients to download, and 2615 construct/check the entire YANG schema for each device. Instead 2616 they can rely on the named packages with secure checksums. YANG 2617 library's use of a 'content-id' is unique only to the device that 2618 generated them. 2620 3. Packages may be versioned using a semantic versioning scheme, 2621 YANG library does not provide a schema level semantic version 2622 number. 2624 4. For a YANG library instance data document to contain the 2625 necessary information, it probably needs both YANG library and 2626 various augmentations (e.g. to include each module's semantic 2627 version number), unless a new version of YANG library is defined 2628 containing this information. The module definition for a YANG 2629 package is specified to contain all of the ncessary information 2630 to solve the problem without augmentations 2632 5. YANG library is designed to publish information about the 2633 modules, datastores, and datastore schema used by a server. The 2634 information required to construct an off box schema is not 2635 precisely the same, and hence the definitions might deviate from 2636 each other over time. 2638 Author's Address 2640 Robert Wilton 2641 Cisco Systems, Inc. 2643 Email: rwilton@cisco.com