idnits 2.17.1 draft-rwilton-netmod-yang-packages-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 460 has weird spacing: '...mespace ine...' == Line 464 has weird spacing: '...evision yan...' == Line 474 has weird spacing: '...evision yan...' == Line 543 has weird spacing: '...version yan...' == Line 568 has weird spacing: '...version yan...' == (11 more instances...) -- The document date (December 20, 2018) is 1953 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-module-tags' is defined on line 1286, but no explicit reference was found in the text == Unused Reference: 'I-D.ietf-netmod-artwork-folding' is defined on line 1348, but no explicit reference was found in the text == Unused Reference: 'RFC8199' is defined on line 1358, but no explicit reference was found in the text == Outdated reference: A later version (-10) exists of draft-ietf-netmod-module-tags-03 == Outdated reference: A later version (-21) exists of draft-ietf-netmod-yang-instance-file-format-01 ** Downref: Normative reference to an Informational draft: draft-verdt-netmod-yang-versioning-reqs (ref. 'I-D.verdt-netmod-yang-versioning-reqs') ** Obsolete normative reference: RFC 5246 (Obsoleted by RFC 8446) ** Obsolete normative reference: RFC 6536 (Obsoleted by RFC 8341) == Outdated reference: A later version (-12) exists of draft-ietf-netmod-artwork-folding-00 Summary: 3 errors (**), 0 flaws (~~), 13 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group R. Wilton 3 Internet-Draft Cisco Systems, Inc. 4 Intended status: Standards Track December 20, 2018 5 Expires: June 23, 2019 7 YANG Packages 8 draft-rwilton-netmod-yang-packages-00 10 Abstract 12 This document defines YANG packages, an organizational structure 13 holding a set of related YANG modules, that can be used to simplify 14 the conformance and sharing of YANG schema. It describes how YANG 15 instance data documents are used to define YANG packages, and how the 16 YANG library information published by a server can be augmented with 17 additional packaging related information. 19 Status of This Memo 21 This Internet-Draft is submitted in full conformance with the 22 provisions of BCP 78 and BCP 79. 24 Internet-Drafts are working documents of the Internet Engineering 25 Task Force (IETF). Note that other groups may also distribute 26 working documents as Internet-Drafts. The list of current Internet- 27 Drafts is at https://datatracker.ietf.org/drafts/current/. 29 Internet-Drafts are draft documents valid for a maximum of six months 30 and may be updated, replaced, or obsoleted by other documents at any 31 time. It is inappropriate to use Internet-Drafts as reference 32 material or to cite them other than as "work in progress." 34 This Internet-Draft will expire on June 23, 2019. 36 Copyright Notice 38 Copyright (c) 2018 IETF Trust and the persons identified as the 39 document authors. All rights reserved. 41 This document is subject to BCP 78 and the IETF Trust's Legal 42 Provisions Relating to IETF Documents 43 (https://trustee.ietf.org/license-info) in effect on the date of 44 publication of this document. Please review these documents 45 carefully, as they describe your rights and restrictions with respect 46 to this document. Code Components extracted from this document must 47 include Simplified BSD License text as described in Section 4.e of 48 the Trust Legal Provisions and are provided without warranty as 49 described in the Simplified BSD License. 51 Table of Contents 53 1. Terminology and Conventions . . . . . . . . . . . . . . . . . 2 54 2. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 55 3. Background on YANG packaging . . . . . . . . . . . . . . . . 4 56 4. Objectives . . . . . . . . . . . . . . . . . . . . . . . . . 4 57 5. Package description . . . . . . . . . . . . . . . . . . . . . 5 58 5.1. Package definition rules . . . . . . . . . . . . . . . . 6 59 5.2. Package versioning . . . . . . . . . . . . . . . . . . . 7 60 5.3. Client server package conformance . . . . . . . . . . . . 8 61 5.4. Submodules packaging considerations . . . . . . . . . . . 8 62 5.5. Revision history . . . . . . . . . . . . . . . . . . . . 9 63 5.6. Uniqueness of packages and global registry . . . . . . . 9 64 6. YANG Packaging instance data . . . . . . . . . . . . . . . . 9 65 7. YANG Packaging additions to YANG library . . . . . . . . . . 11 66 7.1. Package List . . . . . . . . . . . . . . . . . . . . . . 11 67 7.2. Binding from schema to package . . . . . . . . . . . . . 11 68 7.3. Tree diagram . . . . . . . . . . . . . . . . . . . . . . 12 69 8. YANG Packaging groupings . . . . . . . . . . . . . . . . . . 12 70 9. YANG Modules . . . . . . . . . . . . . . . . . . . . . . . . 14 71 10. Open Questions/Issues . . . . . . . . . . . . . . . . . . . . 26 72 11. Security Considerations . . . . . . . . . . . . . . . . . . . 26 73 12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 27 74 13. References . . . . . . . . . . . . . . . . . . . . . . . . . 27 75 13.1. Normative References . . . . . . . . . . . . . . . . . . 27 76 13.2. Informative References . . . . . . . . . . . . . . . . . 29 77 Appendix A. Tree output for ietf-yang-library with package 78 augmentations . . . . . . . . . . . . . . . . . . . 29 79 Appendix B. Examples . . . . . . . . . . . . . . . . . . . . . . 31 80 B.1. Example IETF Network Device YANG package . . . . . . . . 31 81 B.2. Example IETF Basic Routing YANG package . . . . . . . . . 34 82 B.3. Package import conflict resolution example . . . . . . . 37 83 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 39 85 1. Terminology and Conventions 87 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 88 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 89 "OPTIONAL" in this document are to be interpreted as described in BCP 90 14 [RFC2119] [RFC8174] when, and only when, they appear in all 91 capitals, as shown here. 93 This document uses terminology introduced in the YANG versioning 94 requirements draft [I-D.verdt-netmod-yang-versioning-reqs]. 96 This document also makes of the following terminology introduced in 97 the Network Management Datastore Architecture [RFC8342]: 99 o datastore schema 101 In addition, this document makes use of the following terminology: 103 o bc: Used as an abbreviation for a backwards-compatible change. 105 o nbc: Used as an abbreviation for a non-backwards-compatible 106 change. 108 o editorial change: A backwards-compatible change that does not 109 change the YANG module semantics in any way. 111 Note - the bc/nbc/editorial terminology should probably be defined 112 and referenced from the YANG module versioning solution draft. 114 2. Introduction 116 This document defines and describes the YANG [RFC7950] constructs 117 that are used to define and use YANG packages. 119 A YANG package is an organizational structure that groups a set of 120 related YANG modules together into a consistent versioned definition. 121 YANG packages can themselves refer to and reuse other package 122 definitions. 124 The draft consists of the following significant sections: 126 A background section that describes some of the prior work in this 127 area, both within IETF and the wider industry. 129 An overview of the objectives for a YANG packaging solution, and also 130 what work is out of scope for this document. 132 The definition of YANG packages, how package definitions are 133 constructed, and how they are used. 135 How YANG instance data documents 136 [I-D.ietf-netmod-yang-instance-file-format] are used to define 137 particular YANG package instances. 139 Augmentations to the YANG library [I-D.ietf-netconf-rfc7895bis] 140 content published by servers to include YANG packaging related 141 information. 143 YANG modules the provide the definitions for YANG packages. 145 Non-normative examples of YANG package instances are provided in the 146 appendicies. 148 3. Background on YANG packaging 150 It has long been acknowledged within the IETF NETMOD community that 151 network management using YANG requires a unit of organization and 152 conformance that is broader in scope than individual YANG modules. 154 'The YANG Package Statement' [I-D.bierman-netmod-yang-package] 155 proposed a YANG package mechanism based on new YANG language 156 statements, where a YANG package is defined in a file similar to how 157 YANG modules are defined, and would require enhancements to YANG 158 compilers to understand the new statements used to define particular 159 package instances. This document did not progress in the working 160 group, although this may have been due to other higher priority 161 concerns or resource constraints within the working group rather than 162 due to consideration of the technical merits of the proposed 163 approach. 165 OpenConfig [openconfigsemver] describes an approach to versioning 166 'bundle releases' based on git tags. I.e. a set of modules, at 167 particular versions, can be marked with the same release tag to 168 indicate that they are known to interoperate together. 170 The NETMOD WG in general, and the YANG versioning design team in 171 particular, are exploring solutions to the YANG versioning 172 requirements, [I-D.verdt-netmod-yang-versioning-reqs]. Solutions to 173 the versioning requirements can be split into several distinct areas. 174 One draft, TBD (draft-verdt-netmod-yang-semver), has a primary focus 175 on YANG versioning scoped to individual modules. But an overall 176 solution should also consider YANG versioning and conformance scoped 177 to a server's datastore schema. YANG packages may help form part of 178 the solution for versioning at the datastore schema level. 180 4. Objectives 182 The main goals of YANG package definitions include, but are not 183 restricted to: 185 o To act as a simplified YANG conformance mechanism. Rather than 186 conformance being performed against a set of individual YANG 187 module revisions, conformance could also be more simply stated in 188 terms of YANG packages, with a set modifications (e.g. additional 189 modules, deviations, or features). 191 o To allow YANG datastore schema to be specified in a more concise 192 way rather than having to list all modules and revisions. YANG 193 package definitions can be defined in documents that can be 194 referenced by a URI rather than requiring explicit lists of 195 modules to be shared between client and server. Hence, a YANG 196 package must contain sufficient information to allow a client or 197 server to precisely construct the schema associated with the 198 package. 200 o To provide generic packaging related YANG grouping definitions for 201 use in other YANG modules, as required. 203 Protocol mechanisms of how clients could negotiate which packages or 204 package versions are be used for client server communications are 205 outside the scope of this document. However, the design of the YANG 206 library augmentations for YANG packages are intended to keep open the 207 possibility of such extensions in future work. 209 Finally, the package definitions proposed by this document are 210 intended to be relatively basic in their definition and the 211 functionality that they support. As indsutry gains experience using 212 YANG packages, the standard YANG mechanisms of updating, or 213 augmenting, YANG modules could be used to extend the functionality 214 supported by YANG packages. 216 5. Package description 218 This document specifies an approach to defining YANG packages that is 219 different to either of the approaches described in the background. 221 The approach defined here is for a YANG package definition structure 222 to be defined using existing YANG language statements without 223 requiring extensions or new YANG statements. By making use of this 224 structure, particular YANG package instances can be defined as YANG 225 instance data documents [I-D.ietf-netmod-yang-instance-file-format] 226 with well defined names and locations. 228 The YANG sementic versioning scheme, described in draft-verdt-netmod- 229 yang-semver (TBD), is used to version YANG packages using an 230 equivalent scheme to how individual YANG modules version numbers are 231 changed. 233 YANG library is augmented to allow servers to report the packages 234 that they implement and to associate those packages back to 235 particular datastore schema. 237 TODO - It would be helpful if the YANG instance data file format 238 [I-D.ietf-netmod-yang-instance-file-format] could also reference a 239 YANG packages to specify the schema associated with an instance data 240 document. This could either be defined in instance-file-format 241 draft, or as a YANG augmentation as part of this draft. 243 Each version of a YANG package defines: a set of YANG modules that 244 are implemented at particular versions or revisions; a set of YANG 245 modules that are import-only with particular versions or revisions; 246 and a set of mandatory module features that implementations of the 247 package MUST implement or otherwise deviate. 249 5.1. Package definition rules 251 The following rules define how packages are defined: 253 Every YANG package definition MUST be referentially complete. 254 I.e. all import and include statements for all YANG modules 255 included in a package MUST resolve to a module specified in the 256 package itself, or an imported package. 258 For a given package, each separate instance of the package MUST 259 have a unique version number that follows the semantic versioning 260 rules described in Section 5.2. 262 A package MAY have a revision-date. Any package revision-dates 263 MUST be unique for different package versions. 265 For each module implemented by a package, only a single revision/ 266 version MUST be implemented. 268 The version/revision of a module listed in the package module list 269 supercedes any version/revision of the module listed in a imported 270 package module list. This allows a package to resolve any 271 conflicting implemented module versions/revisions in imported 272 packages. 274 The replaces-revision leaf-list in the import-only-module list can 275 be used to exclude duplicate revisions of import-only modules from 276 imported packages. Otherwise, the import-only-modules for a 277 package are the import-only-modules from all imported packages 278 combined with any modules listed in the packages import-only- 279 module list. 281 Modules referenced by a package SHOULD specify the version of the 282 module, both in the package definition and within the module 283 definition itself. 285 Modules referenced by a package MUST specify the revision date of 286 the module, both in the package definition and within the module 287 definition itself. 289 5.2. Package versioning 291 Every YANG package must specify a YANG semantic version field that 292 defines the particular version of the package. 294 The rules for incrementing the YANG package version number are 295 equivalent to the semantic versioning rules used to version 296 individual YANG modules, defined in TBD (draft-verdt-netmod-yang- 297 semver). 299 The semantic versioning rules, as they apply to YANG packages, are 300 defined using the following two step process: 302 The first step is to determined whether the change to the YANG 303 package is classified as a major, minor, or editorial based on the 304 content that has changed in the package relative to the previous 305 version. Where available, the semantic version number of the 306 referenced elements in the package (imported packages or modules) can 307 be used to help determine what type of change is being made. The 308 formal rules are: 310 If any of the referenced elements of the package (imported 311 packages or modules) are changed in an nbc way, or if any imported 312 package, module, or mandatory-feature is removed from the package 313 definition, then the package has been updated in an nbc way. 315 If none of the referenced elements of the package (imported 316 packages, modules) are removed or changed in a nbc way, but some 317 referenced elements are changed in a bc way, or new referenced 318 elements or mandatory-features added, then the package is deemed 319 to be updated in a bc way. 321 If none of the referenced elements of the package (imported 322 packages, modules) are added, removed, or changed in a nbc or bc 323 way, but some referenced elements have editorial changes then the 324 package is deemed to be updated in an editorial way. 326 The second step, after it has been determined what type of version 327 change is being made to the YANG package, is for the YANG semantic 328 versioning rules to be applied to update the YANG package semantic 329 version number. The formal rules are: 331 If the package is being updated in a nbc way, then the package 332 version "X.Y.Z[m|M]" SHOULD be updated to "X+1.0.0" unless that 333 package version has already been defined with different content, 334 in which case the package version "X.Y.Z+1M MUST be used instead. 336 If the package is being updated in a bc way, then the package 337 version "X.Y.Z[m|M]" SHOULD be updated to "X.Y+1.0" unless that 338 package version has already been defined with different content, 339 in which case if the current package version is "X.Y.ZM" then it 340 MUST be updated to "X.Y.Z+1M", or otherwise "X.Y.Z+1m". 342 If the package is being updated in an editorial way, then the 343 package version "X.Y.Z[m|M]" MUST be updated to "X.Y.Z+1[m|M], 344 retaining the 'm|M' character if it is already present in the 345 previous version.". 347 Package YANG semantic version numbers begining with 0, i.e "0.X.Y" 348 are regarded as beta definitions and need not follow the nbc 349 rules, and the minor version number can be incremented instead. 351 In all cases, the 3 number fields that comprise a YANG semantic 352 version number associated with a YANG package MUST uniquely 353 identify the contents of that YANG package. 355 5.3. Client server package conformance 357 The YANG semantic versioning scheme used for YANG packages means that 358 a client can determine the nature of changes between two package 359 revisions. 361 This means that a client is not restricted to working only with 362 servers that advertise exactly the same version of package in YANG 363 libary. Instead, reasonable clients should be able to interoperate 364 with a server that supports a package version that is backwards 365 compatible to what the client is designed for. 367 For example, a client coded to support 'foo' package at version 1.0.0 368 should interoperate with a server implementing 'foo' package at 369 version 1.3.5, because the YANG semantic versioning rules require 370 that package version 1.3.5 is backwards compatible to version 1.0.0. 372 This also has a relevance on servers that are capable of supporting 373 version selection because they need not necessarily support every 374 version of a YANG package to ensure good client compatibility. 375 Choosing suitable minor versions within each major version number 376 should generally be sufficient, particular if they can avoid NBC 377 patch level changes (i.e. 'M' labelled versions). 379 5.4. Submodules packaging considerations 381 As defined in [RFC7950] and draft-verdt-netmod-yang-semver (TBD), 382 YANG conformance and versioning is specified in terms of particular 383 revisions of YANG modules rather than for individual submodules. 385 However, YANG package definitions also include the list of submodules 386 included by a module, primarily to provide a location of where the 387 submodule definition can be obtained from, allowing a YANG schema to 388 be fully constructed from a YANG package instance-data definition. 390 Restructuring how a module uses, or does not use, submodules is 391 treated as an editorial level change in YANG semantic versioning, on 392 the condition that there is no change in the modules sementic 393 behavior due to the restructuring. 395 To ensure that a module and any constituent submodule are tightly 396 related, all 'include' statements in a YANG module SHOULD specify 397 revision-dates of the included submodules. If 'include' statement 398 revision-dates are included in the YANG module then they MUST match 399 the 'revision' field specified for the submodule in the packages's 400 submodules lists. 402 5.5. Revision history 404 TODO - Probably eventually delete this section ... 406 YANG packages do not contain a revision history. It is anticipated 407 that YANG packages versions may become branched over time and hence 408 maintaining a linear revision history would likely be promlematic and 409 less useful. Further, if YANG packages versions are managed in a 410 source control system, then additional version meta-data information 411 could be stored in the source control system, which are generally 412 capable of representing a branched revision history. 414 5.6. Uniqueness of packages and global registry 416 The name given to a package SHOULD be globally unique, and it SHOULD 417 include an appropriate organization prefix in the name, equivalent to 418 YANG module naming conventions. 420 Each package MUST define a unique namespace. It is anticipated that 421 a registry of package namespaces would be managed by IANA. It is 422 unclear whether specific standard package versions would need to be 423 managed in a similar way. 425 Ideally a YANG instance data document defining a particular package 426 version would be publically available at one or more URIs. 428 6. YANG Packaging instance data 430 YANG packages are expected to be defined as YANG instance data 431 documents [I-D.ietf-netmod-yang-instance-file-format] using the YANG 432 schema below to define the pacakge data itself. 434 The instance data document for each version of a YANG package SHOULD 435 be made available at one of more locations accessible via a URI. If 436 one of the listed locations defines a definitive reference 437 implementation for the package definition then it MUST be listed as 438 the first entry in the list. 440 The "ietf-yang-package" YANG module has the following structure: 442 module: ietf-yang-package 443 +--ro yang-package 444 +--ro name yang:yang-identifier 445 +--ro version yang-sem-ver 446 +--ro revision-date? yanglib:revision-identifier 447 +--ro location* inet:uri 448 +--ro description? string 449 +--ro reference? string 450 +--ro tag* tags:tag 451 +--ro mandatory-feature* string 452 +--ro imported-packages* [name version] 453 | +--ro name yang:yang-identifier 454 | +--ro version yang-sem-ver 455 | +--ro location* inet:uri 456 +--ro module* [name] 457 | +--ro name yang:yang-identifier 458 | +--ro revision? revision-identifier 459 | +--ro version? yang-sem-ver 460 | +--ro namespace inet:uri 461 | +--ro location* inet:uri 462 | +--ro submodule* [name] 463 | +--ro name yang:yang-identifier 464 | +--ro revision yanglib:revision-identifier 465 | +--ro location* inet:uri 466 +--ro import-only-module* [name revision] 467 +--ro name yang:yang-identifier 468 +--ro revision union 469 +--ro version? yang-sem-ver 470 +--ro namespace inet:uri 471 +--ro location* inet:uri 472 +--ro submodule* [name] 473 | +--ro name yang:yang-identifier 474 | +--ro revision yanglib:revision-identifier 475 | +--ro location* inet:uri 476 +--ro replaces-revision* yanglib:revision-identifier 478 7. YANG Packaging additions to YANG library 480 7.1. Package List 482 The main addition is a top level 'yang-library/package' list that 483 lists all package of all versions known to the server. Each package 484 itself is defined using imported packages and module-sets to define 485 the specific set of modules implemented and imported by the package. 486 The use of module-sets allows the module definitions to be shared 487 with the existing YANG library schema definitions. The existing rule 488 of RFC 7995bis related to combining modules-sets also applies here, 489 i.e. The combined set of modules defined by the module-sets MUST NOT 490 contain modules implemented at different revisions. I.e. the module- 491 sets leaf-list is directly equivalent to the explicit module and 492 import-only-module lists in the instance data YANG package 493 definition. 495 The 'yang-library/package' list MAY include multiple versions of a 496 particular package. E.g. if the server is capable of allowing 497 clients to select which package versions should be used by the 498 server. 500 7.2. Binding from schema to package 502 The second augmentation is to allow a server to optionally indicate 503 that a schema definition directly relates to a package. Since YANG 504 packages are available offline, it may be sufficient for a client to 505 only check that a compatible version of the YANG package is being 506 implemented by the server without fetching and comparing the full 507 module list. 509 If a server indicates that its schema maps to a particular package 510 then it MUST support all mandatory-features defined as part of that 511 package, and it MUST NOT have any deviations to the modules defined 512 by the package. A server MAY implement features not specified in the 513 package's mandatory-features list. 515 If a server cannot faithfully implement a package then it can define 516 a new package to accurately report what it does implement. The new 517 package can include the original package as an imported package, and 518 the new package can define additional modules containing deviations 519 to the original package, allowing the new package to accurately 520 describe the server behavior. There is no specific mechanism 521 provided to indicate that a mandatory-feature is not supported on a 522 server, but deviations MAY be used to disable functionality 523 predicated by a mandatory-feature. 525 7.3. Tree diagram 527 The "ietf-yang-library-packages" YANG module has the following 528 structure: 530 module: ietf-yang-library-packages 531 augment /yanglib:yang-library: 532 +--ro package* [name version] 533 +--ro name yang:yang-identifier 534 +--ro version yang-sem-ver 535 +--ro revision-date? yanglib:revision-identifier 536 +--ro location* inet:uri 537 +--ro description? string 538 +--ro reference? string 539 +--ro tag* tags:tag 540 +--ro mandatory-feature* string 541 +--ro imported-packages* [name version] 542 | +--ro name yang:yang-identifier 543 | +--ro version yang-sem-ver 544 +--ro module-set* 545 -> /yanglib:yang-library/module-set/name 546 augment /yanglib:yang-library/yanglib:schema: 547 +--ro package 548 +--ro name? -> /yanglib:yang-library/package/name 549 +--ro version? leafref 550 augment /yanglib:yang-library/yanglib:module-set/ 551 yanglib:import-only-module: 552 +--ro replaces-revision* yanglib:revision-identifier 554 8. YANG Packaging groupings 556 Groupings for YANG packaging related constructs are provided in a 557 'types' module for use by the instance-data and YANG library 558 constructs described previously. They are also avaiable to be used 559 by other modules that have a need for packaging information. 561 The "ietf-yang-package-types" YANG module has the following 562 structure: 564 module: ietf-yang-package-types 566 grouping yang-pkg-identification-leafs 567 +---- name yang:yang-identifier 568 +---- version yang-sem-ver 569 grouping yang-pkg-common-leafs 570 +---- revision-date? yanglib:revision-identifier 571 +---- location* inet:uri 572 +---- description? string 573 +---- reference? string 574 +---- tag* tags:tag 575 +---- mandatory-feature* string 576 +---- imported-packages* [name version] 577 +---- name yang:yang-identifier 578 +---- version yang-sem-ver 579 grouping yang-pkg-library-definition 580 +---- name yang:yang-identifier 581 +---- version yang-sem-ver 582 +---- revision-date? yanglib:revision-identifier 583 +---- location* inet:uri 584 +---- description? string 585 +---- reference? string 586 +---- tag* tags:tag 587 +---- mandatory-feature* string 588 +---- imported-packages* [name version] 589 | +---- name yang:yang-identifier 590 | +---- version yang-sem-ver 591 +---- module-set* 592 -> /yanglib:yang-library/module-set/name 593 grouping yang-pkg-file-definition 594 +---- name yang:yang-identifier 595 +---- version yang-sem-ver 596 +---- revision-date? yanglib:revision-identifier 597 +---- location* inet:uri 598 +---- description? string 599 +---- reference? string 600 +---- tag* tags:tag 601 +---- mandatory-feature* string 602 +---- imported-packages* [name version] 603 | +---- name yang:yang-identifier 604 | +---- version yang-sem-ver 605 | +---- location* inet:uri 606 +---- module* [name] 607 | +---- name yang:yang-identifier 608 | +---- revision? revision-identifier 609 | +---- version? yang-sem-ver 610 | +---- namespace inet:uri 611 | +---- location* inet:uri 612 | +---- submodule* [name] 613 | +---- name? yang:yang-identifier 614 | +---- revision yanglib:revision-identifier 615 | +---- location* inet:uri 616 +---- import-only-module* [name revision] 617 +---- name? yang:yang-identifier 618 +---- revision? union 619 +---- version? yang-sem-ver 620 +---- namespace inet:uri 621 +---- location* inet:uri 622 +---- submodule* [name] 623 | +---- name? yang:yang-identifier 624 | +---- revision yanglib:revision-identifier 625 | +---- location* inet:uri 626 +---- replaces-revision* yanglib:revision-identifier 628 9. YANG Modules 630 The YANG module definitions for the modules described in the previous 631 sections. 633 file "ietf-yang-package-types@2018-11-26.yang" 634 module ietf-yang-package-types { 635 yang-version 1.1; 636 namespace "urn:ietf:params:xml:ns:yang:ietf-yang-package-types"; 637 prefix "pkg-types"; 639 import ietf-yang-types { 640 prefix yang; 641 reference "RFC 6991: Common YANG Data Types."; 642 } 643 import ietf-inet-types { 644 prefix inet; 645 reference "RFC 6991: Common YANG Data Types."; 646 } 647 import ietf-yang-library { 648 prefix yanglib; 649 reference "RFC 7895bis: YANG Library"; 650 } 651 import ietf-module-tags { 652 prefix tags; 653 reference 654 "XXX, (draft-ietf-netmod-module-tags-03): YANG Module Tags"; 655 } 657 organization 658 "IETF NETMOD (Network Modeling) Working Group"; 660 contact 661 "WG Web: 662 WG List: 663 Author: Rob Wilton 664 "; 666 description 667 "This module provides type and grouping definitions for YANG 668 packages. 670 Copyright (c) 2018 IETF Trust and the persons identified as 671 authors of the code. All rights reserved. 673 Redistribution and use in source and binary forms, with or 674 without modification, is permitted pursuant to, and subject 675 to the license terms contained in, the Simplified BSD License 676 set forth in Section 4.c of the IETF Trust's Legal Provisions 677 Relating to IETF Documents 678 (http://trustee.ietf.org/license-info). 680 This version of this YANG module is part of RFC XXXX; see 681 the RFC itself for full legal notices."; 683 // RFC Ed.: update the date below with the date of RFC publication 684 // and remove this note. 685 // RFC Ed.: replace XXXX with actual RFC number and remove this 686 // note. 687 revision 2018-11-26 { 688 description 689 "Initial revision"; 690 reference 691 "RFC XXXX: YANG Schema Versioning."; 692 } 694 /* 695 * Typedefs 696 */ 698 typedef yang-sem-ver { 699 type string { 700 pattern '\d+[.]\d+[.]\d+[mM]?'; 701 } 702 description 703 "Represents a YANG semantic version number."; 704 reference 705 "TODO - Should be defined by YANG versioning types module"; 706 } 708 /* 709 * Groupings 710 */ 712 grouping yang-pkg-identification-leafs { 713 description 714 "Parameters for identifying a specific version of a YANG 715 package"; 717 leaf name { 718 type yang:yang-identifier; 719 mandatory true; 720 description 721 "The YANG package name."; 722 } 724 leaf version { 725 type yang-sem-ver; 726 mandatory true; 727 description 728 "YANG package version. Follows YANG semantic versions rules 729 defined in XXX"; 730 } 731 } 733 grouping yang-pkg-common-leafs { 734 description 735 "Defines definitions common to all YANG package definitions."; 737 leaf revision-date { 738 type yanglib:revision-identifier; 740 description 741 "An optional revision identifier of when this package version 742 was created. This does not need to be unique across all 743 versions of a package."; 744 } 746 leaf-list location { 747 type inet:uri; 748 description 749 "Contains a URL that represents where an instance data file 750 for this YANG package can be found. 752 This leaf will only be present if there is a URL 753 available for retrieval of the schema for this entry. 755 If multiple locations are provided, then the first location 756 in the leaf-list MUST be the definitive location that 757 uniquely identifies this package"; 758 } 759 leaf description { 760 type string; 762 description "Provides a description of the package"; 763 } 765 leaf reference { 766 type string; 768 description "Allows for a reference for the package"; 769 } 771 leaf-list tag { 772 type tags:tag; 773 description 774 "Tags associated with a YANG package. Module tags defined in 775 XXX, ietf-netmod-module-tags can be used here but with the 776 modification that the tag applies to the entire package 777 rather than a specific module. See the IANA 'YANG Module Tag 778 Prefix' registry for reserved prefixes and the IANA 'YANG 779 Module IETF Tag' registry for IETF standard tags."; 780 } 782 leaf-list mandatory-feature { 783 type string; 784 // TODO - Is there a better type for this? 785 description 786 "List all features from modules included in the package that 787 MUST be supported by any server implementing the package. 788 All other features defined in included packages are OPTIONAL 789 to implement. 791 Features are identified using :"; 792 } 794 list imported-packages { 795 key "name version"; 796 description 797 "An entry in this list represents a package that is imported 798 as part of the package definition. 800 If packages implement different revisions or versions of the 801 same module, then an explicit entry in the module list MUST 802 be provided to select the specific module version 803 'implemented' by this package definition. 805 For import-only modules, the replaces-revision leaf-list can 806 be used to select the specific module versions imported by 807 this package."; 808 reference 809 "XXX"; 811 uses yang-pkg-identification-leafs; 812 } 813 } 815 grouping yang-pkg-file-definition { 816 description 817 "The set of parameters that describe a particular YANG package."; 819 uses yang-pkg-identification-leafs; 821 uses yang-pkg-common-leafs { 822 augment "imported-packages" { 823 description "Add the package location path"; 825 leaf-list location { 826 type inet:uri; 827 description 828 "Contains a URL that represents where an instance data 829 file for this YANG package can be found. 831 This leaf will only be present if there is a URL 832 available for retrieval of the schema for this entry. 834 If multiple locations are provided, then the first 835 location in the leaf-list MUST be the definitive location 836 that uniquely identifies this package"; 837 } 838 } 839 } 841 list module { 842 key "name"; 843 description 844 "An entry in this list represents a module that must be 845 implemented by a server implementing this package, as per 846 RFC 7950 section 5.6.5, with a particular set of supported 847 features and deviations. 849 A entry in this list overrides any module version 850 'implemented' by an imported package"; 851 reference 852 "RFC 7950: The YANG 1.1 Data Modeling Language."; 854 uses yanglib:module-identification-leafs; 855 leaf version { 856 type yang-sem-ver; 857 description 858 "The YANG module or submodule version. If no version 859 statement is present in the YANG module or submodule, this 860 leaf is not instantiated."; 861 } 863 leaf namespace { 864 type inet:uri; 865 mandatory true; 866 description 867 "The XML namespace identifier for this module."; 868 } 869 uses yanglib:location-leaf-list; 871 list submodule { 872 key "name"; 873 description 874 "Each entry represents one submodule within the 875 parent module."; 877 leaf name { 878 type yang:yang-identifier; 879 description 880 "The YANG submodule name."; 881 } 882 leaf revision { 883 type yanglib:revision-identifier; 884 mandatory true; 885 description 886 "The YANG submodule revision date. If the parent module 887 include statement for this submodule includes a revision 888 date then it MUST match this leaf's value."; 889 } 891 uses yanglib:location-leaf-list; 892 } 893 } 895 list import-only-module { 896 key "name revision"; 897 description 898 "An entry in this list indicates that the server imports 899 reusable definitions from the specified revision of the 900 module, but does not implement any protocol accessible 901 objects from this revision. 903 Multiple entries for the same module name MAY exist. This 904 can occur if multiple modules import the same module, but 905 specify different revision-dates in the import statements."; 907 leaf name { 908 type yang:yang-identifier; 909 description 910 "The YANG module name."; 911 } 912 leaf revision { 913 type union { 914 type yanglib:revision-identifier; 915 type string { 916 length 0; 917 } 918 } 919 description 920 "The YANG module revision date. A zero-length string is 921 used if no revision statement is present in the YANG 922 module."; 923 } 924 leaf version { 925 type yang-sem-ver; 926 description 927 "The YANG module or submodule version. If no version 928 statement is present in the YANG module or submodule, this 929 leaf is not instantiated."; 930 } 931 leaf namespace { 932 type inet:uri; 933 mandatory true; 934 description 935 "The XML namespace identifier for this module."; 936 } 938 uses yanglib:location-leaf-list; 940 list submodule { 941 key "name"; 942 description 943 "Each entry represents one submodule within the 944 parent module."; 946 leaf name { 947 type yang:yang-identifier; 948 description 949 "The YANG submodule name."; 950 } 951 leaf revision { 952 type yanglib:revision-identifier; 953 mandatory true; 954 description 955 "The YANG submodule revision date. If the parent module 956 include statement for this submodule includes a revision 957 date then it MUST match this leaf's value."; 958 } 960 uses yanglib:location-leaf-list; 961 } 963 leaf-list replaces-revision { 964 type yanglib:revision-identifier; 965 description 966 "Gives the revision of an import-only-module defined in 967 an imported package that is replaced by this 968 import-only-module revision."; 969 } 970 } 971 } 973 grouping yang-pkg-library-definition { 974 description 975 "The set of parameters that describe a particular YANG package."; 977 uses yang-pkg-identification-leafs; 978 uses yang-pkg-common-leafs; 980 leaf-list module-set { 981 type leafref { 982 path "/yanglib:yang-library/yanglib:module-set/yanglib:name"; 983 } 984 description 985 "Describes any modules in addition to, and replacing, and 986 modules defined in the imported packages. 988 If a non import-only module appears in multiple module sets, 989 then the module revision and the associated features and 990 deviations must be identical."; 991 } 992 } 993 } 994 996 file "ietf-yang-package2018-11-26.yang" 997 module ietf-yang-package { 998 yang-version 1.1; 999 namespace "urn:ietf:params:xml:ns:yang:ietf-yang-package"; 1000 prefix pkg; 1002 import ietf-yang-package-types { 1003 prefix pkg-types; 1004 reference "RFC XXX: YANG Schema Versioning."; 1005 } 1007 organization 1008 "IETF NETMOD (Network Modeling) Working Group"; 1010 contact 1011 "WG Web: 1012 WG List: 1014 Author: Rob Wilton 1015 "; 1017 description 1018 "This module provides a definition of a YANG package, which is 1019 used as the schema for an YANG instance data document specifying 1020 a YANG package. 1022 Copyright (c) 2018 IETF Trust and the persons identified as 1023 authors of the code. All rights reserved. 1025 Redistribution and use in source and binary forms, with or 1026 without modification, is permitted pursuant to, and subject 1027 to the license terms contained in, the Simplified BSD License 1028 set forth in Section 4.c of the IETF Trust's Legal Provisions 1029 Relating to IETF Documents 1030 (http://trustee.ietf.org/license-info). 1032 This version of this YANG module is part of RFC XXXX; see 1033 the RFC itself for full legal notices."; 1035 // RFC Ed.: update the date below with the date of RFC publication 1036 // and remove this note. 1037 // RFC Ed.: replace XXXX with actual RFC number and remove this 1038 // note. 1039 revision 2018-11-26 { 1040 description 1041 "Initial revision"; 1042 reference 1043 "RFC XXXX: YANG Schema Versioning."; 1044 } 1045 /* 1046 * Top-level container 1047 */ 1049 container yang-package { 1050 config false; 1051 description 1052 "Defines a YANG package. 1054 Intended to be used to specify a YANG package as an instance 1055 data document."; 1057 uses pkg-types:yang-pkg-file-definition; 1058 } 1059 } 1060 1062 file "ietf-yang-library-packages@2018-11-26.yang" 1063 module ietf-yang-library-packages { 1064 yang-version 1.1; 1065 namespace 1066 "urn:ietf:params:xml:ns:yang:ietf-yang-library-packages"; 1067 prefix pkg; 1069 import ietf-yang-package-types { 1070 prefix pkg-types; 1071 reference "RFC XXX: YANG Packages."; 1072 } 1073 import ietf-yang-library { 1074 prefix yanglib; 1075 reference "RFC 7895bis: YANG Library"; 1076 } 1078 organization 1079 "IETF NETMOD (Network Modeling) Working Group"; 1081 contact 1082 "WG Web: 1083 WG List: 1085 Author: Rob Wilton 1086 "; 1088 description 1089 "This module provides defined augmentations to YANG library to 1090 allow a server to report YANG package information. 1092 Copyright (c) 2018 IETF Trust and the persons identified as 1093 authors of the code. All rights reserved. 1095 Redistribution and use in source and binary forms, with or 1096 without modification, is permitted pursuant to, and subject 1097 to the license terms contained in, the Simplified BSD License 1098 set forth in Section 4.c of the IETF Trust's Legal Provisions 1099 Relating to IETF Documents 1100 (http://trustee.ietf.org/license-info). 1102 This version of this YANG module is part of RFC XXXX; see 1103 the RFC itself for full legal notices."; 1105 // RFC Ed.: update the date below with the date of RFC publication 1106 // and remove this note. 1107 // RFC Ed.: replace XXXX with actual RFC number and remove this 1108 // note. 1109 revision 2018-11-26 { 1110 description 1111 "Initial revision"; 1112 reference 1113 "RFC XXXX: YANG Schema Versioning."; 1114 } 1116 /* 1117 * Add in the list of packaged into YANG libary. 1118 */ 1119 augment "/yanglib:yang-library" { 1120 description "Add YANG package definitions into YANG library"; 1122 list package { 1123 config "false"; 1124 key "name version"; 1126 description "Defines the packages available on this server."; 1128 uses "pkg-types:yang-pkg-library-definition"; 1129 } 1130 } 1132 /* 1133 * Allow schema to be related to a YANG package. 1134 */ 1135 augment "/yanglib:yang-library/yanglib:schema" { 1136 description 1137 "Allow datastore schema to be related to a YANG package"; 1139 container package { 1140 leaf name { 1141 type leafref { 1142 path "/yanglib:yang-library/package/name"; 1143 } 1144 description 1145 "The name of the package this schema relates to."; 1146 } 1147 leaf version { 1148 type leafref { 1149 path '/yanglib:yang-library/' 1150 + 'package[name = current()/../name]/version'; 1151 } 1153 description 1154 "The version of the package this schema relates to."; 1155 } 1157 description 1158 "Describes which package the schema directly relates to, if 1159 any."; 1160 } 1161 } 1163 /* 1164 * Allow import-only modules to list the versions that they are 1165 * replacing. 1166 */ 1168 augment 1169 "/yanglib:yang-library/yanglib:module-set/" + 1170 "yanglib:import-only-module" { 1172 description 1173 "Add replaces-revision to import-only-module definitions"; 1175 leaf-list replaces-revision { 1176 type yanglib:revision-identifier; 1177 description 1178 "Gives the revision of an import-only-module defined in an 1179 imported package that is replaced by this import-only-module 1180 revision. 1182 Only used for YANG package definitions"; 1183 } 1184 } 1185 } 1186 1188 10. Open Questions/Issues 1190 1. Should the YANG library changes be done as an augmentation (as 1191 per this draft), or is a new version of YANG library better? 1193 2. Is it OK for the YANG definition used for package instance data 1194 vs YANG library to differ? The reason for the difference is to 1195 allow "Module Sets" to be reused, potentially minimizing 1196 duplicate data in YANG library. 1198 3. Is name sufficient to uniquely identify a package, or should they 1199 also define the equivalent to a namespace? The current proposed 1200 solution is for the first entry in the location list to define a 1201 canonical location 1203 4. Is disabling features using deviations sufficient? There are 1204 some cases where this cannot work, e.g. a deviation cannot remove 1205 an identity. 1207 5. Should a package (or implementation) be able to remove modules 1208 from a package? Current thinking is the answer should be no 1209 because it greatly reduces the usefulness of package conformance. 1211 6. Should a package include RFC 8199 related metadata? E.g., does a 1212 package contain device or service level YANG models? The current 1213 proposal is to gain this flexibility by allowing module tags to 1214 be added to package definitions. 1216 7. Considering version selection, should the YANG library package 1217 definition have a flag to indicate whether a particular package 1218 can be selected by a client? Probably the answer here is to 1219 defer this issue to a separate version selection draft that can 1220 add a flag via augmentation. 1222 8. TODO - Once draft-verdt-netmod-yang-semver is published, add 1223 appropriate references to this draft for module level semantic 1224 versioning. 1226 11. Security Considerations 1228 The YANG modules specified in this document defines a schema for data 1229 that is accessed by network management protocols such as NETCONF 1230 [RFC6241] or RESTCONF [RFC8040]. The lowest NETCONF layer is the 1231 secure transport layer, and the mandatory-to-implement secure 1232 transport is Secure Shell (SSH) [RFC6242]. The lowest RESTCONF layer 1233 is HTTPS, and the mandatory-to-implement secure transport is TLS 1234 [RFC5246]. 1236 The NETCONF access control model [RFC6536] provides the means to 1237 restrict access for particular NETCONF or RESTCONF users to a 1238 preconfigured subset of all available NETCONF or RESTCONF protocol 1239 operations and content. 1241 Similarly to YANG library [I-D.ietf-netconf-rfc7895bis], some of the 1242 readable data nodes in these YANG modules may be considered sensitive 1243 or vulnerable in some network environments. It is thus important to 1244 control read access (e.g., via get, get-config, or notification) to 1245 these data nodes. 1247 One additional key different to YANG library, is that the 'ietf-yang- 1248 package' YANG module defines a schema to allow YANG packages to be 1249 defined in YANG instance data documents, that are outside the 1250 security controls of the network management protocols. Hence, it is 1251 important to also consider controlling access to these package 1252 instance data documents to restrict access to sensitive information. 1254 As per the YANG library security considerations, the module, revision 1255 and version information in YANG packages may help an attacker 1256 identify the server capabilities and server implementations with 1257 known bugs since the set of YANG modules supported by a server may 1258 reveal the kind of device and the manufacturer of the device. Server 1259 vulnerabilities may be specific to particular modules, module 1260 revisions, module features, or even module deviations. For example, 1261 if a particular operation on a particular data node is known to cause 1262 a server to crash or significantly degrade device performance, then 1263 the packaging information will help an attacker identify server 1264 implementations with such a defect, in order to launch a denial-of- 1265 service attack on the device. 1267 12. IANA Considerations 1269 It is expected that a central registry of standard YANG package 1270 definitions is required to support this packaging solution. 1272 It is unclear whether an IANA registry is also required to manage 1273 specific package versions. It is highly desirable to have a specific 1274 canonical location, under IETF control, where the definitive YANG 1275 package versions can be obtained from. 1277 13. References 1279 13.1. Normative References 1281 [I-D.ietf-netconf-rfc7895bis] 1282 Bierman, A., Bjorklund, M., Schoenwaelder, J., Watsen, K., 1283 and R. Wilton, "YANG Library", draft-ietf-netconf- 1284 rfc7895bis-07 (work in progress), October 2018. 1286 [I-D.ietf-netmod-module-tags] 1287 Hopps, C., Berger, L., and D. Bogdanovic, "YANG Module 1288 Tags", draft-ietf-netmod-module-tags-03 (work in 1289 progress), October 2018. 1291 [I-D.ietf-netmod-yang-instance-file-format] 1292 Lengyel, B. and B. Claise, "YANG Instance Data File 1293 Format", draft-ietf-netmod-yang-instance-file-format-01 1294 (work in progress), December 2018. 1296 [I-D.verdt-netmod-yang-versioning-reqs] 1297 Clarke, J., "YANG Module Versioning Requirements", draft- 1298 verdt-netmod-yang-versioning-reqs-02 (work in progress), 1299 November 2018. 1301 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1302 Requirement Levels", BCP 14, RFC 2119, 1303 DOI 10.17487/RFC2119, March 1997, 1304 . 1306 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 1307 (TLS) Protocol Version 1.2", RFC 5246, 1308 DOI 10.17487/RFC5246, August 2008, 1309 . 1311 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 1312 and A. Bierman, Ed., "Network Configuration Protocol 1313 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 1314 . 1316 [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure 1317 Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011, 1318 . 1320 [RFC6536] Bierman, A. and M. Bjorklund, "Network Configuration 1321 Protocol (NETCONF) Access Control Model", RFC 6536, 1322 DOI 10.17487/RFC6536, March 2012, 1323 . 1325 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 1326 RFC 7950, DOI 10.17487/RFC7950, August 2016, 1327 . 1329 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 1330 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 1331 . 1333 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1334 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1335 May 2017, . 1337 [RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 1338 and R. Wilton, "Network Management Datastore Architecture 1339 (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018, 1340 . 1342 13.2. Informative References 1344 [I-D.bierman-netmod-yang-package] 1345 Bierman, A., "The YANG Package Statement", draft-bierman- 1346 netmod-yang-package-00 (work in progress), July 2015. 1348 [I-D.ietf-netmod-artwork-folding] 1349 Watsen, K., Wu, Q., Farrel, A., and B. Claise, "Handling 1350 Long Lines in Artwork in Internet-Drafts and RFCs", draft- 1351 ietf-netmod-artwork-folding-00 (work in progress), 1352 November 2018. 1354 [openconfigsemver] 1355 "Semantic Versioning for Openconfig Models", 1356 . 1358 [RFC8199] Bogdanovic, D., Claise, B., and C. Moberg, "YANG Module 1359 Classification", RFC 8199, DOI 10.17487/RFC8199, July 1360 2017, . 1362 Appendix A. Tree output for ietf-yang-library with package 1363 augmentations 1365 Complete tree output for ietf-yang-library with package 1366 augmentations. 1368 module: ietf-yang-library 1369 +--ro yang-library 1370 | +--ro module-set* [name] 1371 | | +--ro name string 1372 | | +--ro module* [name] 1373 | | | +--ro name yang:yang-identifier 1374 | | | +--ro revision? revision-identifier 1375 | | | +--ro namespace inet:uri 1376 | | | +--ro location* inet:uri 1377 | | | +--ro submodule* [name] 1378 | | | | +--ro name yang:yang-identifier 1379 | | | | +--ro revision? revision-identifier 1380 | | | | +--ro location* inet:uri 1381 | | | +--ro feature* yang:yang-identifier 1382 | | | +--ro deviation* -> ../../module/name 1383 | | +--ro import-only-module* [name revision] 1384 | | +--ro name yang:yang-identifier 1385 | | +--ro revision union 1386 | | +--ro namespace inet:uri 1387 | | +--ro location* inet:uri 1388 | | +--ro submodule* [name] 1389 | | | +--ro name yang:yang-identifier 1390 | | | +--ro revision? revision-identifier 1391 | | | +--ro location* inet:uri 1392 | | +--ro pkg:replaces-revision* 1393 | | yanglib:revision-identifier 1394 | +--ro schema* [name] 1395 | | +--ro name string 1396 | | +--ro module-set* -> ../../module-set/name 1397 | | +--ro pkg:package 1398 | | +--ro pkg:name? 1399 | | | -> /yanglib:yang-library/package/name 1400 | | +--ro pkg:version? leafref 1401 | +--ro datastore* [name] 1402 | | +--ro name ds:datastore-ref 1403 | | +--ro schema -> ../../schema/name 1404 | +--ro content-id string 1405 | +--ro pkg:package* [name version] 1406 | +--ro pkg:name yang:yang-identifier 1407 | +--ro pkg:version yang-sem-ver 1408 | +--ro pkg:revision-date? yanglib:revision-identifier 1409 | +--ro pkg:location* inet:uri 1410 | +--ro pkg:description? string 1411 | +--ro pkg:reference? string 1412 | +--ro pkg:tag* tags:tag 1413 | +--ro pkg:mandatory-feature* string 1414 | +--ro pkg:imported-packages* [name version] 1415 | | +--ro pkg:name yang:yang-identifier 1416 | | +--ro pkg:version yang-sem-ver 1417 | +--ro pkg:module-set* 1418 | -> /yanglib:yang-library/module-set/name 1419 x--ro modules-state 1420 x--ro module-set-id string 1421 x--ro module* [name revision] 1422 x--ro name yang:yang-identifier 1423 x--ro revision union 1424 +--ro schema? inet:uri 1425 x--ro namespace inet:uri 1426 x--ro feature* yang:yang-identifier 1427 x--ro deviation* [name revision] 1428 | x--ro name yang:yang-identifier 1429 | x--ro revision union 1430 x--ro conformance-type enumeration 1431 x--ro submodule* [name revision] 1432 x--ro name yang:yang-identifier 1433 x--ro revision union 1434 +--ro schema? inet:uri 1436 notifications: 1437 +---n yang-library-update 1438 | +--ro content-id -> /yang-library/content-id 1439 x---n yang-library-change 1440 x--ro module-set-id -> /modules-state/module-set-id 1442 Appendix B. Examples 1444 This section provides various examples of YANG packages, and as such 1445 this text is non-normative. The purpose of the examples is to only 1446 illustrate the file format of YANG packages, and how package 1447 dependencies work. It does not imply that such packages will be 1448 defined by IETF, or which modules would be included in those packages 1449 even if they were defined. 1451 B.1. Example IETF Network Device YANG package 1453 This section provides an instance data document example of an IETF 1454 Network Device YANG package formatted in JSON. 1456 This example package is intended to represent the standard set of 1457 YANG modules, with import dependencies, to implement a basic network 1458 device without any dynamic routing or layer 2 services. E.g., it 1459 includes functionality such as system information, interface and 1460 basic IP configuration. 1462 As for all YANG packages, all import dependencies are fully resolved. 1463 Because this example uses YANG modules that have been standardized 1464 before YANG semantic versioning, they modules are referenced by 1465 revision date rather than version number. 1467 file "example-ietf-network-device-pkg.json" 1468 ========= NOTE: '\\' line wrapping per BCP XX (RFC XXXX) =========== 1469 { 1470 "ietf-yang-instance-data:instance-data-set": { 1471 "name": "example-ietf-network-device-pkg", 1472 "target-ptr": "TBD", 1473 "timestamp": "2018-12-13T17:00:00Z", 1474 "description": "Example IETF network device YANG package definit\ 1475 \ion", 1476 "content-data": { 1477 "ietf-yang-package:yang-package": { 1478 "name": "example-ietf-network-device", 1479 "version": "1.1.2", 1480 "namespace": "urn:ietf:params:xml:ns:yang-pkg:ietf-network-d\ 1481 \evice", 1482 "location": "file://example.org/yang/packages/ietf-network-d\ 1483 \evice@v1.1.2.json", 1484 "description": "This package defines a small sample set of Y\ 1485 \ANG modules that could represent the basic set of modules that a st\ 1486 \andard network device might be expected to support.", 1487 "reference": "XXX, draft-rwilton-netmod-yang-packages", 1488 "revision-date": "2018-11-26", 1489 "module": [ 1490 { 1491 "name": "iana-crypt-hash", 1492 "revision": "2014-08-06", 1493 "namespace": "urn:ietf:params:xml:ns:yang:iana-crypt-has\ 1494 \h", 1495 "location": "https://raw.githubusercontent.com/YangModel\ 1496 \s/yang/master/standard/ietf/RFC/iana-crypt-hash%402014-08-06.yang" 1497 }, 1498 { 1499 "name": "ietf-system", 1500 "revision": "2014-08-06", 1501 "namespace": "urn:ietf:params:xml:ns:yang:ietf-system", 1502 "location": "https://raw.githubusercontent.com/YangModel\ 1503 \s/yang/master/standard/ietf/RFC/ietf-system%402014-08-06.yang" 1504 }, 1505 { 1506 "name": "ietf-interfaces", 1507 "revision": "2018-02-20", 1508 "namespace": "urn:ietf:params:xml:ns:yang:ietf-interface\ 1509 \s", 1510 "location": "https://raw.githubusercontent.com/YangModel\ 1511 \s/yang/master/standard/ietf/RFC/ietf-interfaces%402018-02-20.yang" 1512 }, 1513 { 1514 "name": "ietf-netconf-acm", 1515 "revision": "2018-02-14", 1516 "namespace": "urn:ietf:params:xml:ns:yang:ietf-netconf-a\ 1518 \cm", 1519 "location": "https://raw.githubusercontent.com/YangModel\ 1520 \s/yang/master/standard/ietf/RFC/ietf-netconf-acm%402018-02-14.yang" 1521 }, 1522 { 1523 "name": "ietf-key-chain", 1524 "revision": "2017-06-15", 1525 "namespace": "urn:ietf:params:xml:ns:yang:ietf-key-chain\ 1526 \", 1527 "location": "https://raw.githubusercontent.com/YangModel\ 1528 \s/yang/master/standard/ietf/RFC/ietf-key-chain@2017-06-15.yang" 1529 }, 1530 { 1531 "name": "ietf-ip", 1532 "revision": "2018-02-22", 1533 "namespace": "urn:ietf:params:xml:ns:yang:ietf-ip", 1534 "location": "https://raw.githubusercontent.com/YangModel\ 1535 \s/yang/master/standard/ietf/RFC/ietf-ip%402018-02-22.yang" 1536 } 1537 ], 1538 "import-only-module": [ 1539 { 1540 "name": "ietf-yang-types", 1541 "revision": "2013-07-15", 1542 "namespace": "urn:ietf:params:xml:ns:yang:ietf-yang-type\ 1543 \s", 1544 "location": "https://raw.githubusercontent.com/YangModel\ 1545 \s/yang/master/standard/ietf/RFC/ietf-yang-types%402013-07-15.yang" 1546 }, 1547 { 1548 "name": "ietf-inet-types", 1549 "revision": "2013-07-15", 1550 "namespace": "urn:ietf:params:xml:ns:yang:ietf-inet-type\ 1551 \s", 1552 "location": "https://raw.githubusercontent.com/YangModel\ 1553 \s/yang/master/standard/ietf/RFC/ietf-inet-types%402013-07-15.yang" 1554 } 1555 ] 1556 } 1557 } 1558 } 1559 } 1560 1562 B.2. Example IETF Basic Routing YANG package 1564 This section provides an instance data document example of a basic 1565 IETF Routing YANG package formatted in JSON. 1567 This example package is intended to represent the standard set of 1568 YANG modules, with import dependencies, that builds upon the example- 1569 ietf-network-device YANG package to add support for basic dynamic 1570 routing and ACLs. 1572 As for all YANG packages, all import dependencies are fully resolved. 1573 Because this example uses YANG modules that have been standardized 1574 before YANG semantic versioning, they modules are referenced by 1575 revision date rather than version number. Locations have been 1576 excluded where they are not currently known, e.g., for YANG modules 1577 defined in IETF drafts. In a normal YANG package, locations would be 1578 expected to be provided for all YANG modules. 1580 file "example-ietf-routing-pkg.json" 1581 ========== NOTE: '\\' line wrapping per BCP XX (RFC XXXX) =========== 1583 { 1584 "ietf-yang-instance-data:instance-data-set": { 1585 "name": "example-ietf-routing-pkg", 1586 "target-ptr": "TBD", 1587 "timestamp": "2018-12-13T17:00:00Z", 1588 "description": "Example IETF routing YANG package definition", 1589 "content-data": { 1590 "ietf-yang-package:yang-package": { 1591 "name": "example-ietf-routing", 1592 "version": "1.3.1", 1593 "namespace": "urn:ietf:params:xml:ns:yang-pkg:ietf-routing", 1594 "location": "file://example.org/yang/packages/ietf-routing@v\ 1595 \1.3.1.json", 1596 "description": "This package defines a small sample set of I\ 1597 \ETF routing YANG modules that could represent the set of IETF routi\ 1598 \ng functionality that a basic IP network device might be expected t\ 1599 \o support.", 1600 "reference": "XXX, draft-rwilton-netmod-yang-packages", 1601 "revision-date": "2018-11-26", 1602 "imported-packages": [ 1603 { 1604 "name": "ietf-network-device", 1605 "version": "1.1.2", 1606 "location": [ 1607 "http://example.org/yang/packages/ietf-network-device@\ 1608 \v1.1.2.json" 1609 ] 1610 } 1611 ], 1612 "module": [ 1613 { 1614 "name": "ietf-routing", 1615 "revision": "2018-03-13", 1616 "namespace": "urn:ietf:params:xml:ns:yang:ietf-routing", 1617 "location": [ 1618 "https://raw.githubusercontent.com/YangModels/yang/mas\ 1619 \ter/standard/ietf/RFC/ietf-routing@2018-03-13.yang" 1620 ] 1621 }, 1622 { 1623 "name": "ietf-ipv4-unicast-routing", 1624 "revision": "2018-03-13", 1625 "namespace": "urn:ietf:params:xml:ns:yang:ietf-ipv4-unca\ 1626 \st-routing", 1627 "location": [ 1628 "https://raw.githubusercontent.com/YangModels/yang/mas\ 1629 \ter/standard/ietf/RFC/ietf-ipv4-unicast-routing@2018-03-13.yang" 1630 ] 1631 }, 1632 { 1633 "name": "ietf-ipv6-unicast-routing", 1634 "revision": "2018-03-13", 1635 "namespace": "urn:ietf:params:xml:ns:yang:ietf-ipv6-unca\ 1636 \st-routing", 1637 "location": [ 1638 "https://raw.githubusercontent.com/YangModels/yang/mas\ 1639 \ter/standard/ietf/RFC/ietf-ipv6-unicast-routing@2018-03-13.yang" 1640 ] 1641 }, 1642 { 1643 "name": "ietf-isis", 1644 "revision": "2018-12-11", 1645 "namespace": "urn:ietf:params:xml:ns:yang:ietf-isis" 1646 }, 1647 { 1648 "name": "ietf-interfaces-common", 1649 "revision": "2018-07-02", 1650 "namespace": "urn:ietf:params:xml:ns:yang:ietf-interface\ 1651 \s-common" 1652 }, 1653 { 1654 "name": "ietf-if-l3-vlan", 1655 "revision": "2017-10-30", 1656 "namespace": "urn:ietf:params:xml:ns:yang:ietf-if-l3-vla\ 1658 \n" 1659 }, 1660 { 1661 "name": "ietf-routing-policy", 1662 "revision": "2018-10-19", 1663 "namespace": "urn:ietf:params:xml:ns:yang:ietf-routing-p\ 1664 \olicy" 1665 }, 1666 { 1667 "name": "ietf-bgp", 1668 "revision": "2018-05-09", 1669 "namespace": "urn:ietf:params:xml:ns:yang:ietf-bgp" 1670 }, 1671 { 1672 "name": "ietf-access-control-list", 1673 "revision": "2018-11-06", 1674 "namespace": "urn:ietf:params:xml:ns:yang:ietf-access-co\ 1675 \ntrol-list" 1676 } 1677 ], 1678 "import-only-module": [ 1679 { 1680 "name": "ietf-routing-types", 1681 "revision": "2017-12-04", 1682 "namespace": "urn:ietf:params:xml:ns:yang:ietf-routing-t\ 1683 \ypes", 1684 "location": [ 1685 "https://raw.githubusercontent.com/YangModels/yang/mas\ 1686 \ter/standard/ietf/RFC/ietf-routing-types@2017-12-04.yang" 1687 ] 1688 }, 1689 { 1690 "name": "iana-routing-types", 1691 "revision": "2017-12-04", 1692 "namespace": "urn:ietf:params:xml:ns:yang:iana-routing-t\ 1693 \ypes", 1694 "location": [ 1695 "https://raw.githubusercontent.com/YangModels/yang/mas\ 1696 \ter/standard/ietf/RFC/iana-routing-types@2017-12-04.yang" 1697 ] 1698 }, 1699 { 1700 "name": "ietf-bgp-types", 1701 "revision": "2018-05-09", 1702 "namespace": "urn:ietf:params:xml:ns:yang:ietf-bgp-types" 1703 }, 1704 { 1705 "name": "ietf-packet-fields", 1706 "revision": "2018-11-06", 1707 "namespace": "urn:ietf:params:xml:ns:yang:ietf-packet-fi\ 1708 \elds" 1709 }, 1710 { 1711 "name": "ietf-ethertypes", 1712 "revision": "2018-11-06", 1713 "namespace": "urn:ietf:params:xml:ns:yang:ietf-ethertype\ 1714 \s" 1715 } 1716 ] 1717 } 1718 } 1719 } 1720 } 1721 1723 B.3. Package import conflict resolution example 1725 This section provides an example of how a package can resolve 1726 conflicting module versions from imported packages. 1728 In this example, YANG package 'example-3-pkg' imports both 'example- 1729 import-1' and 'example-import-2' packages. However, the two imported 1730 packages implement different versions of 'example-module-A' so the 1731 'example-3-pkg' package selects version '1.2.3' to resolve the 1732 conflict. Similarly, for import-only modules, the 'example-3-pkg' 1733 package does not require both versions of example-types-module-C to 1734 be imported, so it indicates that it only imports revision 1735 '2018-11-26' and not '2018-01-01'. 1737 { 1738 "ietf-yang-instance-data:instance-data-set": { 1739 "name": "example-import-1-pkg", 1740 "description": "First imported example package", 1741 "content-data": { 1742 "ietf-yang-package:yang-package": { 1743 "name": "example-import-1", 1744 "version": "1.0.0", 1745 "reference": "XXX, draft-rwilton-netmod-yang-packages", 1746 "revision-date": "2018-01-01", 1747 "module": [ 1748 { 1749 "name": "example-module-A", 1750 "version": "1.0.0" 1751 }, 1752 { 1753 "name": "example-module-B", 1754 "version": "1.0.0" 1755 } 1756 ], 1757 "import-only-module": [ 1758 { 1759 "name": "example-types-module-C", 1760 "revision": "2018-01-01" 1761 }, 1762 { 1763 "name": "example-types-module-D", 1764 "revision": "2018-01-01" 1765 } 1766 ] 1767 } 1768 } 1769 } 1770 } 1772 { 1773 "ietf-yang-instance-data:instance-data-set": { 1774 "name": "example-import-2-pkg", 1775 "description": "Second imported example package", 1776 "content-data": { 1777 "ietf-yang-package:yang-package": { 1778 "name": "example-import-2", 1779 "version": "2.0.0", 1780 "reference": "XXX, draft-rwilton-netmod-yang-packages", 1781 "revision-date": "2018-11-26", 1782 "module": [ 1783 { 1784 "name": "example-module-A", 1785 "version": "1.2.3" 1786 }, 1787 { 1788 "name": "example-module-E", 1789 "version": "1.1.0" 1790 } 1791 ], 1792 "import-only-module": [ 1793 { 1794 "name": "example-types-module-C", 1795 "revision": "2018-11-26" 1796 }, 1797 { 1798 "name": "example-types-module-D", 1799 "revision": "2018-11-26" 1801 } 1802 ] 1803 } 1804 } 1805 } 1806 } 1808 { 1809 "ietf-yang-instance-data:instance-data-set": { 1810 "name": "example-3-pkg", 1811 "description": "Importing example package", 1812 "content-data": { 1813 "ietf-yang-package:yang-package": { 1814 "name": "example-3", 1815 "version": "1.0.0", 1816 "reference": "XXX, draft-rwilton-netmod-yang-packages", 1817 "revision-date": "2018-11-26", 1818 "imported-packages": [ 1819 { 1820 "name": "example-import-1", 1821 "version": "1.0.0" 1822 }, 1823 { 1824 "name": "example-import-2", 1825 "version": "2.0.0" 1826 } 1827 ], 1828 "module": [ 1829 { 1830 "name": "example-module-A", 1831 "version": "1.2.3" 1832 } 1833 ], 1834 "import-only-module": [ 1835 { 1836 "name": "example-types-module-C", 1837 "revision": "2018-11-26", 1838 "replaces-revision": [ "2018-01-01 "] 1839 } 1840 ] 1841 } 1842 } 1843 } 1844 } 1846 Author's Address 1847 Robert Wilton 1848 Cisco Systems, Inc.