idnits 2.17.1 draft-ietf-netmod-yang-packages-03.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: ---------------------------------------------------------------------------- == There is 1 instance of lines with non-ascii characters in the document. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** There are 10 instances of too long lines in the document, the longest one being 23 characters in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 693 has weird spacing: '...version pkg...' == Line 720 has weird spacing: '...evision yan...' == Line 730 has weird spacing: '...evision yan...' -- The document date (4 March 2022) is 777 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: 'RFC8791' is defined on line 1940, but no explicit reference was found in the text == Unused Reference: 'I-D.ietf-netmod-artwork-folding' is defined on line 1952, but no explicit reference was found in the text == Unused Reference: 'RFC8199' is defined on line 1964, but no explicit reference was found in the text == Outdated reference: A later version (-11) exists of draft-ietf-netmod-yang-module-versioning-05 == Outdated reference: A later version (-15) exists of draft-ietf-netmod-yang-semver-06 ** Downref: Normative reference to an Informational draft: draft-ietf-netmod-yang-solutions (ref. 'I-D.ietf-netmod-yang-solutions') == Outdated reference: A later version (-09) exists of draft-ietf-netmod-yang-versioning-reqs-06 ** Downref: Normative reference to an Informational draft: draft-ietf-netmod-yang-versioning-reqs (ref. 'I-D.ietf-netmod-yang-versioning-reqs') ** Obsolete normative reference: RFC 5246 (Obsoleted by RFC 8446) ** Obsolete normative reference: RFC 6536 (Obsoleted by RFC 8341) Summary: 5 errors (**), 0 flaws (~~), 11 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group R. Wilton, Ed. 3 Internet-Draft R. Rahman 4 Intended status: Standards Track J. Clarke 5 Expires: 5 September 2022 Cisco Systems, Inc. 6 J. Sterne 7 Nokia 8 B. Wu, Ed. 9 Huawei 10 4 March 2022 12 YANG Packages 13 draft-ietf-netmod-yang-packages-03 15 Abstract 17 This document defines YANG packages; a versioned organizational 18 structure used to manage schema and conformance of YANG modules as a 19 cohesive set instead of individually. 21 It describes how packages: are represented on a server, can be 22 defined in offline YANG instance data files, and can be used to 23 define the content schema associated with YANG instance data files. 25 Status of This Memo 27 This Internet-Draft is submitted in full conformance with the 28 provisions of BCP 78 and BCP 79. 30 Internet-Drafts are working documents of the Internet Engineering 31 Task Force (IETF). Note that other groups may also distribute 32 working documents as Internet-Drafts. The list of current Internet- 33 Drafts is at https://datatracker.ietf.org/drafts/current/. 35 Internet-Drafts are draft documents valid for a maximum of six months 36 and may be updated, replaced, or obsoleted by other documents at any 37 time. It is inappropriate to use Internet-Drafts as reference 38 material or to cite them other than as "work in progress." 40 This Internet-Draft will expire on 5 September 2022. 42 Copyright Notice 44 Copyright (c) 2022 IETF Trust and the persons identified as the 45 document authors. All rights reserved. 47 This document is subject to BCP 78 and the IETF Trust's Legal 48 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 49 license-info) in effect on the date of publication of this document. 50 Please review these documents carefully, as they describe your rights 51 and restrictions with respect to this document. Code Components 52 extracted from this document must include Revised BSD License text as 53 described in Section 4.e of the Trust Legal Provisions and are 54 provided without warranty as described in the Revised BSD License. 56 Table of Contents 58 1. Terminology and Conventions . . . . . . . . . . . . . . . . . 3 59 2. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 60 3. Background on YANG packages . . . . . . . . . . . . . . . . . 4 61 4. Objectives . . . . . . . . . . . . . . . . . . . . . . . . . 5 62 5. YANG Package Definition . . . . . . . . . . . . . . . . . . . 6 63 5.1. Package definition rules . . . . . . . . . . . . . . . . 7 64 5.2. Package versioning . . . . . . . . . . . . . . . . . . . 8 65 5.2.1. Updating a package with a new version . . . . . . . . 8 66 5.2.1.1. Non-Backwards-compatible changes . . . . . . . . 8 67 5.2.1.2. Backwards-compatible changes . . . . . . . . . . 8 68 5.2.1.3. Editorial changes . . . . . . . . . . . . . . . . 9 69 5.2.2. YANG Semantic Versioning for packages . . . . . . . . 9 70 5.3. Package conformance . . . . . . . . . . . . . . . . . . . 10 71 5.3.1. Use of YANG semantic versioning . . . . . . . . . . . 10 72 5.3.2. The relationship between packages and datastores . . 11 73 5.4. Schema referential completeness . . . . . . . . . . . . . 12 74 5.5. Package name scoping and uniqueness . . . . . . . . . . . 13 75 5.5.1. Globally scoped packages . . . . . . . . . . . . . . 13 76 5.5.2. Server scoped packages . . . . . . . . . . . . . . . 13 77 5.6. Submodules packages considerations . . . . . . . . . . . 13 78 5.7. Package tags . . . . . . . . . . . . . . . . . . . . . . 14 79 5.8. YANG Package Usage Guidance . . . . . . . . . . . . . . . 14 80 5.8.1. Use of deviations in YANG packages . . . . . . . . . 14 81 5.8.2. Use of features in YANG modules and YANG packages . . 15 82 5.9. YANG package core definition . . . . . . . . . . . . . . 15 83 6. Package Instance Data Files . . . . . . . . . . . . . . . . . 17 84 7. Package Definitions on a Server . . . . . . . . . . . . . . . 18 85 7.1. Package List . . . . . . . . . . . . . . . . . . . . . . 18 86 7.2. Tree diagram . . . . . . . . . . . . . . . . . . . . . . 18 87 8. YANG Library Package Bindings . . . . . . . . . . . . . . . . 19 88 9. YANG packages as schema for YANG instance data document . . . 19 89 10. YANG Modules . . . . . . . . . . . . . . . . . . . . . . . . 20 90 11. Security Considerations . . . . . . . . . . . . . . . . . . . 37 91 12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 38 92 13. Open Questions/Issues . . . . . . . . . . . . . . . . . . . . 39 93 14. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 40 94 15. References . . . . . . . . . . . . . . . . . . . . . . . . . 40 95 15.1. Normative References . . . . . . . . . . . . . . . . . . 40 96 15.2. Informative References . . . . . . . . . . . . . . . . . 42 97 Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 43 98 A.1. Example IETF Network Device YANG package . . . . . . . . 43 99 A.2. Example IETF Basic Routing YANG package . . . . . . . . . 45 100 A.3. Package import conflict resolution example . . . . . . . 48 101 Appendix B. Possible alternative solutions . . . . . . . . . . . 51 102 B.1. Using module tags . . . . . . . . . . . . . . . . . . . . 52 103 B.2. Using YANG library . . . . . . . . . . . . . . . . . . . 52 104 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 53 106 1. Terminology and Conventions 108 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 109 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 110 "OPTIONAL" in this document are to be interpreted as described in BCP 111 14 [RFC2119] [RFC8174] when, and only when, they appear in all 112 capitals, as shown here. 114 This document uses terminology introduced in the YANG versioning 115 requirements draft [I-D.ietf-netmod-yang-versioning-reqs]. 117 This document also makes of the following terminology introduced in 118 the Network Management Datastore Architecture [RFC8342]: 120 * datastore schema 122 This document also makes of the following terminology introduced in 123 the YANG 1.1 Data Modeling Language [RFC7950]: 125 * data node 127 * schema node 129 In addition, this document defines the following terminology: 131 * YANG package: a versioned organizational structure used to manage 132 a set of YANG modules that collectively define a package schema. 133 YANG packages are defined in Section 5. 135 * package schema: The combined set of schema nodes defined by a YANG 136 package. Package schema can be used to define datastore schema. 138 * 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.ietf-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 * 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.ietf-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 * 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.ietf-netmod-yang-module-versioning]. When used in the 153 context of a YANG package, it follows the definition in 154 Section 5.2.1.3. 156 2. Introduction 158 This document defines and describes the YANG [RFC7950] constructs 159 that are used to define and use YANG packages. 161 A YANG package is a versioned organizational structure used to manage 162 a set of YANG modules that collectively define a package schema. For 163 example, a YANG package could contain the set of YANG modules 164 required to implement an L2VPN service on a network device. 166 Non-normative examples of YANG packages are provided in the 167 appendices. 169 3. Background on YANG packages 171 It has long been acknowledged within the YANG community that network 172 management using YANG requires a unit of organization and conformance 173 that is broader in scope than individual YANG modules. 175 'The YANG Package Statement' [I-D.bierman-netmod-yang-package] 176 proposed a YANG package mechanism based on new YANG language 177 statements, where a YANG package is defined in a file similar to how 178 YANG modules are defined, and would require enhancements to YANG 179 compilers to understand the new statements used to define packages. 181 OpenConfig [openconfigsemver] describes an approach to versioning 182 'bundle releases' based on git tags. I.e. a set of modules, at 183 particular versions, can be marked with the same release tag to 184 indicate that they are known to interoperate together. 186 The NETMOD WG in general, and the YANG versioning design team in 187 particular, are exploring solutions [I-D.ietf-netmod-yang-solutions] 188 to the YANG versioning requirements, 189 [I-D.ietf-netmod-yang-versioning-reqs]. Solutions to the versioning 190 requirements can be split into several distinct areas. 191 [I-D.ietf-netmod-yang-module-versioning] is focused on YANG 192 versioning scoped to individual modules. The overall solution must 193 also consider YANG versioning and conformance scoped to sets of 194 modules. YANG packages provide part of the solution for versioning 195 sets of modules. 197 4. Objectives 199 The main goals of YANG package definitions include, but are not 200 restricted to: 202 * To provide an alternative, simplified, YANG conformance mechanism. 203 Rather than conformance being performed against a set of 204 individual YANG module revisions, features, and deviations, 205 conformance can be more simply stated in terms of YANG packages, 206 with a set of modifications (e.g. additional modules, deviations, 207 or features). 209 * To allow datastore schema to be specified in a concise way rather 210 than having each server explicitly list all modules, revisions, 211 and features. YANG package definitions can be defined in 212 documents that are available offline, and accessible via a URL, 213 rather than requiring explicit lists of modules to be shared 214 between client and server. Hence, a YANG package must contain 215 sufficient information to allow a client or server to precisely 216 construct the schema associated with the package. 218 * To define a mainly linear versioned history of sets of modules 219 versions that are known to work together. I.e. to help mitigate 220 the problem where a client must manage devices from multiple 221 vendors, and vendor A implements version 1.0.0 of module foo and 222 version 2.0.0 of module bar, and vendor B implements version 2.0.0 223 of module foo and version 1.0.0 of module bar. For a client, 224 trying to interoperate with multiple vendors, and many YANG 225 modules, finding a consistent lowest common denominator set of 226 YANG module versions may be difficult, if not impossible. 228 Protocol mechanisms of how clients can negotiate which packages or 229 package versions are to be used for NETCONF/RESTCONF communications 230 are outside the scope of this document, and are defined in 231 [I-D.ietf-netmod-yang-ver-selection]. 233 Finally, the package definitions proposed by this document are 234 intended to be relatively basic in their definition and the 235 functionality that they support. As industry gains experience using 236 YANG packages, the standard YANG mechanisms of updating, or 237 augmenting YANG modules could also be used to extend the 238 functionality supported by YANG packages, if required. 240 5. YANG Package Definition 242 This document specifies an approach to defining YANG packages that is 243 different to either of the approaches described in the background. 245 A YANG package is a versioned organizational structure used to manage 246 a set of YANG modules that collectively define a package schema. 248 Each YANG package has a name that SHOULD end with the suffix "-pkg". 249 Package names are normally expected to be globally unique, but in 250 some cases the package name may be locally scoped to a server or 251 device, as described in Section 5.5. 253 YANG packages are versioned using the same approaches described in 254 [I-D.ietf-netmod-yang-module-versioning] and 255 [I-D.ietf-netmod-yang-semver]. This is described in further detail 256 in Section 5.2. 258 Each YANG package version, defines: 260 * some metadata about the package, e.g., description, tags, scoping, 261 referential completeness, location information. 263 * a set of YANG modules, at particular revisions, that are 264 implemented by servers that implement the package. The modules 265 may contain deviations. 267 * a set of import-only YANG modules, at particular revisions, that 268 are used 'import-only' by the servers that implement the package. 270 * a set of included YANG packages, at particular revisions, that are 271 also implemented by servers that implement the package. 273 * a set of YANG module features that must be supported by servers 274 that implement the package. 276 The structure for YANG package definitions uses existing YANG 277 language statements, YANG Data Structure Extensions 278 [I-D.ietf-netmod-yang-data-ext], and YANG Instance Data File Format 279 [I-D.ietf-netmod-yang-instance-file-format]. 281 YANG package definitions are available offline in YANG instance data 282 files. Client applications can be designed to support particular 283 package versions that they expect to interoperate with. 285 YANG package definitions are available from the server via 286 augmentations to YANG Library [RFC8525]. Rather than client 287 applications downloading the entire contents of YANG library to 288 confirm that the server's datastore schema are compatible with the 289 client, they can simply check the names and versions of the packages 290 advertised in YANG library to know what schema to expect in the 291 server datastores. 293 YANG package definitions can also be used to define the content 294 schema associated with YANG instance data files holding other, e.g., 295 non packages related, instance data. 297 5.1. Package definition rules 299 Packages are defined using the following rules: 301 1. A YANG package MAY represent a referentially complete set of 302 modules or MAY represent a set of modules with some module import 303 dependencies missing, as described in Section 5.4. 305 2. Packages definitions are hierarchical. A package can include 306 other packages. Only a single version of a package can be 307 included, and conflicting package includes (e.g. from descendant 308 package includes) MUST be explicitly resolved by indicating which 309 version takes precedence, and which versions are being replaced. 311 3. YANG packages definitions MAY include modules containing 312 deviation statements, but those deviation statements MUST only be 313 used in an [RFC7950] compatible way to indicate where a server, 314 or class of servers, deviates from a published standard. 315 Deviations MUST NOT be included in a package definition that is 316 part of a published standard. See section Section 5.8.1 for 317 further guidance on the use of deviations in YANG packages. 319 4. For each module implemented by a package, only a single revision 320 of that module MUST be implemented. Multiple revisions of a 321 module MAY be listed as import-only dependencies. 323 5. The revision of a module listed in the package 'module' list 324 supersedes any 'implemented' revision of the module listed in an 325 included package module list. The 'replaces-revision' leaf-list 326 is used to indicate which 'implemented' or 'import-only' module 327 revisions are replaces by this module revision. This allows a 328 package to explicitly resolve conflicts between implemented 329 module revisions in included packages. 331 6. The 'replaces-revision' leaf-list in the 'import-only-module' 332 list can be used to exclude duplicate revisions of import-only 333 modules from included packages. Otherwise, the import-only- 334 modules for a package are the import-only-modules from all 335 included packages combined with any modules listed in the 336 packages import-only-module list. 338 5.2. Package versioning 340 Individual versions of a YANG package are versioned using the 341 "revision-label" scheme defined in section 3.3 of 342 [I-D.ietf-netmod-yang-module-versioning]. 344 5.2.1. Updating a package with a new version 346 Package compatibility is fundamentally defined by how the package 347 schema between two package versions has changed. 349 When a package definition is updated, the version associated with the 350 package MUST be updated appropriately, taking into consideration the 351 scope of the changes as defined by the rules below. 353 5.2.1.1. Non-Backwards-compatible changes 355 The following changes classify as non-backwards-compatible changes to 356 a package definition: 358 * Changing an 'included-package' list entry to select a package 359 version that is non-backwards-compatible to the prior package 360 version, or removing a previously included package. 362 * Changing a 'module' or 'import-only-module' list entry to select a 363 module revision that is non-backwards-compatible to the prior 364 module revision, or removing a previously implemented module. 366 * Removing a feature from the 'mandatory-feature' leaf-list. 368 * Adding, changing, or removing a module containing one or more 369 deviations, that when applied to the target module would create a 370 change that is considered a non-backwards-compatible change to the 371 affected data node in the schema associated with the prior package 372 version. 374 5.2.1.2. Backwards-compatible changes 376 The following changes classify as backwards-compatible changes to a 377 package definition: 379 * Changing an 'included-package' list entry to select a package 380 version that is backwards-compatible to the prior package version, 381 or including a new package that does not conflict with any 382 existing included package or module. 384 * Changing a 'module' or 'import-only-module' list entry to select a 385 module revision that is backwards-compatible to the prior module 386 revision, or including a new module to the package definition. 388 * Adding a feature to the 'mandatory-feature' leaf-list. 390 * Adding, changing, or removing a module containing one or more 391 deviations, that when applied to the target module would create a 392 change that is considered a backwards-compatible change to the 393 affected data node in the schema associated with the prior package 394 version. 396 5.2.1.3. Editorial changes 398 The following changes classify as editorial changes to a package 399 definition: 401 * Changing a 'included-package' list entry to select a package 402 version that is classified as an editorial change relative to the 403 prior package version. 405 * Changing a 'module' or 'import-only-module' list entry to select a 406 module revision that is classified as an editorial change relative 407 to the prior module revision. 409 * Any change to any metadata associated with a package definition. 411 5.2.2. YANG Semantic Versioning for packages 413 YANG Semantic Versioning [I-D.ietf-netmod-yang-semver] MAY be used as 414 an appropriate type of revision-label for the package version leaf. 416 If the format of the leaf matches the 'ysver:version' type specified 417 in ietf-yang-semver.yang, then the package version leaf MUST be 418 interpreted as a YANG semantic version number. 420 For YANG packages defined by the IETF, YANG semantic version numbers 421 MUST be used as the version scheme for YANG packages. 423 The rules for incrementing the YANG package version number are 424 equivalent to the semantic versioning rules used to version 425 individual YANG modules, defined in section 3.2 of 426 [I-D.ietf-netmod-yang-semver], but use the rules defined previously 427 in Section 5.2.1 to determine whether a change is classified as non- 428 backwards-compatible, backwards-compatible, or editorial. Where 429 available, the semantic version number of the referenced elements in 430 the package (included packages or modules) can be used to help 431 determine the scope of changes being made. 433 5.3. Package conformance 435 YANG packages allows for conformance to be checked at a package level 436 rather than requiring a client to download all modules, revisions, 437 and deviations from the server to ensure that the datastore schema 438 used by the server is compatible with the client. 440 YANG package conformance is analogous to how YANG [RFC7950] requires 441 that servers either implement a module faithfully, or otherwise use 442 deviations to indicate areas of non-conformance. 444 For a top level package representing a datastore schema, servers MUST 445 implement the package definition faithfully, including all mandatory 446 features. 448 Package definitions MAY modify the schema for directly or 449 hierarchically included packages through the use of different module 450 revisions or module deviations. 452 5.3.1. Use of YANG semantic versioning 454 Using the YANG semantic versioning scheme for package version numbers 455 and module revision labels can help with conformance. In the general 456 case, clients should be able to determine the nature of changes 457 between two package versions by comparing the version number. 459 This usually means that a client does not have to be restricted to 460 working only with servers that advertise exactly the same version of 461 a package in YANG library. Instead, reasonable clients should be 462 able to interoperate with any server that supports a package version 463 that is backwards compatible to version that the client is designed 464 for, assuming that the client is designed to ignore operational 465 values for unknown data nodes. 467 For example, a client coded to support 'foo' package at version 1.0.0 468 should interoperate with a server implementing 'foo' package at 469 version 1.3.5, because the YANG semantic versioning rules require 470 that package version 1.3.5 is backwards compatible to version 1.0.0. 472 This also has a relevance on servers that are capable of supporting 473 version selection because they need not support every version of a 474 YANG package to ensure good client compatibility. Choosing suitable 475 minor versions within each major version number should generally be 476 sufficient, particular if they can avoid non-backwards-compatible 477 patch level changes. 479 5.3.2. The relationship between packages and datastores 481 As defined by NMDA [RFC8342], each datastore has an associated 482 datastore schema. Sections 5.1 and 5.3 of NMDA defines further 483 constraints on the schema associated with datastores. These 484 constraints can be summarized thus: 486 * The schema for all conventional datastores is the same. 488 * The schema for non conventional configuration datastores (e.g., 489 dynamic datastores) may completely differ (i.e. no overlap at all) 490 from the schema associated with the conventional configuration 491 datastores, or may partially or fully overlap with the schema of 492 the conventional configuration datastores. A dynamic datastore, 493 for example, may support different modules than conventional 494 datastores, or may support a subset or superset of modules, 495 features, or data nodes supported in the conventional 496 configuration datastores. Where a data node exists in multiple 497 datastore schema it has the same type, properties and semantics. 499 * The schema for the operational datastore is intended to be a 500 superset of all the configuration datastores (i.e. includes all 501 the schema nodes from the conventional configuration datastores), 502 but data nodes can be omitted if they cannot be accurately 503 reported. The operational datastore schema can include additional 504 modules containing only config false data nodes, but there is no 505 harm in including those modules in the configuration datastore 506 schema as well. 508 Given that YANG packages represent a schema, it follows that each 509 datastore schema can be represented using packages. In addition, the 510 schema for most datastores on a server are often closely related. 511 Given that there are many ways that a datastore schema could be 512 represented using packages, the following guidance provides a 513 consistent approach to help clients understand the relationship 514 between the different datastore schema supported by a device (e.g., 515 which parts of the schema are common and which parts have 516 differences): 518 * Any datastores (e.g., conventional configuration datastores) that 519 have exactly the same datastore schema MUST use the same package 520 definitions. This is to avoid, for example, the creation of a 521 'running-cfg' package and a separate 'intended-cfg' package that 522 have identical schema. 524 * Common package definitions SHOULD be used for those parts of the 525 datastore schema that are common between datastores, when those 526 datastores do not share exactly the same datastore schema. E.g., 527 if a substantial part of the schema is common between the 528 conventional, dynamic, and operational datastores then a single 529 common package can be used to describe the common parts, along 530 with other packages to describe the unique parts of each datastore 531 schema. 533 * YANG modules that do not contain any configuration data nodes 534 SHOULD be included in the package for configuration datastores if 535 that helps unify the package definitions. 537 * The packages for the operational datastore schema MUST include all 538 packages for all configuration datastores, along with any required 539 modules defining deviations to mark unsupported data nodes. The 540 deviations MAY be defined directly in the packages defining the 541 operational datastore schema, or in separate non referentially 542 complete packages. 544 * The schema for a datastore MAY be represented using a single 545 package or as the union of a set of compatible packages, i.e., 546 equivalently to a set of non-conflicting packages being included 547 together in an overarching package definition. 549 5.4. Schema referential completeness 551 A YANG package may represent a schema that is 'referentially 552 complete', or 'referentially incomplete', indicated in the package 553 definition by the 'complete' flag. 555 If all import statements in all YANG modules included in the package 556 (either directly, or through included packages) can be resolved to a 557 module revision defined with the YANG package definition, then the 558 package is classified as referentially complete. Conversely, if one 559 or more import statements cannot be resolved to a module specified as 560 part of the package definition, then the package is classified as 561 referentially incomplete. 563 A package that represents the exact contents of a datastore schema 564 MUST always be referentially complete. 566 Referentially incomplete packages can be used, along with locally 567 scoped packages, to represent an update to a device's datastore 568 schema as part of an optional software hot fix. E.g., the base 569 software is made available as a complete globally scoped package. 570 The hot fix is made available as an incomplete globally scoped 571 package. A device's datastore schema can define a local package that 572 implements the base software package updated with the hot fix 573 package. 575 Referentially incomplete packages could also be used to group sets of 576 logically related modules together, but without requiring a fixed 577 dependency on all imported 'types' modules (e.g., iana-if- 578 types.yang), instead leaving the choice of specific revisions of 579 'types' modules to be resolved when the package definition is used. 581 5.5. Package name scoping and uniqueness 583 YANG package names can be globally unique, or locally scoped to a 584 particular server or device. 586 5.5.1. Globally scoped packages 588 The name given to a package MUST be globally unique, and it MUST 589 include an appropriate organization prefix in the name, equivalent to 590 YANG module naming conventions. 592 Ideally a YANG instance data file defining a particular package 593 version would be publicly available at one or more URLs. 595 5.5.2. Server scoped packages 597 Package definitions may be scoped to a particular server by setting 598 the 'is-local' leaf to true in the package definition. 600 Locally scoped packages MAY have a package name that is not globally 601 unique. 603 Locally scoped packages MAY have a definition that is not available 604 offline from the server in a YANG instance data file. 606 5.6. Submodules packages considerations 608 As defined in [RFC7950] and [I-D.ietf-netmod-yang-semver], YANG 609 conformance and versioning is specified in terms of particular 610 revisions of YANG modules rather than for individual submodules. 612 However, YANG package definitions also include the list of submodules 613 included by a module, primarily to provide a location of where the 614 submodule definition can be obtained from, allowing a schema to be 615 fully constructed from a YANG package instance data file definition. 617 5.7. Package tags 619 [I-D.ietf-netmod-module-tags] defines YANG module tags as a mechanism 620 to annotate a module definition with additional metadata. Tags MAY 621 also be associated to a package definition via the 'tags' leaf-list. 622 The tags use the same registry and definitions used by YANG module 623 tags. 625 5.8. YANG Package Usage Guidance 627 It is RECOMMENDED that organizations that publish YANG modules also 628 publish YANG package definition that group and version those modules 629 into units of related functionality. This increases 630 interoperability, by encouraging implementations to use the same 631 collections of YANG modules versions. Using packages also makes it 632 easier to understand relationship between modules, and enables 633 functionality to be described on a more abstract level than 634 individual modules. 636 5.8.1. Use of deviations in YANG packages 638 [RFC7950] section 5.6.3 defines deviations as the mechanism to allow 639 servers to indicate where they do not conform to a published YANG 640 module that is being implemented. 642 In cases where implementations contain deviations from published 643 packages, then those implementations SHOULD define a package that 644 includes both the published packages and all modules containing 645 deviations. This implementation specific package accurately reflects 646 the schema used by the device and allows clients to determine how the 647 implementation differs from the published package schema in an 648 offline consumable way, e.g., when published in an instance data file 649 (see section 6). 651 Organizations may wish to reuse YANG modules and YANG packages 652 published by other organizations for new functionality. Sometimes, 653 they may desire to modify the published YANG modules. However, they 654 MUST NOT use deviations in an attempt to achieve this because such 655 deviations cause two problems: 657 They prevent implementations from reporting their own deviations 658 for the same nodes. 660 They fracture the ecosystem by preventing implementations from 661 conforming to the standards specified by both organizations. This 662 hurts the interoperability in the YANG community, promotes 663 development of disconnected functional silos, and hurts creativity 664 in the market. 666 5.8.2. Use of features in YANG modules and YANG packages 668 The YANG language supports feature statements as the mechanism to 669 make parts of a schema optional. Published standard YANG modules 670 SHOULD make use of appropriate feature statements to provide 671 flexibility in how YANG modules may be used by implementations and 672 used by YANG modules published by other organizations. 674 YANG packages support 'mandatory features' which allow a package to 675 specify features that MUST be implemented by any conformant 676 implementation of the package as a mechanism to simplify and manage 677 the schema represented by a YANG package. 679 5.9. YANG package core definition 681 The ietf-yang-package-types.yang module defines a grouping to specify 682 the core elements of the YANG package structure that is used within 683 YANG package instance data files (ietf-yang-package-instance.yang) 684 and also on the server (ietf-yang-packages.yang). 686 The "ietf-yang-package-types" YANG module has the following 687 structure: 689 module: ietf-yang-package-types 691 grouping yang-pkg-identification-leafs 692 +-- name pkg-name 693 +-- version pkg-version 695 grouping yang-pkg-instance 696 +-- name pkg-name 697 +-- version pkg-version 698 +-- timestamp? yang:date-and-time 699 +-- organization? string 700 +-- contact? string 701 +-- description? string 702 +-- reference? string 703 +-- complete? boolean 704 +-- local? boolean 705 +-- tag* tags:tag 706 +-- mandatory-feature* scoped-feature 707 +-- included-package* [name version] 708 | +-- name pkg-name 709 | +-- version pkg-version 710 | +-- replaces-version* pkg-version 711 | +-- location* inet:uri 712 +-- module* [name] 713 | +-- name yang:yang-identifier 714 | +-- revision? rev:revision-date-or-label 715 | +-- replaces-revision* rev:revision-date-or-label 716 | +-- namespace? inet:uri 717 | +-- location* inet:uri 718 | +-- submodule* [name] 719 | +-- name? yang:yang-identifier 720 | +-- revision yang:revision-identifier 721 | +-- location* inet:uri 722 +-- import-only-module* [name revision] 723 +-- name? yang:yang-identifier 724 +-- revision? rev:revision-date-or-label 725 +-- replaces-revision* rev:revision-date-or-label 726 +-- namespace? inet:uri 727 +-- location* inet:uri 728 +-- submodule* [name] 729 +-- name? yang:yang-identifier 730 +-- revision yang:revision-identifier 731 +-- location* inet:uri 733 6. Package Instance Data Files 735 YANG packages SHOULD be available offline from the server, defined as 736 YANG instance data files [I-D.ietf-netmod-yang-instance-file-format] 737 using the schema below to define the package data. 739 The following rules apply to the format of the YANG package instance 740 files: 742 1. The file SHOULD be encoded in JSON. 744 2. The name of the file SHOULD follow the format "@.json". 747 3. The package name MUST be specified in both the instance-data-set 748 'name' and package 'name' leafs. 750 4. The 'description' field of the instance-data-set SHOULD be "YANG 751 package definition". 753 5. The 'timestamp', "organization', 'contact' fields are defined in 754 both the instance-data-set metadata and the YANG package 755 metadata. Package definitions SHOULD only define these fields as 756 part of the package definition. If any of these fields are 757 populated in the instance-data-set metadata then they MUST 758 contain the same value as the corresponding leaves in the package 759 definition. 761 6. The 'revision' list in the instance data file SHOULD NOT be used, 762 since versioning is handled by the package definition. 764 7. The instance data file for each version of a YANG package SHOULD 765 be made available at one of more locations accessible via URLs. 766 If one of the listed locations defines a definitive reference 767 implementation for the package definition then it MUST be listed 768 as the first entry in the list. 770 The "ietf-yang-package" YANG module has the following structure: 772 module: ietf-yang-package 774 structure package: 775 // Uses the yang-package-instance grouping defined in 776 // ietf-yang-package-types.yang 777 +-- name pkg-name 778 +-- version pkg-version 779 ... remainder of yang-package-instance grouping ... 781 7. Package Definitions on a Server 783 7.1. Package List 785 A top level 'packages' container holds the list of all versions of 786 all packages known to the server. Each list entry uses the common 787 package definition, but with the addition of package location that 788 cannot be contained within a offline package definition contained in 789 an instance data file. 791 The '/packages/package' list MAY include multiple versions of a 792 particular package. E.g. if the server is capable of allowing 793 clients to select which package versions should be used by the 794 server. 796 7.2. Tree diagram 798 The "ietf-yang-packages" YANG module has the following structure: 800 module: ietf-yang-packages 801 +--ro packages 802 +--ro package* [name version] 803 // Uses the yang-package-instance grouping defined in 804 // ietf-yang-package-types.yang, with location: 805 +--ro name pkg-name 806 +--ro version pkg-version 807 ... remainder of yang-package-instance grouping ... 808 +--ro location* inet:uri 810 8. YANG Library Package Bindings 812 The YANG packages module also augments YANG library to allow a server 813 to optionally indicate that a datastore schema is defined by a 814 package, or a union of compatible packages. Since packages can 815 generally be made available offline in instance data files, it may be 816 sufficient for a client to only check that a compatible version of 817 the package is implemented by the server without fetching either the 818 package definition, or downloading and comparing the full list of 819 modules and enabled features. 821 If a server indicates that a datastore schema maps to a particular 822 package, then it MUST exactly match the schema defined by that 823 package, taking into account enabled features and any deviations. 825 If a server cannot faithfully implement a package then it can define 826 a new package to accurately report what it does implement. The new 827 package can include the original package as an included package, and 828 the new package can define additional modules containing deviations 829 to the modules in the original package, allowing the new package to 830 accurately describe the server's behavior. There is no specific 831 mechanism provided to indicate that a mandatory-feature in package 832 definition is not supported on a server, but deviations MAY be used 833 to disable functionality predicated by an if-feature statement. 835 The "ietf-yl-packages" YANG module has the following structure: 837 module: ietf-yl-packages 838 augment /yanglib:yang-library/yanglib:schema: 839 +--ro package* [name version] 840 +--ro name -> /pkgs:packages/package/name 841 +--ro version leafref 843 9. YANG packages as schema for YANG instance data document 845 YANG package definitions can be used as the content schema definition 846 for YANG instance data files. When using a package-based content 847 schema, the name and version of the package MUST be specified, a 848 package URL to the package definition MAY also be provided. 850 The "ietf-yang-inst-data-pkg" YANG module has the following 851 structure: 853 module: ietf-yang-inst-data-pkg 855 augment-structure /yid:instance-data-set/yid:content-schema/yid:content-schema-spec: 856 +--:(pkg-schema) 857 +-- pkg-schema 858 +-- name pkg-name 859 +-- version pkg-version 860 +-- location* inet:uri 862 10. YANG Modules 864 The YANG module definitions for the modules described in the previous 865 sections. 867 868 file "ietf-yang-package-types#0.3.0-draft-ietf-netmod-yang-packages-03.yang" 869 module ietf-yang-package-types { 870 yang-version 1.1; 871 namespace "urn:ietf:params:xml:ns:yang:ietf-yang-package-types"; 872 prefix pkg-types; 874 import ietf-yang-revisions { 875 prefix rev; 876 reference 877 "XXXX: Updated YANG Module Revision Handling"; 878 } 879 import ietf-yang-types { 880 prefix yang; 881 rev:revision-or-derived "2019-07-21"; 882 reference 883 "RFC 6991bis: Common YANG Data Types."; 884 } 885 import ietf-inet-types { 886 prefix inet; 887 rev:revision-or-derived "2013-07-15"; 888 reference 889 "RFC 6991: Common YANG Data Types."; 890 } 891 import ietf-module-tags { 892 prefix tags; 893 reference 894 "RFC 8819: YANG Module Tags."; 895 } 897 organization 898 "IETF NETMOD (Network Modeling) Working Group"; 899 contact 900 "WG Web: 901 WG List: 903 Author: Rob Wilton 904 "; 905 description 906 "This module provides type and grouping definitions for YANG 907 packages. 909 Copyright (c) 2022 IETF Trust and the persons identified as 910 authors of the code. All rights reserved. 912 Redistribution and use in source and binary forms, with or 913 without modification, is permitted pursuant to, and subject 914 to the license terms contained in, the Revised BSD License 915 set forth in Section 4.c of the IETF Trust's Legal Provisions 916 Relating to IETF Documents 917 (https://trustee.ietf.org/license-info). 919 This version of this YANG module is part of RFC XXXX; see 920 the RFC itself for full legal notices. 922 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL 923 NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'NOT RECOMMENDED', 924 'MAY', and 'OPTIONAL' in this document are to be interpreted as 925 described in BCP 14 (RFC 2119) (RFC 8174) when, and only when, 926 they appear in all capitals, as shown here."; 928 // RFC Ed.: update the date below with the date of RFC publication 929 // and remove this note. 930 // RFC Ed.: replace XXXX with actual RFC number and remove this 931 // note. 933 revision 2022-03-04 { 934 rev:revision-label 0.3.0-draft-ietf-netmod-yang-packages-03; 935 description 936 "Initial revision"; 937 reference 938 "RFC XXXX: YANG Packages"; 939 } 941 /* 942 * Typedefs 943 */ 945 typedef pkg-name { 946 type yang:yang-identifier; 947 description 948 "Package names are typed as YANG identifiers."; 950 } 952 typedef pkg-version { 953 type rev:revision-date-or-label; 954 description 955 "Package versions SHOULD be a revision-label (e.g. perhaps a 956 YANG Semver version string). Package versions MAY also be a 957 revision-date"; 958 } 960 typedef pkg-identifier { 961 type rev:name-revision; 962 description 963 "Package identifiers combine a pkg-name and a pkg-version"; 964 } 966 typedef scoped-feature { 967 type string { 968 pattern '[a-zA-Z_][a-zA-Z0-9\-_.]*:[a-zA-Z_][a-zA-Z0-9\-_.]*'; 969 } 970 description 971 "Represents a feature name scoped to a particular module, 972 identified as the ':', where both 973 and are YANG identifier strings, 974 as defiend by Section 12 or RFC 6020."; 975 reference 976 "RFC XXXX, YANG Packages."; 977 } 979 /* 980 * Groupings 981 */ 983 grouping yang-pkg-identification-leafs { 984 description 985 "Parameters for identifying a specific version of a YANG 986 package"; 987 leaf name { 988 type pkg-name; 989 mandatory true; 990 description 991 "The YANG package name."; 992 } 993 leaf version { 994 type pkg-version; 995 mandatory true; 996 description 997 "Uniquely identies a particular version of a YANG package. 999 Follows the definition for revision labels defined in 1000 draft-verdt-nemod-yang-module-versioning, section XXX"; 1001 } 1002 } 1004 grouping yang-pkg-instance { 1005 description 1006 "Specifies the data node for a full YANG package instance 1007 represented either on a server or as a YANG instance data 1008 document."; 1009 uses yang-pkg-identification-leafs; 1010 leaf timestamp { 1011 type yang:date-and-time; 1012 description 1013 "An optional timestamp for when this package was created. 1014 This does not need to be unique across all versions of a 1015 package."; 1016 } 1017 leaf organization { 1018 type string; 1019 description 1020 "Organization responsible for this package"; 1021 } 1022 leaf contact { 1023 type string; 1024 description 1025 "Contact information for the person or organization to whom 1026 queries concerning this package should be sent."; 1027 } 1028 leaf description { 1029 type string; 1030 description 1031 "Provides a description of the package"; 1032 } 1033 leaf reference { 1034 type string; 1035 description 1036 "Allows for a reference for the package"; 1037 } 1038 leaf complete { 1039 type boolean; 1040 default "true"; 1041 description 1042 "Indicates whether the schema defined by this package is 1043 referentially complete. I.e. all module imports can be 1044 resolved to a module explicitly defined in this package or 1045 one of the included packages."; 1046 } 1047 leaf local { 1048 type boolean; 1049 default "false"; 1050 description 1051 "Defines that the package definition is local to the server, 1052 and the name of the package MAY not be unique, and the 1053 package definition MAY not be available in an offline file. 1055 Local packages can be used when the schema for the device 1056 can be changed at runtime through the addition or removal of 1057 software packages, or hot fixes."; 1058 } 1059 leaf-list tag { 1060 type tags:tag; 1061 description 1062 "Tags associated with a YANG package. Module tags defined in 1063 XXX, ietf-netmod-module-tags can be used here but with the 1064 modification that the tag applies to the entire package 1065 rather than a specific module. See the IANA 'YANG Module 1066 Tag Prefix' registry for reserved prefixes and the IANA 1067 'YANG Module IETF Tag' registry for IETF standard tags."; 1068 } 1069 leaf-list mandatory-feature { 1070 type scoped-feature; 1071 description 1072 "Lists features from any modules included in the package that 1073 MUST be supported by any server implementing the package. 1075 Features already specified in a 'mandatory-feature' list of 1076 any included package MUST also be supported by server 1077 implementations and do not need to be repeated in this list. 1079 All other features defined in modules included in the 1080 package are OPTIONAL to implement. 1082 Features are identified using :"; 1083 } 1084 list included-package { 1085 key "name version"; 1086 description 1087 "An entry in this list represents a package that is included 1088 as part of the package definition, or an indirectly included 1089 package that is changed in a non backwards compatible way. 1091 It can be used to resolve inclusion of conflicting package 1092 versions by explicitly specifying which package version is 1093 used. 1095 If included packages implement different revisions 1096 of the same module, then an explicit entry in the 1097 module list MUST be provided to select the specific module 1098 revision 'implemented' by this package definition. 1100 For import-only modules, the 'replaces-revision' leaf-list 1101 can be used to select the specific module revisions used by 1102 this package."; 1103 reference 1104 "XXX"; 1105 uses yang-pkg-identification-leafs; 1106 leaf-list replaces-version { 1107 type pkg-version; 1108 description 1109 "Gives the version of an included package version that 1110 is replaced by this included package version."; 1111 } 1112 leaf-list location { 1113 type inet:uri; 1114 description 1115 "Contains a URL that represents where an instance data file 1116 for this YANG package can be found. 1118 This leaf will only be present if there is a URL available 1119 for retrieval of the schema for this entry. 1121 If multiple locations are provided, then the first 1122 location in the leaf-list MUST be the definitive location 1123 that uniquely identifies this package"; 1124 } 1125 } 1126 list module { 1127 key "name"; 1128 description 1129 "An entry in this list represents a module that must be 1130 implemented by a server implementing this package, as per 1131 RFC 7950 section 5.6.5, with a particular set of supported 1132 features and deviations. 1134 A entry in this list overrides any module revision 1135 'implemented' by an included package. Any replaced module 1136 revision SHOULD also be listed in the 'replaces-revision' 1137 list."; 1138 reference 1139 "RFC 7950: The YANG 1.1 Data Modeling Language."; 1140 leaf name { 1141 type yang:yang-identifier; 1142 mandatory true; 1143 description 1144 "The YANG module name."; 1145 } 1146 leaf revision { 1147 type rev:revision-date-or-label; 1148 description 1149 "The YANG module revision date or revision-label. 1151 If no revision statement is present in the YANG module, 1152 this leaf is not instantiated."; 1153 } 1154 leaf-list replaces-revision { 1155 type rev:revision-date-or-label; 1156 description 1157 "Gives the revision of an module (implemented or 1158 import-only) defined in an included package that is 1159 replaced by this implemented module revision."; 1160 } 1161 leaf namespace { 1162 type inet:uri; 1163 description 1164 "The XML namespace identifier for this module."; 1165 } 1166 leaf-list location { 1167 type inet:uri; 1168 description 1169 "Contains a URL that represents the YANG schema resource 1170 for this module. 1172 This leaf will only be present if there is a URL available 1173 for retrieval of the schema for this entry."; 1174 } 1175 list submodule { 1176 key "name"; 1177 description 1178 "Each entry represents one submodule within the 1179 parent module."; 1180 leaf name { 1181 type yang:yang-identifier; 1182 description 1183 "The YANG submodule name."; 1184 } 1185 leaf revision { 1186 type rev:revision-date-or-label; 1187 mandatory true; 1188 description 1189 "The YANG submodule revision date or revision-label. 1191 If the parent module include statement for this submodule 1192 includes a revision date then it MUST match the revision 1193 date specified here or it MUST match the revision-date 1194 associated with the revision-label specified here."; 1195 } 1196 leaf-list location { 1197 type inet:uri; 1198 description 1199 "Contains a URL that represents the YANG schema resource 1200 for this submodule. 1202 This leaf will only be present if there is a URL 1203 available for retrieval of the schema for this entry."; 1204 } 1205 } 1206 } 1207 list import-only-module { 1208 key "name revision"; 1209 description 1210 "An entry in this list indicates that the server imports 1211 reusable definitions from the specified revision of the 1212 module, but does not implement any protocol accessible 1213 objects from this revision. 1215 Multiple entries for the same module name MAY exist. This 1216 can occur if multiple modules import the same module, but 1217 specify different revision-dates in the import statements."; 1218 leaf name { 1219 type yang:yang-identifier; 1220 description 1221 "The YANG module name."; 1222 } 1223 leaf revision { 1224 type rev:revision-date-or-label; 1225 description 1226 "The YANG module revision date or revision-label. 1228 If no revision statement is present in the YANG module, 1229 this leaf is not instantiated."; 1230 } 1231 leaf-list replaces-revision { 1232 type rev:revision-date-or-label; 1233 description 1234 "Gives the revision of an import-only-module defined in an 1235 included package that is replaced by this 1236 import-only-module revision."; 1237 } 1238 leaf namespace { 1239 type inet:uri; 1240 description 1241 "The XML namespace identifier for this module."; 1242 } 1243 leaf-list location { 1244 type inet:uri; 1245 description 1246 "Contains a URL that represents the YANG schema resource 1247 for this module. 1249 This leaf will only be present if there is a URL available 1250 for retrieval of the schema for this entry."; 1251 } 1252 list submodule { 1253 key "name"; 1254 description 1255 "Each entry represents one submodule within the 1256 parent module."; 1257 leaf name { 1258 type yang:yang-identifier; 1259 description 1260 "The YANG submodule name."; 1261 } 1262 leaf revision { 1263 type yang:revision-identifier; 1264 mandatory true; 1265 description 1266 "The YANG submodule revision date. If the parent module 1267 include statement for this submodule includes a revision 1268 date then it MUST match this leaf's value."; 1269 } 1270 leaf-list location { 1271 type inet:uri; 1272 description 1273 "Contains a URL that represents the YANG schema resource 1274 for this submodule. 1276 This leaf will only be present if there is a URL 1277 available for retrieval of the schema for this entry."; 1278 } 1279 } 1280 } 1281 } 1282 } 1283 1284 1285 file "ietf-yang-package-instance#0.3.0-draft-ietf-netmod-yang-packages-03.yang" 1286 module ietf-yang-package-instance { 1287 yang-version 1.1; 1288 namespace "urn:ietf:params:xml:ns:yang:ietf-yang-package-instance"; 1289 prefix pkg-inst; 1291 import ietf-yang-revisions { 1292 prefix rev; 1293 reference 1294 "XXXX: Updated YANG Module Revision Handling"; 1295 } 1296 import ietf-yang-package-types { 1297 prefix pkg-types; 1298 rev:revision-or-derived "0.2.0"; 1299 reference 1300 "RFC XXX: this RFC."; 1301 } 1302 import ietf-yang-structure-ext { 1303 prefix sx; 1304 reference 1305 "RFC 8791: YANG Data Structure Extensions."; 1306 } 1308 organization 1309 "IETF NETMOD (Network Modeling) Working Group"; 1310 contact 1311 "WG Web: 1312 WG List: 1314 Author: Rob Wilton 1315 "; 1316 description 1317 "This module provides a definition of a YANG package, which is 1318 used as the content schema for an YANG instance data document specifying 1319 a YANG package. 1321 Copyright (c) 2022 IETF Trust and the persons identified as 1322 authors of the code. All rights reserved. 1324 Redistribution and use in source and binary forms, with or 1325 without modification, is permitted pursuant to, and subject 1326 to the license terms contained in, the Revised BSD License 1327 set forth in Section 4.c of the IETF Trust's Legal Provisions 1328 Relating to IETF Documents 1329 (https://trustee.ietf.org/license-info). 1331 This version of this YANG module is part of RFC XXXX; see 1332 the RFC itself for full legal notices. 1334 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL 1335 NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'NOT RECOMMENDED', 1336 'MAY', and 'OPTIONAL' in this document are to be interpreted as 1337 described in BCP 14 (RFC 2119) (RFC 8174) when, and only when, 1338 they appear in all capitals, as shown here."; 1340 // RFC Ed.: update the date below with the date of RFC publication 1341 // and remove this note. 1342 // RFC Ed.: replace XXXX with actual RFC number and remove this 1343 // note. 1345 revision 2022-03-04 { 1346 rev:revision-label 0.3.0-draft-ietf-netmod-yang-packages-03; 1347 description 1348 "Initial revision"; 1349 reference 1350 "RFC XXXX: YANG Packages"; 1351 } 1353 /* 1354 * Top-level structure 1355 */ 1356 sx:structure "package" { 1357 description 1358 "Defines the YANG package structure for use in a YANG instance 1359 data document."; 1360 uses pkg-types:yang-pkg-instance; 1361 } 1362 } 1363 1365 1366 file "ietf-yang-packages#0.3.0-draft-ietf-netmod-yang-packages-03.yang" 1367 module ietf-yang-packages { 1368 yang-version 1.1; 1369 namespace "urn:ietf:params:xml:ns:yang:ietf-yang-packages"; 1370 prefix pkgs; 1372 import ietf-yang-revisions { 1373 prefix rev; 1374 reference 1375 "XXXX: Updated YANG Module Revision Handling"; 1376 } 1377 import ietf-yang-package-types { 1378 prefix pkg-types; 1379 rev:revision-or-derived "0.2.0"; 1380 reference 1381 "RFC XXX: this RFC."; 1382 } 1383 import ietf-inet-types { 1384 prefix inet; 1385 rev:revision-or-derived "2013-07-15"; 1386 reference 1387 "RFC 6991: Common YANG Data Types."; 1388 } 1390 organization 1391 "IETF NETMOD (Network Modeling) Working Group"; 1392 contact 1393 "WG Web: 1394 WG List: 1396 Author: Rob Wilton 1397 "; 1398 description 1399 "This module defines YANG packages on a server implementation. 1401 Copyright (c) 2022 IETF Trust and the persons identified as 1402 authors of the code. All rights reserved. 1404 Redistribution and use in source and binary forms, with or 1405 without modification, is permitted pursuant to, and subject 1406 to the license terms contained in, the Revised BSD License 1407 set forth in Section 4.c of the IETF Trust's Legal Provisions 1408 Relating to IETF Documents 1409 (https://trustee.ietf.org/license-info). 1411 This version of this YANG module is part of RFC XXXX; see 1412 the RFC itself for full legal notices. 1414 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL 1415 NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'NOT RECOMMENDED', 1416 'MAY', and 'OPTIONAL' in this document are to be interpreted as 1417 described in BCP 14 (RFC 2119) (RFC 8174) when, and only when, 1418 they appear in all capitals, as shown here."; 1420 // RFC Ed.: update the date below with the date of RFC publication 1421 // and remove this note. 1422 // RFC Ed.: replace XXXX with actual RFC number and remove this 1423 // note. 1425 revision 2022-03-04 { 1426 rev:revision-label 0.3.0-draft-ietf-netmod-yang-packages-03; 1427 description 1428 "Initial revision"; 1429 reference 1430 "RFC XXXX: YANG Packages"; 1431 } 1433 /* 1434 * Groupings 1435 */ 1437 grouping yang-pkg-ref { 1438 description 1439 "Defines the leaves used to reference a single YANG package"; 1440 leaf name { 1441 type leafref { 1442 path "/pkgs:packages/pkgs:package/pkgs:name"; 1443 } 1444 description 1445 "The name of the references package."; 1446 } 1447 leaf version { 1448 type leafref { 1449 path "/pkgs:packages" 1450 + '/pkgs:package[pkgs:name = current()/../name]' 1451 + "/pkgs:version"; 1452 } 1453 description 1454 "The version of the referenced package."; 1455 } 1456 } 1458 grouping yang-ds-pkg-ref { 1459 description 1460 "Defines the list used to reference a set of YANG packages that 1461 collectively represent a datastore schema."; 1462 list package { 1463 key "name version"; 1464 description 1465 "Identifies the YANG packages that collectively defines the 1466 schema for the associated datastore. 1468 The datastore schema is defined as the union of all 1469 referenced packages, that MUST represent a referentially 1470 complete schema. 1472 All of the referenced packages must be compatible with no 1473 conflicting module versions or dependencies."; 1474 uses yang-pkg-ref; 1475 } 1477 } 1479 /* 1480 * Top level data nodes. 1481 */ 1483 container packages { 1484 config false; 1485 description 1486 "All YANG package definitions"; 1487 list package { 1488 key "name version"; 1489 description 1490 "YANG package instance"; 1491 uses pkg-types:yang-pkg-instance; 1492 leaf-list location { 1493 type inet:uri; 1494 description 1495 "Contains a URL that represents where an instance data file 1496 for this YANG package can be found. 1498 This leaf will only be present if there is a URL available 1499 for retrieval of the schema for this entry. 1501 If multiple locations are provided, then the first 1502 location in the leaf-list MUST be the definitive location 1503 that uniquely identifies this package"; 1504 } 1505 } 1506 } 1507 } 1508 1510 1511 file "ietf-yl-package#0.3.0-draft-ietf-netmod-yang-packages-03.yang" 1512 module ietf-yl-packages { 1513 yang-version 1.1; 1514 namespace "urn:ietf:params:xml:ns:yang:ietf-yl-packages"; 1515 prefix yl-pkgs; 1517 import ietf-yang-revisions { 1518 prefix rev; 1519 reference 1520 "XXXX: Updated YANG Module Revision Handling"; 1521 } 1522 import ietf-yang-packages { 1523 prefix pkgs; 1524 rev:revision-or-derived "0.2.0"; 1525 reference 1526 "RFC XXX: YANG Packages."; 1527 } 1528 import ietf-yang-library { 1529 prefix yanglib; 1530 rev:revision-or-derived "2019-01-04"; 1531 reference 1532 "RFC 8525: YANG Library"; 1533 } 1535 organization 1536 "IETF NETMOD (Network Modeling) Working Group"; 1537 contact 1538 "WG Web: 1539 WG List: 1541 Author: Rob Wilton 1542 "; 1543 description 1544 "This module provides defined augmentations to YANG library to 1545 allow a server to report YANG package information. 1547 Copyright (c) 2022 IETF Trust and the persons identified as 1548 authors of the code. All rights reserved. 1550 Redistribution and use in source and binary forms, with or 1551 without modification, is permitted pursuant to, and subject 1552 to the license terms contained in, the Revised BSD License 1553 set forth in Section 4.c of the IETF Trust's Legal Provisions 1554 Relating to IETF Documents 1555 (https://trustee.ietf.org/license-info). 1557 This version of this YANG module is part of RFC XXXX; see 1558 the RFC itself for full legal notices. 1560 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL 1561 NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'NOT RECOMMENDED', 1562 'MAY', and 'OPTIONAL' in this document are to be interpreted as 1563 described in BCP 14 (RFC 2119) (RFC 8174) when, and only when, 1564 they appear in all capitals, as shown here."; 1566 // RFC Ed.: update the date below with the date of RFC publication 1567 // and remove this note. 1568 // RFC Ed.: replace XXXX with actual RFC number and remove this 1569 // note. 1571 revision 2022-03-04 { 1572 rev:revision-label 0.3.0-draft-ietf-netmod-yang-packages-03; 1573 description 1574 "Initial revision"; 1575 reference 1576 "RFC XXXX: YANG Packages"; 1577 } 1579 /* 1580 * Augmentations 1581 */ 1583 augment "/yanglib:yang-library/yanglib:schema" { 1584 description 1585 "Allow datastore schema to be related to a set of YANG 1586 packages"; 1587 uses pkgs:yang-ds-pkg-ref; 1588 } 1589 } 1590 1592 1593 file "ietf-yang-inst-data-pkg#0.3.0-draft-ietf-netmod-yang-packages-03.yang" 1594 module ietf-yang-inst-data-pkg { 1595 yang-version 1.1; 1596 namespace "urn:ietf:params:xml:ns:yang:ietf-yang-inst-data-pkg"; 1597 prefix yid-pkg; 1599 import ietf-yang-revisions { 1600 prefix rev; 1601 reference 1602 "XXXX: Updated YANG Module Revision Handling"; 1603 } 1604 import ietf-yang-package-types { 1605 prefix pkg-types; 1606 rev:revision-or-derived "0.2.0"; 1607 reference 1608 "RFC XXX: this RFC."; 1609 } 1610 import ietf-yang-structure-ext { 1611 prefix sx; 1612 reference 1613 "RFC 8791: YANG Data Structure Extensions."; 1614 } 1615 import ietf-yang-instance-data { 1616 prefix yid; 1617 reference 1618 "RFC 9195: A File Format for YANG Instance Data."; 1619 } 1620 import ietf-inet-types { 1621 prefix inet; 1622 reference 1623 "RFC 6991: Common YANG Data Types."; 1624 } 1626 organization 1627 "IETF NETMOD (Network Modeling) Working Group"; 1628 contact 1629 "WG Web: 1630 WG List: 1632 Author: Rob Wilton 1633 "; 1634 description 1635 "The module augments ietf-yang-instance-data to allow package 1636 definitions to be used to define content schema in YANG instance data 1637 documents. 1639 Copyright (c) 2022 IETF Trust and the persons identified as 1640 authors of the code. All rights reserved. 1642 Redistribution and use in source and binary forms, with or 1643 without modification, is permitted pursuant to, and subject 1644 to the license terms contained in, the Revised BSD License 1645 set forth in Section 4.c of the IETF Trust's Legal Provisions 1646 Relating to IETF Documents 1647 (https://trustee.ietf.org/license-info). 1649 This version of this YANG module is part of RFC XXXX; see 1650 the RFC itself for full legal notices. 1652 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL 1653 NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'NOT RECOMMENDED', 1654 'MAY', and 'OPTIONAL' in this document are to be interpreted as 1655 described in BCP 14 (RFC 2119) (RFC 8174) when, and only when, 1656 they appear in all capitals, as shown here."; 1658 // RFC Ed.: update the date below with the date of RFC publication 1659 // and remove this note. 1660 // RFC Ed.: replace XXXX with actual RFC number and remove this 1661 // note. 1663 revision 2022-03-04 { 1664 rev:revision-label 0.3.0-draft-ietf-netmod-yang-packages-03; 1665 description 1666 "Initial revision"; 1667 reference 1668 "RFC XXXX: YANG Packages"; 1669 } 1671 /* 1672 * Augmentations 1673 */ 1674 sx:augment-structure "/yid:instance-data-set/yid:content-schema/yid:content-schema-spec" { 1675 description 1676 "Add package reference to instance data set schema 1677 specification"; 1678 case pkg-schema { 1679 container pkg-schema { 1680 uses pkg-types:yang-pkg-identification-leafs; 1681 leaf-list location { 1682 type inet:uri; 1683 description 1684 "Contains a URL that represents where an instance data 1685 file for this YANG package can be found. 1687 This leaf will only be present if there is a URL 1688 available for retrieval of the schema for this entry. 1690 If multiple locations are provided, then the first 1691 location in the leaf-list MUST be the definitive 1692 location that uniquely identifies this package"; 1693 } 1694 } 1695 } 1696 } 1697 } 1698 1700 11. Security Considerations 1702 The YANG modules specified in this document defines a schema for data 1703 that is accessed by network management protocols such as NETCONF 1704 [RFC6241] or RESTCONF [RFC8040]. The lowest NETCONF layer is the 1705 secure transport layer, and the mandatory-to-implement secure 1706 transport is Secure Shell (SSH) [RFC6242]. The lowest RESTCONF layer 1707 is HTTPS, and the mandatory-to-implement secure transport is TLS 1708 [RFC5246]. 1710 The NETCONF access control model [RFC6536] provides the means to 1711 restrict access for particular NETCONF or RESTCONF users to a 1712 preconfigured subset of all available NETCONF or RESTCONF protocol 1713 operations and content. 1715 Similarly to YANG library [I-D.ietf-netconf-rfc7895bis], some of the 1716 readable data nodes in these YANG modules may be considered sensitive 1717 or vulnerable in some network environments. It is thus important to 1718 control read access (e.g., via get, get-config, or notification) to 1719 these data nodes. 1721 One additional key different to YANG library, is that the 'ietf-yang- 1722 package' YANG module defines a schema to allow YANG packages to be 1723 defined in YANG instance data files, that are outside the security 1724 controls of the network management protocols. Hence, it is important 1725 to also consider controlling access to these package instance data 1726 files to restrict access to sensitive information. 1728 As per the YANG library security considerations, the module, revision 1729 information in YANG packages may help an attacker identify the server 1730 capabilities and server implementations with known bugs since the set 1731 of YANG modules supported by a server may reveal the kind of device 1732 and the manufacturer of the device. Server vulnerabilities may be 1733 specific to particular modules, module revisions, module features, or 1734 even module deviations. For example, if a particular operation on a 1735 particular data node is known to cause a server to crash or 1736 significantly degrade device performance, then the YANG packages 1737 information will help an attacker identify server implementations 1738 with such a defect, in order to launch a denial-of-service attack on 1739 the device. 1741 12. IANA Considerations 1743 It is expected that a central registry of standard YANG package 1744 definitions is required to support this solution. 1746 It is unclear whether an IANA registry is also required to manage 1747 specific package versions. It is highly desirable to have a specific 1748 canonical location, under IETF control, where the definitive YANG 1749 package versions can be obtained from. 1751 This document requests IANA to registers a URI in the "IETF XML 1752 Registry" [RFC3688]. Following the format in RFC 3688, the following 1753 registrations are requested. 1755 URI: urn:ietf:params:xml:ns:yang:ietf-yang-package-types.yang 1756 Registrant Contact: The IESG. 1757 XML: N/A, the requested URI is an XML namespace. 1759 URI: urn:ietf:params:xml:ns:yang:ietf-yang-package-instance.yang 1760 Registrant Contact: The IESG. 1761 XML: N/A, the requested URI is an XML namespace. 1763 URI: urn:ietf:params:xml:ns:yang:ietf-yang-packages.yang 1764 Registrant Contact: The IESG. 1765 XML: N/A, the requested URI is an XML namespace. 1767 URI: urn:ietf:params:xml:ns:yang:ietf-yl-packages.yang 1768 Registrant Contact: The IESG. 1769 XML: N/A, the requested URI is an XML namespace. 1771 URI: urn:ietf:params:xml:ns:yang:ietf-yang-inst-data-pkg.yang 1772 Registrant Contact: The IESG. 1773 XML: N/A, the requested URI is an XML namespace. 1775 This document requests that the following YANG modules are added in 1776 the "YANG Module Names" registry [RFC6020]: 1778 Name: ietf-yang-package-types.yang 1779 Namespace: urn:ietf:params:xml:ns:yang:ietf-yang-package- 1780 types.yang 1781 Prefix: pkg-types 1782 Reference: RFC XXXX 1784 Name: ietf-yang-package-instance.yang 1785 Namespace: urn:ietf:params:xml:ns:yang:ietf-yang-package- 1786 instance.yang 1787 Prefix: pkg-inst 1788 Reference: RFC XXXX 1790 Name: ietf-yang-packages.yang 1791 Namespace: urn:ietf:params:xml:ns:yang:ietf-yang-packages.yang 1792 Prefix: pkgs 1793 Reference: RFC XXXX 1795 Name: ietf-yl-packages.yang 1796 Namespace: urn:ietf:params:xml:ns:yang:ietf-yl-packages.yang 1797 Prefix: yl-pkgs 1798 Reference: RFC XXXX 1800 Name: ietf-yang-inst-data-pkg.yang 1801 Namespace: urn:ietf:params:xml:ns:yang:ietf-yang-inst-data- 1802 pkg.yang 1803 Prefix: yid-pkg 1804 Reference: RFC XXXX 1806 13. Open Questions/Issues 1808 All issues, along with the draft text, are currently being tracked at 1809 https://github.com/rgwilton/YANG-Packages-Draft/issues/ 1811 14. Acknowledgements 1813 Feedback helping shape this document has kindly been provided by Andy 1814 Bierman, James Cumming, Mahesh Jethanandani, Balazs Lengyel, Ladislav 1815 Lhotka,and Jan Lindblad. 1817 15. References 1819 15.1. Normative References 1821 [I-D.ietf-netconf-rfc7895bis] 1822 Bierman, A., Bjorklund, M., Schoenwaelder, J., Watsen, K., 1823 and R. Wilton, "YANG Library", Work in Progress, Internet- 1824 Draft, draft-ietf-netconf-rfc7895bis-07, 17 October 2018, 1825 . 1828 [I-D.ietf-netmod-module-tags] 1829 Hopps, C., Berger, L., and D. Bogdanovic, "YANG Module 1830 Tags", Work in Progress, Internet-Draft, draft-ietf- 1831 netmod-module-tags-10, 29 February 2020, 1832 . 1835 [I-D.ietf-netmod-yang-data-ext] 1836 Bierman, A., Bjorklund, M., and K. Watsen, "YANG Data 1837 Structure Extensions", Work in Progress, Internet-Draft, 1838 draft-ietf-netmod-yang-data-ext-05, 9 December 2019, 1839 . 1842 [I-D.ietf-netmod-yang-instance-file-format] 1843 Lengyel, B. and B. Claise, "A File Format for YANG 1844 Instance Data", Work in Progress, Internet-Draft, draft- 1845 ietf-netmod-yang-instance-file-format-21, 8 October 2021, 1846 . 1849 [I-D.ietf-netmod-yang-module-versioning] 1850 Wilton, R., Rahman, R., Lengyel, B., Clarke, J., and J. 1851 Sterne, "Updated YANG Module Revision Handling", Work in 1852 Progress, Internet-Draft, draft-ietf-netmod-yang-module- 1853 versioning-05, 8 November 2021, 1854 . 1857 [I-D.ietf-netmod-yang-semver] 1858 Clarke, J., Wilton, R., Rahman, R., Lengyel, B., Sterne, 1859 J., and B. Claise, "YANG Semantic Versioning", Work in 1860 Progress, Internet-Draft, draft-ietf-netmod-yang-semver- 1861 06, 30 November 2021, . 1864 [I-D.ietf-netmod-yang-solutions] 1865 Wilton, R., "YANG Versioning Solution Overview", Work in 1866 Progress, Internet-Draft, draft-ietf-netmod-yang- 1867 solutions-01, 2 November 2020, 1868 . 1871 [I-D.ietf-netmod-yang-ver-selection] 1872 Wilton, R., Rahman, R., Clarke, J., Sterne, J., and B. Wu, 1873 "YANG Schema Selection", Work in Progress, Internet-Draft, 1874 draft-ietf-netmod-yang-ver-selection-00, 17 March 2020, 1875 . 1878 [I-D.ietf-netmod-yang-versioning-reqs] 1879 Clarke, J., "YANG Module Versioning Requirements", Work in 1880 Progress, Internet-Draft, draft-ietf-netmod-yang- 1881 versioning-reqs-06, 6 January 2022, 1882 . 1885 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1886 Requirement Levels", BCP 14, RFC 2119, 1887 DOI 10.17487/RFC2119, March 1997, 1888 . 1890 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 1891 DOI 10.17487/RFC3688, January 2004, 1892 . 1894 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 1895 (TLS) Protocol Version 1.2", RFC 5246, 1896 DOI 10.17487/RFC5246, August 2008, 1897 . 1899 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 1900 the Network Configuration Protocol (NETCONF)", RFC 6020, 1901 DOI 10.17487/RFC6020, October 2010, 1902 . 1904 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 1905 and A. Bierman, Ed., "Network Configuration Protocol 1906 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 1907 . 1909 [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure 1910 Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011, 1911 . 1913 [RFC6536] Bierman, A. and M. Bjorklund, "Network Configuration 1914 Protocol (NETCONF) Access Control Model", RFC 6536, 1915 DOI 10.17487/RFC6536, March 2012, 1916 . 1918 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 1919 RFC 7950, DOI 10.17487/RFC7950, August 2016, 1920 . 1922 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 1923 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 1924 . 1926 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1927 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1928 May 2017, . 1930 [RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 1931 and R. Wilton, "Network Management Datastore Architecture 1932 (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018, 1933 . 1935 [RFC8525] Bierman, A., Bjorklund, M., Schoenwaelder, J., Watsen, K., 1936 and R. Wilton, "YANG Library", RFC 8525, 1937 DOI 10.17487/RFC8525, March 2019, 1938 . 1940 [RFC8791] Bierman, A., Björklund, M., and K. Watsen, "YANG Data 1941 Structure Extensions", RFC 8791, DOI 10.17487/RFC8791, 1942 June 2020, . 1944 15.2. Informative References 1946 [I-D.bierman-netmod-yang-package] 1947 Bierman, A., "The YANG Package Statement", Work in 1948 Progress, Internet-Draft, draft-bierman-netmod-yang- 1949 package-00, 6 July 2015, . 1952 [I-D.ietf-netmod-artwork-folding] 1953 Watsen, K., Auerswald, E., Farrel, A., and Q. Wu, 1954 "Handling Long Lines in Content of Internet-Drafts and 1955 RFCs", Work in Progress, Internet-Draft, draft-ietf- 1956 netmod-artwork-folding-12, 20 January 2020, 1957 . 1960 [openconfigsemver] 1961 "Semantic Versioning for OpenConfig Models", 1962 . 1964 [RFC8199] Bogdanovic, D., Claise, B., and C. Moberg, "YANG Module 1965 Classification", RFC 8199, DOI 10.17487/RFC8199, July 1966 2017, . 1968 Appendix A. Examples 1970 This section provides various examples of YANG packages, and as such 1971 this text is non-normative. The purpose of the examples is to only 1972 illustrate the file format of YANG packages, and how package 1973 dependencies work. It does not imply that such packages will be 1974 defined by IETF, or which modules would be included in those packages 1975 even if they were defined. For brevity, the examples exclude 1976 namespace declarations, and use a shortened URL of "tiny.cc/ietf- 1977 yang" as a replacement for 1978 "https://raw.githubusercontent.com/YangModels/yang/master/standard/ 1979 ietf/RFC". 1981 A.1. Example IETF Network Device YANG package 1983 This section provides an instance data file example of an IETF 1984 Network Device YANG package formatted in JSON. 1986 This example package is intended to represent the standard set of 1987 YANG modules, with import dependencies, to implement a basic network 1988 device without any dynamic routing or layer 2 services. E.g., it 1989 includes functionality such as system information, interface and 1990 basic IP configuration. 1992 As for all YANG packages, all import dependencies are fully resolved. 1993 Because this example uses YANG modules that have been standardized 1994 before YANG semantic versioning, the modules are referenced by 1995 revision date rather than revision number. 1997 file "example-ietf-network-device-pkg.json" 1998 ========= NOTE: '\' line wrapping per BCP XX (RFC XXXX) =========== 2000 { 2001 "ietf-yang-instance-data:instance-data-set": { 2002 "name": "example-ietf-network-device-pkg", 2003 "content-schema": { 2004 "pkg-schema": { 2005 "name": "ietf-yang-package-defn-pkg", 2006 "version": "0.1.0" 2007 } 2008 }, 2009 "description": "YANG package definition", 2010 "content-data": { 2011 "ietf-yang-package-instance:yang-package": { 2012 "name": "example-ietf-network-device-pkg", 2013 "version": "1.1.2", 2014 "timestamp": "2018-12-13T17:00:00Z", 2015 "organization": "IETF NETMOD Working Group", 2016 "contact" : "WG Web: , \ 2017 WG List: ", 2018 "description": "Example IETF network device YANG package.\ 2019 \ 2020 This package defines a small sample set of \ 2021 YANG modules that could represent the basic set of \ 2022 modules that a standard network device might be expected \ 2023 to support.", 2024 "reference": "XXX, draft-rwilton-netmod-yang-packages", 2025 "location": [ "file://example.org/yang/packages/\ 2026 ietf-network-device@v1.1.2.json" ], 2027 "module": [ 2028 { 2029 "name": "iana-crypt-hash", 2030 "revision": "2014-08-06", 2031 "location": [ "https://tiny.cc/ietf-yang/\ 2032 iana-crypt-hash%402014-08-06.yang" ], 2033 }, 2034 { 2035 "name": "ietf-system", 2036 "revision": "2014-08-06", 2037 "location": [ "https://tiny.cc/ietf-yang/\ 2038 ietf-system%402014-08-06.yang" ], 2039 }, 2040 { 2041 "name": "ietf-interfaces", 2042 "revision": "2018-02-20", 2043 "location": [ "https://tiny.cc/ietf-yang/\ 2044 ietf-interfaces%402018-02-20.yang" ], 2046 }, 2047 { 2048 "name": "ietf-netconf-acm", 2049 "revision": "2018-02-14", 2050 "location": [ "https://tiny.cc/ietf-yang/\ 2051 ietf-netconf-acm%402018-02-14.yang" ], 2052 }, 2053 { 2054 "name": "ietf-key-chain", 2055 "revision": "2017-06-15", 2056 "location": [ "https://tiny.cc/ietf-yang/\ 2057 ietf-key-chain@2017-06-15.yang" ], 2058 }, 2059 { 2060 "name": "ietf-ip", 2061 "revision": "2018-02-22", 2062 "location": [ "https://tiny.cc/ietf-yang/\ 2063 ietf-ip%402018-02-22.yang" ], 2064 } 2065 ], 2066 "import-only-module": [ 2067 { 2068 "name": "ietf-yang-types", 2069 "revision": "2013-07-15", 2070 "location": [ "https://tiny.cc/ietf-yang/\ 2071 ietf-yang-types%402013-07-15.yang" ], 2072 }, 2073 { 2074 "name": "ietf-inet-types", 2075 "revision": "2013-07-15", 2076 "location": [ "https://tiny.cc/ietf-yang/\ 2077 ietf-inet-types%402013-07-15.yang" ], 2078 } 2079 ] 2080 } 2081 } 2082 } 2083 } 2084 2086 A.2. Example IETF Basic Routing YANG package 2088 This section provides an instance data file example of a basic IETF 2089 Routing YANG package formatted in JSON. 2091 This example package is intended to represent the standard set of 2092 YANG modules, with import dependencies, that builds upon the example- 2093 ietf-network-device YANG package to add support for basic dynamic 2094 routing and ACLs. 2096 As for all YANG packages, all import dependencies are fully resolved. 2097 Because this example uses YANG modules that have been standardized 2098 before YANG semantic versioning, they modules are referenced by 2099 revision date rather than revision number. Locations have been 2100 excluded where they are not currently known, e.g., for YANG modules 2101 defined in IETF drafts. In a normal YANG package, locations would be 2102 expected to be provided for all YANG modules. 2104 file "example-ietf-routing-pkg.json" 2105 ========== NOTE: '\' line wrapping per BCP XX (RFC XXXX) =========== 2107 { 2108 "ietf-yang-instance-data:instance-data-set": { 2109 "name": "example-ietf-routing-pkg", 2110 "content-schema": { 2111 "pkg-schema": { 2112 "name": "ietf-yang-package-defn-pkg", 2113 "version": "0.1.0" 2114 } 2115 }, 2116 "description": "YANG package definition", 2117 "content-data": { 2118 "ietf-yang-package-instance:yang-package": { 2119 "name": "example-ietf-routing", 2120 "version": "1.3.1", 2121 "timestamp": "2018-12-13T17:00:00Z", 2122 "description": "This package defines a small sample set of \ 2123 IETF routing YANG modules that could represent the set of \ 2124 IETF routing functionality that a basic IP network device \ 2125 might be expected to support.", 2126 "reference": "XXX, draft-rwilton-netmod-yang-packages", 2127 "imported-packages": [ 2128 { 2129 "name": "ietf-network-device", 2130 "version": "1.1.2", 2131 "location": [ "http://example.org/yang/packages/\ 2132 ietf-network-device@v1.1.2.json" ], 2133 } 2134 ], 2135 "module": [ 2136 { 2137 "name": "ietf-routing", 2138 "revision": "2018-03-13", 2139 "location": [ "https://tiny.cc/ietf-yang/\ 2140 ietf-routing@2018-03-13.yang" ], 2141 }, 2142 { 2143 "name": "ietf-ipv4-unicast-routing", 2144 "revision": "2018-03-13", 2145 "location": [ "https://tiny.cc/ietf-yang/\ 2146 ietf-ipv4-unicast-routing@2018-03-13.yang" ], 2147 }, 2148 { 2149 "name": "ietf-ipv6-unicast-routing", 2150 "revision": "2018-03-13", 2151 "location": [ "https://tiny.cc/ietf-yang/\ 2152 ietf-ipv6-unicast-routing@2018-03-13.yang" ], 2153 }, 2154 { 2155 "name": "ietf-isis", 2156 "revision": "2018-12-11", 2157 "location": [ "https://tiny.cc/ietf-yang/\ 2158 " ], 2159 }, 2160 { 2161 "name": "ietf-interfaces-common", 2162 "revision": "2018-07-02", 2163 "location": [ "https://tiny.cc/ietf-yang/\ 2164 " ], 2165 }, 2166 { 2167 "name": "ietf-if-l3-vlan", 2168 "revision": "2017-10-30", 2169 "location": [ "https://tiny.cc/ietf-yang/\ 2170 " ], 2171 }, 2172 { 2173 "name": "ietf-routing-policy", 2174 "revision": "2018-10-19", 2175 "location": [ "https://tiny.cc/ietf-yang/\ 2176 " ], 2177 }, 2178 { 2179 "name": "ietf-bgp", 2180 "revision": "2018-05-09", 2181 "location": [ "https://tiny.cc/ietf-yang/\ 2182 " ], 2183 }, 2184 { 2185 "name": "ietf-access-control-list", 2186 "revision": "2018-11-06", 2187 "location": [ "https://tiny.cc/ietf-yang/\ 2188 " ], 2189 } 2190 ], 2191 "import-only-module": [ 2192 { 2193 "name": "ietf-routing-types", 2194 "revision": "2017-12-04", 2195 "location": [ "https://tiny.cc/ietf-yang/\ 2196 ietf-routing-types@2017-12-04.yang" ], 2197 }, 2198 { 2199 "name": "iana-routing-types", 2200 "revision": "2017-12-04", 2201 "location": [ "https://tiny.cc/ietf-yang/\ 2202 iana-routing-types@2017-12-04.yang" ], 2203 }, 2204 { 2205 "name": "ietf-bgp-types", 2206 "revision": "2018-05-09", 2207 "location": [ "https://tiny.cc/ietf-yang/\ 2208 " ], 2209 }, 2210 { 2211 "name": "ietf-packet-fields", 2212 "revision": "2018-11-06", 2213 "location": [ "https://tiny.cc/ietf-yang/\ 2214 " ], 2215 }, 2216 { 2217 "name": "ietf-ethertypes", 2218 "revision": "2018-11-06", 2219 "location": [ "https://tiny.cc/ietf-yang/\ 2220 " ], 2221 } 2222 ] 2223 } 2224 } 2225 } 2226 } 2227 2229 A.3. Package import conflict resolution example 2231 This section provides an example of how a package can resolve 2232 conflicting module revisions from imported packages. 2234 In this example, YANG package 'example-3-pkg' imports both 'example- 2235 import-1' and 'example-import-2' packages. However, the two imported 2236 packages implement different revisions of 'example-module-A' so the 2237 'example-3-pkg' package selects version '1.2.3' to resolve the 2238 conflict. Similarly, for import-only modules, the 'example-3-pkg' 2239 package does not require both revisions of example-types-module-C to 2240 be imported, so it indicates that it only imports revision 2241 '2018-11-26' and not '2018-01-01'. 2243 { 2244 "ietf-yang-instance-data:instance-data-set": { 2245 "name": "example-import-1-pkg", 2246 "content-schema": { 2247 "pkg-schema": { 2248 "name": "ietf-yang-package-defn-pkg", 2249 "version": "0.1.0" 2250 } 2251 }, 2252 "description": "First imported example package", 2253 "content-data": { 2254 "ietf-yang-package-instance:yang-package": { 2255 "name": "example-import-1", 2256 "version": "1.0.0", 2257 "reference": "XXX, draft-rwilton-netmod-yang-packages", 2258 "revision-date": "2018-01-01", 2259 "module": [ 2260 { 2261 "name": "example-module-A", 2262 "revision": "1.0.0" 2263 }, 2264 { 2265 "name": "example-module-B", 2266 "revision": "1.0.0" 2267 } 2268 ], 2269 "import-only-module": [ 2270 { 2271 "name": "example-types-module-C", 2272 "revision": "2018-01-01" 2273 }, 2274 { 2275 "name": "example-types-module-D", 2276 "revision": "2018-01-01" 2277 } 2278 ] 2279 } 2280 } 2282 } 2283 } 2285 { 2286 "ietf-yang-instance-data:instance-data-set": { 2287 "name": "example-import-2-pkg", 2288 "content-schema": { 2289 "pkg-schema": { 2290 "name": "ietf-yang-package-defn-pkg", 2291 "version": "0.1.0" 2292 } 2293 }, 2294 "description": "Second imported example package", 2295 "content-data": { 2296 "ietf-yang-package:yang-package": { 2297 "name": "example-import-2", 2298 "version": "2.0.0", 2299 "reference": "XXX, draft-rwilton-netmod-yang-packages", 2300 "revision-date": "2018-11-26", 2301 "module": [ 2302 { 2303 "name": "example-module-A", 2304 "revision": "1.2.3" 2305 }, 2306 { 2307 "name": "example-module-E", 2308 "revision": "1.1.0" 2309 } 2310 ], 2311 "import-only-module": [ 2312 { 2313 "name": "example-types-module-C", 2314 "revision": "2018-11-26" 2315 }, 2316 { 2317 "name": "example-types-module-D", 2318 "revision": "2018-11-26" 2319 } 2320 ] 2321 } 2322 } 2323 } 2324 } 2326 { 2327 "ietf-yang-instance-data:instance-data-set": { 2328 "name": "example-3-pkg", 2329 "content-schema": { 2330 "pkg-schema": { 2331 "name": "ietf-yang-package-defn-pkg", 2332 "version": "0.1.0" 2333 } 2334 }, 2335 "description": "Importing example package", 2336 "content-data": { 2337 "ietf-yang-package:yang-package": { 2338 "name": "example-3", 2339 "version": "1.0.0", 2340 "reference": "XXX, draft-rwilton-netmod-yang-packages", 2341 "revision-date": "2018-11-26", 2342 "included-package": [ 2343 { 2344 "name": "example-import-1", 2345 "version": "1.0.0" 2346 }, 2347 { 2348 "name": "example-import-2", 2349 "version": "2.0.0" 2350 } 2351 ], 2352 "module": [ 2353 { 2354 "name": "example-module-A", 2355 "revision": "1.2.3" 2356 } 2357 ], 2358 "import-only-module": [ 2359 { 2360 "name": "example-types-module-C", 2361 "revision": "2018-11-26", 2362 "replaces-revision": [ "2018-01-01 "] 2363 } 2364 ] 2365 } 2366 } 2367 } 2368 } 2370 Appendix B. Possible alternative solutions 2372 This section briefly describes some alternative solutions. It can be 2373 removed if this document is adopted as a WG draft. 2375 B.1. Using module tags 2377 Module tags have been suggested as an alternative solution, and 2378 indeed that can address some of the same requirements as YANG 2379 packages but not all of them. 2381 Module tags can be used to group or organize YANG modules. However, 2382 this raises the question of where this tag information is stored. 2383 Module tags either require that the YANG module files themselves are 2384 updated with the module tag information (creating another versioning 2385 problem), or for the module tag information to be hosted elsewhere, 2386 perhaps in a centralize YANG Catalog, or in instance data files 2387 similar to how YANG packages have been defined in this draft. 2389 One of the principle aims of YANG packages is to be a versioned 2390 object that defines a precise set of YANG modules versions that work 2391 together. Module tags cannot meet this aim without an explosion of 2392 module tags definitions (i.e. a separate module tag must be defined 2393 for each package version). 2395 Module tags cannot support the hierachical scheme to construct schema 2396 that is proposed in this draft. 2398 B.2. Using YANG library 2400 Another question is whether it is necessary to define new YANG 2401 modules to define YANG packages, and whether YANG library could just 2402 be reused in an instance data file. The use of YANG packages offers 2403 several benefits over just using YANG library: 2405 1. Packages allow schema to be built in a hierarchical fashion. 2406 [I-D.ietf-netconf-rfc7895bis] only allows one layer of hierarchy 2407 (using module sets), and there must be no conflicts between 2408 module revisions in different module-sets. 2410 2. Packages can be made available off the box, with a well defined 2411 unique name, avoiding the need for clients to download, and 2412 construct/check the entire schema for each datastore. YANG 2413 library's use of a 'content-id' is unique only to the device that 2414 generated them. 2416 3. Packages may be versioned using a semantic versioning scheme, 2417 YANG library does not provide a schema level semantic version 2418 number. 2420 4. For a YANG library instance data file to contain the necessary 2421 information, it probably needs both YANG library and various 2422 augmentations (e.g. to include each module's semantic version 2423 number), unless a new version of YANG library is defined 2424 containing this information. The module definition for a YANG 2425 package is specified to contain all of the ncessary information 2426 to solve the problem without augmentations 2428 5. YANG library is designed to publish information about the 2429 modules, datastores, and datastore schema used by a server. The 2430 information required to construct an off box schema is not 2431 precisely the same, and hence the definitions might deviate from 2432 each other over time. 2434 Authors' Addresses 2436 Robert Wilton (editor) 2437 Cisco Systems, Inc. 2438 Email: rwilton@cisco.com 2440 Reshad Rahman 2441 Cisco Systems, Inc. 2442 Email: rrahman@cisco.com 2444 Joe Clarke 2445 Cisco Systems, Inc. 2446 Email: jclarke@cisco.com 2448 Jason Sterne 2449 Nokia 2450 Email: jason.sterne@nokia.com 2452 Bo Wu (editor) 2453 Huawei 2454 Email: lana.wubo@huawei.com