idnits 2.17.1 draft-ietf-netmod-yang-packages-01.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 743 has weird spacing: '...version pkg...' == Line 775 has weird spacing: '...evision yan...' == Line 787 has weird spacing: '...evision yan...' -- The document date (November 2, 2020) is 1270 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 2155, but no explicit reference was found in the text == Unused Reference: 'RFC8199' is defined on line 2165, but no explicit reference was found in the text == Outdated reference: A later version (-21) exists of draft-ietf-netmod-yang-instance-file-format-12 == Outdated reference: A later version (-11) exists of draft-ietf-netmod-yang-module-versioning-01 == Outdated reference: A later version (-15) exists of draft-ietf-netmod-yang-semver-01 == Outdated reference: A later version (-01) exists of draft-ietf-netmod-yang-solutions-00 ** Downref: Normative reference to an Informational draft: draft-ietf-netmod-yang-solutions (ref. 'I-D.ietf-netmod-yang-solutions') == Outdated reference: A later version (-09) exists of draft-ietf-netmod-yang-versioning-reqs-03 ** Downref: Normative reference to an Informational draft: draft-ietf-netmod-yang-versioning-reqs (ref. 'I-D.ietf-netmod-yang-versioning-reqs') ** Obsolete normative reference: RFC 5246 (Obsoleted by RFC 8446) ** Obsolete normative reference: RFC 6536 (Obsoleted by RFC 8341) Summary: 4 errors (**), 0 flaws (~~), 11 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group R. Wilton, Ed. 3 Internet-Draft R. Rahman 4 Intended status: Standards Track J. Clarke 5 Expires: May 6, 2021 Cisco Systems, Inc. 6 J. Sterne 7 Nokia 8 B. Wu, Ed. 9 Huawei 10 November 2, 2020 12 YANG Packages 13 draft-ietf-netmod-yang-packages-01 15 Abstract 17 This document defines YANG packages, a versioned organizational 18 structure holding a set of related YANG modules that collectively 19 define a YANG schema. It describes how packages: are represented on 20 a server, can be defined in offline YANG instance data files, and can 21 be used to define the schema associated with YANG instance data 22 files. 24 Status of This Memo 26 This Internet-Draft is submitted in full conformance with the 27 provisions of BCP 78 and BCP 79. 29 Internet-Drafts are working documents of the Internet Engineering 30 Task Force (IETF). Note that other groups may also distribute 31 working documents as Internet-Drafts. The list of current Internet- 32 Drafts is at https://datatracker.ietf.org/drafts/current/. 34 Internet-Drafts are draft documents valid for a maximum of six months 35 and may be updated, replaced, or obsoleted by other documents at any 36 time. It is inappropriate to use Internet-Drafts as reference 37 material or to cite them other than as "work in progress." 39 This Internet-Draft will expire on May 6, 2021. 41 Copyright Notice 43 Copyright (c) 2020 IETF Trust and the persons identified as the 44 document authors. All rights reserved. 46 This document is subject to BCP 78 and the IETF Trust's Legal 47 Provisions Relating to IETF Documents 48 (https://trustee.ietf.org/license-info) in effect on the date of 49 publication of this document. Please review these documents 50 carefully, as they describe your rights and restrictions with respect 51 to this document. Code Components extracted from this document must 52 include Simplified BSD License text as described in Section 4.e of 53 the Trust Legal Provisions and are provided without warranty as 54 described in the Simplified BSD License. 56 Table of Contents 58 1. Terminology and Conventions . . . . . . . . . . . . . . . . . 3 59 2. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 60 3. Background on YANG packages . . . . . . . . . . . . . . . . . 4 61 4. Objectives . . . . . . . . . . . . . . . . . . . . . . . . . 5 62 5. YANG Package Definition . . . . . . . . . . . . . . . . . . . 6 63 5.1. Package definition rules . . . . . . . . . . . . . . . . 7 64 5.2. Package versioning . . . . . . . . . . . . . . . . . . . 8 65 5.2.1. Updating a package with a new version . . . . . . . . 8 66 5.2.1.1. Non-Backwards-compatible changes . . . . . . . . 8 67 5.2.1.2. Backwards-compatible changes . . . . . . . . . . 9 68 5.2.1.3. Editorial changes . . . . . . . . . . . . . . . . 9 69 5.2.2. YANG Semantic Versioning for packages . . . . . . . . 9 70 5.2.3. Revision history . . . . . . . . . . . . . . . . . . 10 71 5.3. Package conformance . . . . . . . . . . . . . . . . . . . 10 72 5.3.1. Use of YANG semantic versioning . . . . . . . . . . . 10 73 5.3.2. Package checksums . . . . . . . . . . . . . . . . . . 11 74 5.3.3. The relationship between packages and datastores . . 12 75 5.4. Schema referential completeness . . . . . . . . . . . . . 13 76 5.5. Package name scoping and uniqueness . . . . . . . . . . . 14 77 5.5.1. Globally scoped packages . . . . . . . . . . . . . . 14 78 5.5.2. Server scoped packages . . . . . . . . . . . . . . . 14 79 5.6. Submodules packages considerations . . . . . . . . . . . 14 80 5.7. Package tags . . . . . . . . . . . . . . . . . . . . . . 14 81 5.8. YANG Package Usage Guidance . . . . . . . . . . . . . . . 15 82 5.8.1. Use of deviations in YANG packages . . . . . . . . . 15 83 5.8.2. Use of features in YANG modules and YANG packages . . 16 84 5.9. YANG package core definition . . . . . . . . . . . . . . 16 85 6. Package Instance Data Files . . . . . . . . . . . . . . . . . 17 86 7. Package Definitions on a Server . . . . . . . . . . . . . . . 18 87 7.1. Package List . . . . . . . . . . . . . . . . . . . . . . 18 88 7.2. Tree diagram . . . . . . . . . . . . . . . . . . . . . . 19 89 8. YANG Library Package Bindings . . . . . . . . . . . . . . . . 19 90 9. YANG packages as schema for YANG instance data document . . . 20 91 10. YANG Modules . . . . . . . . . . . . . . . . . . . . . . . . 20 92 11. Security Considerations . . . . . . . . . . . . . . . . . . . 41 93 12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 42 94 13. Open Questions/Issues . . . . . . . . . . . . . . . . . . . . 44 95 14. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 44 96 15. References . . . . . . . . . . . . . . . . . . . . . . . . . 44 97 15.1. Normative References . . . . . . . . . . . . . . . . . . 44 98 15.2. Informative References . . . . . . . . . . . . . . . . . 46 99 Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 46 100 A.1. Example IETF Network Device YANG package . . . . . . . . 47 101 A.2. Example IETF Basic Routing YANG package . . . . . . . . . 49 102 A.3. Package import conflict resolution example . . . . . . . 52 103 Appendix B. Possible alternative solutions . . . . . . . . . . . 55 104 B.1. Using module tags . . . . . . . . . . . . . . . . . . . . 55 105 B.2. Using YANG library . . . . . . . . . . . . . . . . . . . 56 106 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 56 108 1. Terminology and Conventions 110 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 111 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 112 "OPTIONAL" in this document are to be interpreted as described in BCP 113 14 [RFC2119] [RFC8174] when, and only when, they appear in all 114 capitals, as shown here. 116 This document uses terminology introduced in the YANG versioning 117 requirements draft [I-D.ietf-netmod-yang-versioning-reqs]. 119 This document also makes of the following terminology introduced in 120 the Network Management Datastore Architecture [RFC8342]: 122 o datastore schema 124 This document also makes of the following terminology introduced in 125 the YANG 1.1 Data Modeling Language [RFC7950]: 127 o data node 129 In addition, this document defines the following terminology: 131 o YANG schema: A datastore schema, not bound to any particular 132 datastore. 134 o YANG package: An organizational structure containing a collection 135 of YANG modules, normally defined in a YANG instance data file. A 136 YANG package defines a YANG schema by specifying a set of YANG 137 modules and their revisions, other packages and their revisions, 138 mandatory features, and deviations. YANG packages are defined in 139 Section 5. 141 o backwards-compatible (BC) change: When used in the context of a 142 YANG module, it follows the definition in Section 3.1.1 of 143 [I-D.ietf-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 non-backwards-compatible (NBC) change: When used in the context of 148 a YANG module, it follows the definition in Section 3.1.2 of 149 [I-D.ietf-netmod-yang-module-versioning]. When used in the 150 context of a YANG package, it follows the definition in 151 Section 5.2.1.2. 153 o editorial change: When used in the context of a YANG module, it 154 follows the definition of an 'editorial change' in 3.2 of 155 [I-D.ietf-netmod-yang-module-versioning]. When used in the 156 context of a YANG package, it follows the definition in 157 Section 5.2.1.3. 159 2. Introduction 161 This document defines and describes the YANG [RFC7950] constructs 162 that are used to define and use YANG packages. 164 A YANG package is an organizational structure that groups a set of 165 YANG modules together into a consistent versioned definition. For 166 example, a YANG package could define the set of YANG modules required 167 to implement an L2VPN service on a network device. YANG packages can 168 themselves refer to, and reuse, other package definitions. 170 Non-normative examples of YANG packages are provided in the 171 appendices. 173 3. Background on YANG packages 175 It has long been acknowledged within the YANG community that network 176 management using YANG requires a unit of organization and conformance 177 that is broader in scope than individual YANG modules. 179 'The YANG Package Statement' [I-D.bierman-netmod-yang-package] 180 proposed a YANG package mechanism based on new YANG language 181 statements, where a YANG package is defined in a file similar to how 182 YANG modules are defined, and would require enhancements to YANG 183 compilers to understand the new statements used to define packages. 185 OpenConfig [openconfigsemver] describes an approach to versioning 186 'bundle releases' based on git tags. I.e. a set of modules, at 187 particular versions, can be marked with the same release tag to 188 indicate that they are known to interoperate together. 190 The NETMOD WG in general, and the YANG versioning design team in 191 particular, are exploring solutions [I-D.ietf-netmod-yang-solutions] 192 to the YANG versioning requirements, 193 [I-D.ietf-netmod-yang-versioning-reqs]. Solutions to the versioning 194 requirements can be split into several distinct areas. 195 [I-D.ietf-netmod-yang-module-versioning] is focused on YANG 196 versioning scoped to individual modules. The overall solution must 197 also consider YANG versioning and conformance scoped to YANG schema. 198 YANG packages provide part of the solution for versioning YANG 199 schema. 201 4. Objectives 203 The main goals of YANG package definitions include, but are not 204 restricted to: 206 o To provide an alternative, simplified, YANG conformance mechanism. 207 Rather than conformance being performed against a set of 208 individual YANG module revisions, features, and deviations, 209 conformance can be more simply stated in terms of YANG packages, 210 with a set of modifications (e.g. additional modules, deviations, 211 or features). 213 o To allow YANG schema to be specified in a concise way rather than 214 having each server explicitly list all modules, revisions, and 215 features. YANG package definitions can be defined in documents 216 that are available offline, and accessible via a URL, rather than 217 requiring explicit lists of modules to be shared between client 218 and server. Hence, a YANG package must contain sufficient 219 information to allow a client or server to precisely construct the 220 schema associated with the package. 222 o To define a mainly linear versioned history of sets of modules 223 versions that are known to work together. I.e. to help mitigate 224 the problem where a client must manage devices from multiple 225 vendors, and vendor A implements version 1.0.0 of module foo and 226 version 2.0.0 of module bar, and vendor B implements version 2.0.0 227 of module foo and version 1.0.0 of module bar. For a client, 228 trying to interoperate with multiple vendors, and many YANG 229 modules, finding a consistent lowest common denominator set of 230 YANG module versions may be difficult, if not impossible. 232 Protocol mechanisms of how clients can negotiate which packages or 233 package versions are to be used for NETCONF/RESTCONF communications 234 are outside the scope of this document, and are defined in 235 [I-D.ietf-netmod-yang-ver-selection]. 237 Finally, the package definitions proposed by this document are 238 intended to be relatively basic in their definition and the 239 functionality that they support. As industry gains experience using 240 YANG packages, the standard YANG mechanisms of updating, or 241 augmenting YANG modules could also be used to extend the 242 functionality supported by YANG packages, if required. 244 5. YANG Package Definition 246 This document specifies an approach to defining YANG packages that is 247 different to either of the approaches described in the background. 249 A YANG package is a versioned organizational structure defining a set 250 of related YANG modules, packages, features, and deviations. A YANG 251 package collectively defines a YANG schema. 253 Each YANG package has a name that SHOULD end with the suffix "-pkg". 254 Package names are normally expected to be globally unique, but in 255 some cases the package name may be locally scoped to a server or 256 device, as described in Section 5.5. 258 YANG packages are versioned using the same approaches described in 259 [I-D.ietf-netmod-yang-module-versioning] and 260 [I-D.ietf-netmod-yang-semver]. This is described in further detail 261 in Section 5.2. 263 Each YANG package version, defines: 265 o some metadata about the package, e.g., description, tags, scoping, 266 referential completeness, location information. 268 o a set of YANG modules, at particular revisions, that are 269 implemented by servers that implement the package. The modules 270 may contain deviations. 272 o a set of import-only YANG modules, at particular revisions, that 273 are used 'import-only' by the servers that implement the package. 275 o a set of included YANG packages, at particular revisions, that are 276 also implemented by servers that implement the package. 278 o a set of YANG module features that must be supported by servers 279 that implement the package. 281 The structure for YANG package definitions uses existing YANG 282 language statements, YANG Data Structure Extensions 283 [I-D.ietf-netmod-yang-data-ext], and YANG Instance Data File Format 284 [I-D.ietf-netmod-yang-instance-file-format]. 286 YANG package definitions are available offline in YANG instance data 287 files. Client applications can be designed to support particular 288 package versions that they expect to interoperate with. 290 YANG package definitions are available from the server via 291 augmentations to YANG Library [RFC8525]. Rather than client 292 applications downloading the entire contents of YANG library to 293 confirm that the server schema is compatible with the client, they 294 can check, or download, a much shorter YANG package definition, and 295 validate that it conforms to the expected schema. 297 YANG package definitions can also be used to define the schema 298 associated with YANG instance data files holding other, e.g., non 299 packages related, instance data. 301 5.1. Package definition rules 303 Packages are defined using the following rules: 305 1. A YANG package MAY represent a complete YANG schema or only part 306 of a YANG schema with some module import dependencies missing, as 307 described in Section 5.4. 309 2. Packages definitions are hierarchical. A package can include 310 other packages. Only a single version of a package can be 311 included, and conflicting package includes (e.g. from descendant 312 package includes) MUST be explicitly resolved by indicating which 313 version takes precedence, and which versions are being replaced. 315 3. For each module implemented by a package, only a single revision 316 of that module MUST be implemented. Multiple revisions of a 317 module MAY be listed as import-only dependencies. 319 4. The revision of a module listed in the package 'module' list 320 supersedes any 'implemented' revision of the module listed in an 321 included package module list. The 'replaces-revision' leaf-list 322 is used to indicate which 'implemented' or 'import-only' module 323 revisions are replaces by this module revision. This allows a 324 package to explicitly resolve conflicts between implemented 325 module revisions in included packages. 327 5. The 'replaces-revision' leaf-list in the 'import-only-module' 328 list can be used to exclude duplicate revisions of import-only 329 modules from included packages. Otherwise, the import-only- 330 modules for a package are the import-only-modules from all 331 included packages combined with any modules listed in the 332 packages import-only-module list. 334 6. YANG packages definitions MAY include modules containing 335 deviation statements, but those deviation statements MUST only be 336 used in an RFC 7950 compatible way to indicate where a server, or 337 class of servers, deviates from a published standard. Deviations 338 MUST NOT be included in a package definition that is part of a 339 published standard. See section 5.8.1 for further guidance on 340 the use of deviations in YANG packages. 342 5.2. Package versioning 344 Individual versions of a YANG package are versioned using the 345 "revision-label" scheme defined in section 3.3 of 346 [I-D.ietf-netmod-yang-module-versioning]. 348 5.2.1. Updating a package with a new version 350 Package compatibility is fundamentally defined by how the YANG schema 351 between two package versions has changed. 353 When a package definition is updated, the version associated with the 354 package MUST be updated appropriately, taking into consideration the 355 scope of the changes as defined by the rules below. 357 A package definition SHOULD define the previous version of the 358 package in the 'previous-version' leaf unless it is the initial 359 version of the package. If the 'previous-version' leaf is provided 360 then the package definition MUST set the 'nbc-changes' leaf if the 361 new version is non-backwards-compatible with respect to the package 362 version defined in the 'previous-version' leaf. 364 5.2.1.1. Non-Backwards-compatible changes 366 The following changes classify as non-backwards-compatible changes to 367 a package definition: 369 o Changing an 'included-package' list entry to select a package 370 version that is non-backwards-compatible to the prior package 371 version, or removing a previously included package. 373 o Changing a 'module' or 'import-only-module' list entry to select a 374 module revision that is non-backwards-compatible to the prior 375 module revision, or removing a previously implemented module. 377 o Removing a feature from the 'mandatory-feature' leaf-list. 379 o Adding, changing, or removing a deviation that is considered a 380 non-backwards-compatible change to the affected data node in the 381 schema associated with the prior package version. 383 5.2.1.2. Backwards-compatible changes 385 The following changes classify as backwards-compatible changes to a 386 package definition: 388 o Changing an 'included-package' list entry to select a package 389 version that is backwards-compatible to the prior package version, 390 or including a new package that does not conflict with any 391 existing included package or module. 393 o Changing a 'module' or 'import-only-module' list entry to select a 394 module revision that is backwards-compatible to the prior module 395 revision, or including a new module to the package definition. 397 o Adding a feature to the 'mandatory-feature' leaf-list. 399 o Adding, changing, or removing a deviation that is considered a 400 backwards-compatible change to the affected data node in the 401 schema associated with the prior package version. 403 5.2.1.3. Editorial changes 405 The following changes classify as editorial changes to a package 406 definition: 408 o Changing a 'included-package' list entry to select a package 409 version that is classified as an editorial change relative to the 410 prior package version. 412 o Changing a 'module' or 'import-only-module' list entry to select a 413 module revision that is classified as an editorial change relative 414 to the prior module revision. 416 o Any change to any metadata associated with a package definition 417 that causes it to have a different checksum value. 419 5.2.2. YANG Semantic Versioning for packages 421 YANG Semantic Versioning [I-D.ietf-netmod-yang-semver] MAY be used as 422 an appropriate type of revision-label for the package version leaf. 424 If the format of the leaf matches the 'yangver:version' type 425 specified in ietf-yang-semver.yang, then the package version leaf 426 MUST be interpreted as a YANG semantic version number. 428 For YANG packages defined by the IETF, YANG semantic version numbers 429 MUST be used as the version scheme for YANG packages. 431 The rules for incrementing the YANG package version number are 432 equivalent to the semantic versioning rules used to version 433 individual YANG modules, defined in section 3.2 of 434 [I-D.ietf-netmod-yang-semver], but use the rules defined previously 435 in Section 5.2.1 to determine whether a change is classified as non- 436 backwards-compatible, backwards-compatible, or editorial. Where 437 available, the semantic version number of the referenced elements in 438 the package (included packages or modules) can be used to help 439 determine the scope of changes being made. 441 5.2.3. Revision history 443 YANG packages do not contain a revision history. This is because 444 packages may have many revisions and a long revision history would 445 bloat the package definition. By recursively examining the 446 'previous-version' leaf of a package definition, a full revision 447 history (including where non-backwards-compatible changes have 448 occurred) can be dynamically constructed, if all package versions are 449 available. 451 5.3. Package conformance 453 YANG packages allows for conformance to be checked at a package level 454 rather than requiring a client to download all modules, revisions, 455 and deviations from the server to ensure that the datastore schema 456 used by the server is compatible with the client. 458 YANG package conformance is analogous to how YANG [RFC7950] requires 459 that servers either implement a module faithfully, or otherwise use 460 deviations to indicate areas of non-conformance. 462 For a top level package representing a datastore schema, servers MUST 463 implement the package definition faithfully, including all mandatory 464 features. 466 Package definitions MAY modify the schema for directly or 467 hierarchically included packages through the use of different module 468 revisions or module deviations. If the schema of any included 469 package is modified in a non-backwards-compatible way then it MUST be 470 indicated by setting the 'nbc-modified' leaf to true. 472 5.3.1. Use of YANG semantic versioning 474 Using the YANG semantic versioning scheme for package version numbers 475 and module revision labels can help with conformance. In the general 476 case, clients should be able to determine the nature of changes 477 between two package versions by comparing the version number. 479 This usually means that a client does not have to be restricted to 480 working only with servers that advertise exactly the same version of 481 a package in YANG library. Instead, reasonable clients should be 482 able to interoperate with any server that supports a package version 483 that is backwards compatible to version that the client is designed 484 for, assuming that the client is designed to ignore operational 485 values for unknown data nodes. 487 For example, a client coded to support 'foo' package at version 1.0.0 488 should interoperate with a server implementing 'foo' package at 489 version 1.3.5, because the YANG semantic versioning rules require 490 that package version 1.3.5 is backwards compatible to version 1.0.0. 492 This also has a relevance on servers that are capable of supporting 493 version selection because they need not support every version of a 494 YANG package to ensure good client compatibility. Choosing suitable 495 minor versions within each major version number should generally be 496 sufficient, particular if they can avoid non-backwards-compatible 497 patch level changes. 499 5.3.2. Package checksums 501 Each YANG package definition may have a checksum associated with it 502 to allow a client to validate that the package definition of the 503 server matches the expected package definition without downloading 504 the full package definition from the server. 506 The checksum for a package is calculated using the SHA-256 hash (XXX, 507 reference) of the full file contents of the YANG package instance 508 data file. This means that the checksum includes all whitespace and 509 formatting, encoding, and all meta-data fields associated with the 510 package and the instance data file). 512 The checksum for a module is calculated using the SHA-256 hash of the 513 YANG module file definition. This means that the checksum includes 514 all whitespace, formatting, and comments within the YANG module. 516 Packages that are locally scoped to a server may not have an offline 517 instance data file available, and hence MAY not have a checksum. 519 The package definition allows URLs and checksums to be specified for 520 all included packages, modules and submodules within the package 521 definition. Checksums SHOULD be included in package definitions to 522 validate the full integrity of the package. 524 On a server, package checksums SHOULD also be provided for the top 525 level packages associated with the datastore schema. 527 5.3.3. The relationship between packages and datastores 529 As defined by NMDA [RFC8342], each datastore has an associated 530 datastore schema. Sections 5.1 and 5.3 of NMDA defines further 531 constraints on the schema associated with datastores. These 532 constraints can be summarized thus: 534 o The schema for all conventional datastores is the same. 536 o The schema for non conventional configuration datastores (e.g., 537 dynamic datastores) may completely differ (i.e. no overlap at all) 538 from the schema associated with the conventional configuration 539 datastores, or may partially or fully overlap with the schema of 540 the conventional configuration datastores. A dynamic datastore, 541 for example, may support different modules than conventional 542 datastores, or may support a subset or superset of modules, 543 features, or data nodes supported in the conventional 544 configuration datastores. Where a data node exists in multiple 545 datastore schema it has the same type, properties and semantics. 547 o The schema for the operational datastore is intended to be a 548 superset of all the configuration datastores (i.e. includes all 549 the schema nodes from the conventional configuration datastores), 550 but data nodes can be omitted if they cannot be accurately 551 reported. The operational datastore schema can include additional 552 modules containing only config false data nodes, but there is no 553 harm in including those modules in the configuration datastore 554 schema as well. 556 Given that YANG packages represent a YANG schema, it follows that 557 each datastore schema can be represented using packages. In 558 addition, the schema for most datastores on a server are often 559 closely related. Given that there are many ways that a datastore 560 schema could be represented using packages, the following guidance 561 provides a consistent approach to help clients understand the 562 relationship between the different datastore schema supported by a 563 device (e.g., which parts of the schema are common and which parts 564 have differences): 566 o Any datastores (e.g., conventional configuration datastores) that 567 have exactly the same datastore schema MUST use the same package 568 definitions. This is to avoid, for example, the creation of a 569 'running-cfg' package and a separate 'intended-cfg' package that 570 have identical schema. 572 o Common package definitions SHOULD be used for those parts of the 573 datastore schema that are common between datastores, when those 574 datastores do not share exactly the same datastore schema. E.g., 575 if a substantial part of the schema is common between the 576 conventional, dynamic, and operational datastores then a single 577 common package can be used to describe the common parts, along 578 with other packages to describe the unique parts of each datastore 579 schema. 581 o YANG modules that do not contain any configuration data nodes 582 SHOULD be included in the package for configuration datastores if 583 that helps unify the package definitions. 585 o The packages for the operational datastore schema MUST include all 586 packages for all configuration datastores, along with any required 587 modules defining deviations to mark unsupported data nodes. The 588 deviations MAY be defined directly in the packages defining the 589 operational datastore schema, or in separate non referentially 590 complete packages. 592 o The schema for a datastore MAY be represented using a single 593 package or as the union of a set of compatible packages, i.e., 594 equivalently to a set of non-conflicting packages being included 595 together in an overarching package definition. 597 5.4. Schema referential completeness 599 A YANG package may represent a schema that is 'referentially 600 complete', or 'referentially incomplete', indicated in the package 601 definition by the 'complete' flag. 603 If all import statements in all YANG modules included in the package 604 (either directly, or through included packages) can be resolved to a 605 module revision defined with the YANG package definition, then the 606 package is classified as referentially complete. Conversely, if one 607 or more import statements cannot be resolved to a module specified as 608 part of the package definition, then the package is classified as 609 referentially incomplete. 611 A package that represents the exact contents of a datastore schema 612 MUST always be referentially complete. 614 Referentially incomplete packages can be used, along with locally 615 scoped packages, to represent an update to a device's datastore 616 schema as part of an optional software hot fix. E.g., the base 617 software is made available as a complete globally scoped package. 618 The hot fix is made available as an incomplete globally scoped 619 package. A device's datastore schema can define a local package that 620 implements the base software package updated with the hot fix 621 package. 623 Referentially incomplete packages could also be used to group sets of 624 logically related modules together, but without requiring a fixed 625 dependency on all imported 'types' modules (e.g., iana-if- 626 types.yang), instead leaving the choice of specific revisions of 627 'types' modules to be resolved when the package definition is used. 629 5.5. Package name scoping and uniqueness 631 YANG package names can be globally unique, or locally scoped to a 632 particular server or device. 634 5.5.1. Globally scoped packages 636 The name given to a package MUST be globally unique, and it MUST 637 include an appropriate organization prefix in the name, equivalent to 638 YANG module naming conventions. 640 Ideally a YANG instance data file defining a particular package 641 version would be publicly available at one or more URLs. 643 5.5.2. Server scoped packages 645 Package definitions may be scoped to a particular server by setting 646 the 'is-local' leaf to true in the package definition. 648 Locally scoped packages MAY have a package name that is not globally 649 unique. 651 Locally scoped packages MAY have a definition that is not available 652 offline from the server in a YANG instance data file. 654 5.6. Submodules packages considerations 656 As defined in [RFC7950] and [I-D.ietf-netmod-yang-semver], YANG 657 conformance and versioning is specified in terms of particular 658 revisions of YANG modules rather than for individual submodules. 660 However, YANG package definitions also include the list of submodules 661 included by a module, primarily to provide a location of where the 662 submodule definition can be obtained from, allowing a YANG schema to 663 be fully constructed from a YANG package instance data file 664 definition. 666 5.7. Package tags 668 [I-D.ietf-netmod-module-tags] defines YANG module tags as a mechanism 669 to annotate a module definition with additional metadata. Tags MAY 670 also be associated to a package definition via the 'tags' leaf-list. 672 The tags use the same registry and definitions used by YANG module 673 tags. 675 5.8. YANG Package Usage Guidance 677 It is RECOMMENDED that organizations that publish YANG modules also 678 publish YANG package definition that group and version those modules 679 into units of related functionality. This increases 680 interoperability, by encouraging implementations to use the same 681 collections of YANG modules versions. Using packages also makes it 682 easier to understand relationship between modules, and enables 683 functionality to be described on a more abstract level than 684 individual modules. 686 5.8.1. Use of deviations in YANG packages 688 [RFC7950] section 5.6.3 defines deviations as the mechanism to allow 689 servers to indicate where they do not conform to a published YANG 690 module that is being implemented. 692 In cases where implementations contain deviations from published 693 packages, then those implementations SHOULD define a package that 694 includes both the published packages and all modules containing 695 deviations. This implementation specific package accurately reflects 696 the schema used by the device and allows clients to determine how the 697 implementation differs from the published package schema in an 698 offline consumable way, e.g., when published in an instance data file 699 (see section 6). 701 Organizations may wish to reuse YANG modules and YANG packages 702 published by other organizations for new functionality. Sometimes, 703 they may desire to modify the published YANG modules. However, they 704 MUST NOT use deviations in an attempt to achieve this because such 705 deviations cause two problems: 707 They prevent implementations from reporting their own deviations 708 for the same nodes. 710 They fracture the ecosystem by preventing implementations from 711 conforming to the standards specified by both organizations. This 712 hurts the interoperability in the YANG community, promotes 713 development of disconnected functional silos, and hurts creativity 714 in the market. 716 5.8.2. Use of features in YANG modules and YANG packages 718 The YANG language supports feature statements as the mechanism to 719 make parts of a schema optional. Published standard YANG modules 720 SHOULD make use of appropriate feature statements to provide 721 flexibility in how YANG modules may be used by implementations and 722 used by YANG modules published by other organizations. 724 YANG packages support 'mandatory features' which allow a package to 725 specify features that MUST be implemented by any conformant 726 implementation of the package as a mechanism to simplify and manage 727 the schema represented by a YANG package. 729 5.9. YANG package core definition 731 The ietf-yang-package-types.yang module defines a grouping to specify 732 the core elements of the YANG package structure that is used within 733 YANG package instance data files (ietf-yang-package-instance.yang) 734 and also on the server (ietf-yang-packages.yang). 736 The "ietf-yang-package-types" YANG module has the following 737 structure: 739 module: ietf-yang-package-types 741 grouping yang-pkg-identification-leafs 742 +-- name pkg-name 743 +-- version pkg-version 745 grouping yang-pkg-instance 746 +-- name pkg-name 747 +-- version pkg-version 748 +-- timestamp? yang:date-and-time 749 +-- organization? string 750 +-- contact? string 751 +-- description? string 752 +-- reference? string 753 +-- complete? boolean 754 +-- local? boolean 755 +-- previous-version? pkg-version 756 +-- nbc-changes? boolean 757 +-- tag* tags:tag 758 +-- mandatory-feature* scoped-feature 759 +-- included-package* [name version] 760 | +-- name pkg-name 761 | +-- version pkg-version 762 | +-- replaces-version* pkg-version 763 | +-- nbc-modified? boolean 764 | +-- location* inet:uri 765 | +-- checksum? pkg-types:sha-256-hash 766 +-- module* [name] 767 | +-- name yang:yang-identifier 768 | +-- revision? rev:revision-date-or-label 769 | +-- replaces-revision* rev:revision-date-or-label 770 | +-- namespace? inet:uri 771 | +-- location* inet:uri 772 | +-- checksum? pkg-types:sha-256-hash 773 | +-- submodule* [name] 774 | +-- name? yang:yang-identifier 775 | +-- revision yang:revision-identifier 776 | +-- location* inet:uri 777 | +-- checksum? pkg-types:sha-256-hash 778 +-- import-only-module* [name revision] 779 +-- name? yang:yang-identifier 780 +-- revision? rev:revision-date-or-label 781 +-- replaces-revision* rev:revision-date-or-label 782 +-- namespace? inet:uri 783 +-- location* inet:uri 784 +-- checksum? pkg-types:sha-256-hash 785 +-- submodule* [name] 786 +-- name? yang:yang-identifier 787 +-- revision yang:revision-identifier 788 +-- location* inet:uri 789 +-- checksum? pkg-types:sha-256-hash 791 6. Package Instance Data Files 793 YANG packages SHOULD be available offline from the server, defined as 794 YANG instance data files [I-D.ietf-netmod-yang-instance-file-format] 795 using the YANG schema below to define the package data. 797 The following rules apply to the format of the YANG package instance 798 files: 800 1. The file SHOULD be encoded in JSON. 802 2. The name of the file SHOULD follow the format "@.json". 805 3. The package name MUST be specified in both the instance-data-set 806 'name' and package 'name' leafs. 808 4. The 'description' field of the instance-data-set SHOULD be "YANG 809 package definition". 811 5. The 'timestamp', "organization', 'contact' fields are defined in 812 both the instance-data-set metadata and the YANG package 813 metadata. Package definitions SHOULD only define these fields as 814 part of the package definition. If any of these fields are 815 populated in the instance-data-set metadata then they MUST 816 contain the same value as the corresponding leaves in the package 817 definition. 819 6. The 'revision' list in the instance data file SHOULD NOT be used, 820 since versioning is handled by the package definition. 822 7. The instance data file for each version of a YANG package SHOULD 823 be made available at one of more locations accessible via URLs. 824 If one of the listed locations defines a definitive reference 825 implementation for the package definition then it MUST be listed 826 as the first entry in the list. 828 The "ietf-yang-package" YANG module has the following structure: 830 module: ietf-yang-package 832 structure package: 833 // Uses the yang-package-instance grouping defined in 834 // ietf-yang-package-types.yang 835 +-- name pkg-name 836 +-- version pkg-version 837 ... remainder of yang-package-instance grouping ... 839 7. Package Definitions on a Server 841 7.1. Package List 843 A top level 'packages' container holds the list of all versions of 844 all packages known to the server. Each list entry uses the common 845 package definition, but with the addition of package location and 846 checksum information that cannot be contained within a offline 847 package definition contained in an instance data file. 849 The '/packages/package' list MAY include multiple versions of a 850 particular package. E.g. if the server is capable of allowing 851 clients to select which package versions should be used by the 852 server. 854 7.2. Tree diagram 856 The "ietf-yang-packages" YANG module has the following structure: 858 module: ietf-yang-packages 859 +--ro packages 860 +--ro package* [name version] 861 // Uses the yang-package-instance grouping defined in 862 // ietf-yang-package-types.yang, with location and checksum: 863 +--ro name pkg-name 864 +--ro version pkg-version 865 ... remainder of yang-package-instance grouping ... 866 +--ro location* inet:uri 867 +--ro checksum? pkg-types:sha-256-hash 869 8. YANG Library Package Bindings 871 The YANG packages module also augments YANG library to allow a server 872 to optionally indicate that a datastore schema is defined by a 873 package, or a union of compatible packages. Since packages can 874 generally be made available offline in instance data files, it may be 875 sufficient for a client to only check that a compatible version of 876 the package is implemented by the server without fetching either the 877 package definition, or downloading and comparing the full list of 878 modules and enabled features. 880 If a server indicates that a datastore schema maps to a particular 881 package, then it MUST exactly match the schema defined by that 882 package, taking into account enabled features and any deviations. 884 If a server cannot faithfully implement a package then it can define 885 a new package to accurately report what it does implement. The new 886 package can include the original package as an included package, and 887 the new package can define additional modules containing deviations 888 to the modules in the original package, allowing the new package to 889 accurately describe the server's behavior. There is no specific 890 mechanism provided to indicate that a mandatory-feature in package 891 definition is not supported on a server, but deviations MAY be used 892 to disable functionality predicated by an if-feature statement. 894 The "ietf-yl-packages" YANG module has the following structure: 896 module: ietf-yl-packages 897 augment /yanglib:yang-library/yanglib:schema: 898 +--ro package* [name version] 899 +--ro name -> /pkgs:packages/package/name 900 +--ro version leafref 901 +--ro checksum? leafref 903 9. YANG packages as schema for YANG instance data document 905 YANG package definitions can be used as the schema definition for 906 YANG instance data files. When using a package schema, the name and 907 version of the package MUST be specified, a package checksum and/or 908 URL to the package definition MAY also be provided. 910 The "ietf-yang-inst-data-pkg" YANG module has the following 911 structure: 913 module: ietf-yang-inst-data-pkg 915 augment-structure /yid:instance-data-set/yid:content-schema-spec: 916 +--:(pkg-schema) 917 +-- pkg-schema 918 +-- name pkg-name 919 +-- version pkg-version 920 +-- location* inet:uri 921 +-- checksum? pkg-types:sha-256-hash 923 10. YANG Modules 925 The YANG module definitions for the modules described in the previous 926 sections. 928 file "ietf-yang-package-types@2020-01-21.yang" 929 module ietf-yang-package-types { 930 yang-version 1.1; 931 namespace "urn:ietf:params:xml:ns:yang:ietf-yang-package-types"; 932 prefix "pkg-types"; 934 import ietf-yang-revisions { 935 prefix rev; 936 reference "XXXX: Updated YANG Module Revision Handling"; 938 } 940 import ietf-yang-types { 941 prefix yang; 942 rev:revision-or-derived 2019-07-21; 943 reference "RFC 6991bis: Common YANG Data Types."; 944 } 946 import ietf-inet-types { 947 prefix inet; 948 rev:revision-or-derived 2013-07-15; 949 reference "RFC 6991: Common YANG Data Types."; 950 } 952 import ietf-module-tags { 953 prefix tags; 954 // RFC Ed. Fix revision once revision date of 955 // ietf-module-tags.yang is known. 956 reference "RFC XXX: YANG Module Tags."; 957 } 959 organization 960 "IETF NETMOD (Network Modeling) Working Group"; 962 contact 963 "WG Web: 964 WG List: 966 Author: Rob Wilton 967 "; 969 description 970 "This module provides type and grouping definitions for YANG 971 packages. 973 Copyright (c) 2019 IETF Trust and the persons identified as 974 authors of the code. All rights reserved. 976 Redistribution and use in source and binary forms, with or 977 without modification, is permitted pursuant to, and subject 978 to the license terms contained in, the Simplified BSD License 979 set forth in Section 4.c of the IETF Trust's Legal Provisions 980 Relating to IETF Documents 981 (http://trustee.ietf.org/license-info). 983 This version of this YANG module is part of RFC XXXX; see 984 the RFC itself for full legal notices. 986 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL 987 NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'NOT RECOMMENDED', 988 'MAY', and 'OPTIONAL' in this document are to be interpreted as 989 described in BCP 14 (RFC 2119) (RFC 8174) when, and only when, 990 they appear in all capitals, as shown here."; 992 // RFC Ed.: update the date below with the date of RFC publication 993 // and remove this note. 994 // RFC Ed.: replace XXXX with actual RFC number and remove this 995 // note. 996 revision 2020-01-21 { 997 rev:revision-label 0.2.0; 998 description 999 "Initial revision"; 1000 reference 1001 "RFC XXXX: YANG Packages"; 1002 } 1004 /* 1005 * Typedefs 1006 */ 1008 typedef pkg-name { 1009 type yang:yang-identifier; 1010 description 1011 "Package names are typed as YANG identifiers."; 1012 } 1014 typedef pkg-version { 1015 type rev:revision-date-or-label; 1016 description 1017 "Package versions SHOULD be a revision-label (e.g. perhaps a 1018 YANG Semver version string). Package versions MAY also be a 1019 revision-date"; 1021 } 1023 typedef pkg-identifier { 1024 type rev:name-revision; 1025 description 1026 "Package identifiers combine a pkg-name and a pkg-version"; 1027 } 1029 typedef scoped-feature { 1030 type string { 1031 pattern '[a-zA-Z_][a-zA-Z0-9\-_.]*:[a-zA-Z_][a-zA-Z0-9\-_.]*'; 1032 } 1033 description 1034 "Represents a feature name scoped to a particular module, 1035 identified as the ':', where both 1036 and are YANG identifier strings, 1037 as defiend by Section 12 or RFC 6020."; 1038 reference 1039 "RFC XXXX, YANG Packages."; 1040 } 1042 typedef sha-256-hash { 1043 type string { 1044 length "64"; 1045 pattern "[0-9a-fA-F]*"; 1046 } 1047 description 1048 "A SHA-256 hash represented as a hexadecimal string. 1050 Used as the checksum for modules, submodules and packages in a 1051 YANG package definition. 1053 For modules and submodules the SHA-256 hash is calculated on 1054 the contents of the YANG file defining the module/submodule. 1056 For packages the SHA-256 hash is calculated on the file 1057 containing the YANG instance data document holding the package 1058 definition"; 1059 } 1061 /* 1062 * Groupings 1063 */ 1064 grouping yang-pkg-identification-leafs { 1065 description 1066 "Parameters for identifying a specific version of a YANG 1067 package"; 1069 leaf name { 1070 type pkg-name; 1071 mandatory true; 1072 description 1073 "The YANG package name."; 1074 } 1076 leaf version { 1077 type pkg-version; 1078 mandatory true; 1079 description 1080 "Uniquely identies a particular version of a YANG package. 1082 Follows the definition for revision labels defined in 1083 draft-verdt-nemod-yang-module-versioning, section XXX"; 1084 } 1085 } 1087 grouping yang-pkg-instance { 1088 description 1089 "Specifies the data node for a full YANG package instance 1090 represented either on a server or as a YANG instance data 1091 document."; 1092 uses yang-pkg-identification-leafs; 1094 leaf timestamp { 1095 type yang:date-and-time; 1097 description 1098 "An optional timestamp for when this package was created. 1099 This does not need to be unique across all versions of a 1100 package."; 1101 } 1103 leaf organization { 1104 type string; 1106 description "Organization responsible for this package"; 1107 } 1109 leaf contact { 1110 type string; 1112 description 1113 "Contact information for the person or organization to whom 1114 queries concerning this package should be sent."; 1115 } 1117 leaf description { 1118 type string; 1120 description "Provides a description of the package"; 1121 } 1123 leaf reference { 1124 type string; 1126 description "Allows for a reference for the package"; 1127 } 1128 leaf complete { 1129 type boolean; 1130 default true; 1131 description 1132 "Indicates whether the schema defined by this package is 1133 referentially complete. I.e. all module imports can be 1134 resolved to a module explicitly defined in this package or 1135 one of the included packages."; 1136 } 1138 leaf local { 1139 type boolean; 1140 default false; 1141 description 1142 "Defines that the package definition is local to the server, 1143 and the name of the package MAY not be unique, and the 1144 package definition MAY not be available in an offline file. 1146 Local packages can be used when the schema for the device 1147 can be changed at runtime through the addition or removal of 1148 software packages, or hot fixes."; 1149 } 1151 leaf previous-version { 1152 type pkg-version; 1153 description 1154 "The previous package version that this version has been 1155 derived from. This leaf allows a full version history graph 1156 to be constructed if required."; 1157 } 1159 leaf nbc-changes { 1160 type boolean; 1161 default false; 1162 description 1163 "Indicates whether the defined package version contains 1164 non-backwards-compatible changes relative to the package 1165 version defined in the 'previous-version' leaf."; 1166 } 1168 leaf-list tag { 1169 type tags:tag; 1170 description 1171 "Tags associated with a YANG package. Module tags defined in 1172 XXX, ietf-netmod-module-tags can be used here but with the 1173 modification that the tag applies to the entire package 1174 rather than a specific module. See the IANA 'YANG Module 1175 Tag Prefix' registry for reserved prefixes and the IANA 1176 'YANG Module IETF Tag' registry for IETF standard tags."; 1177 } 1179 leaf-list mandatory-feature { 1180 type scoped-feature; 1181 description 1182 "Lists features from any modules included in the package that 1183 MUST be supported by any server implementing the package. 1185 Features already specified in a 'mandatory-feature' list of 1186 any included package MUST also be supported by server 1187 implementations and do not need to be repeated in this list. 1189 All other features defined in modules included in the 1190 package are OPTIONAL to implement. 1192 Features are identified using :"; 1193 } 1195 list included-package { 1196 key "name version"; 1197 description 1198 "An entry in this list represents a package that is included 1199 as part of the package definition, or an indirectly included 1200 package that is changed in a non backwards compatible way. 1202 It can be used to resolve inclusion of conflicting package 1203 versions by explicitly specifying which package version is 1204 used. 1206 If included packages implement different revisions or 1207 versions of the same module, then an explicit entry in the 1208 module list MUST be provided to select the specific module 1209 version 'implemented' by this package definition. 1211 If the schema for any packages that are included, either 1212 directly or indirectly via another package include, are 1213 changed in any non-backwards-compatible way then they MUST 1214 be explicitly listed in the included-packages list with the 1215 'nbc-modified' leaf set to true. 1217 For import-only modules, the 'replaces-revision' leaf-list 1218 can be used to select the specific module versions used by 1219 this package."; 1220 reference 1221 "XXX"; 1223 uses yang-pkg-identification-leafs; 1224 leaf-list replaces-version { 1225 type pkg-version; 1226 description 1227 "Gives the version of an included package version that 1228 is replaced by this included package revision."; 1229 } 1231 leaf nbc-modified { 1232 type boolean; 1233 default false; 1234 description 1235 "Set to true if any data nodes in this package are modified 1236 in a non backwards compatible way, either through the use 1237 of deviations, or because one of the modules has been 1238 replaced by an incompatible revision. This could also 1239 occur if a module's revision was replaced by an earlier 1240 revision that had the effect of removing some data 1241 nodes."; 1242 } 1244 leaf-list location { 1245 type inet:uri; 1246 description 1247 "Contains a URL that represents where an instance data file 1248 for this YANG package can be found. 1250 This leaf will only be present if there is a URL available 1251 for retrieval of the schema for this entry. 1253 If multiple locations are provided, then the first 1254 location in the leaf-list MUST be the definitive location 1255 that uniquely identifies this package"; 1256 } 1258 leaf checksum { 1259 type pkg-types:sha-256-hash; 1260 description 1261 "The SHA-256 hash calculated on the textual package 1262 definition, represented as a hexadecimal string."; 1263 } 1264 } 1266 list module { 1267 key "name"; 1268 description 1269 "An entry in this list represents a module that must be 1270 implemented by a server implementing this package, as per 1271 RFC 7950 section 5.6.5, with a particular set of supported 1272 features and deviations. 1274 A entry in this list overrides any module revision 1275 'implemented' by an included package. Any replaced module 1276 revision SHOULD also be listed in the 'replaces-revision' 1277 list."; 1278 reference 1279 "RFC 7950: The YANG 1.1 Data Modeling Language."; 1281 leaf name { 1282 type yang:yang-identifier; 1283 mandatory true; 1284 description 1285 "The YANG module name."; 1286 } 1288 leaf revision { 1289 type rev:revision-date-or-label; 1290 description 1291 "The YANG module revision date or revision-label. 1293 If no revision statement is present in the YANG module, 1294 this leaf is not instantiated."; 1295 } 1297 leaf-list replaces-revision { 1298 type rev:revision-date-or-label; 1299 description 1300 "Gives the revision of an module (implemented or 1301 import-only) defined in an included package that is 1302 replaced by this implemented module revision."; 1303 } 1305 leaf namespace { 1306 type inet:uri; 1307 description 1308 "The XML namespace identifier for this module."; 1309 } 1311 leaf-list location { 1312 type inet:uri; 1313 description 1314 "Contains a URL that represents the YANG schema resource 1315 for this module. 1317 This leaf will only be present if there is a URL available 1318 for retrieval of the schema for this entry."; 1319 } 1320 leaf checksum { 1321 type pkg-types:sha-256-hash; 1322 description 1323 "The SHA-256 hash calculated on the textual module 1324 definition, represented as a hexadecimal string."; 1325 } 1327 list submodule { 1328 key "name"; 1329 description 1330 "Each entry represents one submodule within the 1331 parent module."; 1333 leaf name { 1334 type yang:yang-identifier; 1335 description 1336 "The YANG submodule name."; 1337 } 1339 leaf revision { 1340 type yang:revision-identifier; 1341 mandatory true; 1342 description 1343 "The YANG submodule revision date. If the parent module 1344 include statement for this submodule includes a revision 1345 date then it MUST match this leaf's value."; 1346 } 1348 leaf-list location { 1349 type inet:uri; 1350 description 1351 "Contains a URL that represents the YANG schema resource 1352 for this submodule. 1354 This leaf will only be present if there is a URL 1355 available for retrieval of the schema for this entry."; 1356 } 1358 leaf checksum { 1359 type pkg-types:sha-256-hash; 1360 description 1361 "The SHA-256 hash calculated on the textual submodule 1362 definition, represented as a hexadecimal string."; 1363 } 1364 } 1365 } 1367 list import-only-module { 1368 key "name revision"; 1369 description 1370 "An entry in this list indicates that the server imports 1371 reusable definitions from the specified revision of the 1372 module, but does not implement any protocol accessible 1373 objects from this revision. 1375 Multiple entries for the same module name MAY exist. This 1376 can occur if multiple modules import the same module, but 1377 specify different revision-dates in the import statements."; 1379 leaf name { 1380 type yang:yang-identifier; 1381 description 1382 "The YANG module name."; 1383 } 1385 leaf revision { 1386 type rev:revision-date-or-label; 1387 description 1388 "The YANG module revision date or revision-label. 1390 If no revision statement is present in the YANG module, 1391 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."; 1417 } 1419 leaf checksum { 1420 type pkg-types:sha-256-hash; 1421 description 1422 "The SHA-256 hash calculated on the textual submodule 1423 definition, represented as a hexadecimal string."; 1424 } 1426 list submodule { 1427 key "name"; 1428 description 1429 "Each entry represents one submodule within the 1430 parent module."; 1432 leaf name { 1433 type yang:yang-identifier; 1434 description 1435 "The YANG submodule name."; 1436 } 1438 leaf revision { 1439 type yang:revision-identifier; 1440 mandatory true; 1441 description 1442 "The YANG submodule revision date. If the parent module 1443 include statement for this submodule includes a revision 1444 date then it MUST match this leaf's value."; 1445 } 1447 leaf-list location { 1448 type inet:uri; 1449 description 1450 "Contains a URL that represents the YANG schema resource 1451 for this submodule. 1453 This leaf will only be present if there is a URL 1454 available for retrieval of the schema for this entry."; 1455 } 1457 leaf checksum { 1458 type pkg-types:sha-256-hash; 1459 description 1460 "The SHA-256 hash calculated on the textual submodule 1461 definition, represented as a hexadecimal string."; 1462 } 1463 } 1464 } 1466 } 1467 } 1468 1470 file "ietf-yang-package-instance@2020-01-21.yang" 1471 module ietf-yang-package-instance { 1472 yang-version 1.1; 1473 namespace "urn:ietf:params:xml:ns:yang:ietf-yang-package-instance"; 1474 prefix pkg-inst; 1476 import ietf-yang-revisions { 1477 prefix rev; 1478 reference "XXXX: Updated YANG Module Revision Handling"; 1479 } 1481 import ietf-yang-package-types { 1482 prefix pkg-types; 1483 rev:revision-or-derived 0.2.0; 1484 reference "RFC XXX: YANG Schema Versioning."; 1485 } 1487 import ietf-yang-structure-ext { 1488 prefix sx; 1489 reference "RFC XXX: YANG Data Structure Extensions."; 1490 } 1492 organization 1493 "IETF NETMOD (Network Modeling) Working Group"; 1495 contact 1496 "WG Web: 1497 WG List: 1499 Author: Rob Wilton 1500 "; 1502 description 1503 "This module provides a definition of a YANG package, which is 1504 used as the schema for an YANG instance data document specifying 1505 a YANG package. 1507 Copyright (c) 2019 IETF Trust and the persons identified as 1508 authors of the code. All rights reserved. 1510 Redistribution and use in source and binary forms, with or 1511 without modification, is permitted pursuant to, and subject 1512 to the license terms contained in, the Simplified BSD License 1513 set forth in Section 4.c of the IETF Trust's Legal Provisions 1514 Relating to IETF Documents 1515 (http://trustee.ietf.org/license-info). 1517 This version of this YANG module is part of RFC XXXX; see 1518 the RFC itself for full legal notices. 1520 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL 1521 NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'NOT RECOMMENDED', 1522 'MAY', and 'OPTIONAL' in this document are to be interpreted as 1523 described in BCP 14 (RFC 2119) (RFC 8174) when, and only when, 1524 they appear in all capitals, as shown here."; 1526 // RFC Ed.: update the date below with the date of RFC publication 1527 // and remove this note. 1528 // RFC Ed.: replace XXXX with actual RFC number and remove this 1529 // note. 1530 revision 2020-01-21 { 1531 rev:revision-label 0.2.0; 1532 description 1533 "Initial revision"; 1534 reference 1535 "RFC XXXX: YANG Packages"; 1536 } 1538 /* 1539 * Top-level structure 1540 */ 1542 sx:structure package { 1543 description 1544 "Defines the YANG package structure for use in a YANG instance 1545 data document."; 1547 uses pkg-types:yang-pkg-instance; 1548 } 1549 } 1550 1552 file "ietf-yang-package@2020-01-21.yang" 1553 module ietf-yang-packages { 1554 yang-version 1.1; 1555 namespace "urn:ietf:params:xml:ns:yang:ietf-yang-packages"; 1556 prefix pkgs; 1557 import ietf-yang-revisions { 1558 prefix rev; 1559 reference "XXXX: Updated YANG Module Revision Handling"; 1560 } 1562 import ietf-yang-package-types { 1563 prefix pkg-types; 1564 rev:revision-or-derived 0.2.0; 1565 reference "RFC XXX: YANG Packages."; 1566 } 1568 import ietf-inet-types { 1569 prefix inet; 1570 rev:revision-or-derived 2013-07-15; 1571 reference "RFC 6991: Common YANG Data Types."; 1572 } 1574 organization 1575 "IETF NETMOD (Network Modeling) Working Group"; 1577 contact 1578 "WG Web: 1579 WG List: 1581 Author: Rob Wilton 1582 "; 1584 description 1585 "This module defines YANG packages on a server implementation. 1587 Copyright (c) 2018 IETF Trust and the persons identified as 1588 authors of the code. All rights reserved. 1590 Redistribution and use in source and binary forms, with or 1591 without modification, is permitted pursuant to, and subject 1592 to the license terms contained in, the Simplified BSD License 1593 set forth in Section 4.c of the IETF Trust's Legal Provisions 1594 Relating to IETF Documents 1595 (http://trustee.ietf.org/license-info). 1597 This version of this YANG module is part of RFC XXXX; see 1598 the RFC itself for full legal notices. 1600 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL 1601 NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'NOT RECOMMENDED', 1602 'MAY', and 'OPTIONAL' in this document are to be interpreted as 1603 described in BCP 14 (RFC 2119) (RFC 8174) when, and only when, 1604 they appear in all capitals, as shown here."; 1606 // RFC Ed.: update the date below with the date of RFC publication 1607 // and remove this note. 1608 // RFC Ed.: replace XXXX with actual RFC number and remove this 1609 // note. 1610 revision 2020-01-21 { 1611 rev:revision-label 0.2.0; 1612 description 1613 "Initial revision"; 1614 reference 1615 "RFC XXXX: YANG Packages"; 1616 } 1618 /* 1619 * Groupings 1620 */ 1622 grouping yang-pkg-ref { 1623 description 1624 "Defines the leaves used to reference a single YANG package"; 1626 leaf name { 1627 type leafref { 1628 path '/pkgs:packages/pkgs:package/pkgs:name'; 1629 } 1630 description 1631 "The name of the references package."; 1632 } 1634 leaf version { 1635 type leafref { 1636 path '/pkgs:packages' 1637 + '/pkgs:package[pkgs:name = current()/../name]' 1638 + '/pkgs:version'; 1639 } 1641 description 1642 "The version of the referenced package."; 1643 } 1645 leaf checksum { 1646 type leafref { 1647 path '/pkgs:packages' 1648 + '/pkgs:package[pkgs:name = current()/../name]' 1649 + '[pkgs:version = current()/../version]/pkgs:checksum'; 1650 } 1652 description 1653 "The checksum of the referenced package."; 1654 } 1655 } 1657 grouping yang-ds-pkg-ref { 1658 description 1659 "Defines the list used to reference a set of YANG packages that 1660 collectively represent a datastore schema."; 1662 list package { 1663 key "name version"; 1665 description 1666 "Identifies the YANG packages that collectively defines the 1667 schema for the associated datastore. 1669 The datastore schema is defined as the union of all 1670 referenced packages, that MUST represent a referentially 1671 complete schema. 1673 All of the referenced packages must be compatible with no 1674 conflicting module versions or dependencies."; 1676 uses yang-pkg-ref; 1677 } 1678 } 1680 /* 1681 * Top level data nodes. 1682 */ 1684 container packages { 1685 config false; 1686 description "All YANG package definitions"; 1688 list package { 1689 key "name version"; 1691 description 1692 "YANG package instance"; 1694 uses pkg-types:yang-pkg-instance; 1696 leaf-list location { 1697 type inet:uri; 1698 description 1699 "Contains a URL that represents where an instance data file 1700 for this YANG package can be found. 1702 This leaf will only be present if there is a URL available 1703 for retrieval of the schema for this entry. 1705 If multiple locations are provided, then the first 1706 location in the leaf-list MUST be the definitive location 1707 that uniquely identifies this package"; 1708 } 1710 leaf checksum { 1711 type pkg-types:sha-256-hash; 1712 description 1713 "The checksum of the package this schema relates to, 1714 calculated on the 'YANG instance data file' package 1715 definition available in the 'location' leaf list. 1717 This leaf MAY be omitted if the referenced package is 1718 locally scoped without an associated checksum."; 1719 } 1720 } 1721 } 1722 } 1723 1725 file "ietf-yl-package@2020-01-21.yang" 1726 module ietf-yl-packages { 1727 yang-version 1.1; 1728 namespace "urn:ietf:params:xml:ns:yang:ietf-yl-packages"; 1729 prefix yl-pkgs; 1731 import ietf-yang-revisions { 1732 prefix rev; 1733 reference "XXXX: Updated YANG Module Revision Handling"; 1734 } 1736 import ietf-yang-packages { 1737 prefix pkgs; 1738 rev:revision-or-derived 0.2.0; 1739 reference "RFC XXX: YANG Packages."; 1740 } 1742 import ietf-yang-library { 1743 prefix yanglib; 1744 rev:revision-or-derived 2019-01-04; 1745 reference "RFC 8525: YANG Library"; 1747 } 1749 organization 1750 "IETF NETMOD (Network Modeling) Working Group"; 1752 contact 1753 "WG Web: 1754 WG List: 1756 Author: Rob Wilton 1757 "; 1759 description 1760 "This module provides defined augmentations to YANG library to 1761 allow a server to report YANG package information. 1763 Copyright (c) 2018 IETF Trust and the persons identified as 1764 authors of the code. All rights reserved. 1766 Redistribution and use in source and binary forms, with or 1767 without modification, is permitted pursuant to, and subject 1768 to the license terms contained in, the Simplified BSD License 1769 set forth in Section 4.c of the IETF Trust's Legal Provisions 1770 Relating to IETF Documents 1771 (http://trustee.ietf.org/license-info). 1773 This version of this YANG module is part of RFC XXXX; see 1774 the RFC itself for full legal notices. 1776 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL 1777 NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'NOT RECOMMENDED', 1778 'MAY', and 'OPTIONAL' in this document are to be interpreted as 1779 described in BCP 14 (RFC 2119) (RFC 8174) when, and only when, 1780 they appear in all capitals, as shown here."; 1782 // RFC Ed.: update the date below with the date of RFC publication 1783 // and remove this note. 1784 // RFC Ed.: replace XXXX with actual RFC number and remove this 1785 // note. 1786 revision 2020-01-21 { 1787 rev:revision-label 0.2.0; 1788 description 1789 "Initial revision"; 1790 reference 1791 "RFC XXXX: YANG Packages"; 1792 } 1793 /* 1794 * Augmentations 1795 */ 1797 augment "/yanglib:yang-library/yanglib:schema" { 1798 description 1799 "Allow datastore schema to be related to a set of YANG 1800 packages"; 1802 uses pkgs:yang-ds-pkg-ref; 1803 } 1804 } 1805 1807 file "ietf-yang-inst-data-pkg@2020-01-21.yang" 1808 module ietf-yang-inst-data-pkg { 1809 yang-version 1.1; 1810 namespace "urn:ietf:params:xml:ns:yang:ietf-yang-inst-data-pkg"; 1811 prefix yid-pkg; 1813 import ietf-yang-revisions { 1814 prefix rev; 1815 reference "XXXX: Updated YANG Module Revision Handling"; 1816 } 1818 import ietf-yang-package-types { 1819 prefix pkg-types; 1820 rev:revision-or-derived 0.2.0; 1821 reference "RFC XXX: YANG Schema Versioning."; 1822 } 1824 import ietf-yang-structure-ext { 1825 prefix sx; 1826 reference "RFC XXX: YANG Data Structure Extensions."; 1827 } 1829 import ietf-yang-instance-data { 1830 prefix yid; 1831 reference "RFC XXX: YANG Instance Data File Format."; 1832 } 1834 import ietf-inet-types { 1835 prefix inet; 1836 reference "RFC 6991: Common YANG Data Types."; 1837 } 1838 organization 1839 "IETF NETMOD (Network Modeling) Working Group"; 1841 contact 1842 "WG Web: 1843 WG List: 1845 Author: Rob Wilton 1846 "; 1848 description 1849 "The module augments ietf-yang-instance-data to allow package 1850 definitions to be used to define schema in YANG instance data 1851 documents. 1853 Copyright (c) 2019 IETF Trust and the persons identified as 1854 authors of the code. All rights reserved. 1856 Redistribution and use in source and binary forms, with or 1857 without modification, is permitted pursuant to, and subject 1858 to the license terms contained in, the Simplified BSD License 1859 set forth in Section 4.c of the IETF Trust's Legal Provisions 1860 Relating to IETF Documents 1861 (http://trustee.ietf.org/license-info). 1863 This version of this YANG module is part of RFC XXXX; see 1864 the RFC itself for full legal notices. 1866 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL 1867 NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'NOT RECOMMENDED', 1868 'MAY', and 'OPTIONAL' in this document are to be interpreted as 1869 described in BCP 14 (RFC 2119) (RFC 8174) when, and only when, 1870 they appear in all capitals, as shown here."; 1872 // RFC Ed.: update the date below with the date of RFC publication 1873 // and remove this note. 1874 // RFC Ed.: replace XXXX with actual RFC number and remove this 1875 // note. 1876 revision 2020-01-21 { 1877 rev:revision-label 0.2.0; 1878 description 1879 "Initial revision"; 1880 reference 1881 "RFC XXXX: YANG Packages"; 1882 } 1884 /* 1885 * Augmentations 1886 */ 1888 sx:augment-structure 1889 "/yid:instance-data-set/yid:content-schema-spec" { 1890 description 1891 "Add package reference to instance data set schema 1892 specification"; 1893 case pkg-schema { 1894 container pkg-schema { 1895 uses pkg-types:yang-pkg-identification-leafs; 1897 leaf checksum { 1898 type pkg-types:sha-256-hash; 1899 description 1900 "The SHA-256 hash of the package, calculated on 1901 the textual package definition, represented as a 1902 hexadecimal string."; 1903 } 1905 leaf-list location { 1906 type inet:uri; 1907 description 1908 "Contains a URL that represents where an instance data 1909 file for this YANG package can be found. 1911 This leaf will only be present if there is a URL 1912 available for retrieval of the schema for this entry. 1914 If multiple locations are provided, then the first 1915 location in the leaf-list MUST be the definitive 1916 location that uniquely identifies this package"; 1917 } 1918 } 1919 } 1920 } 1921 } 1922 1924 11. Security Considerations 1926 The YANG modules specified in this document defines a schema for data 1927 that is accessed by network management protocols such as NETCONF 1928 [RFC6241] or RESTCONF [RFC8040]. The lowest NETCONF layer is the 1929 secure transport layer, and the mandatory-to-implement secure 1930 transport is Secure Shell (SSH) [RFC6242]. The lowest RESTCONF layer 1931 is HTTPS, and the mandatory-to-implement secure transport is TLS 1932 [RFC5246]. 1934 The NETCONF access control model [RFC6536] provides the means to 1935 restrict access for particular NETCONF or RESTCONF users to a 1936 preconfigured subset of all available NETCONF or RESTCONF protocol 1937 operations and content. 1939 Similarly to YANG library [I-D.ietf-netconf-rfc7895bis], some of the 1940 readable data nodes in these YANG modules may be considered sensitive 1941 or vulnerable in some network environments. It is thus important to 1942 control read access (e.g., via get, get-config, or notification) to 1943 these data nodes. 1945 One additional key different to YANG library, is that the 'ietf-yang- 1946 package' YANG module defines a schema to allow YANG packages to be 1947 defined in YANG instance data files, that are outside the security 1948 controls of the network management protocols. Hence, it is important 1949 to also consider controlling access to these package instance data 1950 files to restrict access to sensitive information. SHA-256 checksums 1951 are used to ensure the integrity of YANG package definitions, 1952 imported modules, and sub-modules. 1954 As per the YANG library security considerations, the module, revision 1955 and version information in YANG packages may help an attacker 1956 identify the server capabilities and server implementations with 1957 known bugs since the set of YANG modules supported by a server may 1958 reveal the kind of device and the manufacturer of the device. Server 1959 vulnerabilities may be specific to particular modules, module 1960 revisions, module features, or even module deviations. For example, 1961 if a particular operation on a particular data node is known to cause 1962 a server to crash or significantly degrade device performance, then 1963 the YANG packages information will help an attacker identify server 1964 implementations with such a defect, in order to launch a denial-of- 1965 service attack on the device. 1967 12. IANA Considerations 1969 It is expected that a central registry of standard YANG package 1970 definitions is required to support this solution. 1972 It is unclear whether an IANA registry is also required to manage 1973 specific package versions. It is highly desirable to have a specific 1974 canonical location, under IETF control, where the definitive YANG 1975 package versions can be obtained from. 1977 This document requests IANA to registers a URI in the "IETF XML 1978 Registry" [RFC3688]. Following the format in RFC 3688, the following 1979 registrations are requested. 1981 URI: urn:ietf:params:xml:ns:yang:ietf-yang-package-types.yang 1982 Registrant Contact: The IESG. 1983 XML: N/A, the requested URI is an XML namespace. 1985 URI: urn:ietf:params:xml:ns:yang:ietf-yang-package-instance.yang 1986 Registrant Contact: The IESG. 1987 XML: N/A, the requested URI is an XML namespace. 1989 URI: urn:ietf:params:xml:ns:yang:ietf-yang-packages.yang 1990 Registrant Contact: The IESG. 1991 XML: N/A, the requested URI is an XML namespace. 1993 URI: urn:ietf:params:xml:ns:yang:ietf-yl-packages.yang 1994 Registrant Contact: The IESG. 1995 XML: N/A, the requested URI is an XML namespace. 1997 URI: urn:ietf:params:xml:ns:yang:ietf-yang-inst-data-pkg.yang 1998 Registrant Contact: The IESG. 1999 XML: N/A, the requested URI is an XML namespace. 2001 This document requests that the following YANG modules are added in 2002 the "YANG Module Names" registry [RFC6020]: 2004 Name: ietf-yang-package-types.yang 2005 Namespace: urn:ietf:params:xml:ns:yang:ietf-yang-package- 2006 types.yang 2007 Prefix: pkg-types 2008 Reference: RFC XXXX 2010 Name: ietf-yang-package-instance.yang 2011 Namespace: urn:ietf:params:xml:ns:yang:ietf-yang-package- 2012 instance.yang 2013 Prefix: pkg-inst 2014 Reference: RFC XXXX 2016 Name: ietf-yang-packages.yang 2017 Namespace: urn:ietf:params:xml:ns:yang:ietf-yang-packages.yang 2018 Prefix: pkgs 2019 Reference: RFC XXXX 2021 Name: ietf-yl-packages.yang 2022 Namespace: urn:ietf:params:xml:ns:yang:ietf-yl-packages.yang 2023 Prefix: yl-pkgs 2024 Reference: RFC XXXX 2026 Name: ietf-yang-inst-data-pkg.yang 2027 Namespace: urn:ietf:params:xml:ns:yang:ietf-yang-inst-data- 2028 pkg.yang 2029 Prefix: yid-pkg 2030 Reference: RFC XXXX 2032 13. Open Questions/Issues 2034 All issues, along with the draft text, are currently being tracked at 2035 https://github.com/rgwilton/YANG-Packages-Draft/issues/ 2037 14. Acknowledgements 2039 Feedback helping shape this document has kindly been provided by Andy 2040 Bierman, James Cumming, Mahesh Jethanandani, Balazs Lengyel, Ladislav 2041 Lhotka,and Jan Lindblad. 2043 15. References 2045 15.1. Normative References 2047 [I-D.ietf-netconf-rfc7895bis] 2048 Bierman, A., Bjorklund, M., Schoenwaelder, J., Watsen, K., 2049 and R. Wilton, "YANG Library", draft-ietf-netconf- 2050 rfc7895bis-07 (work in progress), October 2018. 2052 [I-D.ietf-netmod-module-tags] 2053 Hopps, C., Berger, L., and D. Bogdanovic, "YANG Module 2054 Tags", draft-ietf-netmod-module-tags-10 (work in 2055 progress), February 2020. 2057 [I-D.ietf-netmod-yang-data-ext] 2058 Bierman, A., Bjorklund, M., and K. Watsen, "YANG Data 2059 Structure Extensions", draft-ietf-netmod-yang-data-ext-05 2060 (work in progress), December 2019. 2062 [I-D.ietf-netmod-yang-instance-file-format] 2063 Lengyel, B. and B. Claise, "YANG Instance Data File 2064 Format", draft-ietf-netmod-yang-instance-file-format-12 2065 (work in progress), April 2020. 2067 [I-D.ietf-netmod-yang-module-versioning] 2068 Wilton, R., Rahman, R., Lengyel, B., Clarke, J., Sterne, 2069 J., Claise, B., and K. D'Souza, "Updated YANG Module 2070 Revision Handling", draft-ietf-netmod-yang-module- 2071 versioning-01 (work in progress), July 2020. 2073 [I-D.ietf-netmod-yang-semver] 2074 Claise, B., Clarke, J., Rahman, R., Wilton, R., Lengyel, 2075 B., Sterne, J., and K. D'Souza, "YANG Semantic 2076 Versioning", draft-ietf-netmod-yang-semver-01 (work in 2077 progress), July 2020. 2079 [I-D.ietf-netmod-yang-solutions] 2080 Wilton, R., "YANG Versioning Solution Overview", draft- 2081 ietf-netmod-yang-solutions-00 (work in progress), March 2082 2020. 2084 [I-D.ietf-netmod-yang-ver-selection] 2085 Wilton, R., Rahman, R., Clarke, J., Sterne, J., and W. Bo, 2086 "YANG Schema Selection", draft-ietf-netmod-yang-ver- 2087 selection-00 (work in progress), March 2020. 2089 [I-D.ietf-netmod-yang-versioning-reqs] 2090 Clarke, J., "YANG Module Versioning Requirements", draft- 2091 ietf-netmod-yang-versioning-reqs-03 (work in progress), 2092 June 2020. 2094 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2095 Requirement Levels", BCP 14, RFC 2119, 2096 DOI 10.17487/RFC2119, March 1997, 2097 . 2099 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 2100 DOI 10.17487/RFC3688, January 2004, 2101 . 2103 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 2104 (TLS) Protocol Version 1.2", RFC 5246, 2105 DOI 10.17487/RFC5246, August 2008, 2106 . 2108 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 2109 the Network Configuration Protocol (NETCONF)", RFC 6020, 2110 DOI 10.17487/RFC6020, October 2010, 2111 . 2113 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 2114 and A. Bierman, Ed., "Network Configuration Protocol 2115 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 2116 . 2118 [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure 2119 Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011, 2120 . 2122 [RFC6536] Bierman, A. and M. Bjorklund, "Network Configuration 2123 Protocol (NETCONF) Access Control Model", RFC 6536, 2124 DOI 10.17487/RFC6536, March 2012, 2125 . 2127 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 2128 RFC 7950, DOI 10.17487/RFC7950, August 2016, 2129 . 2131 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 2132 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 2133 . 2135 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2136 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 2137 May 2017, . 2139 [RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 2140 and R. Wilton, "Network Management Datastore Architecture 2141 (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018, 2142 . 2144 [RFC8525] Bierman, A., Bjorklund, M., Schoenwaelder, J., Watsen, K., 2145 and R. Wilton, "YANG Library", RFC 8525, 2146 DOI 10.17487/RFC8525, March 2019, 2147 . 2149 15.2. Informative References 2151 [I-D.bierman-netmod-yang-package] 2152 Bierman, A., "The YANG Package Statement", draft-bierman- 2153 netmod-yang-package-00 (work in progress), July 2015. 2155 [I-D.ietf-netmod-artwork-folding] 2156 Watsen, K., Auerswald, E., Farrel, A., and Q. WU, 2157 "Handling Long Lines in Inclusions in Internet-Drafts and 2158 RFCs", draft-ietf-netmod-artwork-folding-12 (work in 2159 progress), January 2020. 2161 [openconfigsemver] 2162 "Semantic Versioning for OpenConfig Models", 2163 . 2165 [RFC8199] Bogdanovic, D., Claise, B., and C. Moberg, "YANG Module 2166 Classification", RFC 8199, DOI 10.17487/RFC8199, July 2167 2017, . 2169 Appendix A. Examples 2171 This section provides various examples of YANG packages, and as such 2172 this text is non-normative. The purpose of the examples is to only 2173 illustrate the file format of YANG packages, and how package 2174 dependencies work. It does not imply that such packages will be 2175 defined by IETF, or which modules would be included in those packages 2176 even if they were defined. For brevity, the examples exclude 2177 namespace declarations, and use a shortened URL of "tiny.cc/ietf- 2178 yang" as a replacement for 2179 "https://raw.githubusercontent.com/YangModels/yang/master/standard/ 2180 ietf/RFC". 2182 A.1. Example IETF Network Device YANG package 2184 This section provides an instance data file example of an IETF 2185 Network Device YANG package formatted in JSON. 2187 This example package is intended to represent the standard set of 2188 YANG modules, with import dependencies, to implement a basic network 2189 device without any dynamic routing or layer 2 services. E.g., it 2190 includes functionality such as system information, interface and 2191 basic IP configuration. 2193 As for all YANG packages, all import dependencies are fully resolved. 2194 Because this example uses YANG modules that have been standardized 2195 before YANG semantic versioning, they modules are referenced by 2196 revision date rather than version number. 2198 file "example-ietf-network-device-pkg.json" 2199 ========= NOTE: '\' line wrapping per BCP XX (RFC XXXX) =========== 2201 { 2202 "ietf-yang-instance-data:instance-data-set": { 2203 "name": "example-ietf-network-device-pkg", 2204 "pkg-schema": { 2205 package: "ietf-yang-package-defn-pkg@0.1.0.json" 2206 }, 2207 "description": "YANG package definition", 2208 "content-data": { 2209 "ietf-yang-package-instance:yang-package": { 2210 "name": "example-ietf-network-device-pkg", 2211 "version": "1.1.2", 2212 "timestamp": "2018-12-13T17:00:00Z", 2213 "organization": "IETF NETMOD Working Group", 2214 "contact" : "WG Web: , \ 2215 WG List: ", 2216 "description": "Example IETF network device YANG package.\ 2217 \ 2218 This package defines a small sample set of \ 2219 YANG modules that could represent the basic set of \ 2220 modules that a standard network device might be expected \ 2221 to support.", 2223 "reference": "XXX, draft-rwilton-netmod-yang-packages", 2224 "location": [ "file://example.org/yang/packages/\ 2225 ietf-network-device@v1.1.2.json" ], 2226 "module": [ 2227 { 2228 "name": "iana-crypt-hash", 2229 "revision": "2014-08-06", 2230 "location": [ "https://tiny.cc/ietf-yang/\ 2231 iana-crypt-hash%402014-08-06.yang" ], 2232 "checksum": "fa9fde408ddec2c16bf2c6b9e4c2f80b\ 2233 813a2f9e48c127016f3fa96da346e02d" 2234 }, 2235 { 2236 "name": "ietf-system", 2237 "revision": "2014-08-06", 2238 "location": [ "https://tiny.cc/ietf-yang/\ 2239 ietf-system%402014-08-06.yang" ], 2240 "checksum": "8a692ee2521b4ffe87a88303a61a1038\ 2241 79ee26bff050c1b05a2027ae23205d3f" 2242 }, 2243 { 2244 "name": "ietf-interfaces", 2245 "revision": "2018-02-20", 2246 "location": [ "https://tiny.cc/ietf-yang/\ 2247 ietf-interfaces%402018-02-20.yang" ], 2248 "checksum": "f6faea9938f0341ed48fda93dba9a69a\ 2249 a32ee7142c463342efec3d38f4eb3621" 2250 }, 2251 { 2252 "name": "ietf-netconf-acm", 2253 "revision": "2018-02-14", 2254 "location": [ "https://tiny.cc/ietf-yang/\ 2255 ietf-netconf-acm%402018-02-14.yang" ], 2256 "checksum": "e03f91317f9538a89296e99df3ff0c40\ 2257 03cdfea70bf517407643b3ec13c1ed25" 2258 }, 2259 { 2260 "name": "ietf-key-chain", 2261 "revision": "2017-06-15", 2262 "location": [ "https://tiny.cc/ietf-yang/\ 2263 ietf-key-chain@2017-06-15.yang" ], 2264 "checksum": "6250705f59fc9ad786e8d74172ce90d5\ 2265 8deec437982cbca7922af40b3ae8107c" 2266 }, 2267 { 2268 "name": "ietf-ip", 2269 "revision": "2018-02-22", 2270 "location": [ "https://tiny.cc/ietf-yang/\ 2271 ietf-ip%402018-02-22.yang" ], 2272 "checksum": "b624c84a66c128ae69ab107a5179ca8e\ 2273 20e693fb57dbe5cb56c3db2ebb18c894" 2274 } 2275 ], 2276 "import-only-module": [ 2277 { 2278 "name": "ietf-yang-types", 2279 "revision": "2013-07-15", 2280 "location": [ "https://tiny.cc/ietf-yang/\ 2281 ietf-yang-types%402013-07-15.yang" ], 2282 "checksum": "a04cdcc875764a76e89b7a0200c6b9d8\ 2283 00b10713978093acda7840c7c2907c3f" 2284 }, 2285 { 2286 "name": "ietf-inet-types", 2287 "revision": "2013-07-15", 2288 "location": [ "https://tiny.cc/ietf-yang/\ 2289 ietf-inet-types%402013-07-15.yang" ], 2290 "checksum": "12d98b0143a5ca5095b36420f9ebc1ff\ 2291 a61cfd2eaa850080244cadf01b86ddf9" 2292 } 2293 ] 2294 } 2295 } 2296 } 2297 } 2298 2300 A.2. Example IETF Basic Routing YANG package 2302 This section provides an instance data file example of a basic IETF 2303 Routing YANG package formatted in JSON. 2305 This example package is intended to represent the standard set of 2306 YANG modules, with import dependencies, that builds upon the example- 2307 ietf-network-device YANG package to add support for basic dynamic 2308 routing and ACLs. 2310 As for all YANG packages, all import dependencies are fully resolved. 2311 Because this example uses YANG modules that have been standardized 2312 before YANG semantic versioning, they modules are referenced by 2313 revision date rather than version number. Locations have been 2314 excluded where they are not currently known, e.g., for YANG modules 2315 defined in IETF drafts. In a normal YANG package, locations would be 2316 expected to be provided for all YANG modules. 2318 file "example-ietf-routing-pkg.json" 2319 ========== NOTE: '\' line wrapping per BCP XX (RFC XXXX) =========== 2321 { 2322 "ietf-yang-instance-data:instance-data-set": { 2323 "name": "example-ietf-routing-pkg", 2324 "module": [ "ietf-yang-package@2019-09-11.yang" ], 2325 "description": "YANG package definition", 2326 "content-data": { 2327 "ietf-yang-package-instance:yang-package": { 2328 "name": "example-ietf-routing", 2329 "version": "1.3.1", 2330 "timestamp": "2018-12-13T17:00:00Z", 2331 "description": "This package defines a small sample set of \ 2332 IETF routing YANG modules that could represent the set of \ 2333 IETF routing functionality that a basic IP network device \ 2334 might be expected to support.", 2335 "reference": "XXX, draft-rwilton-netmod-yang-packages", 2336 "imported-packages": [ 2337 { 2338 "name": "ietf-network-device", 2339 "version": "1.1.2", 2340 "location": [ "http://example.org/yang/packages/\ 2341 ietf-network-device@v1.1.2.json" ], 2342 "checksum": "" 2343 } 2344 ], 2345 "module": [ 2346 { 2347 "name": "ietf-routing", 2348 "revision": "2018-03-13", 2349 "location": [ "https://tiny.cc/ietf-yang/\ 2350 ietf-routing@2018-03-13.yang" ], 2351 "checksum": "" 2352 }, 2353 { 2354 "name": "ietf-ipv4-unicast-routing", 2355 "revision": "2018-03-13", 2356 "location": [ "https://tiny.cc/ietf-yang/\ 2357 ietf-ipv4-unicast-routing@2018-03-13.yang" ], 2358 "checksum": "" 2359 }, 2360 { 2361 "name": "ietf-ipv6-unicast-routing", 2362 "revision": "2018-03-13", 2363 "location": [ "https://tiny.cc/ietf-yang/\ 2364 ietf-ipv6-unicast-routing@2018-03-13.yang" ], 2365 "checksum": "" 2367 }, 2368 { 2369 "name": "ietf-isis", 2370 "revision": "2018-12-11", 2371 "location": [ "https://tiny.cc/ietf-yang/\ 2372 " ], 2373 "checksum": "" 2374 }, 2375 { 2376 "name": "ietf-interfaces-common", 2377 "revision": "2018-07-02", 2378 "location": [ "https://tiny.cc/ietf-yang/\ 2379 " ], 2380 "checksum": "" 2381 }, 2382 { 2383 "name": "ietf-if-l3-vlan", 2384 "revision": "2017-10-30", 2385 "location": [ "https://tiny.cc/ietf-yang/\ 2386 " ], 2387 "checksum": "" 2388 }, 2389 { 2390 "name": "ietf-routing-policy", 2391 "revision": "2018-10-19", 2392 "location": [ "https://tiny.cc/ietf-yang/\ 2393 " ], 2394 "checksum": "" 2395 }, 2396 { 2397 "name": "ietf-bgp", 2398 "revision": "2018-05-09", 2399 "location": [ "https://tiny.cc/ietf-yang/\ 2400 " ], 2401 "checksum": "" 2402 }, 2403 { 2404 "name": "ietf-access-control-list", 2405 "revision": "2018-11-06", 2406 "location": [ "https://tiny.cc/ietf-yang/\ 2407 " ], 2408 "checksum": "" 2409 } 2410 ], 2411 "import-only-module": [ 2412 { 2413 "name": "ietf-routing-types", 2414 "revision": "2017-12-04", 2415 "location": [ "https://tiny.cc/ietf-yang/\ 2416 ietf-routing-types@2017-12-04.yang" ], 2417 "checksum": "" 2418 }, 2419 { 2420 "name": "iana-routing-types", 2421 "revision": "2017-12-04", 2422 "location": [ "https://tiny.cc/ietf-yang/\ 2423 iana-routing-types@2017-12-04.yang" ], 2424 "checksum": "" 2425 }, 2426 { 2427 "name": "ietf-bgp-types", 2428 "revision": "2018-05-09", 2429 "location": [ "https://tiny.cc/ietf-yang/\ 2430 " ], 2431 "checksum": "" 2432 }, 2433 { 2434 "name": "ietf-packet-fields", 2435 "revision": "2018-11-06", 2436 "location": [ "https://tiny.cc/ietf-yang/\ 2437 " ], 2438 "checksum": "" 2439 }, 2440 { 2441 "name": "ietf-ethertypes", 2442 "revision": "2018-11-06", 2443 "location": [ "https://tiny.cc/ietf-yang/\ 2444 " ], 2445 "checksum": "" 2446 } 2447 ] 2448 } 2449 } 2450 } 2451 } 2452 2454 A.3. Package import conflict resolution example 2456 This section provides an example of how a package can resolve 2457 conflicting module versions from imported packages. 2459 In this example, YANG package 'example-3-pkg' imports both 'example- 2460 import-1' and 'example-import-2' packages. However, the two imported 2461 packages implement different versions of 'example-module-A' so the 2462 'example-3-pkg' package selects version '1.2.3' to resolve the 2463 conflict. Similarly, for import-only modules, the 'example-3-pkg' 2464 package does not require both versions of example-types-module-C to 2465 be imported, so it indicates that it only imports revision 2466 '2018-11-26' and not '2018-01-01'. 2468 { 2469 "ietf-yang-instance-data:instance-data-set": { 2470 "name": "example-import-1-pkg", 2471 "description": "First imported example package", 2472 "content-data": { 2473 "ietf-yang-package-instance:yang-package": { 2474 "name": "example-import-1", 2475 "version": "1.0.0", 2476 "reference": "XXX, draft-rwilton-netmod-yang-packages", 2477 "revision-date": "2018-01-01", 2478 "module": [ 2479 { 2480 "name": "example-module-A", 2481 "version": "1.0.0" 2482 }, 2483 { 2484 "name": "example-module-B", 2485 "version": "1.0.0" 2486 } 2487 ], 2488 "import-only-module": [ 2489 { 2490 "name": "example-types-module-C", 2491 "revision": "2018-01-01" 2492 }, 2493 { 2494 "name": "example-types-module-D", 2495 "revision": "2018-01-01" 2496 } 2497 ] 2498 } 2499 } 2500 } 2501 } 2503 { 2504 "ietf-yang-instance-data:instance-data-set": { 2505 "name": "example-import-2-pkg", 2506 "description": "Second imported example package", 2507 "content-data": { 2508 "ietf-yang-package:yang-package": { 2509 "name": "example-import-2", 2510 "version": "2.0.0", 2511 "reference": "XXX, draft-rwilton-netmod-yang-packages", 2512 "revision-date": "2018-11-26", 2513 "module": [ 2514 { 2515 "name": "example-module-A", 2516 "version": "1.2.3" 2517 }, 2518 { 2519 "name": "example-module-E", 2520 "version": "1.1.0" 2521 } 2522 ], 2523 "import-only-module": [ 2524 { 2525 "name": "example-types-module-C", 2526 "revision": "2018-11-26" 2527 }, 2528 { 2529 "name": "example-types-module-D", 2530 "revision": "2018-11-26" 2531 } 2532 ] 2533 } 2534 } 2535 } 2536 } 2538 { 2539 "ietf-yang-instance-data:instance-data-set": { 2540 "name": "example-3-pkg", 2541 "description": "Importing example package", 2542 "content-data": { 2543 "ietf-yang-package:yang-package": { 2544 "name": "example-3", 2545 "version": "1.0.0", 2546 "reference": "XXX, draft-rwilton-netmod-yang-packages", 2547 "revision-date": "2018-11-26", 2548 "included-package": [ 2549 { 2550 "name": "example-import-1", 2551 "version": "1.0.0" 2552 }, 2553 { 2554 "name": "example-import-2", 2555 "version": "2.0.0" 2556 } 2558 ], 2559 "module": [ 2560 { 2561 "name": "example-module-A", 2562 "version": "1.2.3" 2563 } 2564 ], 2565 "import-only-module": [ 2566 { 2567 "name": "example-types-module-C", 2568 "revision": "2018-11-26", 2569 "replaces-revision": [ "2018-01-01 "] 2570 } 2571 ] 2572 } 2573 } 2574 } 2575 } 2577 Appendix B. Possible alternative solutions 2579 This section briefly describes some alternative solutions. It can be 2580 removed if this document is adopted as a WG draft. 2582 B.1. Using module tags 2584 Module tags have been suggested as an alternative solution, and 2585 indeed that can address some of the same requirements as YANG 2586 packages but not all of them. 2588 Module tags can be used to group or organize YANG modules. However, 2589 this raises the question of where this tag information is stored. 2590 Module tags either require that the YANG module files themselves are 2591 updated with the module tag information (creating another versioning 2592 problem), or for the module tag information to be hosted elsewhere, 2593 perhaps in a centralize YANG Catalog, or in instance data files 2594 similar to how YANG packages have been defined in this draft. 2596 One of the principle aims of YANG packages is to be a versioned 2597 object that defines a precise set of YANG modules versions that work 2598 together. Module tags cannot meet this aim without an explosion of 2599 module tags definitions (i.e. a separate module tag must be defined 2600 for each package version). 2602 Module tags cannot support the hierachical scheme to construct YANG 2603 schema that is proposed in this draft. 2605 B.2. Using YANG library 2607 Another question is whether it is necessary to define new YANG 2608 modules to define YANG packages, and whether YANG library could just 2609 be reused in an instance data file. The use of YANG packages offers 2610 several benefits over just using YANG library: 2612 1. Packages allow schema to be built in a hierarchical fashion. 2613 [I-D.ietf-netconf-rfc7895bis] only allows one layer of hierarchy 2614 (using module sets), and there must be no conflicts between 2615 module revisions in different module-sets. 2617 2. Packages can be made available off the box, with a well defined 2618 unique name, avoiding the need for clients to download, and 2619 construct/check the entire YANG schema for each device. Instead 2620 they can rely on the named packages with secure checksums. YANG 2621 library's use of a 'content-id' is unique only to the device that 2622 generated them. 2624 3. Packages may be versioned using a semantic versioning scheme, 2625 YANG library does not provide a schema level semantic version 2626 number. 2628 4. For a YANG library instance data file to contain the necessary 2629 information, it probably needs both YANG library and various 2630 augmentations (e.g. to include each module's semantic version 2631 number), unless a new version of YANG library is defined 2632 containing this information. The module definition for a YANG 2633 package is specified to contain all of the ncessary information 2634 to solve the problem without augmentations 2636 5. YANG library is designed to publish information about the 2637 modules, datastores, and datastore schema used by a server. The 2638 information required to construct an off box schema is not 2639 precisely the same, and hence the definitions might deviate from 2640 each other over time. 2642 Authors' Addresses 2644 Robert Wilton (editor) 2645 Cisco Systems, Inc. 2647 Email: rwilton@cisco.com 2648 Reshad Rahman 2649 Cisco Systems, Inc. 2651 Email: rrahman@cisco.com 2653 Joe Clarke 2654 Cisco Systems, Inc. 2656 Email: jclarke@cisco.com 2658 Jason Sterne 2659 Nokia 2661 Email: jason.sterne@nokia.com 2663 Bo Wu (editor) 2664 Huawei 2666 Email: lana.wubo@huawei.com