idnits 2.17.1 draft-ietf-netmod-yang-packages-02.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 713 has weird spacing: '...version pkg...' == Line 743 has weird spacing: '...evision yan...' == Line 753 has weird spacing: '...evision yan...' -- The document date (25 October 2021) is 914 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 2054, but no explicit reference was found in the text == Unused Reference: 'RFC8199' is defined on line 2066, but no explicit reference was found in the text == Outdated reference: A later version (-11) exists of draft-ietf-netmod-yang-module-versioning-03 == Outdated reference: A later version (-15) exists of draft-ietf-netmod-yang-semver-03 ** 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-05 ** Downref: Normative reference to an Informational draft: draft-ietf-netmod-yang-versioning-reqs (ref. 'I-D.ietf-netmod-yang-versioning-reqs') ** Obsolete normative reference: RFC 5246 (Obsoleted by RFC 8446) ** Obsolete normative reference: RFC 6536 (Obsoleted by RFC 8341) Summary: 4 errors (**), 0 flaws (~~), 9 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: 28 April 2022 Cisco Systems, Inc. 6 J. Sterne 7 Nokia 8 B. Wu, Ed. 9 Huawei 10 25 October 2021 12 YANG Packages 13 draft-ietf-netmod-yang-packages-02 15 Abstract 17 This document defines YANG packages, a versioned organizational 18 structure holding a set of related YANG modules that collectively 19 define a YANG schema. It describes how packages: are represented on 20 a server, can be defined in offline YANG instance data files, and can 21 be used to define the schema associated with YANG instance data 22 files. 24 Status of This Memo 26 This Internet-Draft is submitted in full conformance with the 27 provisions of BCP 78 and BCP 79. 29 Internet-Drafts are working documents of the Internet Engineering 30 Task Force (IETF). Note that other groups may also distribute 31 working documents as Internet-Drafts. The list of current Internet- 32 Drafts is at https://datatracker.ietf.org/drafts/current/. 34 Internet-Drafts are draft documents valid for a maximum of six months 35 and may be updated, replaced, or obsoleted by other documents at any 36 time. It is inappropriate to use Internet-Drafts as reference 37 material or to cite them other than as "work in progress." 39 This Internet-Draft will expire on 28 April 2022. 41 Copyright Notice 43 Copyright (c) 2021 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 (https://trustee.ietf.org/ 48 license-info) in effect on the date of publication of this document. 49 Please review these documents carefully, as they describe your rights 50 and restrictions with respect to this document. Code Components 51 extracted from this document must include Simplified BSD License text 52 as described in Section 4.e of the Trust Legal Provisions and are 53 provided without warranty as described in the Simplified BSD License. 55 Table of Contents 57 1. Terminology and Conventions . . . . . . . . . . . . . . . . . 3 58 2. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 59 3. Background on YANG packages . . . . . . . . . . . . . . . . . 4 60 4. Objectives . . . . . . . . . . . . . . . . . . . . . . . . . 5 61 5. YANG Package Definition . . . . . . . . . . . . . . . . . . . 6 62 5.1. Package definition rules . . . . . . . . . . . . . . . . 7 63 5.2. Package versioning . . . . . . . . . . . . . . . . . . . 8 64 5.2.1. Updating a package with a new version . . . . . . . . 8 65 5.2.1.1. Non-Backwards-compatible changes . . . . . . . . 8 66 5.2.1.2. Backwards-compatible changes . . . . . . . . . . 9 67 5.2.1.3. Editorial changes . . . . . . . . . . . . . . . . 9 68 5.2.2. YANG Semantic Versioning for packages . . . . . . . . 9 69 5.2.3. Revision history . . . . . . . . . . . . . . . . . . 10 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 . . . . . . . . . . . 14 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 . . . . . . . . . . . . . . . . . 16 84 7. Package Definitions on a Server . . . . . . . . . . . . . . . 17 85 7.1. Package List . . . . . . . . . . . . . . . . . . . . . . 18 86 7.2. Tree diagram . . . . . . . . . . . . . . . . . . . . . . 18 87 8. YANG Library Package Bindings . . . . . . . . . . . . . . . . 18 88 9. YANG packages as schema for YANG instance data document . . . 19 89 10. YANG Modules . . . . . . . . . . . . . . . . . . . . . . . . 19 90 11. Security Considerations . . . . . . . . . . . . . . . . . . . 39 91 12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 40 92 13. Open Questions/Issues . . . . . . . . . . . . . . . . . . . . 41 93 14. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 41 94 15. References . . . . . . . . . . . . . . . . . . . . . . . . . 41 95 15.1. Normative References . . . . . . . . . . . . . . . . . . 41 96 15.2. Informative References . . . . . . . . . . . . . . . . . 44 98 Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 44 99 A.1. Example IETF Network Device YANG package . . . . . . . . 45 100 A.2. Example IETF Basic Routing YANG package . . . . . . . . . 47 101 A.3. Package import conflict resolution example . . . . . . . 50 102 Appendix B. Possible alternative solutions . . . . . . . . . . . 52 103 B.1. Using module tags . . . . . . . . . . . . . . . . . . . . 52 104 B.2. Using YANG library . . . . . . . . . . . . . . . . . . . 53 105 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 53 107 1. Terminology and Conventions 109 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 110 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 111 "OPTIONAL" in this document are to be interpreted as described in BCP 112 14 [RFC2119] [RFC8174] when, and only when, they appear in all 113 capitals, as shown here. 115 This document uses terminology introduced in the YANG versioning 116 requirements draft [I-D.ietf-netmod-yang-versioning-reqs]. 118 This document also makes of the following terminology introduced in 119 the Network Management Datastore Architecture [RFC8342]: 121 * datastore schema 123 This document also makes of the following terminology introduced in 124 the YANG 1.1 Data Modeling Language [RFC7950]: 126 * data node 128 In addition, this document defines the following terminology: 130 * YANG schema: A datastore schema, not bound to any particular 131 datastore. 133 * YANG package: An organizational structure containing a collection 134 of YANG modules, normally defined in a YANG instance data file. A 135 YANG package defines a YANG schema by specifying a set of YANG 136 modules and their revisions, other packages and their revisions, 137 mandatory features, and deviations. YANG packages are defined in 138 Section 5. 140 * backwards-compatible (BC) change: When used in the context of a 141 YANG module, it follows the definition in Section 3.1.1 of 142 [I-D.ietf-netmod-yang-module-versioning]. When used in the 143 context of a YANG package, it follows the definition in 144 Section 5.2.1.2. 146 * non-backwards-compatible (NBC) change: When used in the context of 147 a YANG module, it follows the definition in Section 3.1.2 of 148 [I-D.ietf-netmod-yang-module-versioning]. When used in the 149 context of a YANG package, it follows the definition in 150 Section 5.2.1.2. 152 * editorial change: When used in the context of a YANG module, it 153 follows the definition of an 'editorial change' in 3.2 of 154 [I-D.ietf-netmod-yang-module-versioning]. When used in the 155 context of a YANG package, it follows the definition in 156 Section 5.2.1.3. 158 2. Introduction 160 This document defines and describes the YANG [RFC7950] constructs 161 that are used to define and use YANG packages. 163 A YANG package is an organizational structure that groups a set of 164 YANG modules together into a consistent versioned definition. For 165 example, a YANG package could define the set of YANG modules required 166 to implement an L2VPN service on a network device. YANG packages can 167 themselves refer to, and reuse, other package definitions. 169 Non-normative examples of YANG packages are provided in the 170 appendices. 172 3. Background on YANG packages 174 It has long been acknowledged within the YANG community that network 175 management using YANG requires a unit of organization and conformance 176 that is broader in scope than individual YANG modules. 178 'The YANG Package Statement' [I-D.bierman-netmod-yang-package] 179 proposed a YANG package mechanism based on new YANG language 180 statements, where a YANG package is defined in a file similar to how 181 YANG modules are defined, and would require enhancements to YANG 182 compilers to understand the new statements used to define packages. 184 OpenConfig [openconfigsemver] describes an approach to versioning 185 'bundle releases' based on git tags. I.e. a set of modules, at 186 particular versions, can be marked with the same release tag to 187 indicate that they are known to interoperate together. 189 The NETMOD WG in general, and the YANG versioning design team in 190 particular, are exploring solutions [I-D.ietf-netmod-yang-solutions] 191 to the YANG versioning requirements, 192 [I-D.ietf-netmod-yang-versioning-reqs]. Solutions to the versioning 193 requirements can be split into several distinct areas. 195 [I-D.ietf-netmod-yang-module-versioning] is focused on YANG 196 versioning scoped to individual modules. The overall solution must 197 also consider YANG versioning and conformance scoped to YANG schema. 198 YANG packages provide part of the solution for versioning YANG 199 schema. 201 4. Objectives 203 The main goals of YANG package definitions include, but are not 204 restricted to: 206 * To provide an alternative, simplified, YANG conformance mechanism. 207 Rather than conformance being performed against a set of 208 individual YANG module revisions, features, and deviations, 209 conformance can be more simply stated in terms of YANG packages, 210 with a set of modifications (e.g. additional modules, deviations, 211 or features). 213 * To allow YANG schema to be specified in a concise way rather than 214 having each server explicitly list all modules, revisions, and 215 features. YANG package definitions can be defined in documents 216 that are available offline, and accessible via a URL, rather than 217 requiring explicit lists of modules to be shared between client 218 and server. Hence, a YANG package must contain sufficient 219 information to allow a client or server to precisely construct the 220 schema associated with the package. 222 * To define a mainly linear versioned history of sets of modules 223 versions that are known to work together. I.e. to help mitigate 224 the problem where a client must manage devices from multiple 225 vendors, and vendor A implements version 1.0.0 of module foo and 226 version 2.0.0 of module bar, and vendor B implements version 2.0.0 227 of module foo and version 1.0.0 of module bar. For a client, 228 trying to interoperate with multiple vendors, and many YANG 229 modules, finding a consistent lowest common denominator set of 230 YANG module versions may be difficult, if not impossible. 232 Protocol mechanisms of how clients can negotiate which packages or 233 package versions are to be used for NETCONF/RESTCONF communications 234 are outside the scope of this document, and are defined in 235 [I-D.ietf-netmod-yang-ver-selection]. 237 Finally, the package definitions proposed by this document are 238 intended to be relatively basic in their definition and the 239 functionality that they support. As industry gains experience using 240 YANG packages, the standard YANG mechanisms of updating, or 241 augmenting YANG modules could also be used to extend the 242 functionality supported by YANG packages, if required. 244 5. YANG Package Definition 246 This document specifies an approach to defining YANG packages that is 247 different to either of the approaches described in the background. 249 A YANG package is a versioned organizational structure defining a set 250 of related YANG modules, packages, features, and deviations. A YANG 251 package collectively defines a YANG schema. 253 Each YANG package has a name that SHOULD end with the suffix "-pkg". 254 Package names are normally expected to be globally unique, but in 255 some cases the package name may be locally scoped to a server or 256 device, as described in Section 5.5. 258 YANG packages are versioned using the same approaches described in 259 [I-D.ietf-netmod-yang-module-versioning] and 260 [I-D.ietf-netmod-yang-semver]. This is described in further detail 261 in Section 5.2. 263 Each YANG package version, defines: 265 * some metadata about the package, e.g., description, tags, scoping, 266 referential completeness, location information. 268 * a set of YANG modules, at particular revisions, that are 269 implemented by servers that implement the package. The modules 270 may contain deviations. 272 * a set of import-only YANG modules, at particular revisions, that 273 are used 'import-only' by the servers that implement the package. 275 * a set of included YANG packages, at particular revisions, that are 276 also implemented by servers that implement the package. 278 * a set of YANG module features that must be supported by servers 279 that implement the package. 281 The structure for YANG package definitions uses existing YANG 282 language statements, YANG Data Structure Extensions 283 [I-D.ietf-netmod-yang-data-ext], and YANG Instance Data File Format 284 [I-D.ietf-netmod-yang-instance-file-format]. 286 YANG package definitions are available offline in YANG instance data 287 files. Client applications can be designed to support particular 288 package versions that they expect to interoperate with. 290 YANG package definitions are available from the server via 291 augmentations to YANG Library [RFC8525]. Rather than client 292 applications downloading the entire contents of YANG library to 293 confirm that the server schema is compatible with the client, they 294 can check, or download, a much shorter YANG package definition, and 295 validate that it conforms to the expected schema. 297 YANG package definitions can also be used to define the schema 298 associated with YANG instance data files holding other, e.g., non 299 packages related, instance data. 301 5.1. Package definition rules 303 Packages are defined using the following rules: 305 1. A YANG package MAY represent a complete YANG schema or only part 306 of a YANG schema with some module import dependencies missing, as 307 described in Section 5.4. 309 2. Packages definitions are hierarchical. A package can include 310 other packages. Only a single version of a package can be 311 included, and conflicting package includes (e.g. from descendant 312 package includes) MUST be explicitly resolved by indicating which 313 version takes precedence, and which versions are being replaced. 315 3. For each module implemented by a package, only a single revision 316 of that module MUST be implemented. Multiple revisions of a 317 module MAY be listed as import-only dependencies. 319 4. The revision of a module listed in the package 'module' list 320 supersedes any 'implemented' revision of the module listed in an 321 included package module list. The 'replaces-revision' leaf-list 322 is used to indicate which 'implemented' or 'import-only' module 323 revisions are replaces by this module revision. This allows a 324 package to explicitly resolve conflicts between implemented 325 module revisions in included packages. 327 5. The 'replaces-revision' leaf-list in the 'import-only-module' 328 list can be used to exclude duplicate revisions of import-only 329 modules from included packages. Otherwise, the import-only- 330 modules for a package are the import-only-modules from all 331 included packages combined with any modules listed in the 332 packages import-only-module list. 334 6. YANG packages definitions MAY include modules containing 335 deviation statements, but those deviation statements MUST only be 336 used in an RFC 7950 compatible way to indicate where a server, or 337 class of servers, deviates from a published standard. Deviations 338 MUST NOT be included in a package definition that is part of a 339 published standard. See section 5.8.1 for further guidance on 340 the use of deviations in YANG packages. 342 5.2. Package versioning 344 Individual versions of a YANG package are versioned using the 345 "revision-label" scheme defined in section 3.3 of 346 [I-D.ietf-netmod-yang-module-versioning]. 348 5.2.1. Updating a package with a new version 350 Package compatibility is fundamentally defined by how the YANG schema 351 between two package versions has changed. 353 When a package definition is updated, the version associated with the 354 package MUST be updated appropriately, taking into consideration the 355 scope of the changes as defined by the rules below. 357 A package definition SHOULD define the previous version of the 358 package in the 'previous-version' leaf unless it is the initial 359 version of the package. If the 'previous-version' leaf is provided 360 then the package definition MUST set the 'nbc-changes' leaf if the 361 new version is non-backwards-compatible with respect to the package 362 version defined in the 'previous-version' leaf. 364 5.2.1.1. Non-Backwards-compatible changes 366 The following changes classify as non-backwards-compatible changes to 367 a package definition: 369 * Changing an 'included-package' list entry to select a package 370 version that is non-backwards-compatible to the prior package 371 version, or removing a previously included package. 373 * Changing a 'module' or 'import-only-module' list entry to select a 374 module revision that is non-backwards-compatible to the prior 375 module revision, or removing a previously implemented module. 377 * Removing a feature from the 'mandatory-feature' leaf-list. 379 * Adding, changing, or removing a deviation that is considered a 380 non-backwards-compatible change to the affected data node in the 381 schema associated with the prior package version. 383 5.2.1.2. Backwards-compatible changes 385 The following changes classify as backwards-compatible changes to a 386 package definition: 388 * Changing an 'included-package' list entry to select a package 389 version that is backwards-compatible to the prior package version, 390 or including a new package that does not conflict with any 391 existing included package or module. 393 * Changing a 'module' or 'import-only-module' list entry to select a 394 module revision that is backwards-compatible to the prior module 395 revision, or including a new module to the package definition. 397 * Adding a feature to the 'mandatory-feature' leaf-list. 399 * Adding, changing, or removing a deviation that is considered a 400 backwards-compatible change to the affected data node in the 401 schema associated with the prior package version. 403 5.2.1.3. Editorial changes 405 The following changes classify as editorial changes to a package 406 definition: 408 * Changing a 'included-package' list entry to select a package 409 version that is classified as an editorial change relative to the 410 prior package version. 412 * Changing a 'module' or 'import-only-module' list entry to select a 413 module revision that is classified as an editorial change relative 414 to the prior module revision. 416 * Any change to any metadata associated with a package definition. 418 5.2.2. YANG Semantic Versioning for packages 420 YANG Semantic Versioning [I-D.ietf-netmod-yang-semver] MAY be used as 421 an appropriate type of revision-label for the package version leaf. 423 If the format of the leaf matches the 'yangver:version' type 424 specified in ietf-yang-semver.yang, then the package version leaf 425 MUST be interpreted as a YANG semantic version number. 427 For YANG packages defined by the IETF, YANG semantic version numbers 428 MUST be used as the version scheme for YANG packages. 430 The rules for incrementing the YANG package version number are 431 equivalent to the semantic versioning rules used to version 432 individual YANG modules, defined in section 3.2 of 433 [I-D.ietf-netmod-yang-semver], but use the rules defined previously 434 in Section 5.2.1 to determine whether a change is classified as non- 435 backwards-compatible, backwards-compatible, or editorial. Where 436 available, the semantic version number of the referenced elements in 437 the package (included packages or modules) can be used to help 438 determine the scope of changes being made. 440 5.2.3. Revision history 442 YANG packages do not contain a revision history. This is because 443 packages may have many revisions and a long revision history would 444 bloat the package definition. By recursively examining the 445 'previous-version' leaf of a package definition, a full revision 446 history (including where non-backwards-compatible changes have 447 occurred) can be dynamically constructed, if all package versions are 448 available. 450 5.3. Package conformance 452 YANG packages allows for conformance to be checked at a package level 453 rather than requiring a client to download all modules, revisions, 454 and deviations from the server to ensure that the datastore schema 455 used by the server is compatible with the client. 457 YANG package conformance is analogous to how YANG [RFC7950] requires 458 that servers either implement a module faithfully, or otherwise use 459 deviations to indicate areas of non-conformance. 461 For a top level package representing a datastore schema, servers MUST 462 implement the package definition faithfully, including all mandatory 463 features. 465 Package definitions MAY modify the schema for directly or 466 hierarchically included packages through the use of different module 467 revisions or module deviations. If the schema of any included 468 package is modified in a non-backwards-compatible way then it MUST be 469 indicated by setting the 'nbc-modified' leaf to true. 471 5.3.1. Use of YANG semantic versioning 473 Using the YANG semantic versioning scheme for package version numbers 474 and module revision labels can help with conformance. In the general 475 case, clients should be able to determine the nature of changes 476 between two package versions by comparing the version number. 478 This usually means that a client does not have to be restricted to 479 working only with servers that advertise exactly the same version of 480 a package in YANG library. Instead, reasonable clients should be 481 able to interoperate with any server that supports a package version 482 that is backwards compatible to version that the client is designed 483 for, assuming that the client is designed to ignore operational 484 values for unknown data nodes. 486 For example, a client coded to support 'foo' package at version 1.0.0 487 should interoperate with a server implementing 'foo' package at 488 version 1.3.5, because the YANG semantic versioning rules require 489 that package version 1.3.5 is backwards compatible to version 1.0.0. 491 This also has a relevance on servers that are capable of supporting 492 version selection because they need not support every version of a 493 YANG package to ensure good client compatibility. Choosing suitable 494 minor versions within each major version number should generally be 495 sufficient, particular if they can avoid non-backwards-compatible 496 patch level changes. 498 5.3.2. The relationship between packages and datastores 500 As defined by NMDA [RFC8342], each datastore has an associated 501 datastore schema. Sections 5.1 and 5.3 of NMDA defines further 502 constraints on the schema associated with datastores. These 503 constraints can be summarized thus: 505 * The schema for all conventional datastores is the same. 507 * The schema for non conventional configuration datastores (e.g., 508 dynamic datastores) may completely differ (i.e. no overlap at all) 509 from the schema associated with the conventional configuration 510 datastores, or may partially or fully overlap with the schema of 511 the conventional configuration datastores. A dynamic datastore, 512 for example, may support different modules than conventional 513 datastores, or may support a subset or superset of modules, 514 features, or data nodes supported in the conventional 515 configuration datastores. Where a data node exists in multiple 516 datastore schema it has the same type, properties and semantics. 518 * The schema for the operational datastore is intended to be a 519 superset of all the configuration datastores (i.e. includes all 520 the schema nodes from the conventional configuration datastores), 521 but data nodes can be omitted if they cannot be accurately 522 reported. The operational datastore schema can include additional 523 modules containing only config false data nodes, but there is no 524 harm in including those modules in the configuration datastore 525 schema as well. 527 Given that YANG packages represent a YANG schema, it follows that 528 each datastore schema can be represented using packages. In 529 addition, the schema for most datastores on a server are often 530 closely related. Given that there are many ways that a datastore 531 schema could be represented using packages, the following guidance 532 provides a consistent approach to help clients understand the 533 relationship between the different datastore schema supported by a 534 device (e.g., which parts of the schema are common and which parts 535 have differences): 537 * Any datastores (e.g., conventional configuration datastores) that 538 have exactly the same datastore schema MUST use the same package 539 definitions. This is to avoid, for example, the creation of a 540 'running-cfg' package and a separate 'intended-cfg' package that 541 have identical schema. 543 * Common package definitions SHOULD be used for those parts of the 544 datastore schema that are common between datastores, when those 545 datastores do not share exactly the same datastore schema. E.g., 546 if a substantial part of the schema is common between the 547 conventional, dynamic, and operational datastores then a single 548 common package can be used to describe the common parts, along 549 with other packages to describe the unique parts of each datastore 550 schema. 552 * YANG modules that do not contain any configuration data nodes 553 SHOULD be included in the package for configuration datastores if 554 that helps unify the package definitions. 556 * The packages for the operational datastore schema MUST include all 557 packages for all configuration datastores, along with any required 558 modules defining deviations to mark unsupported data nodes. The 559 deviations MAY be defined directly in the packages defining the 560 operational datastore schema, or in separate non referentially 561 complete packages. 563 * The schema for a datastore MAY be represented using a single 564 package or as the union of a set of compatible packages, i.e., 565 equivalently to a set of non-conflicting packages being included 566 together in an overarching package definition. 568 5.4. Schema referential completeness 570 A YANG package may represent a schema that is 'referentially 571 complete', or 'referentially incomplete', indicated in the package 572 definition by the 'complete' flag. 574 If all import statements in all YANG modules included in the package 575 (either directly, or through included packages) can be resolved to a 576 module revision defined with the YANG package definition, then the 577 package is classified as referentially complete. Conversely, if one 578 or more import statements cannot be resolved to a module specified as 579 part of the package definition, then the package is classified as 580 referentially incomplete. 582 A package that represents the exact contents of a datastore schema 583 MUST always be referentially complete. 585 Referentially incomplete packages can be used, along with locally 586 scoped packages, to represent an update to a device's datastore 587 schema as part of an optional software hot fix. E.g., the base 588 software is made available as a complete globally scoped package. 589 The hot fix is made available as an incomplete globally scoped 590 package. A device's datastore schema can define a local package that 591 implements the base software package updated with the hot fix 592 package. 594 Referentially incomplete packages could also be used to group sets of 595 logically related modules together, but without requiring a fixed 596 dependency on all imported 'types' modules (e.g., iana-if- 597 types.yang), instead leaving the choice of specific revisions of 598 'types' modules to be resolved when the package definition is used. 600 5.5. Package name scoping and uniqueness 602 YANG package names can be globally unique, or locally scoped to a 603 particular server or device. 605 5.5.1. Globally scoped packages 607 The name given to a package MUST be globally unique, and it MUST 608 include an appropriate organization prefix in the name, equivalent to 609 YANG module naming conventions. 611 Ideally a YANG instance data file defining a particular package 612 version would be publicly available at one or more URLs. 614 5.5.2. Server scoped packages 616 Package definitions may be scoped to a particular server by setting 617 the 'is-local' leaf to true in the package definition. 619 Locally scoped packages MAY have a package name that is not globally 620 unique. 622 Locally scoped packages MAY have a definition that is not available 623 offline from the server in a YANG instance data file. 625 5.6. Submodules packages considerations 627 As defined in [RFC7950] and [I-D.ietf-netmod-yang-semver], YANG 628 conformance and versioning is specified in terms of particular 629 revisions of YANG modules rather than for individual submodules. 631 However, YANG package definitions also include the list of submodules 632 included by a module, primarily to provide a location of where the 633 submodule definition can be obtained from, allowing a YANG schema to 634 be fully constructed from a YANG package instance data file 635 definition. 637 5.7. Package tags 639 [I-D.ietf-netmod-module-tags] defines YANG module tags as a mechanism 640 to annotate a module definition with additional metadata. Tags MAY 641 also be associated to a package definition via the 'tags' leaf-list. 642 The tags use the same registry and definitions used by YANG module 643 tags. 645 5.8. YANG Package Usage Guidance 647 It is RECOMMENDED that organizations that publish YANG modules also 648 publish YANG package definition that group and version those modules 649 into units of related functionality. This increases 650 interoperability, by encouraging implementations to use the same 651 collections of YANG modules versions. Using packages also makes it 652 easier to understand relationship between modules, and enables 653 functionality to be described on a more abstract level than 654 individual modules. 656 5.8.1. Use of deviations in YANG packages 658 [RFC7950] section 5.6.3 defines deviations as the mechanism to allow 659 servers to indicate where they do not conform to a published YANG 660 module that is being implemented. 662 In cases where implementations contain deviations from published 663 packages, then those implementations SHOULD define a package that 664 includes both the published packages and all modules containing 665 deviations. This implementation specific package accurately reflects 666 the schema used by the device and allows clients to determine how the 667 implementation differs from the published package schema in an 668 offline consumable way, e.g., when published in an instance data file 669 (see section 6). 671 Organizations may wish to reuse YANG modules and YANG packages 672 published by other organizations for new functionality. Sometimes, 673 they may desire to modify the published YANG modules. However, they 674 MUST NOT use deviations in an attempt to achieve this because such 675 deviations cause two problems: 677 They prevent implementations from reporting their own deviations 678 for the same nodes. 680 They fracture the ecosystem by preventing implementations from 681 conforming to the standards specified by both organizations. This 682 hurts the interoperability in the YANG community, promotes 683 development of disconnected functional silos, and hurts creativity 684 in the market. 686 5.8.2. Use of features in YANG modules and YANG packages 688 The YANG language supports feature statements as the mechanism to 689 make parts of a schema optional. Published standard YANG modules 690 SHOULD make use of appropriate feature statements to provide 691 flexibility in how YANG modules may be used by implementations and 692 used by YANG modules published by other organizations. 694 YANG packages support 'mandatory features' which allow a package to 695 specify features that MUST be implemented by any conformant 696 implementation of the package as a mechanism to simplify and manage 697 the schema represented by a YANG package. 699 5.9. YANG package core definition 701 The ietf-yang-package-types.yang module defines a grouping to specify 702 the core elements of the YANG package structure that is used within 703 YANG package instance data files (ietf-yang-package-instance.yang) 704 and also on the server (ietf-yang-packages.yang). 706 The "ietf-yang-package-types" YANG module has the following 707 structure: 709 module: ietf-yang-package-types 711 grouping yang-pkg-identification-leafs 712 +-- name pkg-name 713 +-- version pkg-version 715 grouping yang-pkg-instance 716 +-- name pkg-name 717 +-- version pkg-version 718 +-- timestamp? yang:date-and-time 719 +-- organization? string 720 +-- contact? string 721 +-- description? string 722 +-- reference? string 723 +-- complete? boolean 724 +-- local? boolean 725 +-- previous-version? pkg-version 726 +-- nbc-changes? boolean 727 +-- tag* tags:tag 728 +-- mandatory-feature* scoped-feature 729 +-- included-package* [name version] 730 | +-- name pkg-name 731 | +-- version pkg-version 732 | +-- replaces-version* pkg-version 733 | +-- nbc-modified? boolean 734 | +-- location* inet:uri 735 +-- module* [name] 736 | +-- name yang:yang-identifier 737 | +-- revision? rev:revision-date-or-label 738 | +-- replaces-revision* rev:revision-date-or-label 739 | +-- namespace? inet:uri 740 | +-- location* inet:uri 741 | +-- submodule* [name] 742 | +-- name? yang:yang-identifier 743 | +-- revision yang:revision-identifier 744 | +-- location* inet:uri 745 +-- import-only-module* [name revision] 746 +-- name? yang:yang-identifier 747 +-- revision? rev:revision-date-or-label 748 +-- replaces-revision* rev:revision-date-or-label 749 +-- namespace? inet:uri 750 +-- location* inet:uri 751 +-- submodule* [name] 752 +-- name? yang:yang-identifier 753 +-- revision yang:revision-identifier 754 +-- location* inet:uri 756 6. Package Instance Data Files 758 YANG packages SHOULD be available offline from the server, defined as 759 YANG instance data files [I-D.ietf-netmod-yang-instance-file-format] 760 using the YANG schema below to define the package data. 762 The following rules apply to the format of the YANG package instance 763 files: 765 1. The file SHOULD be encoded in JSON. 767 2. The name of the file SHOULD follow the format "@.json". 770 3. The package name MUST be specified in both the instance-data-set 771 'name' and package 'name' leafs. 773 4. The 'description' field of the instance-data-set SHOULD be "YANG 774 package definition". 776 5. The 'timestamp', "organization', 'contact' fields are defined in 777 both the instance-data-set metadata and the YANG package 778 metadata. Package definitions SHOULD only define these fields as 779 part of the package definition. If any of these fields are 780 populated in the instance-data-set metadata then they MUST 781 contain the same value as the corresponding leaves in the package 782 definition. 784 6. The 'revision' list in the instance data file SHOULD NOT be used, 785 since versioning is handled by the package definition. 787 7. The instance data file for each version of a YANG package SHOULD 788 be made available at one of more locations accessible via URLs. 789 If one of the listed locations defines a definitive reference 790 implementation for the package definition then it MUST be listed 791 as the first entry in the list. 793 The "ietf-yang-package" YANG module has the following structure: 795 module: ietf-yang-package 797 structure package: 798 // Uses the yang-package-instance grouping defined in 799 // ietf-yang-package-types.yang 800 +-- name pkg-name 801 +-- version pkg-version 802 ... remainder of yang-package-instance grouping ... 804 7. Package Definitions on a Server 805 7.1. Package List 807 A top level 'packages' container holds the list of all versions of 808 all packages known to the server. Each list entry uses the common 809 package definition, but with the addition of package location that 810 cannot be contained within a offline package definition contained in 811 an instance data file. 813 The '/packages/package' list MAY include multiple versions of a 814 particular package. E.g. if the server is capable of allowing 815 clients to select which package versions should be used by the 816 server. 818 7.2. Tree diagram 820 The "ietf-yang-packages" YANG module has the following structure: 822 module: ietf-yang-packages 823 +--ro packages 824 +--ro package* [name version] 825 // Uses the yang-package-instance grouping defined in 826 // ietf-yang-package-types.yang, with location: 827 +--ro name pkg-name 828 +--ro version pkg-version 829 ... remainder of yang-package-instance grouping ... 830 +--ro location* inet:uri 832 8. YANG Library Package Bindings 834 The YANG packages module also augments YANG library to allow a server 835 to optionally indicate that a datastore schema is defined by a 836 package, or a union of compatible packages. Since packages can 837 generally be made available offline in instance data files, it may be 838 sufficient for a client to only check that a compatible version of 839 the package is implemented by the server without fetching either the 840 package definition, or downloading and comparing the full list of 841 modules and enabled features. 843 If a server indicates that a datastore schema maps to a particular 844 package, then it MUST exactly match the schema defined by that 845 package, taking into account enabled features and any deviations. 847 If a server cannot faithfully implement a package then it can define 848 a new package to accurately report what it does implement. The new 849 package can include the original package as an included package, and 850 the new package can define additional modules containing deviations 851 to the modules in the original package, allowing the new package to 852 accurately describe the server's behavior. There is no specific 853 mechanism provided to indicate that a mandatory-feature in package 854 definition is not supported on a server, but deviations MAY be used 855 to disable functionality predicated by an if-feature statement. 857 The "ietf-yl-packages" YANG module has the following structure: 859 module: ietf-yl-packages 860 augment /yanglib:yang-library/yanglib:schema: 861 +--ro package* [name version] 862 +--ro name -> /pkgs:packages/package/name 863 +--ro version leafref 865 9. YANG packages as schema for YANG instance data document 867 YANG package definitions can be used as the schema definition for 868 YANG instance data files. When using a package schema, the name and 869 version of the package MUST be specified, a package URL to the 870 package definition MAY also be provided. 872 The "ietf-yang-inst-data-pkg" YANG module has the following 873 structure: 875 module: ietf-yang-inst-data-pkg 877 augment-structure /yid:instance-data-set/yid:content-schema-spec: 878 +--:(pkg-schema) 879 +-- pkg-schema 880 +-- name pkg-name 881 +-- version pkg-version 882 +-- location* inet:uri 884 10. YANG Modules 886 The YANG module definitions for the modules described in the previous 887 sections. 889 file "ietf-yang-package-types@2021-10-25.yang" 890 module ietf-yang-package-types { 891 yang-version 1.1; 892 namespace "urn:ietf:params:xml:ns:yang:ietf-yang-package-types"; 893 prefix "pkg-types"; 894 import ietf-yang-revisions { 895 prefix rev; 896 reference "XXXX: Updated YANG Module Revision Handling"; 897 } 899 import ietf-yang-types { 900 prefix yang; 901 rev:revision-or-derived 2019-07-21; 902 reference "RFC 6991bis: Common YANG Data Types."; 903 } 905 import ietf-inet-types { 906 prefix inet; 907 rev:revision-or-derived 2013-07-15; 908 reference "RFC 6991: Common YANG Data Types."; 909 } 911 import ietf-module-tags { 912 prefix tags; 913 // RFC Ed. Fix revision once revision date of 914 // ietf-module-tags.yang is known. 915 reference "RFC XXX: YANG Module Tags."; 916 } 918 organization 919 "IETF NETMOD (Network Modeling) Working Group"; 921 contact 922 "WG Web: 923 WG List: 925 Author: Rob Wilton 926 "; 928 description 929 "This module provides type and grouping definitions for YANG 930 packages. 932 Copyright (c) 2019 IETF Trust and the persons identified as 933 authors of the code. All rights reserved. 935 Redistribution and use in source and binary forms, with or 936 without modification, is permitted pursuant to, and subject 937 to the license terms contained in, the Simplified BSD License 938 set forth in Section 4.c of the IETF Trust's Legal Provisions 939 Relating to IETF Documents 940 (http://trustee.ietf.org/license-info). 941 This version of this YANG module is part of RFC XXXX; see 942 the RFC itself for full legal notices. 944 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL 945 NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'NOT RECOMMENDED', 946 'MAY', and 'OPTIONAL' in this document are to be interpreted as 947 described in BCP 14 (RFC 2119) (RFC 8174) when, and only when, 948 they appear in all capitals, as shown here."; 950 // RFC Ed.: update the date below with the date of RFC publication 951 // and remove this note. 952 // RFC Ed.: replace XXXX with actual RFC number and remove this 953 // note. 954 revision 2021-10-25 { 955 rev:revision-label 0.2.0; 956 description 957 "Initial revision"; 958 reference 959 "RFC XXXX: YANG Packages"; 960 } 962 /* 963 * Typedefs 964 */ 966 typedef pkg-name { 967 type yang:yang-identifier; 968 description 969 "Package names are typed as YANG identifiers."; 970 } 972 typedef pkg-version { 973 type rev:revision-date-or-label; 974 description 975 "Package versions SHOULD be a revision-label (e.g. perhaps a 976 YANG Semver version string). Package versions MAY also be a 977 revision-date"; 979 } 981 typedef pkg-identifier { 982 type rev:name-revision; 983 description 984 "Package identifiers combine a pkg-name and a pkg-version"; 985 } 987 typedef scoped-feature { 988 type string { 989 pattern '[a-zA-Z_][a-zA-Z0-9\-_.]*:[a-zA-Z_][a-zA-Z0-9\-_.]*'; 990 } 991 description 992 "Represents a feature name scoped to a particular module, 993 identified as the ':', where both 994 and are YANG identifier strings, 995 as defiend by Section 12 or RFC 6020."; 996 reference 997 "RFC XXXX, YANG Packages."; 998 } 1000 /* 1001 * Groupings 1002 */ 1003 grouping yang-pkg-identification-leafs { 1004 description 1005 "Parameters for identifying a specific version of a YANG 1006 package"; 1008 leaf name { 1009 type pkg-name; 1010 mandatory true; 1011 description 1012 "The YANG package name."; 1013 } 1015 leaf version { 1016 type pkg-version; 1017 mandatory true; 1018 description 1019 "Uniquely identies a particular version of a YANG package. 1021 Follows the definition for revision labels defined in 1022 draft-verdt-nemod-yang-module-versioning, section XXX"; 1023 } 1024 } 1026 grouping yang-pkg-instance { 1027 description 1028 "Specifies the data node for a full YANG package instance 1029 represented either on a server or as a YANG instance data 1030 document."; 1031 uses yang-pkg-identification-leafs; 1033 leaf timestamp { 1034 type yang:date-and-time; 1035 description 1036 "An optional timestamp for when this package was created. 1037 This does not need to be unique across all versions of a 1038 package."; 1039 } 1041 leaf organization { 1042 type string; 1044 description "Organization responsible for this package"; 1045 } 1047 leaf contact { 1048 type string; 1050 description 1051 "Contact information for the person or organization to whom 1052 queries concerning this package should be sent."; 1053 } 1055 leaf description { 1056 type string; 1058 description "Provides a description of the package"; 1059 } 1061 leaf reference { 1062 type string; 1064 description "Allows for a reference for the package"; 1065 } 1067 leaf complete { 1068 type boolean; 1069 default true; 1070 description 1071 "Indicates whether the schema defined by this package is 1072 referentially complete. I.e. all module imports can be 1073 resolved to a module explicitly defined in this package or 1074 one of the included packages."; 1075 } 1077 leaf local { 1078 type boolean; 1079 default false; 1080 description 1081 "Defines that the package definition is local to the server, 1082 and the name of the package MAY not be unique, and the 1083 package definition MAY not be available in an offline file. 1085 Local packages can be used when the schema for the device 1086 can be changed at runtime through the addition or removal of 1087 software packages, or hot fixes."; 1088 } 1090 leaf previous-version { 1091 type pkg-version; 1092 description 1093 "The previous package version that this version has been 1094 derived from. This leaf allows a full version history graph 1095 to be constructed if required."; 1096 } 1098 leaf nbc-changes { 1099 type boolean; 1100 default false; 1101 description 1102 "Indicates whether the defined package version contains 1103 non-backwards-compatible changes relative to the package 1104 version defined in the 'previous-version' leaf."; 1105 } 1107 leaf-list tag { 1108 type tags:tag; 1109 description 1110 "Tags associated with a YANG package. Module tags defined in 1111 XXX, ietf-netmod-module-tags can be used here but with the 1112 modification that the tag applies to the entire package 1113 rather than a specific module. See the IANA 'YANG Module 1114 Tag Prefix' registry for reserved prefixes and the IANA 1115 'YANG Module IETF Tag' registry for IETF standard tags."; 1116 } 1118 leaf-list mandatory-feature { 1119 type scoped-feature; 1120 description 1121 "Lists features from any modules included in the package that 1122 MUST be supported by any server implementing the package. 1124 Features already specified in a 'mandatory-feature' list of 1125 any included package MUST also be supported by server 1126 implementations and do not need to be repeated in this list. 1128 All other features defined in modules included in the 1129 package are OPTIONAL to implement. 1131 Features are identified using :"; 1132 } 1134 list included-package { 1135 key "name version"; 1136 description 1137 "An entry in this list represents a package that is included 1138 as part of the package definition, or an indirectly included 1139 package that is changed in a non backwards compatible way. 1141 It can be used to resolve inclusion of conflicting package 1142 versions by explicitly specifying which package version is 1143 used. 1145 If included packages implement different revisions or 1146 versions of the same module, then an explicit entry in the 1147 module list MUST be provided to select the specific module 1148 version 'implemented' by this package definition. 1150 If the schema for any packages that are included, either 1151 directly or indirectly via another package include, are 1152 changed in any non-backwards-compatible way then they MUST 1153 be explicitly listed in the included-packages list with the 1154 'nbc-modified' leaf set to true. 1156 For import-only modules, the 'replaces-revision' leaf-list 1157 can be used to select the specific module versions used by 1158 this package."; 1159 reference 1160 "XXX"; 1162 uses yang-pkg-identification-leafs; 1164 leaf-list replaces-version { 1165 type pkg-version; 1166 description 1167 "Gives the version of an included package version that 1168 is replaced by this included package revision."; 1169 } 1171 leaf nbc-modified { 1172 type boolean; 1173 default false; 1174 description 1175 "Set to true if any data nodes in this package are modified 1176 in a non backwards compatible way, either through the use 1177 of deviations, or because one of the modules has been 1178 replaced by an incompatible revision. This could also 1179 occur if a module's revision was replaced by an earlier 1180 revision that had the effect of removing some data 1181 nodes."; 1182 } 1184 leaf-list location { 1185 type inet:uri; 1186 description 1187 "Contains a URL that represents where an instance data file 1188 for this YANG package can be found. 1190 This leaf will only be present if there is a URL available 1191 for retrieval of the schema for this entry. 1193 If multiple locations are provided, then the first 1194 location in the leaf-list MUST be the definitive location 1195 that uniquely identifies this package"; 1196 } 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 } 1255 list submodule { 1256 key "name"; 1257 description 1258 "Each entry represents one submodule within the 1259 parent module."; 1261 leaf name { 1262 type yang:yang-identifier; 1263 description 1264 "The YANG submodule name."; 1265 } 1267 leaf revision { 1268 type yang:revision-identifier; 1269 mandatory true; 1270 description 1271 "The YANG submodule revision date. If the parent module 1272 include statement for this submodule includes a revision 1273 date then it MUST match this leaf's value."; 1275 } 1277 leaf-list location { 1278 type inet:uri; 1279 description 1280 "Contains a URL that represents the YANG schema resource 1281 for this submodule. 1283 This leaf will only be present if there is a URL 1284 available for retrieval of the schema for this entry."; 1285 } 1287 } 1288 } 1290 list import-only-module { 1291 key "name revision"; 1292 description 1293 "An entry in this list indicates that the server imports 1294 reusable definitions from the specified revision of the 1295 module, but does not implement any protocol accessible 1296 objects from this revision. 1298 Multiple entries for the same module name MAY exist. This 1299 can occur if multiple modules import the same module, but 1300 specify different revision-dates in the import statements."; 1302 leaf name { 1303 type yang:yang-identifier; 1304 description 1305 "The YANG module name."; 1306 } 1308 leaf revision { 1309 type rev:revision-date-or-label; 1310 description 1311 "The YANG module revision date or revision-label. 1313 If no revision statement is present in the YANG module, 1314 this leaf is not instantiated."; 1315 } 1317 leaf-list replaces-revision { 1318 type rev:revision-date-or-label; 1319 description 1320 "Gives the revision of an import-only-module defined in an 1321 included package that is replaced by this 1322 import-only-module revision."; 1324 } 1326 leaf namespace { 1327 type inet:uri; 1328 description 1329 "The XML namespace identifier for this module."; 1330 } 1332 leaf-list location { 1333 type inet:uri; 1334 description 1335 "Contains a URL that represents the YANG schema resource 1336 for this module. 1338 This leaf will only be present if there is a URL available 1339 for retrieval of the schema for this entry."; 1340 } 1342 list submodule { 1343 key "name"; 1344 description 1345 "Each entry represents one submodule within the 1346 parent module."; 1348 leaf name { 1349 type yang:yang-identifier; 1350 description 1351 "The YANG submodule name."; 1352 } 1354 leaf revision { 1355 type yang:revision-identifier; 1356 mandatory true; 1357 description 1358 "The YANG submodule revision date. If the parent module 1359 include statement for this submodule includes a revision 1360 date then it MUST match this leaf's value."; 1361 } 1363 leaf-list location { 1364 type inet:uri; 1365 description 1366 "Contains a URL that represents the YANG schema resource 1367 for this submodule. 1369 This leaf will only be present if there is a URL 1370 available for retrieval of the schema for this entry."; 1372 } 1373 } 1374 } 1375 } 1376 } 1377 1379 file "ietf-yang-package-instance@2021-10-25.yang" 1380 module ietf-yang-package-instance { 1381 yang-version 1.1; 1382 namespace "urn:ietf:params:xml:ns:yang:ietf-yang-package-instance"; 1383 prefix pkg-inst; 1385 import ietf-yang-revisions { 1386 prefix rev; 1387 reference "XXXX: Updated YANG Module Revision Handling"; 1388 } 1390 import ietf-yang-package-types { 1391 prefix pkg-types; 1392 rev:revision-or-derived 0.2.0; 1393 reference "RFC XXX: YANG Schema Versioning."; 1394 } 1396 import ietf-yang-structure-ext { 1397 prefix sx; 1398 reference "RFC XXX: YANG Data Structure Extensions."; 1399 } 1401 organization 1402 "IETF NETMOD (Network Modeling) Working Group"; 1404 contact 1405 "WG Web: 1406 WG List: 1408 Author: Rob Wilton 1409 "; 1411 description 1412 "This module provides a definition of a YANG package, which is 1413 used as the schema for an YANG instance data document specifying 1414 a YANG package. 1416 Copyright (c) 2019 IETF Trust and the persons identified as 1417 authors of the code. All rights reserved. 1419 Redistribution and use in source and binary forms, with or 1420 without modification, is permitted pursuant to, and subject 1421 to the license terms contained in, the Simplified BSD License 1422 set forth in Section 4.c of the IETF Trust's Legal Provisions 1423 Relating to IETF Documents 1424 (http://trustee.ietf.org/license-info). 1426 This version of this YANG module is part of RFC XXXX; see 1427 the RFC itself for full legal notices. 1429 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL 1430 NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'NOT RECOMMENDED', 1431 'MAY', and 'OPTIONAL' in this document are to be interpreted as 1432 described in BCP 14 (RFC 2119) (RFC 8174) when, and only when, 1433 they appear in all capitals, as shown here."; 1435 // RFC Ed.: update the date below with the date of RFC publication 1436 // and remove this note. 1437 // RFC Ed.: replace XXXX with actual RFC number and remove this 1438 // note. 1439 revision 2020-01-21 { 1440 rev:revision-label 0.2.0; 1441 description 1442 "Initial revision"; 1443 reference 1444 "RFC XXXX: YANG Packages"; 1445 } 1447 /* 1448 * Top-level structure 1449 */ 1451 sx:structure package { 1452 description 1453 "Defines the YANG package structure for use in a YANG instance 1454 data document."; 1456 uses pkg-types:yang-pkg-instance; 1457 } 1458 } 1459 1461 file "ietf-yang-package@2021-10-25.yang" 1462 module ietf-yang-packages { 1463 yang-version 1.1; 1464 namespace "urn:ietf:params:xml:ns:yang:ietf-yang-packages"; 1465 prefix pkgs; 1466 import ietf-yang-revisions { 1467 prefix rev; 1468 reference "XXXX: Updated YANG Module Revision Handling"; 1469 } 1471 import ietf-yang-package-types { 1472 prefix pkg-types; 1473 rev:revision-or-derived 0.2.0; 1474 reference "RFC XXX: YANG Packages."; 1475 } 1477 import ietf-inet-types { 1478 prefix inet; 1479 rev:revision-or-derived 2013-07-15; 1480 reference "RFC 6991: Common YANG Data Types."; 1481 } 1483 organization 1484 "IETF NETMOD (Network Modeling) Working Group"; 1486 contact 1487 "WG Web: 1488 WG List: 1490 Author: Rob Wilton 1491 "; 1493 description 1494 "This module defines YANG packages on a server implementation. 1496 Copyright (c) 2018 IETF Trust and the persons identified as 1497 authors of the code. All rights reserved. 1499 Redistribution and use in source and binary forms, with or 1500 without modification, is permitted pursuant to, and subject 1501 to the license terms contained in, the Simplified BSD License 1502 set forth in Section 4.c of the IETF Trust's Legal Provisions 1503 Relating to IETF Documents 1504 (http://trustee.ietf.org/license-info). 1506 This version of this YANG module is part of RFC XXXX; see 1507 the RFC itself for full legal notices. 1509 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL 1510 NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'NOT RECOMMENDED', 1511 'MAY', and 'OPTIONAL' in this document are to be interpreted as 1512 described in BCP 14 (RFC 2119) (RFC 8174) when, and only when, 1513 they appear in all capitals, as shown here."; 1515 // RFC Ed.: update the date below with the date of RFC publication 1516 // and remove this note. 1517 // RFC Ed.: replace XXXX with actual RFC number and remove this 1518 // note. 1519 revision 2021-10-25 { 1520 rev:revision-label 0.2.0; 1521 description 1522 "Initial revision"; 1523 reference 1524 "RFC XXXX: YANG Packages"; 1525 } 1527 /* 1528 * Groupings 1529 */ 1531 grouping yang-pkg-ref { 1532 description 1533 "Defines the leaves used to reference a single YANG package"; 1535 leaf name { 1536 type leafref { 1537 path '/pkgs:packages/pkgs:package/pkgs:name'; 1538 } 1539 description 1540 "The name of the references package."; 1541 } 1543 leaf version { 1544 type leafref { 1545 path '/pkgs:packages' 1546 + '/pkgs:package[pkgs:name = current()/../name]' 1547 + '/pkgs:version'; 1548 } 1550 description 1551 "The version of the referenced package."; 1552 } 1554 } 1556 grouping yang-ds-pkg-ref { 1557 description 1558 "Defines the list used to reference a set of YANG packages that 1559 collectively represent a datastore schema."; 1561 list package { 1562 key "name version"; 1564 description 1565 "Identifies the YANG packages that collectively defines the 1566 schema for the associated datastore. 1568 The datastore schema is defined as the union of all 1569 referenced packages, that MUST represent a referentially 1570 complete schema. 1572 All of the referenced packages must be compatible with no 1573 conflicting module versions or dependencies."; 1575 uses yang-pkg-ref; 1576 } 1577 } 1579 /* 1580 * Top level data nodes. 1581 */ 1583 container packages { 1584 config false; 1585 description "All YANG package definitions"; 1587 list package { 1588 key "name version"; 1590 description 1591 "YANG package instance"; 1593 uses pkg-types:yang-pkg-instance; 1595 leaf-list location { 1596 type inet:uri; 1597 description 1598 "Contains a URL that represents where an instance data file 1599 for this YANG package can be found. 1601 This leaf will only be present if there is a URL available 1602 for retrieval of the schema for this entry. 1604 If multiple locations are provided, then the first 1605 location in the leaf-list MUST be the definitive location 1606 that uniquely identifies this package"; 1607 } 1608 } 1610 } 1611 } 1612 1614 file "ietf-yl-package@2020-01-21.yang" 1615 module ietf-yl-packages { 1616 yang-version 1.1; 1617 namespace "urn:ietf:params:xml:ns:yang:ietf-yl-packages"; 1618 prefix yl-pkgs; 1620 import ietf-yang-revisions { 1621 prefix rev; 1622 reference "XXXX: Updated YANG Module Revision Handling"; 1623 } 1625 import ietf-yang-packages { 1626 prefix pkgs; 1627 rev:revision-or-derived 0.2.0; 1628 reference "RFC XXX: YANG Packages."; 1629 } 1631 import ietf-yang-library { 1632 prefix yanglib; 1633 rev:revision-or-derived 2019-01-04; 1634 reference "RFC 8525: YANG Library"; 1635 } 1637 organization 1638 "IETF NETMOD (Network Modeling) Working Group"; 1640 contact 1641 "WG Web: 1642 WG List: 1644 Author: Rob Wilton 1645 "; 1647 description 1648 "This module provides defined augmentations to YANG library to 1649 allow a server to report YANG package information. 1651 Copyright (c) 2018 IETF Trust and the persons identified as 1652 authors of the code. All rights reserved. 1654 Redistribution and use in source and binary forms, with or 1655 without modification, is permitted pursuant to, and subject 1656 to the license terms contained in, the Simplified BSD License 1657 set forth in Section 4.c of the IETF Trust's Legal Provisions 1658 Relating to IETF Documents 1659 (http://trustee.ietf.org/license-info). 1661 This version of this YANG module is part of RFC XXXX; see 1662 the RFC itself for full legal notices. 1664 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL 1665 NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'NOT RECOMMENDED', 1666 'MAY', and 'OPTIONAL' in this document are to be interpreted as 1667 described in BCP 14 (RFC 2119) (RFC 8174) when, and only when, 1668 they appear in all capitals, as shown here."; 1670 // RFC Ed.: update the date below with the date of RFC publication 1671 // and remove this note. 1672 // RFC Ed.: replace XXXX with actual RFC number and remove this 1673 // note. 1674 revision 2020-01-21 { 1675 rev:revision-label 0.2.0; 1676 description 1677 "Initial revision"; 1678 reference 1679 "RFC XXXX: YANG Packages"; 1680 } 1682 /* 1683 * Augmentations 1684 */ 1686 augment "/yanglib:yang-library/yanglib:schema" { 1687 description 1688 "Allow datastore schema to be related to a set of YANG 1689 packages"; 1691 uses pkgs:yang-ds-pkg-ref; 1692 } 1693 } 1694 1696 file "ietf-yang-inst-data-pkg@2021-10-25.yang" 1697 module ietf-yang-inst-data-pkg { 1698 yang-version 1.1; 1699 namespace "urn:ietf:params:xml:ns:yang:ietf-yang-inst-data-pkg"; 1700 prefix yid-pkg; 1702 import ietf-yang-revisions { 1703 prefix rev; 1704 reference "XXXX: Updated YANG Module Revision Handling"; 1705 } 1707 import ietf-yang-package-types { 1708 prefix pkg-types; 1709 rev:revision-or-derived 0.2.0; 1710 reference "RFC XXX: YANG Schema Versioning."; 1711 } 1713 import ietf-yang-structure-ext { 1714 prefix sx; 1715 reference "RFC XXX: YANG Data Structure Extensions."; 1716 } 1718 import ietf-yang-instance-data { 1719 prefix yid; 1720 reference "RFC XXX: YANG Instance Data File Format."; 1721 } 1723 import ietf-inet-types { 1724 prefix inet; 1725 reference "RFC 6991: Common YANG Data Types."; 1726 } 1728 organization 1729 "IETF NETMOD (Network Modeling) Working Group"; 1731 contact 1732 "WG Web: 1733 WG List: 1735 Author: Rob Wilton 1736 "; 1738 description 1739 "The module augments ietf-yang-instance-data to allow package 1740 definitions to be used to define schema in YANG instance data 1741 documents. 1743 Copyright (c) 2019 IETF Trust and the persons identified as 1744 authors of the code. All rights reserved. 1746 Redistribution and use in source and binary forms, with or 1747 without modification, is permitted pursuant to, and subject 1748 to the license terms contained in, the Simplified BSD License 1749 set forth in Section 4.c of the IETF Trust's Legal Provisions 1750 Relating to IETF Documents 1751 (http://trustee.ietf.org/license-info). 1752 This version of this YANG module is part of RFC XXXX; see 1753 the RFC itself for full legal notices. 1755 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL 1756 NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'NOT RECOMMENDED', 1757 'MAY', and 'OPTIONAL' in this document are to be interpreted as 1758 described in BCP 14 (RFC 2119) (RFC 8174) when, and only when, 1759 they appear in all capitals, as shown here."; 1761 // RFC Ed.: update the date below with the date of RFC publication 1762 // and remove this note. 1763 // RFC Ed.: replace XXXX with actual RFC number and remove this 1764 // note. 1765 revision 2020-01-21 { 1766 rev:revision-label 0.2.0; 1767 description 1768 "Initial revision"; 1769 reference 1770 "RFC XXXX: YANG Packages"; 1771 } 1773 /* 1774 * Augmentations 1775 */ 1777 sx:augment-structure 1778 "/yid:instance-data-set/yid:content-schema-spec" { 1779 description 1780 "Add package reference to instance data set schema 1781 specification"; 1782 case pkg-schema { 1783 container pkg-schema { 1784 uses pkg-types:yang-pkg-identification-leafs; 1786 leaf-list location { 1787 type inet:uri; 1788 description 1789 "Contains a URL that represents where an instance data 1790 file for this YANG package can be found. 1792 This leaf will only be present if there is a URL 1793 available for retrieval of the schema for this entry. 1795 If multiple locations are provided, then the first 1796 location in the leaf-list MUST be the definitive 1797 location that uniquely identifies this package"; 1798 } 1799 } 1801 } 1802 } 1803 } 1804 1806 11. Security Considerations 1808 The YANG modules specified in this document defines a schema for data 1809 that is accessed by network management protocols such as NETCONF 1810 [RFC6241] or RESTCONF [RFC8040]. The lowest NETCONF layer is the 1811 secure transport layer, and the mandatory-to-implement secure 1812 transport is Secure Shell (SSH) [RFC6242]. The lowest RESTCONF layer 1813 is HTTPS, and the mandatory-to-implement secure transport is TLS 1814 [RFC5246]. 1816 The NETCONF access control model [RFC6536] provides the means to 1817 restrict access for particular NETCONF or RESTCONF users to a 1818 preconfigured subset of all available NETCONF or RESTCONF protocol 1819 operations and content. 1821 Similarly to YANG library [I-D.ietf-netconf-rfc7895bis], some of the 1822 readable data nodes in these YANG modules may be considered sensitive 1823 or vulnerable in some network environments. It is thus important to 1824 control read access (e.g., via get, get-config, or notification) to 1825 these data nodes. 1827 One additional key different to YANG library, is that the 'ietf-yang- 1828 package' YANG module defines a schema to allow YANG packages to be 1829 defined in YANG instance data files, that are outside the security 1830 controls of the network management protocols. Hence, it is important 1831 to also consider controlling access to these package instance data 1832 files to restrict access to sensitive information. 1834 As per the YANG library security considerations, the module, revision 1835 and version information in YANG packages may help an attacker 1836 identify the server capabilities and server implementations with 1837 known bugs since the set of YANG modules supported by a server may 1838 reveal the kind of device and the manufacturer of the device. Server 1839 vulnerabilities may be specific to particular modules, module 1840 revisions, module features, or even module deviations. For example, 1841 if a particular operation on a particular data node is known to cause 1842 a server to crash or significantly degrade device performance, then 1843 the YANG packages information will help an attacker identify server 1844 implementations with such a defect, in order to launch a denial-of- 1845 service attack on the device. 1847 12. IANA Considerations 1849 It is expected that a central registry of standard YANG package 1850 definitions is required to support this solution. 1852 It is unclear whether an IANA registry is also required to manage 1853 specific package versions. It is highly desirable to have a specific 1854 canonical location, under IETF control, where the definitive YANG 1855 package versions can be obtained from. 1857 This document requests IANA to registers a URI in the "IETF XML 1858 Registry" [RFC3688]. Following the format in RFC 3688, the following 1859 registrations are requested. 1861 URI: urn:ietf:params:xml:ns:yang:ietf-yang-package-types.yang 1862 Registrant Contact: The IESG. 1863 XML: N/A, the requested URI is an XML namespace. 1865 URI: urn:ietf:params:xml:ns:yang:ietf-yang-package-instance.yang 1866 Registrant Contact: The IESG. 1867 XML: N/A, the requested URI is an XML namespace. 1869 URI: urn:ietf:params:xml:ns:yang:ietf-yang-packages.yang 1870 Registrant Contact: The IESG. 1871 XML: N/A, the requested URI is an XML namespace. 1873 URI: urn:ietf:params:xml:ns:yang:ietf-yl-packages.yang 1874 Registrant Contact: The IESG. 1875 XML: N/A, the requested URI is an XML namespace. 1877 URI: urn:ietf:params:xml:ns:yang:ietf-yang-inst-data-pkg.yang 1878 Registrant Contact: The IESG. 1879 XML: N/A, the requested URI is an XML namespace. 1881 This document requests that the following YANG modules are added in 1882 the "YANG Module Names" registry [RFC6020]: 1884 Name: ietf-yang-package-types.yang 1885 Namespace: urn:ietf:params:xml:ns:yang:ietf-yang-package- 1886 types.yang 1887 Prefix: pkg-types 1888 Reference: RFC XXXX 1890 Name: ietf-yang-package-instance.yang 1891 Namespace: urn:ietf:params:xml:ns:yang:ietf-yang-package- 1892 instance.yang 1893 Prefix: pkg-inst 1894 Reference: RFC XXXX 1895 Name: ietf-yang-packages.yang 1896 Namespace: urn:ietf:params:xml:ns:yang:ietf-yang-packages.yang 1897 Prefix: pkgs 1898 Reference: RFC XXXX 1900 Name: ietf-yl-packages.yang 1901 Namespace: urn:ietf:params:xml:ns:yang:ietf-yl-packages.yang 1902 Prefix: yl-pkgs 1903 Reference: RFC XXXX 1905 Name: ietf-yang-inst-data-pkg.yang 1906 Namespace: urn:ietf:params:xml:ns:yang:ietf-yang-inst-data- 1907 pkg.yang 1908 Prefix: yid-pkg 1909 Reference: RFC XXXX 1911 13. Open Questions/Issues 1913 All issues, along with the draft text, are currently being tracked at 1914 https://github.com/rgwilton/YANG-Packages-Draft/issues/ 1916 14. Acknowledgements 1918 Feedback helping shape this document has kindly been provided by Andy 1919 Bierman, James Cumming, Mahesh Jethanandani, Balazs Lengyel, Ladislav 1920 Lhotka,and Jan Lindblad. 1922 15. References 1924 15.1. Normative References 1926 [I-D.ietf-netconf-rfc7895bis] 1927 Bierman, A., Bjorklund, M., Schoenwaelder, J., Watsen, K., 1928 and R. Wilton, "YANG Library", Work in Progress, Internet- 1929 Draft, draft-ietf-netconf-rfc7895bis-07, 17 October 2018, 1930 . 1933 [I-D.ietf-netmod-module-tags] 1934 Hopps, C., Berger, L., and D. Bogdanovic, "YANG Module 1935 Tags", Work in Progress, Internet-Draft, draft-ietf- 1936 netmod-module-tags-10, 29 February 2020, 1937 . 1940 [I-D.ietf-netmod-yang-data-ext] 1941 Bierman, A., Bjorklund, M., and K. Watsen, "YANG Data 1942 Structure Extensions", Work in Progress, Internet-Draft, 1943 draft-ietf-netmod-yang-data-ext-05, 9 December 2019, 1944 . 1947 [I-D.ietf-netmod-yang-instance-file-format] 1948 Lengyel, B. and B. Claise, "YANG Instance Data File 1949 Format", Work in Progress, Internet-Draft, draft-ietf- 1950 netmod-yang-instance-file-format-21, 8 October 2021, 1951 . 1954 [I-D.ietf-netmod-yang-module-versioning] 1955 Wilton, R., Rahman, R., Lengyel, B., Clarke, J., and J. 1956 Sterne, "Updated YANG Module Revision Handling", Work in 1957 Progress, Internet-Draft, draft-ietf-netmod-yang-module- 1958 versioning-03, 12 July 2021, 1959 . 1962 [I-D.ietf-netmod-yang-semver] 1963 Claise, B., Clarke, J., Rahman, R., Wilton, R., Lengyel, 1964 B., Sterne, J., and K. D'Souza, "YANG Semantic 1965 Versioning", Work in Progress, Internet-Draft, draft-ietf- 1966 netmod-yang-semver-03, 12 July 2021, 1967 . 1970 [I-D.ietf-netmod-yang-solutions] 1971 Wilton, R., "YANG Versioning Solution Overview", Work in 1972 Progress, Internet-Draft, draft-ietf-netmod-yang- 1973 solutions-01, 2 November 2020, 1974 . 1977 [I-D.ietf-netmod-yang-ver-selection] 1978 Wilton, R., Rahman, R., Clarke, J., Sterne, J., and B. Wu, 1979 "YANG Schema Selection", Work in Progress, Internet-Draft, 1980 draft-ietf-netmod-yang-ver-selection-00, 17 March 2020, 1981 . 1984 [I-D.ietf-netmod-yang-versioning-reqs] 1985 Clarke, J., "YANG Module Versioning Requirements", Work in 1986 Progress, Internet-Draft, draft-ietf-netmod-yang- 1987 versioning-reqs-05, 6 July 2021, 1988 . 1991 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1992 Requirement Levels", BCP 14, RFC 2119, 1993 DOI 10.17487/RFC2119, March 1997, 1994 . 1996 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 1997 DOI 10.17487/RFC3688, January 2004, 1998 . 2000 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 2001 (TLS) Protocol Version 1.2", RFC 5246, 2002 DOI 10.17487/RFC5246, August 2008, 2003 . 2005 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 2006 the Network Configuration Protocol (NETCONF)", RFC 6020, 2007 DOI 10.17487/RFC6020, October 2010, 2008 . 2010 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 2011 and A. Bierman, Ed., "Network Configuration Protocol 2012 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 2013 . 2015 [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure 2016 Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011, 2017 . 2019 [RFC6536] Bierman, A. and M. Bjorklund, "Network Configuration 2020 Protocol (NETCONF) Access Control Model", RFC 6536, 2021 DOI 10.17487/RFC6536, March 2012, 2022 . 2024 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 2025 RFC 7950, DOI 10.17487/RFC7950, August 2016, 2026 . 2028 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 2029 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 2030 . 2032 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2033 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 2034 May 2017, . 2036 [RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 2037 and R. Wilton, "Network Management Datastore Architecture 2038 (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018, 2039 . 2041 [RFC8525] Bierman, A., Bjorklund, M., Schoenwaelder, J., Watsen, K., 2042 and R. Wilton, "YANG Library", RFC 8525, 2043 DOI 10.17487/RFC8525, March 2019, 2044 . 2046 15.2. Informative References 2048 [I-D.bierman-netmod-yang-package] 2049 Bierman, A., "The YANG Package Statement", Work in 2050 Progress, Internet-Draft, draft-bierman-netmod-yang- 2051 package-00, 6 July 2015, . 2054 [I-D.ietf-netmod-artwork-folding] 2055 Watsen, K., Auerswald, E., Farrel, A., and Q. Wu, 2056 "Handling Long Lines in Content of Internet-Drafts and 2057 RFCs", Work in Progress, Internet-Draft, draft-ietf- 2058 netmod-artwork-folding-12, 20 January 2020, 2059 . 2062 [openconfigsemver] 2063 "Semantic Versioning for OpenConfig Models", 2064 . 2066 [RFC8199] Bogdanovic, D., Claise, B., and C. Moberg, "YANG Module 2067 Classification", RFC 8199, DOI 10.17487/RFC8199, July 2068 2017, . 2070 Appendix A. Examples 2072 This section provides various examples of YANG packages, and as such 2073 this text is non-normative. The purpose of the examples is to only 2074 illustrate the file format of YANG packages, and how package 2075 dependencies work. It does not imply that such packages will be 2076 defined by IETF, or which modules would be included in those packages 2077 even if they were defined. For brevity, the examples exclude 2078 namespace declarations, and use a shortened URL of "tiny.cc/ietf- 2079 yang" as a replacement for 2080 "https://raw.githubusercontent.com/YangModels/yang/master/standard/ 2081 ietf/RFC". 2083 A.1. Example IETF Network Device YANG package 2085 This section provides an instance data file example of an IETF 2086 Network Device YANG package formatted in JSON. 2088 This example package is intended to represent the standard set of 2089 YANG modules, with import dependencies, to implement a basic network 2090 device without any dynamic routing or layer 2 services. E.g., it 2091 includes functionality such as system information, interface and 2092 basic IP configuration. 2094 As for all YANG packages, all import dependencies are fully resolved. 2095 Because this example uses YANG modules that have been standardized 2096 before YANG semantic versioning, they modules are referenced by 2097 revision date rather than version number. 2099 file "example-ietf-network-device-pkg.json" 2100 ========= NOTE: '\' line wrapping per BCP XX (RFC XXXX) =========== 2102 { 2103 "ietf-yang-instance-data:instance-data-set": { 2104 "name": "example-ietf-network-device-pkg", 2105 "pkg-schema": { 2106 package: "ietf-yang-package-defn-pkg@0.1.0.json" 2107 }, 2108 "description": "YANG package definition", 2109 "content-data": { 2110 "ietf-yang-package-instance:yang-package": { 2111 "name": "example-ietf-network-device-pkg", 2112 "version": "1.1.2", 2113 "timestamp": "2018-12-13T17:00:00Z", 2114 "organization": "IETF NETMOD Working Group", 2115 "contact" : "WG Web: , \ 2116 WG List: ", 2117 "description": "Example IETF network device YANG package.\ 2118 \ 2119 This package defines a small sample set of \ 2120 YANG modules that could represent the basic set of \ 2121 modules that a standard network device might be expected \ 2122 to support.", 2123 "reference": "XXX, draft-rwilton-netmod-yang-packages", 2124 "location": [ "file://example.org/yang/packages/\ 2125 ietf-network-device@v1.1.2.json" ], 2126 "module": [ 2127 { 2128 "name": "iana-crypt-hash", 2129 "revision": "2014-08-06", 2130 "location": [ "https://tiny.cc/ietf-yang/\ 2131 iana-crypt-hash%402014-08-06.yang" ], 2132 }, 2133 { 2134 "name": "ietf-system", 2135 "revision": "2014-08-06", 2136 "location": [ "https://tiny.cc/ietf-yang/\ 2137 ietf-system%402014-08-06.yang" ], 2138 }, 2139 { 2140 "name": "ietf-interfaces", 2141 "revision": "2018-02-20", 2142 "location": [ "https://tiny.cc/ietf-yang/\ 2143 ietf-interfaces%402018-02-20.yang" ], 2144 }, 2145 { 2146 "name": "ietf-netconf-acm", 2147 "revision": "2018-02-14", 2148 "location": [ "https://tiny.cc/ietf-yang/\ 2149 ietf-netconf-acm%402018-02-14.yang" ], 2150 }, 2151 { 2152 "name": "ietf-key-chain", 2153 "revision": "2017-06-15", 2154 "location": [ "https://tiny.cc/ietf-yang/\ 2155 ietf-key-chain@2017-06-15.yang" ], 2156 }, 2157 { 2158 "name": "ietf-ip", 2159 "revision": "2018-02-22", 2160 "location": [ "https://tiny.cc/ietf-yang/\ 2161 ietf-ip%402018-02-22.yang" ], 2162 } 2163 ], 2164 "import-only-module": [ 2165 { 2166 "name": "ietf-yang-types", 2167 "revision": "2013-07-15", 2168 "location": [ "https://tiny.cc/ietf-yang/\ 2169 ietf-yang-types%402013-07-15.yang" ], 2170 }, 2171 { 2172 "name": "ietf-inet-types", 2173 "revision": "2013-07-15", 2174 "location": [ "https://tiny.cc/ietf-yang/\ 2175 ietf-inet-types%402013-07-15.yang" ], 2176 } 2177 ] 2178 } 2180 } 2181 } 2182 } 2183 2185 A.2. Example IETF Basic Routing YANG package 2187 This section provides an instance data file example of a basic IETF 2188 Routing YANG package formatted in JSON. 2190 This example package is intended to represent the standard set of 2191 YANG modules, with import dependencies, that builds upon the example- 2192 ietf-network-device YANG package to add support for basic dynamic 2193 routing and ACLs. 2195 As for all YANG packages, all import dependencies are fully resolved. 2196 Because this example uses YANG modules that have been standardized 2197 before YANG semantic versioning, they modules are referenced by 2198 revision date rather than version number. Locations have been 2199 excluded where they are not currently known, e.g., for YANG modules 2200 defined in IETF drafts. In a normal YANG package, locations would be 2201 expected to be provided for all YANG modules. 2203 file "example-ietf-routing-pkg.json" 2204 ========== NOTE: '\' line wrapping per BCP XX (RFC XXXX) =========== 2206 { 2207 "ietf-yang-instance-data:instance-data-set": { 2208 "name": "example-ietf-routing-pkg", 2209 "module": [ "ietf-yang-package@2019-09-11.yang" ], 2210 "description": "YANG package definition", 2211 "content-data": { 2212 "ietf-yang-package-instance:yang-package": { 2213 "name": "example-ietf-routing", 2214 "version": "1.3.1", 2215 "timestamp": "2018-12-13T17:00:00Z", 2216 "description": "This package defines a small sample set of \ 2217 IETF routing YANG modules that could represent the set of \ 2218 IETF routing functionality that a basic IP network device \ 2219 might be expected to support.", 2220 "reference": "XXX, draft-rwilton-netmod-yang-packages", 2221 "imported-packages": [ 2222 { 2223 "name": "ietf-network-device", 2224 "version": "1.1.2", 2225 "location": [ "http://example.org/yang/packages/\ 2226 ietf-network-device@v1.1.2.json" ], 2227 } 2229 ], 2230 "module": [ 2231 { 2232 "name": "ietf-routing", 2233 "revision": "2018-03-13", 2234 "location": [ "https://tiny.cc/ietf-yang/\ 2235 ietf-routing@2018-03-13.yang" ], 2236 }, 2237 { 2238 "name": "ietf-ipv4-unicast-routing", 2239 "revision": "2018-03-13", 2240 "location": [ "https://tiny.cc/ietf-yang/\ 2241 ietf-ipv4-unicast-routing@2018-03-13.yang" ], 2242 }, 2243 { 2244 "name": "ietf-ipv6-unicast-routing", 2245 "revision": "2018-03-13", 2246 "location": [ "https://tiny.cc/ietf-yang/\ 2247 ietf-ipv6-unicast-routing@2018-03-13.yang" ], 2248 }, 2249 { 2250 "name": "ietf-isis", 2251 "revision": "2018-12-11", 2252 "location": [ "https://tiny.cc/ietf-yang/\ 2253 " ], 2254 }, 2255 { 2256 "name": "ietf-interfaces-common", 2257 "revision": "2018-07-02", 2258 "location": [ "https://tiny.cc/ietf-yang/\ 2259 " ], 2260 }, 2261 { 2262 "name": "ietf-if-l3-vlan", 2263 "revision": "2017-10-30", 2264 "location": [ "https://tiny.cc/ietf-yang/\ 2265 " ], 2266 }, 2267 { 2268 "name": "ietf-routing-policy", 2269 "revision": "2018-10-19", 2270 "location": [ "https://tiny.cc/ietf-yang/\ 2271 " ], 2272 }, 2273 { 2274 "name": "ietf-bgp", 2275 "revision": "2018-05-09", 2276 "location": [ "https://tiny.cc/ietf-yang/\ 2277 " ], 2278 }, 2279 { 2280 "name": "ietf-access-control-list", 2281 "revision": "2018-11-06", 2282 "location": [ "https://tiny.cc/ietf-yang/\ 2283 " ], 2284 } 2285 ], 2286 "import-only-module": [ 2287 { 2288 "name": "ietf-routing-types", 2289 "revision": "2017-12-04", 2290 "location": [ "https://tiny.cc/ietf-yang/\ 2291 ietf-routing-types@2017-12-04.yang" ], 2292 }, 2293 { 2294 "name": "iana-routing-types", 2295 "revision": "2017-12-04", 2296 "location": [ "https://tiny.cc/ietf-yang/\ 2297 iana-routing-types@2017-12-04.yang" ], 2298 }, 2299 { 2300 "name": "ietf-bgp-types", 2301 "revision": "2018-05-09", 2302 "location": [ "https://tiny.cc/ietf-yang/\ 2303 " ], 2304 }, 2305 { 2306 "name": "ietf-packet-fields", 2307 "revision": "2018-11-06", 2308 "location": [ "https://tiny.cc/ietf-yang/\ 2309 " ], 2310 }, 2311 { 2312 "name": "ietf-ethertypes", 2313 "revision": "2018-11-06", 2314 "location": [ "https://tiny.cc/ietf-yang/\ 2315 " ], 2316 } 2317 ] 2318 } 2319 } 2320 } 2321 } 2322 2324 A.3. Package import conflict resolution example 2326 This section provides an example of how a package can resolve 2327 conflicting module versions from imported packages. 2329 In this example, YANG package 'example-3-pkg' imports both 'example- 2330 import-1' and 'example-import-2' packages. However, the two imported 2331 packages implement different versions of 'example-module-A' so the 2332 'example-3-pkg' package selects version '1.2.3' to resolve the 2333 conflict. Similarly, for import-only modules, the 'example-3-pkg' 2334 package does not require both versions of example-types-module-C to 2335 be imported, so it indicates that it only imports revision 2336 '2018-11-26' and not '2018-01-01'. 2338 { 2339 "ietf-yang-instance-data:instance-data-set": { 2340 "name": "example-import-1-pkg", 2341 "description": "First imported example package", 2342 "content-data": { 2343 "ietf-yang-package-instance:yang-package": { 2344 "name": "example-import-1", 2345 "version": "1.0.0", 2346 "reference": "XXX, draft-rwilton-netmod-yang-packages", 2347 "revision-date": "2018-01-01", 2348 "module": [ 2349 { 2350 "name": "example-module-A", 2351 "version": "1.0.0" 2352 }, 2353 { 2354 "name": "example-module-B", 2355 "version": "1.0.0" 2356 } 2357 ], 2358 "import-only-module": [ 2359 { 2360 "name": "example-types-module-C", 2361 "revision": "2018-01-01" 2362 }, 2363 { 2364 "name": "example-types-module-D", 2365 "revision": "2018-01-01" 2366 } 2367 ] 2368 } 2369 } 2370 } 2372 } 2374 { 2375 "ietf-yang-instance-data:instance-data-set": { 2376 "name": "example-import-2-pkg", 2377 "description": "Second imported example package", 2378 "content-data": { 2379 "ietf-yang-package:yang-package": { 2380 "name": "example-import-2", 2381 "version": "2.0.0", 2382 "reference": "XXX, draft-rwilton-netmod-yang-packages", 2383 "revision-date": "2018-11-26", 2384 "module": [ 2385 { 2386 "name": "example-module-A", 2387 "version": "1.2.3" 2388 }, 2389 { 2390 "name": "example-module-E", 2391 "version": "1.1.0" 2392 } 2393 ], 2394 "import-only-module": [ 2395 { 2396 "name": "example-types-module-C", 2397 "revision": "2018-11-26" 2398 }, 2399 { 2400 "name": "example-types-module-D", 2401 "revision": "2018-11-26" 2402 } 2403 ] 2404 } 2405 } 2406 } 2407 } 2409 { 2410 "ietf-yang-instance-data:instance-data-set": { 2411 "name": "example-3-pkg", 2412 "description": "Importing example package", 2413 "content-data": { 2414 "ietf-yang-package:yang-package": { 2415 "name": "example-3", 2416 "version": "1.0.0", 2417 "reference": "XXX, draft-rwilton-netmod-yang-packages", 2418 "revision-date": "2018-11-26", 2419 "included-package": [ 2420 { 2421 "name": "example-import-1", 2422 "version": "1.0.0" 2423 }, 2424 { 2425 "name": "example-import-2", 2426 "version": "2.0.0" 2427 } 2428 ], 2429 "module": [ 2430 { 2431 "name": "example-module-A", 2432 "version": "1.2.3" 2433 } 2434 ], 2435 "import-only-module": [ 2436 { 2437 "name": "example-types-module-C", 2438 "revision": "2018-11-26", 2439 "replaces-revision": [ "2018-01-01 "] 2440 } 2441 ] 2442 } 2443 } 2444 } 2445 } 2447 Appendix B. Possible alternative solutions 2449 This section briefly describes some alternative solutions. It can be 2450 removed if this document is adopted as a WG draft. 2452 B.1. Using module tags 2454 Module tags have been suggested as an alternative solution, and 2455 indeed that can address some of the same requirements as YANG 2456 packages but not all of them. 2458 Module tags can be used to group or organize YANG modules. However, 2459 this raises the question of where this tag information is stored. 2460 Module tags either require that the YANG module files themselves are 2461 updated with the module tag information (creating another versioning 2462 problem), or for the module tag information to be hosted elsewhere, 2463 perhaps in a centralize YANG Catalog, or in instance data files 2464 similar to how YANG packages have been defined in this draft. 2466 One of the principle aims of YANG packages is to be a versioned 2467 object that defines a precise set of YANG modules versions that work 2468 together. Module tags cannot meet this aim without an explosion of 2469 module tags definitions (i.e. a separate module tag must be defined 2470 for each package version). 2472 Module tags cannot support the hierachical scheme to construct YANG 2473 schema that is proposed in this draft. 2475 B.2. Using YANG library 2477 Another question is whether it is necessary to define new YANG 2478 modules to define YANG packages, and whether YANG library could just 2479 be reused in an instance data file. The use of YANG packages offers 2480 several benefits over just using YANG library: 2482 1. Packages allow schema to be built in a hierarchical fashion. 2483 [I-D.ietf-netconf-rfc7895bis] only allows one layer of hierarchy 2484 (using module sets), and there must be no conflicts between 2485 module revisions in different module-sets. 2487 2. Packages can be made available off the box, with a well defined 2488 unique name, avoiding the need for clients to download, and 2489 construct/check the entire YANG schema for each device. YANG 2490 library's use of a 'content-id' is unique only to the device that 2491 generated them. 2493 3. Packages may be versioned using a semantic versioning scheme, 2494 YANG library does not provide a schema level semantic version 2495 number. 2497 4. For a YANG library instance data file to contain the necessary 2498 information, it probably needs both YANG library and various 2499 augmentations (e.g. to include each module's semantic version 2500 number), unless a new version of YANG library is defined 2501 containing this information. The module definition for a YANG 2502 package is specified to contain all of the ncessary information 2503 to solve the problem without augmentations 2505 5. YANG library is designed to publish information about the 2506 modules, datastores, and datastore schema used by a server. The 2507 information required to construct an off box schema is not 2508 precisely the same, and hence the definitions might deviate from 2509 each other over time. 2511 Authors' Addresses 2512 Robert Wilton (editor) 2513 Cisco Systems, Inc. 2515 Email: rwilton@cisco.com 2517 Reshad Rahman 2518 Cisco Systems, Inc. 2520 Email: rrahman@cisco.com 2522 Joe Clarke 2523 Cisco Systems, Inc. 2525 Email: jclarke@cisco.com 2527 Jason Sterne 2528 Nokia 2530 Email: jason.sterne@nokia.com 2532 Bo Wu (editor) 2533 Huawei 2535 Email: lana.wubo@huawei.com