idnits 2.17.1 draft-ietf-netmod-yang-packages-00.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 678 has weird spacing: '...version pkg...' == Line 710 has weird spacing: '...evision yan...' == Line 722 has weird spacing: '...evision yan...' -- The document date (March 17, 2020) is 1491 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 2089, but no explicit reference was found in the text == Unused Reference: 'RFC8199' is defined on line 2099, but no explicit reference was found in the text == Outdated reference: A later version (-21) exists of draft-ietf-netmod-yang-instance-file-format-08 ** Downref: Normative reference to an Informational draft: draft-verdt-netmod-yang-solutions (ref. 'I-D.verdt-netmod-yang-solutions') ** Downref: Normative reference to an Informational draft: draft-verdt-netmod-yang-versioning-reqs (ref. 'I-D.verdt-netmod-yang-versioning-reqs') ** Obsolete normative reference: RFC 5246 (Obsoleted by RFC 8446) ** Obsolete normative reference: RFC 6536 (Obsoleted by RFC 8341) Summary: 4 errors (**), 0 flaws (~~), 7 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: September 18, 2020 Cisco Systems, Inc. 6 J. Sterne 7 Nokia 8 B. Wu 9 Huawei 10 March 17, 2020 12 YANG Packages 13 draft-ietf-netmod-yang-packages-00 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 documents, and 21 can be used to define the schema associated with YANG instance data 22 documents. 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 September 18, 2020. 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 . . . . . . . . . . . . . . . . . . . 7 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 . . . . . . . . . . 8 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 . . 11 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 core definition . . . . . . . . . . . . . . 15 82 6. Package Instance Data Documents . . . . . . . . . . . . . . . 16 83 7. Package Definitions on a Server . . . . . . . . . . . . . . . 17 84 7.1. Package List . . . . . . . . . . . . . . . . . . . . . . 17 85 7.2. Tree diagram . . . . . . . . . . . . . . . . . . . . . . 17 86 8. YANG Library Package Bindings . . . . . . . . . . . . . . . . 18 87 9. YANG packages as schema for YANG instance data document . . . 19 88 10. YANG Modules . . . . . . . . . . . . . . . . . . . . . . . . 19 89 11. Security Considerations . . . . . . . . . . . . . . . . . . . 40 90 12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 41 91 13. Open Questions/Issues . . . . . . . . . . . . . . . . . . . . 43 92 14. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 43 93 15. References . . . . . . . . . . . . . . . . . . . . . . . . . 43 94 15.1. Normative References . . . . . . . . . . . . . . . . . . 43 95 15.2. Informative References . . . . . . . . . . . . . . . . . 45 96 Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 45 97 A.1. Example IETF Network Device YANG package . . . . . . . . 46 98 A.2. Example IETF Basic Routing YANG package . . . . . . . . . 48 99 A.3. Package import conflict resolution example . . . . . . . 51 100 Appendix B. Possible alternative solutions . . . . . . . . . . . 54 101 B.1. Using module tags . . . . . . . . . . . . . . . . . . . . 54 102 B.2. Using YANG library . . . . . . . . . . . . . . . . . . . 55 103 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 55 105 1. Terminology and Conventions 107 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 108 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 109 "OPTIONAL" in this document are to be interpreted as described in BCP 110 14 [RFC2119] [RFC8174] when, and only when, they appear in all 111 capitals, as shown here. 113 This document uses terminology introduced in the YANG versioning 114 requirements draft [I-D.verdt-netmod-yang-versioning-reqs]. 116 This document also makes of the following terminology introduced in 117 the Network Management Datastore Architecture [RFC8342]: 119 o datastore schema 121 This document also makes of the following terminology introduced in 122 the YANG 1.1 Data Modeling Language [RFC7950]: 124 o data node 126 In addition, this document defines the following terminology: 128 o YANG schema: A datastore schema, not bound to any particular 129 datastore. 131 o YANG package: An organizational structure holding a collection of 132 YANG modules related by some common purpose, normally defined in a 133 YANG instance data file. A YANG package defines a YANG schema by 134 specifying a set of YANG modules revisions, package versions, 135 mandatory features, and deviations. YANG packages are defined in 136 Section 5. 138 o backwards-compatible (BC) change: When used in the context of a 139 YANG module, it follows the definition in Section 3.1.1 of 140 [I-D.verdt-netmod-yang-module-versioning]. When used in the 141 context of a YANG package, it follows the definition in 142 Section 5.2.1.2. 144 o non-backwards-compatible (NBC) change: When used in the context of 145 a YANG module, it follows the definition in Section 3.1.2 of 146 [I-D.verdt-netmod-yang-module-versioning]. When used in the 147 context of a YANG package, it follows the definition in 148 Section 5.2.1.2. 150 o editorial change: When used in the context of a YANG module, it 151 follows the definition of an 'editorial change' in 3.2 of 152 [I-D.verdt-netmod-yang-semver]. When used in the context of a 153 YANG package, it follows the definition in Section 5.2.1.3. 155 2. Introduction 157 This document defines and describes the YANG [RFC7950] constructs 158 that are used to define and use YANG packages. 160 A YANG package is an organizational structure that groups a set of 161 YANG modules together into a consistent versioned definition to serve 162 a common purpose. For example, a YANG package could define the set 163 of YANG modules required to implement an L2VPN service on a network 164 device. YANG packages can themselves refer to, and reuse, other 165 package definitions. 167 Non-normative examples of YANG packages are provided in the 168 appendices. 170 3. Background on YANG packages 172 It has long been acknowledged within the YANG community that network 173 management using YANG requires a unit of organization and conformance 174 that is broader in scope than individual YANG modules. 176 'The YANG Package Statement' [I-D.bierman-netmod-yang-package] 177 proposed a YANG package mechanism based on new YANG language 178 statements, where a YANG package is defined in a file similar to how 179 YANG modules are defined, and would require enhancements to YANG 180 compilers to understand the new statements used to define packages. 182 OpenConfig [openconfigsemver] describes an approach to versioning 183 'bundle releases' based on git tags. I.e. a set of modules, at 184 particular versions, can be marked with the same release tag to 185 indicate that they are known to interoperate together. 187 The NETMOD WG in general, and the YANG versioning design team in 188 particular, are exploring solutions [I-D.verdt-netmod-yang-solutions] 189 to the YANG versioning requirements, 190 [I-D.verdt-netmod-yang-versioning-reqs]. Solutions to the versioning 191 requirements can be split into several distinct areas. 193 [I-D.verdt-netmod-yang-module-versioning] is focused on YANG 194 versioning scoped to individual modules. The overall solution must 195 also consider YANG versioning and conformance scoped to YANG schema. 196 YANG packages provide part of the solution for versioning YANG 197 schema. 199 4. Objectives 201 The main goals of YANG package definitions include, but are not 202 restricted to: 204 o To provide an alternative, simplified, YANG conformance mechanism. 205 Rather than conformance being performed against a set of 206 individual YANG module revisions, features, and deviations, 207 conformance can be more simply stated in terms of YANG packages, 208 with a set of modifications (e.g. additional modules, deviations, 209 or features). 211 o To allow YANG schema to be specified in a concise way rather than 212 having each server explicitly list all modules, revisions, and 213 features. YANG package definitions can be defined in documents 214 that are available offline, and accessible via a URL, rather than 215 requiring explicit lists of modules to be shared between client 216 and server. Hence, a YANG package must contain sufficient 217 information to allow a client or server to precisely construct the 218 schema associated with the package. 220 o To define a mainly linear versioned history of sets of modules 221 versions that are known to work together. I.e. to help mitigate 222 the problem where a client must manage devices from multiple 223 vendors, and vendor A implements version 1.0.0 of module foo and 224 version 2.0.0 of module bar, and vendor B implements version 2.0.0 225 of module foo and version 1.0.0 of module bar. For a client, 226 trying to interoperate with multiple vendors, and many YANG 227 modules, finding a consistent lowest common denominator set of 228 YANG module versions may be difficult, if not impossible. 230 Protocol mechanisms of how clients can negotiate which packages or 231 package versions are to be used for NETCONF/RESTCONF communications 232 are outside the scope of this document, and are defined in 233 [I-D.wilton-netmod-yang-ver-selection]. 235 Finally, the package definitions proposed by this document are 236 intended to be relatively basic in their definition and the 237 functionality that they support. As industry gains experience using 238 YANG packages, the standard YANG mechanisms of updating, or 239 augmenting, YANG modules could also be used to extend the 240 functionality supported by YANG packages, if required. 242 5. YANG Package Definition 244 This document specifies an approach to defining YANG packages that is 245 different to either of the approaches described in the background. 247 A YANG package is a versioned organizational structure defining a set 248 of related YANG modules, packages, features, and deviations. A YANG 249 package collectively defines a YANG schema. 251 Each YANG package has a name that SHOULD end with the suffix "-pkg". 252 Package names are normally expected to be globally unique, but in 253 some cases the package name may be locally scoped to a server or 254 device, as described in Section 5.5. 256 YANG packages are versioned using the same approaches described in 257 [I-D.verdt-netmod-yang-module-versioning] and 258 [I-D.verdt-netmod-yang-semver]. This is described in further detail 259 in Section 5.2. 261 Each YANG package version, defines: 263 some metadata about the package, e.g., description, tags, scoping, 264 referential completeness, location information. 266 a set of YANG modules, at particular revisions, that are 267 implemented by servers that implement the package. The modules 268 may contain deviations. 270 a set of import-only YANG modules, at particular revisions, that 271 are used 'import-only' by the servers that implement the package. 273 a set of included YANG packages, at particular revisions, that are 274 also implemented by servers that implement the package. 276 a set of YANG module features that must be supported by servers 277 that implement the package. 279 The structure for YANG package definitions uses existing YANG 280 language statements, YANG Data Structure Extensions 281 [I-D.ietf-netmod-yang-data-ext], and YANG Instance Data File Format 282 [I-D.ietf-netmod-yang-instance-file-format]. 284 YANG package definitions are available offline in YANG Instance Data 285 Documents. Client applications can be designed to support particular 286 package versions that they expect to interoperate with. 288 YANG package definitions are available from the server, via 289 augmentations to YANG Library [RFC8525]. Rather than client 290 applications downloading the entire contents of YANG library to 291 confirm that the server schema is compatible with the client, they 292 can check, or download, a much shorter YANG package definition, and 293 validate that it conforms to the expected schema. 295 YANG package definitions can also be used to define the schema 296 associated with YANG instance data documents holding other, e.g., non 297 packages related, instance data. 299 5.1. Package definition rules 301 The following rules define how packages are defined: 303 A YANG package MAY represent a complete YANG schema or only part 304 of a YANG schema with some module import dependencies missing, as 305 described in Section 5.4. 307 Packages definitions are hierarchical. A package can include 308 other packages. Only a single version of a package can be 309 included, and conflicting package includes (e.g. from descendant 310 package includes) MUST be explicitly resolved by indicating which 311 version takes precedence, and which versions are being replaced. 313 For each module implemented by a package, only a single revision 314 of that module MUST be implemented. Multiple revisions of a 315 module MAY be listed as import-only dependencies. 317 The revision of a module listed in the package 'module' list 318 supersedes any 'implemented' revision of the module listed in an 319 included package module list. The 'replaces-revision' leaf-list 320 is used to indicate which 'implemented' or 'import-only' module 321 revisions are replaces by this module revision. This allows a 322 package to explicitly resolve conflicts between implemented module 323 revisions in included packages. 325 The 'replaces-revision' leaf-list in the 'import-only-module' list 326 can be used to exclude duplicate revisions of import-only modules 327 from included packages. Otherwise, the import-only-modules for a 328 package are the import-only-modules from all included packages 329 combined with any modules listed in the packages import-only- 330 module list. 332 5.2. Package versioning 334 Individual versions of a YANG package are versioned using the 335 "revision-label" scheme defined in section 3.3 of 336 [I-D.verdt-netmod-yang-module-versioning]. 338 5.2.1. Updating a package with a new version 340 Package compatibility is fundamentally defined by how the YANG schema 341 between two package versions has changed. 343 When a package definition is updated, the version associated with the 344 package MUST be updated appropriately, taking into consideration the 345 scope of the changes as defined by the rules below. 347 A package definition SHOULD define the previous version of the 348 package in the 'previous-version' leaf unless it is the initial 349 version of the package. If the 'previous-version' leaf is provided 350 then the package definition MUST set the 'nbc-changes' leaf if the 351 new version is non-backwards-compatible with respect to the package 352 version defined in the 'previous-version' leaf. 354 5.2.1.1. Non-Backwards-compatible changes 356 The following changes classify as NBC changes to a package 357 definition: 359 Changing an 'included-package' list entry to select a package 360 version that is non-backwards-compatible to the prior package 361 version, or removing a previously included package. 363 Changing a 'module' or 'import-only-module' list entry to select a 364 module revision that is non-backwards-compatible to the prior 365 module revision, or removing a previously implemented module. 367 Removing a feature from the 'mandatory-feature' leaf-list. 369 Adding, changing, or removing a deviation that is considered a 370 non-backwards-compatible change to the affected data node in the 371 schema associated with the prior package version. 373 5.2.1.2. Backwards-compatible changes 375 The following changes classify as BC changes to a package definition: 377 Changing an 'included-package' list entry to select a package 378 version that is backwards-compatible to the prior package version, 379 or including a new package that does not conflict with any 380 existing included package or module. 382 Changing a 'module' or 'import-only-module' list entry to select a 383 module revision that is backwards-compatible to the prior module 384 revision, or including a new module to the package definition. 386 Adding a feature to the 'mandatory-feature' leaf-list. 388 Adding, changing, or removing a deviation that is considered a 389 backwards-compatible change to the affected data node in the 390 schema associated with the prior package version. 392 5.2.1.3. Editorial changes 394 The following changes classify as editorial changes to a package 395 definition: 397 Changing a 'included-package' list entry to select a package 398 version that is classified as an editorial change relative to the 399 prior package version. 401 Changing a 'module' or 'import-only-module' list entry to select a 402 module revision that is classified as an editorial change relative 403 to the prior module revision. 405 Any change to any metadata associated with a package definition 406 that causes it to have a different checksum value. 408 5.2.2. YANG Semantic Versioning for packages 410 YANG Semantic Versioning [I-D.verdt-netmod-yang-semver] MAY be used 411 as an appropriate type of revision-label for the package version 412 leaf. 414 If the format of the leaf matches the 'yangver:version' type 415 specified in ietf-yang-semver.yang, then the package version leaf 416 MUST be interpreted as a YANG semantic version number. 418 For YANG packages defined by the IETF, YANG semantic version numbers 419 MUST be used as the version scheme for YANG packages. 421 The rules for incrementing the YANG package version number are 422 equivalent to the semantic versioning rules used to version 423 individual YANG modules, defined in section 3.2 of 424 [I-D.verdt-netmod-yang-semver], but use the rules defined previously 425 in Section 5.2.1 to determine whether a change is classified as non- 426 backwards-compatible, backwards-compatible, or editorial. Where 427 available, the semantic version number of the referenced elements in 428 the package (included packages or modules) can be used to help 429 determine the scope of changes being made. 431 5.2.3. Revision history 433 YANG packages do not contain a revision history. This is because 434 packages may have many revisions and a long revision history would 435 bloat the package definition. By recursively examining the 436 'previous-version' leaf of a package definition, a full revision 437 history (including where non-backwards-compatible changes have 438 occurred) can be dynamically constructed, if all package versions are 439 available. 441 5.3. Package conformance 443 YANG packages allows for conformance to be checked at a package level 444 rather than requiring a client to download all modules, revisions, 445 and deviations from the server to ensure that the datastore schema 446 used by the server is compatible with the client. 448 YANG package conformance is analogous to how YANG [RFC7950] requires 449 that servers either implement a module faithfully, or otherwise use 450 deviations to indicate areas of non-conformance. 452 For a top level package representing a datastore schema, servers MUST 453 implement the package definition faithfully, including all mandatory 454 features. 456 Package definitions MAY modify the schema for directly or 457 hierarchically included packages through the use of different module 458 revisions or module deviations. If the schema of any included 459 package is modified in a non-backwards-compatible way then it MUST be 460 indicated by setting the 'nbc-modified' leaf to true. 462 5.3.1. Use of YANG semantic versioning 464 Using the YANG semantic versioning scheme for package version numbers 465 and module revision labels can help with conformance. In the general 466 case, clients should be able to determine the nature of changes 467 between two package versions by comparing the version number. 469 This usually means that a client does not have to be restricted to 470 working only with servers that advertise exactly the same version of 471 a package in YANG library. Instead, reasonable clients should be 472 able to interoperate with any server that supports a package version 473 that is backwards compatible to version that the client is designed 474 for, assuming that the client is designed to ignore operational 475 values for unknown data nodes. 477 For example, a client coded to support 'foo' package at version 1.0.0 478 should interoperate with a server implementing 'foo' package at 479 version 1.3.5, because the YANG semantic versioning rules require 480 that package version 1.3.5 is backwards compatible to version 1.0.0. 482 This also has a relevance on servers that are capable of supporting 483 version selection because they need not support every version of a 484 YANG package to ensure good client compatibility. Choosing suitable 485 minor versions within each major version number should generally be 486 sufficient, particular if they can avoid NBC patch level changes 487 (i.e. 'M' labeled versions). 489 5.3.2. Package checksums 491 Each YANG package definition may have a checksum associated with it 492 to allow a client to validate that the package definition of the 493 server matches the expected package definition without downloading 494 the full package definition from the server. 496 The checksum for a package is calculated using the SHA-256 hash (XXX, 497 reference) of the full file contents of the YANG package instance 498 data file. This means that the checksum includes all whitespace and 499 formatting, encoding, and all meta-data fields associated with the 500 package and the instance data document). 502 The checksum for a module is calculated using the SHA-256 hash of the 503 YANG module file definition. This means that the checksum includes 504 all whitespace, formatting, and comments within the YANG module. 506 Packages that are locally scoped to a server may not have an offline 507 instance data document available, and hence MAY not have a checksum. 509 The package definition allows URLs and checksums to be specified for 510 all included packages, modules and submodules within the package 511 definition. Checksums SHOULD be included in package definitions to 512 validate the full integrity of the package. 514 On a server, package checksums SHOULD also be provided for the top 515 level packages associated with the datastore schema. 517 5.3.3. The relationship between packages and datastores 519 As defined by NMDA [RFC8342], each datastore has an associated 520 datastore schema. Sections 5.1 and 5.3 of NMDA defines further 521 constraints on the schema associated with datastores. These 522 constraints can be summarized thus: 524 The schema for all conventional datastores is the same. 526 The schema for non conventional configuration datastores (e.g., 527 dynamic datastores) may completely differ (i.e. no overlap at all) 528 from the schema associated with the conventional configuration 529 datastores, or may partially or fully overlap with the schema of 530 the conventional configuration datastores. A dynamic datastore, 531 for example, may support different modules than conventional 532 datastores, or may support a subset or superset of modules, 533 features, or data nodes supported in the conventional 534 configuration datastores. Where a data node exists in multiple 535 datastore schema it has the same type, properties and semantics. 537 The schema for the operational datastore is intended to be a 538 superset of all the configuration datastores (i.e. includes all 539 the schema nodes from the conventional configuration datastores), 540 but data nodes can be omitted if they cannot be accurately 541 reported. The operational datastore schema can include additional 542 modules containing only config false data nodes, but there is no 543 harm in including those modules in the configuration datastore 544 schema as well. 546 Given that YANG packages represent a YANG schema, it follows that 547 each datastore schema can be represented using packages. In 548 addition, the schema for most datastores on a server are often 549 closely related. Given that there are many ways that a datastore 550 schema could be represented using packages, the following guidance 551 provides a consistent approach to help clients understand the 552 relationship between the different datastore schema supported by a 553 device (e.g., which parts of the schema are common and which parts 554 have differences): 556 Any datastores (e.g., conventional configuration datastores) that 557 have exactly the same datastore schema MUST use the same package 558 definitions. This is to avoid, for example, the creation of a 559 'running-cfg' package and a separate 'intended-cfg' package that 560 have identical schema. 562 Common package definitions SHOULD be used for those parts of the 563 datastore schema that are common between datastores, when those 564 datastores do not share exactly the same datastore schema. E.g., 565 if a substantial part of the schema is common between the 566 conventional, dynamic, and operational datastores then a single 567 common package can be used to describe the common parts, along 568 with other packages to describe the unique parts of each datastore 569 schema. 571 YANG modules that do not contain any configuration data nodes 572 SHOULD be included in the package for configuration datastores if 573 that helps unify the package definitions. 575 The packages for the operational datastore schema MUST include all 576 packages for all configuration datastores, along with any required 577 modules defining deviations to mark unsupported data nodes. The 578 deviations MAY be defined directly in the packages defining the 579 operational datastore schema, or in separate non referentially 580 complete packages. 582 The schema for a datastore MAY be represented using a single 583 package or as the union of a set of compatible packages, i.e., 584 equivalently to a set of non-conflicting packages being included 585 together in an overarching package definition. 587 5.4. Schema referential completeness 589 A YANG package may represent a schema that is 'referentially 590 complete', or 'referentially incomplete', indicated in the package 591 definition by the 'complete' flag. 593 If all import statements in all YANG modules included in the package 594 (either directly, or through included packages) can be resolved to a 595 module revision defined with the YANG package definition, then the 596 package is classified as referentially complete. Conversely, if one 597 or more import statements cannot be resolved to a module specified as 598 part of the package definition, then the package is classified as 599 referentially incomplete. 601 A package that represents the exact contents of a datastore schema 602 MUST always be referentially complete. 604 Referentially incomplete packages can be used, along with locally 605 scoped packages, to represent an update to a device's datastore 606 schema as part of an optional software hot fix. E.g., the base 607 software is made available as a complete globally scoped package. 608 The hot fix is made available as an incomplete globally scoped 609 package. A device's datastore schema can define a local package that 610 implements the base software package updated with the hot fix 611 package. 613 Referentially incomplete packages could also be used to group sets of 614 logically related modules together, but without requiring a fixed 615 dependency on all imported 'types' modules (e.g., iana-if- 616 types.yang), instead leaving the choice of specific revisions of 617 'types' modules to be resolved when the package definition is used. 619 5.5. Package name scoping and uniqueness 621 YANG package names can be globally unique, or locally scoped to a 622 particular server or device. 624 5.5.1. Globally scoped packages 626 The name given to a package MUST be globally unique, and it MUST 627 include an appropriate organization prefix in the name, equivalent to 628 YANG module naming conventions. 630 Ideally a YANG instance data document defining a particular package 631 version would be publicly available at one or more URLs. 633 5.5.2. Server scoped packages 635 Package definitions may be scoped to a particular server by setting 636 the 'is-local' leaf to true in the package definition. 638 Locally scoped packages MAY have a package name that is not globally 639 unique. 641 Locally scoped packages MAY have a definition that is not available 642 offline from the server in a YANG instance data document. 644 5.6. Submodules packages considerations 646 As defined in [RFC7950] and [I-D.verdt-netmod-yang-semver], YANG 647 conformance and versioning is specified in terms of particular 648 revisions of YANG modules rather than for individual submodules. 650 However, YANG package definitions also include the list of submodules 651 included by a module, primarily to provide a location of where the 652 submodule definition can be obtained from, allowing a YANG schema to 653 be fully constructed from a YANG package instance-data file 654 definition. 656 5.7. Package tags 658 [I-D.ietf-netmod-module-tags] defines YANG module tags as a mechanism 659 to annotate a module definition with additional metadata. Tags MAY 660 also be associated to a package definition via the 'tags' leaf-list. 661 The tags use the same registry and definitions used by YANG module 662 tags. 664 5.8. YANG package core definition 666 The ietf-yang-package-types.yang module defines a grouping to specify 667 the core elements of the YANG package structure that is used within 668 YANG package instance data documents (ietf-yang-package- 669 instance.yang) and also on the server (ietf-yang-packages.yang). 671 The "ietf-yang-package-types" YANG module has the following 672 structure: 674 module: ietf-yang-package-types 676 grouping yang-pkg-identification-leafs 677 +-- name pkg-name 678 +-- version pkg-version 680 grouping yang-pkg-instance 681 +-- name pkg-name 682 +-- version pkg-version 683 +-- timestamp? yang:date-and-time 684 +-- organization? string 685 +-- contact? string 686 +-- description? string 687 +-- reference? string 688 +-- complete? boolean 689 +-- local? boolean 690 +-- previous-version? pkg-version 691 +-- nbc-changes? boolean 692 +-- tag* tags:tag 693 +-- mandatory-feature* scoped-feature 694 +-- included-package* [name version] 695 | +-- name pkg-name 696 | +-- version pkg-version 697 | +-- replaces-version* pkg-version 698 | +-- nbc-modified? boolean 699 | +-- location* inet:uri 700 | +-- checksum? pkg-types:sha-256-hash 701 +-- module* [name] 702 | +-- name yang:yang-identifier 703 | +-- revision? rev:revision-date-or-label 704 | +-- replaces-revision* rev:revision-date-or-label 705 | +-- namespace? inet:uri 706 | +-- location* inet:uri 707 | +-- checksum? pkg-types:sha-256-hash 708 | +-- submodule* [name] 709 | +-- name? yang:yang-identifier 710 | +-- revision yang:revision-identifier 711 | +-- location* inet:uri 712 | +-- checksum? pkg-types:sha-256-hash 713 +-- import-only-module* [name revision] 714 +-- name? yang:yang-identifier 715 +-- revision? rev:revision-date-or-label 716 +-- replaces-revision* rev:revision-date-or-label 717 +-- namespace? inet:uri 718 +-- location* inet:uri 719 +-- checksum? pkg-types:sha-256-hash 720 +-- submodule* [name] 721 +-- name? yang:yang-identifier 722 +-- revision yang:revision-identifier 723 +-- location* inet:uri 724 +-- checksum? pkg-types:sha-256-hash 726 6. Package Instance Data Documents 728 YANG packages SHOULD be available offline from the server, defined as 729 YANG instance data documents 730 [I-D.ietf-netmod-yang-instance-file-format] using the YANG schema 731 below to define the package data. 733 The format of the YANG package instance file MUST follow the 734 following rules: 736 The file SHOULD be encoded in JSON. 738 The name of the file SHOULD follow the format "@.json". 741 The package name MUST be specified in both the instance-data-set 742 'name' and package 'name' leafs. 744 The 'description' field of the instance-data-set SHOULD be "YANG 745 package definition". 747 The 'timestamp', "organization', 'contact' fields are defined in 748 both the instance-data-set metadata and the YANG package metadata. 749 Package definitions SHOULD only define these fields as part of the 750 package definition. If any of these fields are populated in the 751 instance-data-set metadata then they MUST contain the same value 752 as the corresponding leaves in the package definition. 754 The 'revision' list in the instance data document SHOULD NOT be 755 used, since versioning is handled by the package definition. 757 The instance data document for each version of a YANG package 758 SHOULD be made available at one of more locations accessible via 759 URLs. If one of the listed locations defines a definitive 760 reference implementation for the package definition then it MUST 761 be listed as the first entry in the list. 763 The "ietf-yang-package" YANG module has the following structure: 765 module: ietf-yang-package 767 structure package: 768 // Uses the yang-package-instance grouping defined in 769 // ietf-yang-package-types.yang 770 +-- name pkg-name 771 +-- version pkg-version 772 ... remainder of yang-package-instance grouping ... 774 7. Package Definitions on a Server 776 7.1. Package List 778 A top level 'packages' container holds the list of all versions of 779 all packages known to the server. Each list entry uses the common 780 package definition, but with the addition of package location and 781 checksum information that cannot be contained within a offline 782 package definition contained in an instance data document. 784 The '/packages/package' list MAY include multiple versions of a 785 particular package. E.g. if the server is capable of allowing 786 clients to select which package versions should be used by the 787 server. 789 7.2. Tree diagram 790 The "ietf-yang-packages" YANG module has the following structure: 792 module: ietf-yang-packages 793 +--ro packages 794 +--ro package* [name version] 795 // Uses the yang-package-instance grouping defined in 796 // ietf-yang-package-types.yang, with location and checksum: 797 +--ro name pkg-name 798 +--ro version pkg-version 799 ... remainder of yang-package-instance grouping ... 800 +--ro location* inet:uri 801 +--ro checksum? pkg-types:sha-256-hash 803 8. YANG Library Package Bindings 805 The YANG packages module also augments YANG library to allow a server 806 to optionally indicate that a datastore schema is defined by a 807 package, or a union of compatible packages. Since packages can 808 generally be made available offline in instance data documents, it 809 may be sufficient for a client to only check that a compatible 810 version of the package is implemented by the server without fetching 811 either the package definition, or downloading and comparing the full 812 list of modules and enabled features. 814 If a server indicates that a datastore schema maps to a particular 815 package, then it MUST exactly match the schema defined by that 816 package, taking into account enabled features and any deviations. 818 If a server cannot faithfully implement a package then it can define 819 a new package to accurately report what it does implement. The new 820 package can include the original package as an included package, and 821 the new package can define additional modules containing deviations 822 to the modules in the original package, allowing the new package to 823 accurately describe the server's behavior. There is no specific 824 mechanism provided to indicate that a mandatory-feature in package 825 definition is not supported on a server, but deviations MAY be used 826 to disable functionality predicated by an if-feature statement. 828 The "ietf-yl-packages" YANG module has the following structure: 830 module: ietf-yl-packages 831 augment /yanglib:yang-library/yanglib:schema: 832 +--ro package* [name version] 833 +--ro name -> /pkgs:packages/package/name 834 +--ro version leafref 835 +--ro checksum? leafref 837 9. YANG packages as schema for YANG instance data document 839 YANG package definitions can be used as the schema definition for 840 YANG instance data documents. When using a package schema, the name 841 and version of the package MUST be specified, a package checksum and/ 842 or URL to the package definition MAY also be provided. 844 The "ietf-yang-inst-data-pkg" YANG module has the following 845 structure: 847 module: ietf-yang-inst-data-pkg 849 augment-structure /yid:instance-data-set/yid:content-schema-spec: 850 +--:(pkg-schema) 851 +-- pkg-schema 852 +-- name pkg-name 853 +-- version pkg-version 854 +-- location* inet:uri 855 +-- checksum? pkg-types:sha-256-hash 857 10. YANG Modules 859 The YANG module definitions for the modules described in the previous 860 sections. 862 file "ietf-yang-package-types@2020-01-21.yang" 863 module ietf-yang-package-types { 864 yang-version 1.1; 865 namespace "urn:ietf:params:xml:ns:yang:ietf-yang-package-types"; 866 prefix "pkg-types"; 868 import ietf-yang-revisions { 869 prefix rev; 870 reference "XXXX: Updated YANG Module Revision Handling"; 872 } 874 import ietf-yang-types { 875 prefix yang; 876 rev:revision-or-derived 2019-07-21; 877 reference "RFC 6991bis: Common YANG Data Types."; 878 } 880 import ietf-inet-types { 881 prefix inet; 882 rev:revision-or-derived 2013-07-15; 883 reference "RFC 6991: Common YANG Data Types."; 884 } 886 import ietf-module-tags { 887 prefix tags; 888 // RFC Ed. Fix revision once revision date of 889 // ietf-module-tags.yang is known. 890 reference "RFC XXX: YANG Module Tags."; 891 } 893 organization 894 "IETF NETMOD (Network Modeling) Working Group"; 896 contact 897 "WG Web: 898 WG List: 900 Author: Rob Wilton 901 "; 903 description 904 "This module provides type and grouping definitions for YANG 905 packages. 907 Copyright (c) 2019 IETF Trust and the persons identified as 908 authors of the code. All rights reserved. 910 Redistribution and use in source and binary forms, with or 911 without modification, is permitted pursuant to, and subject 912 to the license terms contained in, the Simplified BSD License 913 set forth in Section 4.c of the IETF Trust's Legal Provisions 914 Relating to IETF Documents 915 (http://trustee.ietf.org/license-info). 917 This version of this YANG module is part of RFC XXXX; see 918 the RFC itself for full legal notices. 920 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL 921 NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'NOT RECOMMENDED', 922 'MAY', and 'OPTIONAL' in this document are to be interpreted as 923 described in BCP 14 (RFC 2119) (RFC 8174) when, and only when, 924 they appear in all capitals, as shown here."; 926 // RFC Ed.: update the date below with the date of RFC publication 927 // and remove this note. 928 // RFC Ed.: replace XXXX with actual RFC number and remove this 929 // note. 930 revision 2020-01-21 { 931 rev:revision-label 0.2.0; 932 description 933 "Initial revision"; 934 reference 935 "RFC XXXX: YANG Packages"; 936 } 938 /* 939 * Typedefs 940 */ 942 typedef pkg-name { 943 type yang:yang-identifier; 944 description 945 "Package names are typed as YANG identifiers."; 946 } 948 typedef pkg-version { 949 type rev:revision-date-or-label; 950 description 951 "Package versions SHOULD be a revision-label (e.g. perhaps a 952 YANG Semver version string). Package versions MAY also be a 953 revision-date"; 955 } 957 typedef pkg-identifier { 958 type rev:name-revision; 959 description 960 "Package identifiers combine a pkg-name and a pkg-version"; 961 } 963 typedef scoped-feature { 964 type string { 965 pattern '[a-zA-Z_][a-zA-Z0-9\-_.]*:[a-zA-Z_][a-zA-Z0-9\-_.]*'; 966 } 967 description 968 "Represents a feature name scoped to a particular module, 969 identified as the ':', where both 970 and are YANG identifier strings, 971 as defiend by Section 12 or RFC 6020."; 972 reference 973 "RFC XXXX, YANG Packages."; 974 } 976 typedef sha-256-hash { 977 type string { 978 length "64"; 979 pattern "[0-9a-fA-F]*"; 980 } 981 description 982 "A SHA-256 hash represented as a hexadecimal string. 984 Used as the checksum for modules, submodules and packages in a 985 YANG package definition. 987 For modules and submodules the SHA-256 hash is calculated on 988 the contents of the YANG file defining the module/submodule. 990 For packages the SHA-256 hash is calculated on the file 991 containing the YANG instance data document holding the package 992 definition"; 993 } 995 /* 996 * Groupings 997 */ 998 grouping yang-pkg-identification-leafs { 999 description 1000 "Parameters for identifying a specific version of a YANG 1001 package"; 1003 leaf name { 1004 type pkg-name; 1005 mandatory true; 1006 description 1007 "The YANG package name."; 1008 } 1010 leaf version { 1011 type pkg-version; 1012 mandatory true; 1013 description 1014 "Uniquely identies a particular version of a YANG package. 1016 Follows the definition for revision labels defined in 1017 draft-verdt-nemod-yang-module-versioning, section XXX"; 1018 } 1019 } 1021 grouping yang-pkg-instance { 1022 description 1023 "Specifies the data node for a full YANG package instance 1024 represented either on a server or as a YANG instance data 1025 document."; 1026 uses yang-pkg-identification-leafs; 1028 leaf timestamp { 1029 type yang:date-and-time; 1031 description 1032 "An optional timestamp for when this package was created. 1033 This does not need to be unique across all versions of a 1034 package."; 1035 } 1037 leaf organization { 1038 type string; 1040 description "Organization responsible for this package"; 1041 } 1043 leaf contact { 1044 type string; 1046 description 1047 "Contact information for the person or organization to whom 1048 queries concerning this package should be sent."; 1049 } 1051 leaf description { 1052 type string; 1054 description "Provides a description of the package"; 1055 } 1057 leaf reference { 1058 type string; 1060 description "Allows for a reference for the package"; 1061 } 1062 leaf complete { 1063 type boolean; 1064 default true; 1065 description 1066 "Indicates whether the schema defined by this package is 1067 referentially complete. I.e. all module imports can be 1068 resolved to a module explicitly defined in this package or 1069 one of the included packages."; 1070 } 1072 leaf local { 1073 type boolean; 1074 default false; 1075 description 1076 "Defines that the package definition is local to the server, 1077 and the name of the package MAY not be unique, and the 1078 package definition MAY not be available in an offline file. 1080 Local packages can be used when the schema for the device 1081 can be changed at runtime through the addition or removal of 1082 software packages, or hot fixes."; 1083 } 1085 leaf previous-version { 1086 type pkg-version; 1087 description 1088 "The previous package version that this version has been 1089 derived from. This leaf allows a full version history graph 1090 to be constructed if required."; 1091 } 1093 leaf nbc-changes { 1094 type boolean; 1095 default false; 1096 description 1097 "Indicates whether the defined package version contains 1098 non-backwards-compatible changes relative to the package 1099 version defined in the 'previous-version' leaf."; 1100 } 1102 leaf-list tag { 1103 type tags:tag; 1104 description 1105 "Tags associated with a YANG package. Module tags defined in 1106 XXX, ietf-netmod-module-tags can be used here but with the 1107 modification that the tag applies to the entire package 1108 rather than a specific module. See the IANA 'YANG Module 1109 Tag Prefix' registry for reserved prefixes and the IANA 1110 'YANG Module IETF Tag' registry for IETF standard tags."; 1111 } 1113 leaf-list mandatory-feature { 1114 type scoped-feature; 1115 description 1116 "Lists features from any modules included in the package that 1117 MUST be supported by any server implementing the package. 1119 Features already specified in a 'mandatory-feature' list of 1120 any included package MUST also be supported by server 1121 implementations and do not need to be repeated in this list. 1123 All other features defined in modules included in the 1124 package are OPTIONAL to implement. 1126 Features are identified using :"; 1127 } 1129 list included-package { 1130 key "name version"; 1131 description 1132 "An entry in this list represents a package that is included 1133 as part of the package definition, or an indirectly included 1134 package that is changed in a non backwards compatible way. 1136 It can be used to resolve inclusion of conflicting package 1137 versions by explicitly specifying which package version is 1138 used. 1140 If included packages implement different revisions or 1141 versions of the same module, then an explicit entry in the 1142 module list MUST be provided to select the specific module 1143 version 'implemented' by this package definition. 1145 If the schema for any packages that are included, either 1146 directly or indirectly via another package include, are 1147 changed in any non-backwards-compatible way then they MUST 1148 be explicitly listed in the included-packages list with the 1149 'nbc-modified' leaf set to true. 1151 For import-only modules, the 'replaces-revision' leaf-list 1152 can be used to select the specific module versions used by 1153 this package."; 1154 reference 1155 "XXX"; 1157 uses yang-pkg-identification-leafs; 1158 leaf-list replaces-version { 1159 type pkg-version; 1160 description 1161 "Gives the version of an included package version that 1162 is replaced by this included package revision."; 1163 } 1165 leaf nbc-modified { 1166 type boolean; 1167 default false; 1168 description 1169 "Set to true if any data nodes in this package are modified 1170 in a non backwards compatible way, either through the use 1171 of deviations, or because one of the modules has been 1172 replaced by an incompatible revision. This could also 1173 occur if a module's revision was replaced by an earlier 1174 revision that had the effect of removing some data 1175 nodes."; 1176 } 1178 leaf-list location { 1179 type inet:uri; 1180 description 1181 "Contains a URL that represents where an instance data file 1182 for this YANG package can be found. 1184 This leaf will only be present if there is a URL available 1185 for retrieval of the schema for this entry. 1187 If multiple locations are provided, then the first 1188 location in the leaf-list MUST be the definitive location 1189 that uniquely identifies this package"; 1190 } 1192 leaf checksum { 1193 type pkg-types:sha-256-hash; 1194 description 1195 "The SHA-256 hash calculated on the textual package 1196 definition, represented as a hexadecimal string."; 1197 } 1198 } 1200 list module { 1201 key "name"; 1202 description 1203 "An entry in this list represents a module that must be 1204 implemented by a server implementing this package, as per 1205 RFC 7950 section 5.6.5, with a particular set of supported 1206 features and deviations. 1208 A entry in this list overrides any module revision 1209 'implemented' by an included package. Any replaced module 1210 revision SHOULD also be listed in the 'replaces-revision' 1211 list."; 1212 reference 1213 "RFC 7950: The YANG 1.1 Data Modeling Language."; 1215 leaf name { 1216 type yang:yang-identifier; 1217 mandatory true; 1218 description 1219 "The YANG module name."; 1220 } 1222 leaf revision { 1223 type rev:revision-date-or-label; 1224 description 1225 "The YANG module revision date or revision-label. 1227 If no revision statement is present in the YANG module, 1228 this leaf is not instantiated."; 1229 } 1231 leaf-list replaces-revision { 1232 type rev:revision-date-or-label; 1233 description 1234 "Gives the revision of an module (implemented or 1235 import-only) defined in an included package that is 1236 replaced by this implemented module revision."; 1237 } 1239 leaf namespace { 1240 type inet:uri; 1241 description 1242 "The XML namespace identifier for this module."; 1243 } 1245 leaf-list location { 1246 type inet:uri; 1247 description 1248 "Contains a URL that represents the YANG schema resource 1249 for this module. 1251 This leaf will only be present if there is a URL available 1252 for retrieval of the schema for this entry."; 1253 } 1254 leaf checksum { 1255 type pkg-types:sha-256-hash; 1256 description 1257 "The SHA-256 hash calculated on the textual module 1258 definition, represented as a hexadecimal string."; 1259 } 1261 list submodule { 1262 key "name"; 1263 description 1264 "Each entry represents one submodule within the 1265 parent module."; 1267 leaf name { 1268 type yang:yang-identifier; 1269 description 1270 "The YANG submodule name."; 1271 } 1273 leaf revision { 1274 type yang:revision-identifier; 1275 mandatory true; 1276 description 1277 "The YANG submodule revision date. If the parent module 1278 include statement for this submodule includes a revision 1279 date then it MUST match this leaf's value."; 1280 } 1282 leaf-list location { 1283 type inet:uri; 1284 description 1285 "Contains a URL that represents the YANG schema resource 1286 for this submodule. 1288 This leaf will only be present if there is a URL 1289 available for retrieval of the schema for this entry."; 1290 } 1292 leaf checksum { 1293 type pkg-types:sha-256-hash; 1294 description 1295 "The SHA-256 hash calculated on the textual submodule 1296 definition, represented as a hexadecimal string."; 1297 } 1298 } 1299 } 1301 list import-only-module { 1302 key "name revision"; 1303 description 1304 "An entry in this list indicates that the server imports 1305 reusable definitions from the specified revision of the 1306 module, but does not implement any protocol accessible 1307 objects from this revision. 1309 Multiple entries for the same module name MAY exist. This 1310 can occur if multiple modules import the same module, but 1311 specify different revision-dates in the import statements."; 1313 leaf name { 1314 type yang:yang-identifier; 1315 description 1316 "The YANG module name."; 1317 } 1319 leaf revision { 1320 type rev:revision-date-or-label; 1321 description 1322 "The YANG module revision date or revision-label. 1324 If no revision statement is present in the YANG module, 1325 this leaf is not instantiated."; 1326 } 1328 leaf-list replaces-revision { 1329 type rev:revision-date-or-label; 1330 description 1331 "Gives the revision of an import-only-module defined in an 1332 included package that is replaced by this 1333 import-only-module revision."; 1334 } 1336 leaf namespace { 1337 type inet:uri; 1338 description 1339 "The XML namespace identifier for this module."; 1340 } 1342 leaf-list location { 1343 type inet:uri; 1344 description 1345 "Contains a URL that represents the YANG schema resource 1346 for this module. 1348 This leaf will only be present if there is a URL available 1349 for retrieval of the schema for this entry."; 1351 } 1353 leaf checksum { 1354 type pkg-types:sha-256-hash; 1355 description 1356 "The SHA-256 hash calculated on the textual submodule 1357 definition, represented as a hexadecimal string."; 1358 } 1360 list submodule { 1361 key "name"; 1362 description 1363 "Each entry represents one submodule within the 1364 parent module."; 1366 leaf name { 1367 type yang:yang-identifier; 1368 description 1369 "The YANG submodule name."; 1370 } 1372 leaf revision { 1373 type yang:revision-identifier; 1374 mandatory true; 1375 description 1376 "The YANG submodule revision date. If the parent module 1377 include statement for this submodule includes a revision 1378 date then it MUST match this leaf's value."; 1379 } 1381 leaf-list location { 1382 type inet:uri; 1383 description 1384 "Contains a URL that represents the YANG schema resource 1385 for this submodule. 1387 This leaf will only be present if there is a URL 1388 available for retrieval of the schema for this entry."; 1389 } 1391 leaf checksum { 1392 type pkg-types:sha-256-hash; 1393 description 1394 "The SHA-256 hash calculated on the textual submodule 1395 definition, represented as a hexadecimal string."; 1396 } 1397 } 1398 } 1400 } 1401 } 1402 1404 file "ietf-yang-package-instance@2020-01-21.yang" 1405 module ietf-yang-package-instance { 1406 yang-version 1.1; 1407 namespace "urn:ietf:params:xml:ns:yang:ietf-yang-package-instance"; 1408 prefix pkg-inst; 1410 import ietf-yang-revisions { 1411 prefix rev; 1412 reference "XXXX: Updated YANG Module Revision Handling"; 1413 } 1415 import ietf-yang-package-types { 1416 prefix pkg-types; 1417 rev:revision-or-derived 0.2.0; 1418 reference "RFC XXX: YANG Schema Versioning."; 1419 } 1421 import ietf-yang-structure-ext { 1422 prefix sx; 1423 reference "RFC XXX: YANG Data Structure Extensions."; 1424 } 1426 organization 1427 "IETF NETMOD (Network Modeling) Working Group"; 1429 contact 1430 "WG Web: 1431 WG List: 1433 Author: Rob Wilton 1434 "; 1436 description 1437 "This module provides a definition of a YANG package, which is 1438 used as the schema for an YANG instance data document specifying 1439 a YANG package. 1441 Copyright (c) 2019 IETF Trust and the persons identified as 1442 authors of the code. All rights reserved. 1444 Redistribution and use in source and binary forms, with or 1445 without modification, is permitted pursuant to, and subject 1446 to the license terms contained in, the Simplified BSD License 1447 set forth in Section 4.c of the IETF Trust's Legal Provisions 1448 Relating to IETF Documents 1449 (http://trustee.ietf.org/license-info). 1451 This version of this YANG module is part of RFC XXXX; see 1452 the RFC itself for full legal notices. 1454 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL 1455 NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'NOT RECOMMENDED', 1456 'MAY', and 'OPTIONAL' in this document are to be interpreted as 1457 described in BCP 14 (RFC 2119) (RFC 8174) when, and only when, 1458 they appear in all capitals, as shown here."; 1460 // RFC Ed.: update the date below with the date of RFC publication 1461 // and remove this note. 1462 // RFC Ed.: replace XXXX with actual RFC number and remove this 1463 // note. 1464 revision 2020-01-21 { 1465 rev:revision-label 0.2.0; 1466 description 1467 "Initial revision"; 1468 reference 1469 "RFC XXXX: YANG Packages"; 1470 } 1472 /* 1473 * Top-level structure 1474 */ 1476 sx:structure package { 1477 description 1478 "Defines the YANG package structure for use in a YANG instance 1479 data document."; 1481 uses pkg-types:yang-pkg-instance; 1482 } 1483 } 1484 1486 file "ietf-yang-package@2020-01-21.yang" 1487 module ietf-yang-packages { 1488 yang-version 1.1; 1489 namespace "urn:ietf:params:xml:ns:yang:ietf-yang-packages"; 1490 prefix pkgs; 1491 import ietf-yang-revisions { 1492 prefix rev; 1493 reference "XXXX: Updated YANG Module Revision Handling"; 1494 } 1496 import ietf-yang-package-types { 1497 prefix pkg-types; 1498 rev:revision-or-derived 0.2.0; 1499 reference "RFC XXX: YANG Packages."; 1500 } 1502 import ietf-inet-types { 1503 prefix inet; 1504 rev:revision-or-derived 2013-07-15; 1505 reference "RFC 6991: Common YANG Data Types."; 1506 } 1508 organization 1509 "IETF NETMOD (Network Modeling) Working Group"; 1511 contact 1512 "WG Web: 1513 WG List: 1515 Author: Rob Wilton 1516 "; 1518 description 1519 "This module defines YANG packages on a server implementation. 1521 Copyright (c) 2018 IETF Trust and the persons identified as 1522 authors of the code. All rights reserved. 1524 Redistribution and use in source and binary forms, with or 1525 without modification, is permitted pursuant to, and subject 1526 to the license terms contained in, the Simplified BSD License 1527 set forth in Section 4.c of the IETF Trust's Legal Provisions 1528 Relating to IETF Documents 1529 (http://trustee.ietf.org/license-info). 1531 This version of this YANG module is part of RFC XXXX; see 1532 the RFC itself for full legal notices. 1534 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL 1535 NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'NOT RECOMMENDED', 1536 'MAY', and 'OPTIONAL' in this document are to be interpreted as 1537 described in BCP 14 (RFC 2119) (RFC 8174) when, and only when, 1538 they appear in all capitals, as shown here."; 1540 // RFC Ed.: update the date below with the date of RFC publication 1541 // and remove this note. 1542 // RFC Ed.: replace XXXX with actual RFC number and remove this 1543 // note. 1544 revision 2020-01-21 { 1545 rev:revision-label 0.2.0; 1546 description 1547 "Initial revision"; 1548 reference 1549 "RFC XXXX: YANG Packages"; 1550 } 1552 /* 1553 * Groupings 1554 */ 1556 grouping yang-pkg-ref { 1557 description 1558 "Defines the leaves used to reference a single YANG package"; 1560 leaf name { 1561 type leafref { 1562 path '/pkgs:packages/pkgs:package/pkgs:name'; 1563 } 1564 description 1565 "The name of the references package."; 1566 } 1568 leaf version { 1569 type leafref { 1570 path '/pkgs:packages' 1571 + '/pkgs:package[pkgs:name = current()/../name]' 1572 + '/pkgs:version'; 1573 } 1575 description 1576 "The version of the referenced package."; 1577 } 1579 leaf checksum { 1580 type leafref { 1581 path '/pkgs:packages' 1582 + '/pkgs:package[pkgs:name = current()/../name]' 1583 + '[pkgs:version = current()/../version]/pkgs:checksum'; 1584 } 1586 description 1587 "The checksum of the referenced package."; 1588 } 1589 } 1591 grouping yang-ds-pkg-ref { 1592 description 1593 "Defines the list used to reference a set of YANG packages that 1594 collectively represent a datastore schema."; 1596 list package { 1597 key "name version"; 1599 description 1600 "Identifies the YANG packages that collectively defines the 1601 schema for the associated datastore. 1603 The datastore schema is defined as the union of all 1604 referenced packages, that MUST represent a referentially 1605 complete schema. 1607 All of the referenced packages must be compatible with no 1608 conflicting module versions or dependencies."; 1610 uses yang-pkg-ref; 1611 } 1612 } 1614 /* 1615 * Top level data nodes. 1616 */ 1618 container packages { 1619 config false; 1620 description "All YANG package definitions"; 1622 list package { 1623 key "name version"; 1625 description 1626 "YANG package instance"; 1628 uses pkg-types:yang-pkg-instance; 1630 leaf-list location { 1631 type inet:uri; 1632 description 1633 "Contains a URL that represents where an instance data file 1634 for this YANG package can be found. 1636 This leaf will only be present if there is a URL available 1637 for retrieval of the schema for this entry. 1639 If multiple locations are provided, then the first 1640 location in the leaf-list MUST be the definitive location 1641 that uniquely identifies this package"; 1642 } 1644 leaf checksum { 1645 type pkg-types:sha-256-hash; 1646 description 1647 "The checksum of the package this schema relates to, 1648 calculated on the 'YANG instance data file' package 1649 definition available in the 'location' leaf list. 1651 This leaf MAY be omitted if the referenced package is 1652 locally scoped without an associated checksum."; 1653 } 1654 } 1655 } 1656 } 1657 1659 file "ietf-yl-package@2020-01-21.yang" 1660 module ietf-yl-packages { 1661 yang-version 1.1; 1662 namespace "urn:ietf:params:xml:ns:yang:ietf-yl-packages"; 1663 prefix yl-pkgs; 1665 import ietf-yang-revisions { 1666 prefix rev; 1667 reference "XXXX: Updated YANG Module Revision Handling"; 1668 } 1670 import ietf-yang-packages { 1671 prefix pkgs; 1672 rev:revision-or-derived 0.2.0; 1673 reference "RFC XXX: YANG Packages."; 1674 } 1676 import ietf-yang-library { 1677 prefix yanglib; 1678 rev:revision-or-derived 2019-01-04; 1679 reference "RFC 8525: YANG Library"; 1681 } 1683 organization 1684 "IETF NETMOD (Network Modeling) Working Group"; 1686 contact 1687 "WG Web: 1688 WG List: 1690 Author: Rob Wilton 1691 "; 1693 description 1694 "This module provides defined augmentations to YANG library to 1695 allow a server to report YANG package information. 1697 Copyright (c) 2018 IETF Trust and the persons identified as 1698 authors of the code. All rights reserved. 1700 Redistribution and use in source and binary forms, with or 1701 without modification, is permitted pursuant to, and subject 1702 to the license terms contained in, the Simplified BSD License 1703 set forth in Section 4.c of the IETF Trust's Legal Provisions 1704 Relating to IETF Documents 1705 (http://trustee.ietf.org/license-info). 1707 This version of this YANG module is part of RFC XXXX; see 1708 the RFC itself for full legal notices. 1710 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL 1711 NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'NOT RECOMMENDED', 1712 'MAY', and 'OPTIONAL' in this document are to be interpreted as 1713 described in BCP 14 (RFC 2119) (RFC 8174) when, and only when, 1714 they appear in all capitals, as shown here."; 1716 // RFC Ed.: update the date below with the date of RFC publication 1717 // and remove this note. 1718 // RFC Ed.: replace XXXX with actual RFC number and remove this 1719 // note. 1720 revision 2020-01-21 { 1721 rev:revision-label 0.2.0; 1722 description 1723 "Initial revision"; 1724 reference 1725 "RFC XXXX: YANG Packages"; 1726 } 1727 /* 1728 * Augmentations 1729 */ 1731 augment "/yanglib:yang-library/yanglib:schema" { 1732 description 1733 "Allow datastore schema to be related to a set of YANG 1734 packages"; 1736 uses pkgs:yang-ds-pkg-ref; 1737 } 1738 } 1739 1741 file "ietf-yang-inst-data-pkg@2020-01-21.yang" 1742 module ietf-yang-inst-data-pkg { 1743 yang-version 1.1; 1744 namespace "urn:ietf:params:xml:ns:yang:ietf-yang-inst-data-pkg"; 1745 prefix yid-pkg; 1747 import ietf-yang-revisions { 1748 prefix rev; 1749 reference "XXXX: Updated YANG Module Revision Handling"; 1750 } 1752 import ietf-yang-package-types { 1753 prefix pkg-types; 1754 rev:revision-or-derived 0.2.0; 1755 reference "RFC XXX: YANG Schema Versioning."; 1756 } 1758 import ietf-yang-structure-ext { 1759 prefix sx; 1760 reference "RFC XXX: YANG Data Structure Extensions."; 1761 } 1763 import ietf-yang-instance-data { 1764 prefix yid; 1765 reference "RFC XXX: YANG Instance Data File Format."; 1766 } 1768 import ietf-inet-types { 1769 prefix inet; 1770 reference "RFC 6991: Common YANG Data Types."; 1771 } 1772 organization 1773 "IETF NETMOD (Network Modeling) Working Group"; 1775 contact 1776 "WG Web: 1777 WG List: 1779 Author: Rob Wilton 1780 "; 1782 description 1783 "The module augments ietf-yang-instance-data to allow package 1784 definitions to be used to define schema in YANG instance data 1785 documents. 1787 Copyright (c) 2019 IETF Trust and the persons identified as 1788 authors of the code. All rights reserved. 1790 Redistribution and use in source and binary forms, with or 1791 without modification, is permitted pursuant to, and subject 1792 to the license terms contained in, the Simplified BSD License 1793 set forth in Section 4.c of the IETF Trust's Legal Provisions 1794 Relating to IETF Documents 1795 (http://trustee.ietf.org/license-info). 1797 This version of this YANG module is part of RFC XXXX; see 1798 the RFC itself for full legal notices. 1800 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL 1801 NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'NOT RECOMMENDED', 1802 'MAY', and 'OPTIONAL' in this document are to be interpreted as 1803 described in BCP 14 (RFC 2119) (RFC 8174) when, and only when, 1804 they appear in all capitals, as shown here."; 1806 // RFC Ed.: update the date below with the date of RFC publication 1807 // and remove this note. 1808 // RFC Ed.: replace XXXX with actual RFC number and remove this 1809 // note. 1810 revision 2020-01-21 { 1811 rev:revision-label 0.2.0; 1812 description 1813 "Initial revision"; 1814 reference 1815 "RFC XXXX: YANG Packages"; 1816 } 1818 /* 1819 * Augmentations 1820 */ 1822 sx:augment-structure 1823 "/yid:instance-data-set/yid:content-schema-spec" { 1824 description 1825 "Add package reference to instance data set schema 1826 specification"; 1827 case pkg-schema { 1828 container pkg-schema { 1829 uses pkg-types:yang-pkg-identification-leafs; 1831 leaf checksum { 1832 type pkg-types:sha-256-hash; 1833 description 1834 "The SHA-256 hash of the package, calculated on 1835 the textual package definition, represented as a 1836 hexadecimal string."; 1837 } 1839 leaf-list location { 1840 type inet:uri; 1841 description 1842 "Contains a URL that represents where an instance data 1843 file for this YANG package can be found. 1845 This leaf will only be present if there is a URL 1846 available for retrieval of the schema for this entry. 1848 If multiple locations are provided, then the first 1849 location in the leaf-list MUST be the definitive 1850 location that uniquely identifies this package"; 1851 } 1852 } 1853 } 1854 } 1855 } 1856 1858 11. Security Considerations 1860 The YANG modules specified in this document defines a schema for data 1861 that is accessed by network management protocols such as NETCONF 1862 [RFC6241] or RESTCONF [RFC8040]. The lowest NETCONF layer is the 1863 secure transport layer, and the mandatory-to-implement secure 1864 transport is Secure Shell (SSH) [RFC6242]. The lowest RESTCONF layer 1865 is HTTPS, and the mandatory-to-implement secure transport is TLS 1866 [RFC5246]. 1868 The NETCONF access control model [RFC6536] provides the means to 1869 restrict access for particular NETCONF or RESTCONF users to a 1870 preconfigured subset of all available NETCONF or RESTCONF protocol 1871 operations and content. 1873 Similarly to YANG library [I-D.ietf-netconf-rfc7895bis], some of the 1874 readable data nodes in these YANG modules may be considered sensitive 1875 or vulnerable in some network environments. It is thus important to 1876 control read access (e.g., via get, get-config, or notification) to 1877 these data nodes. 1879 One additional key different to YANG library, is that the 'ietf-yang- 1880 package' YANG module defines a schema to allow YANG packages to be 1881 defined in YANG instance data documents, that are outside the 1882 security controls of the network management protocols. Hence, it is 1883 important to also consider controlling access to these package 1884 instance data documents to restrict access to sensitive information. 1885 SHA-256 checksums are used to ensure the integrity of YANG package 1886 definitions, imported modules, and sub-modules. 1888 As per the YANG library security considerations, the module, revision 1889 and version information in YANG packages may help an attacker 1890 identify the server capabilities and server implementations with 1891 known bugs since the set of YANG modules supported by a server may 1892 reveal the kind of device and the manufacturer of the device. Server 1893 vulnerabilities may be specific to particular modules, module 1894 revisions, module features, or even module deviations. For example, 1895 if a particular operation on a particular data node is known to cause 1896 a server to crash or significantly degrade device performance, then 1897 the YANG packages information will help an attacker identify server 1898 implementations with such a defect, in order to launch a denial-of- 1899 service attack on the device. 1901 12. IANA Considerations 1903 It is expected that a central registry of standard YANG package 1904 definitions is required to support this solution. 1906 It is unclear whether an IANA registry is also required to manage 1907 specific package versions. It is highly desirable to have a specific 1908 canonical location, under IETF control, where the definitive YANG 1909 package versions can be obtained from. 1911 This document requests IANA to registers a URI in the "IETF XML 1912 Registry" [RFC3688]. Following the format in RFC 3688, the following 1913 registrations are requested. 1915 URI: urn:ietf:params:xml:ns:yang:ietf-yang-package-types.yang 1916 Registrant Contact: The IESG. 1917 XML: N/A, the requested URI is an XML namespace. 1919 URI: urn:ietf:params:xml:ns:yang:ietf-yang-package-instance.yang 1920 Registrant Contact: The IESG. 1921 XML: N/A, the requested URI is an XML namespace. 1923 URI: urn:ietf:params:xml:ns:yang:ietf-yang-packages.yang 1924 Registrant Contact: The IESG. 1925 XML: N/A, the requested URI is an XML namespace. 1927 URI: urn:ietf:params:xml:ns:yang:ietf-yl-packages.yang 1928 Registrant Contact: The IESG. 1929 XML: N/A, the requested URI is an XML namespace. 1931 URI: urn:ietf:params:xml:ns:yang:ietf-yang-inst-data-pkg.yang 1932 Registrant Contact: The IESG. 1933 XML: N/A, the requested URI is an XML namespace. 1935 This document requests that the following YANG modules are added in 1936 the "YANG Module Names" registry [RFC6020]: 1938 Name: ietf-yang-package-types.yang 1939 Namespace: urn:ietf:params:xml:ns:yang:ietf-yang-package- 1940 types.yang 1941 Prefix: pkg-types 1942 Reference: RFC XXXX 1944 Name: ietf-yang-package-instance.yang 1945 Namespace: urn:ietf:params:xml:ns:yang:ietf-yang-package- 1946 instance.yang 1947 Prefix: pkg-inst 1948 Reference: RFC XXXX 1950 Name: ietf-yang-packages.yang 1951 Namespace: urn:ietf:params:xml:ns:yang:ietf-yang-packages.yang 1952 Prefix: pkgs 1953 Reference: RFC XXXX 1955 Name: ietf-yl-packages.yang 1956 Namespace: urn:ietf:params:xml:ns:yang:ietf-yl-packages.yang 1957 Prefix: yl-pkgs 1958 Reference: RFC XXXX 1960 Name: ietf-yang-inst-data-pkg.yang 1961 Namespace: urn:ietf:params:xml:ns:yang:ietf-yang-inst-data- 1962 pkg.yang 1963 Prefix: yid-pkg 1964 Reference: RFC XXXX 1966 13. Open Questions/Issues 1968 All issues, along with the draft text, are currently being tracked at 1969 https://github.com/rgwilton/YANG-Packages-Draft/issues/ 1971 14. Acknowledgements 1973 Feedback helping shape this document has kindly been provided by Andy 1974 Bierman, Bo Wang, Joe Clarke, James Cumming, Mahesh Jethanandani, 1975 Balazs Lengyel, Ladislav Lhotka, Jason Sterne, and Reshad Rahman. 1977 15. References 1979 15.1. Normative References 1981 [I-D.ietf-netconf-rfc7895bis] 1982 Bierman, A., Bjorklund, M., Schoenwaelder, J., Watsen, K., 1983 and R. Wilton, "YANG Library", draft-ietf-netconf- 1984 rfc7895bis-07 (work in progress), October 2018. 1986 [I-D.ietf-netmod-module-tags] 1987 Hopps, C., Berger, L., and D. Bogdanovic, "YANG Module 1988 Tags", draft-ietf-netmod-module-tags-10 (work in 1989 progress), February 2020. 1991 [I-D.ietf-netmod-yang-data-ext] 1992 Bierman, A., Bjorklund, M., and K. Watsen, "YANG Data 1993 Structure Extensions", draft-ietf-netmod-yang-data-ext-05 1994 (work in progress), December 2019. 1996 [I-D.ietf-netmod-yang-instance-file-format] 1997 Lengyel, B. and B. Claise, "YANG Instance Data File 1998 Format", draft-ietf-netmod-yang-instance-file-format-08 1999 (work in progress), March 2020. 2001 [I-D.verdt-netmod-yang-module-versioning] 2002 Claise, B., Clarke, J., Rahman, R., Wilton, R., Lengyel, 2003 B., Sterne, J., and K. D'Souza, "Updated YANG Module 2004 Revision Handling", draft-verdt-netmod-yang-module- 2005 versioning-01 (work in progress), October 2019. 2007 [I-D.verdt-netmod-yang-semver] 2008 Claise, B., Clarke, J., Rahman, R., Wilton, R., Lengyel, 2009 B., Sterne, J., and K. D'Souza, "YANG Semantic 2010 Versioning", draft-verdt-netmod-yang-semver-01 (work in 2011 progress), October 2019. 2013 [I-D.verdt-netmod-yang-solutions] 2014 Wilton, R., "YANG Versioning Solution Overview", draft- 2015 verdt-netmod-yang-solutions-03 (work in progress), 2016 February 2020. 2018 [I-D.verdt-netmod-yang-versioning-reqs] 2019 Clarke, J., "YANG Module Versioning Requirements", draft- 2020 verdt-netmod-yang-versioning-reqs-02 (work in progress), 2021 November 2018. 2023 [I-D.wilton-netmod-yang-ver-selection] 2024 Wilton, R., Rahman, R., Clarke, J., Sterne, J., and W. Bo, 2025 "YANG Schema Selection", draft-wilton-netmod-yang-ver- 2026 selection-02 (work in progress), February 2020. 2028 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2029 Requirement Levels", BCP 14, RFC 2119, 2030 DOI 10.17487/RFC2119, March 1997, 2031 . 2033 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 2034 DOI 10.17487/RFC3688, January 2004, 2035 . 2037 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 2038 (TLS) Protocol Version 1.2", RFC 5246, 2039 DOI 10.17487/RFC5246, August 2008, 2040 . 2042 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 2043 the Network Configuration Protocol (NETCONF)", RFC 6020, 2044 DOI 10.17487/RFC6020, October 2010, 2045 . 2047 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 2048 and A. Bierman, Ed., "Network Configuration Protocol 2049 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 2050 . 2052 [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure 2053 Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011, 2054 . 2056 [RFC6536] Bierman, A. and M. Bjorklund, "Network Configuration 2057 Protocol (NETCONF) Access Control Model", RFC 6536, 2058 DOI 10.17487/RFC6536, March 2012, 2059 . 2061 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 2062 RFC 7950, DOI 10.17487/RFC7950, August 2016, 2063 . 2065 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 2066 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 2067 . 2069 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2070 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 2071 May 2017, . 2073 [RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 2074 and R. Wilton, "Network Management Datastore Architecture 2075 (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018, 2076 . 2078 [RFC8525] Bierman, A., Bjorklund, M., Schoenwaelder, J., Watsen, K., 2079 and R. Wilton, "YANG Library", RFC 8525, 2080 DOI 10.17487/RFC8525, March 2019, 2081 . 2083 15.2. Informative References 2085 [I-D.bierman-netmod-yang-package] 2086 Bierman, A., "The YANG Package Statement", draft-bierman- 2087 netmod-yang-package-00 (work in progress), July 2015. 2089 [I-D.ietf-netmod-artwork-folding] 2090 Watsen, K., Auerswald, E., Farrel, A., and Q. WU, 2091 "Handling Long Lines in Inclusions in Internet-Drafts and 2092 RFCs", draft-ietf-netmod-artwork-folding-12 (work in 2093 progress), January 2020. 2095 [openconfigsemver] 2096 "Semantic Versioning for OpenConfig Models", 2097 . 2099 [RFC8199] Bogdanovic, D., Claise, B., and C. Moberg, "YANG Module 2100 Classification", RFC 8199, DOI 10.17487/RFC8199, July 2101 2017, . 2103 Appendix A. Examples 2105 This section provides various examples of YANG packages, and as such 2106 this text is non-normative. The purpose of the examples is to only 2107 illustrate the file format of YANG packages, and how package 2108 dependencies work. It does not imply that such packages will be 2109 defined by IETF, or which modules would be included in those packages 2110 even if they were defined. For brevity, the examples exclude 2111 namespace declarations, and use a shortened URL of "tiny.cc/ietf- 2112 yang" as a replacement for 2113 "https://raw.githubusercontent.com/YangModels/yang/master/standard/ 2114 ietf/RFC". 2116 A.1. Example IETF Network Device YANG package 2118 This section provides an instance data document example of an IETF 2119 Network Device YANG package formatted in JSON. 2121 This example package is intended to represent the standard set of 2122 YANG modules, with import dependencies, to implement a basic network 2123 device without any dynamic routing or layer 2 services. E.g., it 2124 includes functionality such as system information, interface and 2125 basic IP configuration. 2127 As for all YANG packages, all import dependencies are fully resolved. 2128 Because this example uses YANG modules that have been standardized 2129 before YANG semantic versioning, they modules are referenced by 2130 revision date rather than version number. 2132 file "example-ietf-network-device-pkg.json" 2133 ========= NOTE: '\' line wrapping per BCP XX (RFC XXXX) =========== 2135 { 2136 "ietf-yang-instance-data:instance-data-set": { 2137 "name": "example-ietf-network-device-pkg", 2138 "pkg-schema": { 2139 package: "ietf-yang-package-defn-pkg@0.1.0.json" 2140 }, 2141 "description": "YANG package definition", 2142 "content-data": { 2143 "ietf-yang-package-instance:yang-package": { 2144 "name": "example-ietf-network-device-pkg", 2145 "version": "1.1.2", 2146 "timestamp": "2018-12-13T17:00:00Z", 2147 "organization": "IETF NETMOD Working Group", 2148 "contact" : "WG Web: , \ 2149 WG List: ", 2150 "description": "Example IETF network device YANG package.\ 2151 \ 2152 This package defines a small sample set of \ 2153 YANG modules that could represent the basic set of \ 2154 modules that a standard network device might be expected \ 2155 to support.", 2157 "reference": "XXX, draft-rwilton-netmod-yang-packages", 2158 "location": [ "file://example.org/yang/packages/\ 2159 ietf-network-device@v1.1.2.json" ], 2160 "module": [ 2161 { 2162 "name": "iana-crypt-hash", 2163 "revision": "2014-08-06", 2164 "location": [ "https://tiny.cc/ietf-yang/\ 2165 iana-crypt-hash%402014-08-06.yang" ], 2166 "checksum": "fa9fde408ddec2c16bf2c6b9e4c2f80b\ 2167 813a2f9e48c127016f3fa96da346e02d" 2168 }, 2169 { 2170 "name": "ietf-system", 2171 "revision": "2014-08-06", 2172 "location": [ "https://tiny.cc/ietf-yang/\ 2173 ietf-system%402014-08-06.yang" ], 2174 "checksum": "8a692ee2521b4ffe87a88303a61a1038\ 2175 79ee26bff050c1b05a2027ae23205d3f" 2176 }, 2177 { 2178 "name": "ietf-interfaces", 2179 "revision": "2018-02-20", 2180 "location": [ "https://tiny.cc/ietf-yang/\ 2181 ietf-interfaces%402018-02-20.yang" ], 2182 "checksum": "f6faea9938f0341ed48fda93dba9a69a\ 2183 a32ee7142c463342efec3d38f4eb3621" 2184 }, 2185 { 2186 "name": "ietf-netconf-acm", 2187 "revision": "2018-02-14", 2188 "location": [ "https://tiny.cc/ietf-yang/\ 2189 ietf-netconf-acm%402018-02-14.yang" ], 2190 "checksum": "e03f91317f9538a89296e99df3ff0c40\ 2191 03cdfea70bf517407643b3ec13c1ed25" 2192 }, 2193 { 2194 "name": "ietf-key-chain", 2195 "revision": "2017-06-15", 2196 "location": [ "https://tiny.cc/ietf-yang/\ 2197 ietf-key-chain@2017-06-15.yang" ], 2198 "checksum": "6250705f59fc9ad786e8d74172ce90d5\ 2199 8deec437982cbca7922af40b3ae8107c" 2200 }, 2201 { 2202 "name": "ietf-ip", 2203 "revision": "2018-02-22", 2204 "location": [ "https://tiny.cc/ietf-yang/\ 2205 ietf-ip%402018-02-22.yang" ], 2206 "checksum": "b624c84a66c128ae69ab107a5179ca8e\ 2207 20e693fb57dbe5cb56c3db2ebb18c894" 2208 } 2209 ], 2210 "import-only-module": [ 2211 { 2212 "name": "ietf-yang-types", 2213 "revision": "2013-07-15", 2214 "location": [ "https://tiny.cc/ietf-yang/\ 2215 ietf-yang-types%402013-07-15.yang" ], 2216 "checksum": "a04cdcc875764a76e89b7a0200c6b9d8\ 2217 00b10713978093acda7840c7c2907c3f" 2218 }, 2219 { 2220 "name": "ietf-inet-types", 2221 "revision": "2013-07-15", 2222 "location": [ "https://tiny.cc/ietf-yang/\ 2223 ietf-inet-types%402013-07-15.yang" ], 2224 "checksum": "12d98b0143a5ca5095b36420f9ebc1ff\ 2225 a61cfd2eaa850080244cadf01b86ddf9" 2226 } 2227 ] 2228 } 2229 } 2230 } 2231 } 2232 2234 A.2. Example IETF Basic Routing YANG package 2236 This section provides an instance data document example of a basic 2237 IETF Routing YANG package formatted in JSON. 2239 This example package is intended to represent the standard set of 2240 YANG modules, with import dependencies, that builds upon the example- 2241 ietf-network-device YANG package to add support for basic dynamic 2242 routing and ACLs. 2244 As for all YANG packages, all import dependencies are fully resolved. 2245 Because this example uses YANG modules that have been standardized 2246 before YANG semantic versioning, they modules are referenced by 2247 revision date rather than version number. Locations have been 2248 excluded where they are not currently known, e.g., for YANG modules 2249 defined in IETF drafts. In a normal YANG package, locations would be 2250 expected to be provided for all YANG modules. 2252 file "example-ietf-routing-pkg.json" 2253 ========== NOTE: '\' line wrapping per BCP XX (RFC XXXX) =========== 2255 { 2256 "ietf-yang-instance-data:instance-data-set": { 2257 "name": "example-ietf-routing-pkg", 2258 "module": [ "ietf-yang-package@2019-09-11.yang" ], 2259 "description": "YANG package definition", 2260 "content-data": { 2261 "ietf-yang-package-instance:yang-package": { 2262 "name": "example-ietf-routing", 2263 "version": "1.3.1", 2264 "timestamp": "2018-12-13T17:00:00Z", 2265 "description": "This package defines a small sample set of \ 2266 IETF routing YANG modules that could represent the set of \ 2267 IETF routing functionality that a basic IP network device \ 2268 might be expected to support.", 2269 "reference": "XXX, draft-rwilton-netmod-yang-packages", 2270 "imported-packages": [ 2271 { 2272 "name": "ietf-network-device", 2273 "version": "1.1.2", 2274 "location": [ "http://example.org/yang/packages/\ 2275 ietf-network-device@v1.1.2.json" ], 2276 "checksum": "" 2277 } 2278 ], 2279 "module": [ 2280 { 2281 "name": "ietf-routing", 2282 "revision": "2018-03-13", 2283 "location": [ "https://tiny.cc/ietf-yang/\ 2284 ietf-routing@2018-03-13.yang" ], 2285 "checksum": "" 2286 }, 2287 { 2288 "name": "ietf-ipv4-unicast-routing", 2289 "revision": "2018-03-13", 2290 "location": [ "https://tiny.cc/ietf-yang/\ 2291 ietf-ipv4-unicast-routing@2018-03-13.yang" ], 2292 "checksum": "" 2293 }, 2294 { 2295 "name": "ietf-ipv6-unicast-routing", 2296 "revision": "2018-03-13", 2297 "location": [ "https://tiny.cc/ietf-yang/\ 2298 ietf-ipv6-unicast-routing@2018-03-13.yang" ], 2299 "checksum": "" 2301 }, 2302 { 2303 "name": "ietf-isis", 2304 "revision": "2018-12-11", 2305 "location": [ "https://tiny.cc/ietf-yang/\ 2306 " ], 2307 "checksum": "" 2308 }, 2309 { 2310 "name": "ietf-interfaces-common", 2311 "revision": "2018-07-02", 2312 "location": [ "https://tiny.cc/ietf-yang/\ 2313 " ], 2314 "checksum": "" 2315 }, 2316 { 2317 "name": "ietf-if-l3-vlan", 2318 "revision": "2017-10-30", 2319 "location": [ "https://tiny.cc/ietf-yang/\ 2320 " ], 2321 "checksum": "" 2322 }, 2323 { 2324 "name": "ietf-routing-policy", 2325 "revision": "2018-10-19", 2326 "location": [ "https://tiny.cc/ietf-yang/\ 2327 " ], 2328 "checksum": "" 2329 }, 2330 { 2331 "name": "ietf-bgp", 2332 "revision": "2018-05-09", 2333 "location": [ "https://tiny.cc/ietf-yang/\ 2334 " ], 2335 "checksum": "" 2336 }, 2337 { 2338 "name": "ietf-access-control-list", 2339 "revision": "2018-11-06", 2340 "location": [ "https://tiny.cc/ietf-yang/\ 2341 " ], 2342 "checksum": "" 2343 } 2344 ], 2345 "import-only-module": [ 2346 { 2347 "name": "ietf-routing-types", 2348 "revision": "2017-12-04", 2349 "location": [ "https://tiny.cc/ietf-yang/\ 2350 ietf-routing-types@2017-12-04.yang" ], 2351 "checksum": "" 2352 }, 2353 { 2354 "name": "iana-routing-types", 2355 "revision": "2017-12-04", 2356 "location": [ "https://tiny.cc/ietf-yang/\ 2357 iana-routing-types@2017-12-04.yang" ], 2358 "checksum": "" 2359 }, 2360 { 2361 "name": "ietf-bgp-types", 2362 "revision": "2018-05-09", 2363 "location": [ "https://tiny.cc/ietf-yang/\ 2364 " ], 2365 "checksum": "" 2366 }, 2367 { 2368 "name": "ietf-packet-fields", 2369 "revision": "2018-11-06", 2370 "location": [ "https://tiny.cc/ietf-yang/\ 2371 " ], 2372 "checksum": "" 2373 }, 2374 { 2375 "name": "ietf-ethertypes", 2376 "revision": "2018-11-06", 2377 "location": [ "https://tiny.cc/ietf-yang/\ 2378 " ], 2379 "checksum": "" 2380 } 2381 ] 2382 } 2383 } 2384 } 2385 } 2386 2388 A.3. Package import conflict resolution example 2390 This section provides an example of how a package can resolve 2391 conflicting module versions from imported packages. 2393 In this example, YANG package 'example-3-pkg' imports both 'example- 2394 import-1' and 'example-import-2' packages. However, the two imported 2395 packages implement different versions of 'example-module-A' so the 2396 'example-3-pkg' package selects version '1.2.3' to resolve the 2397 conflict. Similarly, for import-only modules, the 'example-3-pkg' 2398 package does not require both versions of example-types-module-C to 2399 be imported, so it indicates that it only imports revision 2400 '2018-11-26' and not '2018-01-01'. 2402 { 2403 "ietf-yang-instance-data:instance-data-set": { 2404 "name": "example-import-1-pkg", 2405 "description": "First imported example package", 2406 "content-data": { 2407 "ietf-yang-package-instance:yang-package": { 2408 "name": "example-import-1", 2409 "version": "1.0.0", 2410 "reference": "XXX, draft-rwilton-netmod-yang-packages", 2411 "revision-date": "2018-01-01", 2412 "module": [ 2413 { 2414 "name": "example-module-A", 2415 "version": "1.0.0" 2416 }, 2417 { 2418 "name": "example-module-B", 2419 "version": "1.0.0" 2420 } 2421 ], 2422 "import-only-module": [ 2423 { 2424 "name": "example-types-module-C", 2425 "revision": "2018-01-01" 2426 }, 2427 { 2428 "name": "example-types-module-D", 2429 "revision": "2018-01-01" 2430 } 2431 ] 2432 } 2433 } 2434 } 2435 } 2437 { 2438 "ietf-yang-instance-data:instance-data-set": { 2439 "name": "example-import-2-pkg", 2440 "description": "Second imported example package", 2441 "content-data": { 2442 "ietf-yang-package:yang-package": { 2443 "name": "example-import-2", 2444 "version": "2.0.0", 2445 "reference": "XXX, draft-rwilton-netmod-yang-packages", 2446 "revision-date": "2018-11-26", 2447 "module": [ 2448 { 2449 "name": "example-module-A", 2450 "version": "1.2.3" 2451 }, 2452 { 2453 "name": "example-module-E", 2454 "version": "1.1.0" 2455 } 2456 ], 2457 "import-only-module": [ 2458 { 2459 "name": "example-types-module-C", 2460 "revision": "2018-11-26" 2461 }, 2462 { 2463 "name": "example-types-module-D", 2464 "revision": "2018-11-26" 2465 } 2466 ] 2467 } 2468 } 2469 } 2470 } 2472 { 2473 "ietf-yang-instance-data:instance-data-set": { 2474 "name": "example-3-pkg", 2475 "description": "Importing example package", 2476 "content-data": { 2477 "ietf-yang-package:yang-package": { 2478 "name": "example-3", 2479 "version": "1.0.0", 2480 "reference": "XXX, draft-rwilton-netmod-yang-packages", 2481 "revision-date": "2018-11-26", 2482 "included-package": [ 2483 { 2484 "name": "example-import-1", 2485 "version": "1.0.0" 2486 }, 2487 { 2488 "name": "example-import-2", 2489 "version": "2.0.0" 2490 } 2492 ], 2493 "module": [ 2494 { 2495 "name": "example-module-A", 2496 "version": "1.2.3" 2497 } 2498 ], 2499 "import-only-module": [ 2500 { 2501 "name": "example-types-module-C", 2502 "revision": "2018-11-26", 2503 "replaces-revision": [ "2018-01-01 "] 2504 } 2505 ] 2506 } 2507 } 2508 } 2509 } 2511 Appendix B. Possible alternative solutions 2513 This section briefly describes some alternative solutions. It can be 2514 removed if this document is adopted as a WG draft. 2516 B.1. Using module tags 2518 Module tags have been suggested as an alternative solution, and 2519 indeed that can address some of the same requirements as YANG 2520 packages but not all of them. 2522 Module tags can be used to group or organize YANG modules. However, 2523 this raises the question of where this tag information is stored. 2524 Module tags either require that the YANG module files themselves are 2525 updated with the module tag information (creating another versioning 2526 problem), or for the module tag information to be hosted elsewhere, 2527 perhaps in a centralize YANG Catalog, or in instance data documents 2528 similar to how YANG packages have been defined in this draft. 2530 One of the principle aims of YANG packages is to be a versioned 2531 object that defines a precise set of YANG modules versions that work 2532 together. Module tags cannot meet this aim without an explosion of 2533 module tags definitions (i.e. a separate module tag must be defined 2534 for each package version). 2536 Module tags cannot support the hierachical scheme to construct YANG 2537 schema that is proposed in this draft. 2539 B.2. Using YANG library 2541 Another question is whether it is necessary to define new YANG 2542 modules to define YANG packages, and whether YANG library could just 2543 be reused in an instance data document. The use of YANG packages 2544 offers several benefits over just using YANG library: 2546 1. Packages allow schema to be built in a hierarchical fashion. 2547 [I-D.ietf-netconf-rfc7895bis] only allows one layer of hierarchy 2548 (using module sets), and there must be no conflicts between 2549 module revisions in different module-sets. 2551 2. Packages can be made available off the box, with a well defined 2552 unique name, avoiding the need for clients to download, and 2553 construct/check the entire YANG schema for each device. Instead 2554 they can rely on the named packages with secure checksums. YANG 2555 library's use of a 'content-id' is unique only to the device that 2556 generated them. 2558 3. Packages may be versioned using a semantic versioning scheme, 2559 YANG library does not provide a schema level semantic version 2560 number. 2562 4. For a YANG library instance data document to contain the 2563 necessary information, it probably needs both YANG library and 2564 various augmentations (e.g. to include each module's semantic 2565 version number), unless a new version of YANG library is defined 2566 containing this information. The module definition for a YANG 2567 package is specified to contain all of the ncessary information 2568 to solve the problem without augmentations 2570 5. YANG library is designed to publish information about the 2571 modules, datastores, and datastore schema used by a server. The 2572 information required to construct an off box schema is not 2573 precisely the same, and hence the definitions might deviate from 2574 each other over time. 2576 Authors' Addresses 2578 Robert Wilton (editor) 2579 Cisco Systems, Inc. 2581 Email: rwilton@cisco.com 2582 Reshad Rahman 2583 Cisco Systems, Inc. 2585 Email: rrahman@cisco.com 2587 Joe Clarke 2588 Cisco Systems, Inc. 2590 Email: jclarke@cisco.com 2592 Jason Sterne 2593 Nokia 2595 Email: jason.sterne@nokia.com 2597 Bo Wu 2598 Huawei 2600 Email: lana.wubo@huawei.com