idnits 2.17.1 draft-wilton-netmod-yang-ver-selection-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 -- The document date (February 28, 2020) is 1509 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-yang-instance-file-format' is defined on line 962, but no explicit reference was found in the text == Unused Reference: 'RFC6536' is defined on line 1008, but no explicit reference was found in the text == Unused Reference: 'RFC8525' is defined on line 1030, but no explicit reference was found in the text == Unused Reference: 'I-D.ietf-netmod-artwork-folding' is defined on line 1043, but no explicit reference was found in the text == Unused Reference: 'I-D.verdt-netmod-yang-solutions' is defined on line 1049, but no explicit reference was found in the text == Outdated reference: A later version (-21) exists of draft-ietf-netmod-yang-instance-file-format-07 ** 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 6536 (Obsoleted by RFC 8341) Summary: 2 errors (**), 0 flaws (~~), 7 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group R. Wilton 3 Internet-Draft R. Rahman 4 Intended status: Standards Track J. Clarke 5 Expires: August 31, 2020 Cisco Systems, Inc. 6 J. Sterne 7 Nokia 8 B. Wu 9 Huawei 10 February 28, 2020 12 YANG Schema Selection 13 draft-wilton-netmod-yang-ver-selection-02 15 Abstract 17 This document defines a mechanism to allow clients, using NETCONF or 18 RESTCONF, to configure and select YANG schema for interactions with a 19 server. This functionality can help servers support clients using 20 older revisions of YANG modules even if later revisions contain non- 21 backwards-compatible changes. It can also be used to allow clients 22 to select between YANG schema defined by different organizations. 24 This draft provides a solution to YANG versioning requirements 3.1 25 and 3.2. 27 Status of This Memo 29 This Internet-Draft is submitted in full conformance with the 30 provisions of BCP 78 and BCP 79. 32 Internet-Drafts are working documents of the Internet Engineering 33 Task Force (IETF). Note that other groups may also distribute 34 working documents as Internet-Drafts. The list of current Internet- 35 Drafts is at https://datatracker.ietf.org/drafts/current/. 37 Internet-Drafts are draft documents valid for a maximum of six months 38 and may be updated, replaced, or obsoleted by other documents at any 39 time. It is inappropriate to use Internet-Drafts as reference 40 material or to cite them other than as "work in progress." 42 This Internet-Draft will expire on August 31, 2020. 44 Copyright Notice 46 Copyright (c) 2020 IETF Trust and the persons identified as the 47 document authors. All rights reserved. 49 This document is subject to BCP 78 and the IETF Trust's Legal 50 Provisions Relating to IETF Documents 51 (https://trustee.ietf.org/license-info) in effect on the date of 52 publication of this document. Please review these documents 53 carefully, as they describe your rights and restrictions with respect 54 to this document. Code Components extracted from this document must 55 include Simplified BSD License text as described in Section 4.e of 56 the Trust Legal Provisions and are provided without warranty as 57 described in the Simplified BSD License. 59 Table of Contents 61 1. Terminology and Conventions . . . . . . . . . . . . . . . . . 3 62 2. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 63 3. Background . . . . . . . . . . . . . . . . . . . . . . . . . 4 64 4. Objectives . . . . . . . . . . . . . . . . . . . . . . . . . 5 65 5. Solution . . . . . . . . . . . . . . . . . . . . . . . . . . 6 66 5.1. Packages . . . . . . . . . . . . . . . . . . . . . . . . 7 67 5.2. Schema-sets . . . . . . . . . . . . . . . . . . . . . . . 7 68 5.3. Defining and changing client selectable schema-sets . . . 8 69 5.4. Schema selection protocol operations . . . . . . . . . . 8 70 5.4.1. NETCONF . . . . . . . . . . . . . . . . . . . . . . . 8 71 5.4.1.1. schema-sets NETCONF capability . . . . . . . . . 8 72 5.4.2. RESTCONF . . . . . . . . . . . . . . . . . . . . . . 10 73 5.5. Custom schema-sets . . . . . . . . . . . . . . . . . . . 11 74 6. Schema selection from a server perspective . . . . . . . . . 11 75 7. Schema selection from a client perspective . . . . . . . . . 12 76 7.1. Examples . . . . . . . . . . . . . . . . . . . . . . . . 12 77 8. Limitations of the solution . . . . . . . . . . . . . . . . . 13 78 9. Schema Selection YANG module . . . . . . . . . . . . . . . . 13 79 10. YANG Module . . . . . . . . . . . . . . . . . . . . . . . . . 14 80 11. Security Considerations . . . . . . . . . . . . . . . . . . . 20 81 12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 20 82 12.1. NETCONF Capability URNs . . . . . . . . . . . . . . . . 20 83 13. Open Questions/Issues . . . . . . . . . . . . . . . . . . . . 21 84 14. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 21 85 15. References . . . . . . . . . . . . . . . . . . . . . . . . . 21 86 15.1. Normative References . . . . . . . . . . . . . . . . . . 21 87 15.2. Informative References . . . . . . . . . . . . . . . . . 23 88 Appendix A. Schema selection examples . . . . . . . . . . . . . 23 89 A.1. Supporting older versions of a schema . . . . . . . . . . 23 90 A.1.1. Variation - Multiple selectable schema-sets . . . . . 26 91 A.2. Supporting different schema families . . . . . . . . . . 27 92 A.2.1. Choosing a single schema family . . . . . . . . . . . 30 93 A.2.2. Restricting some sessions to particular schema family 30 94 A.2.3. Custom combinable schema-set . . . . . . . . . . . . 31 95 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 31 97 1. Terminology and Conventions 99 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 100 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 101 "OPTIONAL" in this document are to be interpreted as described in BCP 102 14 [RFC2119] [RFC8174] when, and only when, they appear in all 103 capitals, as shown here. 105 This document uses terminology introduced in the YANG versioning 106 requirements [I-D.verdt-netmod-yang-versioning-reqs], YANG Module 107 Versioning [I-D.verdt-netmod-yang-module-versioning] and YANG 108 Packages [I-D.rwilton-netmod-yang-packages]. 110 This document makes of the following terminology introduced in the 111 Network Management Datastore Architecture [RFC8342]: 113 o datastore schema 115 This document defines the following terminology: 117 o YANG schema: The combined set of schema nodes for a set of YANG 118 module revisions, taking into consideration any deviations and 119 enabled features. 121 o versioned schema: A YANG schema with an associated YANG semantic 122 version number, e.g., as might be described by a YANG 123 package[I-D.rwilton-netmod-yang-packages]. 125 o schema-set: A named set of datastore schemas for supported 126 datastores, where every datastore schema is specified as a union 127 of compatible YANG packages. A schema-set is the basic unit of 128 client schema selection. 130 2. Introduction 132 This document describes how NETCONF and RESTCONF clients can use 133 protocol extensions, along with a schema selection YANG module, to 134 choose particular YANG schema for interactions with a server. 136 [I-D.verdt-netmod-yang-versioning-reqs] defines requirements that any 137 solution to YANG versioning must have. 139 YANG Semver [I-D.verdt-netmod-yang-semver], based on YANG Module 140 Versioning, specifies a partial solution to the YANG versioning 141 requirements that focuses on using semantic versioning within 142 individual YANG modules, but does not address all requirements listed 143 in the YANG versioning requirements document. Of particular 144 relevance here, requirements 3.1 and 3.2 are not addressed. 146 YANG Packages describes how sets of related YANG module revisions can 147 be grouped together into a logical entity that defines a YANG schema. 148 Different packages can be defined for different sets of YANG modules, 149 e.g., packages could be defined for the IETF YANG modules, OpenConfig 150 YANG modules, or a vendor's YANG modules. Updated versions of these 151 package definitions can be defined as the contents of these packages 152 evolve over time, e.g., by using new revisions of YANG modules 153 included in the package. 155 This document defines how YANG packages are used to represent 156 versioned datastore schema, and how clients can choose which 157 versioned schemas to use during protocol interactions with a device. 159 3. Background 161 There are three ways that the lifecycle of a data model can be 162 managed: 164 1. Disallow all non-backwards-compatible updates to a YANG module. 165 Broadly this is the approach adopted by [RFC7950], but it has 166 been shown to be too inflexible in some cases. E.g. it makes it 167 hard to fix bugs in a clean fashion - it is not clear that 168 allowing two independent data nodes (one deprecated, one current) 169 to configure the same underlying property is robustly backwards 170 compatible in all scenarios, particularly if the value space and/ 171 or default values differ between the module revisions. 173 2. Allow non-backwards-compatible updates to YANG modules, and use a 174 mechanism such as semantic version numbers to communicate the 175 likely impact of any changes to module users, but require that 176 clients handle non-backwards-compatible changes in servers by 177 migrating to new versions of the modules. Without schema 178 selection, this is what the YANG Semver approach likely achieves. 180 3. Allow non-backwards-compatible updates to YANG modules, but also 181 provide mechanisms to allow servers to support multiple versions 182 of YANG modules, and provide clients with some ability to select 183 which versions of YANG modules they wish to interact with, 184 subject to some reasonable constraints. This is the approach 185 that this document aims to address. It is worth noting that the 186 idea of supporting multiple versions of an API is not new in the 187 wider software industry, and there are many examples of where 188 this approach has been used successfully. 190 4. Objectives 192 The goals of YANG schema selection are: 194 o To provide a mechanism where non-backwards-compatible changes and 195 bug fixes can be made to YANG modules without forcing clients to 196 immediately migrate to new versions of those modules as they get 197 implemented. 199 o To allow servers to support multiple versions of a particular YANG 200 schema, and to allow clients to choose which YANG schema version 201 to use when interoperating with the server. The aim here is to 202 give operators more flexibility as to when they update their 203 management clients. 205 o To provide a mechanism to allow different YANG schema families 206 (e.g., SDO models, OpenConfig models, Vendor models) to be 207 supported by a server, and to allow clients to choose which YANG 208 schema family is used to interoperate with the server. 210 o To closely align with existing NETCONF/RESTCONF protocol 211 semantics. I.e., with the exception of the optional mechanism 212 that allows selection of the schema-set at the beginning of a 213 NETCONF session or RESTCONF request, protocol interactions between 214 client and server are the same as when schema selection is not 215 being used. 217 o To allow considerable freedom for server implementations to decide 218 how to implement schema selection, and choose the schema selection 219 capabilities they support. In particular: 221 * Servers determine which schema-sets can be selected by clients, 222 and which combinations of schema-sets are compatible with each 223 other during concurrent sessions/operations. 225 * Servers can make some schema-sets automatically available for 226 client selection, or require clients to configure the 227 selectable schema-sets before they can be used. 229 * Servers can limit clients to selecting only a single schema-set 230 for all client connections, i.e., replacing the devices default 231 schema-set, or allow clients to use different schema for 232 concurrent sessions/operations. 234 * Servers can restrict some read-write datastores to be read-only 235 when accessed via a particular schema-set, i.e., providing a 236 read-only view of configuration. 238 * Servers may allow clients to combine schema-sets into named 239 custom schema-sets, or only support predefined schema-sets. 241 The following points are non objectives of this document: 243 o This document does not provide a mechanism to allow clients to 244 choose arbitrary sets of YANG module versions to interoperate with 245 the server. 247 o Servers are not required to concurrently support clients using 248 different YANG schema families or versioned schema. A server MAY 249 choose to only allow a single schema family or single versioned 250 schema to be used by all clients. 252 o There is no requirement for a server to support every published 253 version of a YANG package, particularly if some package versions 254 are backwards compatible. Clients are required to interoperate 255 with backwards compatible updates of YANG modules. E.g., if a 256 particular package, using YANG Semver versioning rules, was 257 available in versions 1.0.0, 1.1.0, 1.2.0, 2.0.0, 3.0.0 and 3.1.0, 258 then a server may choose to only support versions 1.2.0, 2.0.0, 259 and 3.1.0, with the knowledge that all clients should be able to 260 interoperate with the server. 262 o There is no requirement to support all parts of all versioned 263 schemas. For some NBC changes in modules, it is not possible for 264 a server to support both the old and new module versions, and to 265 convert between the two. Where appropriate, deviations SHOULD be 266 used, and otherwise an out of band mechanism SHOULD be used to 267 indicate where a mapping has failed. 269 5. Solution 271 An outline of the solution is as follows: 273 1. YANG packages are used to define versioned schema that represent 274 a partial or full datastore schema for one or more datastores. 276 2. Schema-sets are named structures that define a set of supported 277 datastores, along with the schema associated with each of those 278 datastores, specified via leaf references to YANG packages. 280 3. The configurable 'selectable' leaf-list defines which schema-sets 281 may be selected by clients, and the associated configurable 282 'default' leaf defines the schema-set used by clients that do not 283 select a schema-set. 285 4. Clients choose which selectable schema-set to use via NETCONF 286 capability exchange during session initiation, or RESTCONF path. 288 5. Optionally, the configurable 'custom-schema-set' list allows 289 clients to combine schema-sets together into new named schema- 290 sets for selection. 292 5.1. Packages 294 Section 5.3 of YANG Packages specifies how packages SHOULD be used to 295 represent datastore schema. 297 Additional guidance on how YANG packages are specified for schema 298 selection are: 300 o Separate packages MAY be defined for different families of schema, 301 e.g., SDO, OpenConfig, or vendor native. 303 o Separate packages MAY be defined for different versions of schema. 305 o All packages referenced for schema selection, and any recursively 306 included package dependencies, MUST be available on the server in 307 the '/packages' container in the operational state datastore. 309 o Globally scoped packages used for schema selection SHOULD be made 310 available offline in YANG instance data documents, as described in 311 section 6 of YANG Packages. 313 5.2. Schema-sets 315 A schema-set defines a set of datastore schema(s) that could 316 potentially be used for client schema selection. 318 The schema-sets supported by the server are available at '/schema- 319 set-selection/schema-set' in the operational state datastore. 321 Each schema-set has a unique name that identifies the schema-set 322 during schema selection protocol operations, e.g., it is used in both 323 the NETCONF capabilities exchange and the RESTCONF path. 325 A schema-set defines the set of supported datastores that are 326 available when clients use the selected schema-set. The schema for 327 each datastore is specified as the union of one or more compatible 328 YANG packages. Writable datastores (e.g., running) can also be 329 labelled as being read-only if they cannot be written to via client 330 interactions using the schema-set. 332 Not all schema-sets are necessarily compatible with each other, 333 allowing one schema-set to be selected may prevent other schema-sets 334 from being selected at the same time. Hence, each schema-set lists 335 the other schema-sets that it is compatible with. 337 5.3. Defining and changing client selectable schema-sets 339 A device may have to allocate resources to support selectable schema- 340 sets, and the selectable leaf-list '/schema-set-selection/selectable' 341 is the mechanism to constrain the set of schema-sets that can be 342 selected by clients. 344 In the operational state datastore, the 'selectable' leaf-list 345 contains the names of all schema-sets that a client may select from. 346 Entries in this list MAY be added by the system without prior 347 configuration. In addition, the 'default' leaf indicates which 348 schema-set is used by clients that do not explicitly select a schema- 349 set. 351 In configuration, the 'selectable' leaf-list allows clients to 352 configure the schema-sets that are available for clients to select 353 from. A client can also choose the default schema-set that is used 354 by any client that connects without naming a schema-set. 356 5.4. Schema selection protocol operations 358 5.4.1. NETCONF 360 The schema-set being used in a NETCONF session is established at the 361 start of the session through the exchange of capabilities and never 362 changes for the duration of the session. If the server can no longer 363 support the schema-set in use in a NETCONF session, then it MUST 364 disconnect the session. 366 5.4.1.1. schema-sets NETCONF capability 368 A new NETCONF :schema-sets capability, using base:1.1 defined in 369 [RFC6241] 371 This capability is used by the server is advertise selectable schema. 372 The server sends a comma separated list (with no white spaces) of 373 selectable schema-sets it supports. For consistency, the list SHOULD 374 contain the default selectable schema-set first, followed by the 375 remaining selectable schema-sets, matching the order in the '/schema- 376 set-selection/selectable' leaf-list. 378 This capability is used by clients to select a particular schema. 379 The client sends an ordered list of selectable schema that it is 380 willing to use. 382 The selected schema is the first entry in the client schema-set list 383 that is also contained in the server schema-set list. If there is no 384 common entry then the session is terminated with an error. 386 If the client does not include the schema-set capability during the 387 capability exchange then the default selectable schema-set is used. 389 The :schema-sets capability is identified by the following capability 390 string: 392 urn:ietf:params:netconf:capability:schema-sets:1.0 394 In this example, the server advertises its (abbreviated) as 395 follows. This indicates that the server supports the following 396 schema-sets: 398 example-ietf-routing: Versions 2.1.0 (default) and 1.3.1 400 example-vendor-xxx: Versions 9.2.3 and 8.4.2 402 Some extra white spaces have been added for display purposes only. 404 405 406 urn:ietf:params:netconf:base:1.0 407 urn:ietf:params:netconf:base:1.1 408 409 urn:ietf:params:netconf:capability:schema-sets:1.0?list= 410 example-ietf-routing@2.1.0,example-ietf-routing@1.3.1, 411 example-vendor-xxx@9.2.3,example-vendor-xxx@8.4.2 412 413 414 416 The client advertises its (abbreviated) as follows. This 417 indicates the the client prefers to use the example-ietf-routing 418 schema version 2.1.0, but can also use version 1.3.1. Because both 419 the client and server support version 2.1.0, and because the client 420 listed it first, the selected schema-set is example-ietf- 421 routing@2.1.0: Some extra white spaces have been added for display 422 purposes only. 424 425 426 urn:ietf:params:netconf:base:1.1 427 428 urn:ietf:params:netconf:capability:schema-sets:1.0?list= 429 example-ietf-routing@2.1.0,example-ietf-routing@1.3.1 430 431 432 434 5.4.2. RESTCONF 436 For RESTCONF, schema-sets are chosen via use of their name in the 437 request URI. 439 Clients select the desired schema-set by choosing the corresponding 440 RESTCONF root resource. This is done by appending the schema-set 441 name to the RESTCONF API root [RFC8040]. This updates Section 3.1 of 442 [RFC8040] and Section 3 of [RFC8527]. 444 Clients will use RESTCONF root resource {+restconf}/schema/ for all requests pertaining to resources specific to a schema- 446 set. Consider a device which supports schema-sets vendor- 447 schema@3.0.0, vendor-schema@2.1.0 and vendor-schema@1.4.5: clients 448 will use RESTCONF root resource {+restconf}/schema/vendor- 449 schema@X.Y.Z for all requests pertaining to resources defined in 450 schema-set vendor-schema@X.Y.Z. This applies to all RESTCONF 451 resources defined in vendor-schema@X.Y.Z. 453 Here are some examples where {+restconf} is /restconf/. 455 Examples for servers which are NOT NMDA-compliant as per [RFC8527]: 457 1. /restconf/schema/vendor-schema@X.Y.Z/data for datastore 458 resources. 460 2. /restconf/schema/vendor-schema@X.Y.Z/data/module-A:data-X for 461 data resource "data-X" defined in module "module-A". 463 3. /restconf/schema/vendor-schema@X.Y.Z/operations/module-B:op-Y for 464 RPC "op-Y" defined in module "module-B" 466 4. /restconf/schema/vendor-schema@X.Y.Z/data/module-C:containerZ/ 467 myaction for action "myaction" defined in top-container 468 "containerZ" of module "module-C" 470 Examples for servers which are NMDA-compliant as per [RFC8527]: 472 1. /restconf/schema/vendor-schema@X.Y.Z/ds// for 473 datastore resources, e.g. /restconf/schema/vendor- 474 schema@X.Y.Z/ds/ietf-datastores:running refers to the Running 475 configuration datastore. 477 2. /restconf/schema/vendor-schema@X.Y.Z/ds/ietf- 478 datastores:operational for YANG actions. 480 If the chosen schema-set is not available then an error response 481 containing a "404 Not Found" status-line MUST be returned by the 482 server. 484 5.5. Custom schema-sets 486 Custom schema-sets, if supported by the server, allow clients to: 488 o Configure client meaningful names for selectable schema-sets. 490 o Combine compatible schema-sets together into a combined named 491 schema-set that is then selectable by clients. E.g. a client 492 might want to use a combination of standard configuration models 493 along with vendor configuration models to manage functionality not 494 covered by the standard models. 496 6. Schema selection from a server perspective 498 The general premise of this solution is that servers generally 499 implement one native schema, and the schema selection scheme is used 500 to support older version of that native schema and also foreign 501 schema specified by external entities. 503 Overall the solution relies on the ability to map instance data 504 between different schema versions. Depending on the scope of 505 difference between the schema versions then some of these mappings 506 may be very hard, or even impossible, to implement. Hence, there is 507 still a strong incentive to try and minimize NBC changes between 508 schema versions to minimize the mapping complexity. 510 Server implementations MUST serialize configuration requests across 511 the different schema. The expectation is that this would be achieved 512 by mapping all requests to the device's native schema version. 514 Datastore validation MAY need to be performed in two places, firstly 515 in whichever schema a client is interacting in, and secondly in the 516 native schema for the device. This could have a negative performance 517 impact. 519 Depending on the complexity of the mappings between schema versions, 520 it may be necessary for the mappings to be stateful. 522 7. Schema selection from a client perspective 524 Clients can use configuration to choose which schema-sets are 525 available for selection. 527 Clients cannot choose arbitrary individual YANG module versions, and 528 are instead constrained by the versions that the server makes 529 available via schema-sets. 531 Each client protocol connection is to one particular schema-set. 532 From that client session perspective it appears as if the client is 533 interacting with a regular server using the selected schema. If the 534 client queries YANG library, then the version of YANG Library that is 535 returned matches the schema-set that has been selected by the client. 537 The selection of a schema-set by a client MUST NOT change the 538 behaviour of the server experienced by other clients. For example, 539 the get-data response to one client MUST be the same before and after 540 another client selects a schema-set. 542 The server may not support a schema with the exact version desired by 543 the client, and the client may have to choose a later version that is 544 backwards compatible with their desired version. Clients may also 545 have to accept later schema versions that contain NBC fixes, although 546 the assumption is that such NBC fixes should be designed to minimize 547 the impact on clients. 549 There is no guarantee that servers will always be able to support all 550 older schema versions. Deviations SHOULD be used where necessary to 551 indicate that the server is unable to faithfully implement the older 552 schema version. 554 If clients interact with a server using multiple versions, they 555 should not expect that all data nodes in later module versions can 556 always be backported to older schema versions. 558 7.1. Examples 560 Here is a simple example of a NETCONF client migrating to a new 561 schema-set with a server that has multiple schema-sets in the 562 'selectable' leaf-list: 564 1. Disconnect the current session 565 2. Reconnect and select a new schema-set from the 'selectable' leaf- 566 list 568 If a server, for example, only supports a single schema-set at a time 569 by only allowing a single entry in the 'selectable' leaf-list (the 570 default), then a change of the schema-set in the 'selectable' leaf- 571 list (and default) would cause all previously established NETCONF 572 sessions (using the previous 'selectable' schema-set) to be 573 disconnected. 575 If a server only supports a single schema-set at a time (across all 576 sessions), a NETCONF client can migrate to a new schema-set by using 577 the following sequence of steps: 579 1. Configure a new schema-set in the 'selectable' leaf-list, remove 580 the old schema-set, and set the 'default' leaf to that new 581 schema-set. Other configuration can also be done in the same 582 request (using the current schema-set in use on the session). 584 2. The server will process the request and then disconnect the 585 session (since the current schema-set of the session can no 586 longer be supported). All other NETCONF sessions would also be 587 disconnected at this point. 589 3. The client reconnects using the new schema-set (either by 590 selecting it during capability exchange, or by using no selection 591 and relying on the new default schema-set). 593 4. The client can then optionally send a complete new configuration 594 using the new schema (i.e. if the client knows that the server 595 can't perfectly convert everything from the old schema to the new 596 schema). 598 8. Limitations of the solution 600 Not all schema conversions are possible. E.g. an impossible type 601 conversion, or something has been removed. The solution is 602 fundamentally limited by how the schemas actually change, this 603 solution does not provide a magic bullet that can solve all 604 versioning issues. 606 9. Schema Selection YANG module 608 The YANG schema selection YANG module is used by a server to report 609 the schema-sets that are generally available, and to allow clients to 610 configure which schema-sets are available for client selection and 611 which is the default. 613 Custom schema-sets, if supported, allows clients to configure custom 614 combinations of schema-sets that can then be selected by clients. 616 The "ietf-schema-selection" YANG module has the following structure: 618 module: ietf-schema-selection 619 +--rw schema-set-selection! 620 +--rw selectable* -> /schema-set-selection/schema-set/name 621 +--rw default -> /schema-set-selection/selectable 622 +--rw custom* [name] {custom-schema-set}? 623 | +--rw name string 624 | +--rw description? string 625 | +--rw included-schema* 626 | -> /schema-set-selection/schema-set/name 627 +--ro schema-set* [name] 628 +--ro name string 629 +--ro partial? empty 630 +--ro datastore* [name] 631 | +--ro name ds:datastore-ref 632 | +--ro read-only? empty 633 | +--ro package* [name version] 634 | +--ro name -> /pkgs:packages/package/name 635 | +--ro version leafref 636 | +--ro checksum? leafref 637 +--ro selectable-with* 638 | -> /schema-set-selection/schema-set/name 639 +--ro custom-selectable! {custom-schema-set}? 640 +--ro combinable-with* 641 -> /schema-set-selection/schema-set/name 643 10. YANG Module 645 The YANG module definition for the module described in the previous 646 sections. 648 file "ietf-schema-selection@2020-02-29.yang" 649 module ietf-schema-selection { 650 yang-version 1.1; 651 namespace 652 "urn:ietf:params:xml:ns:yang:ietf-schema-selection"; 653 prefix "schema"; 655 import ietf-yang-revisions { 656 prefix rev; 657 reference "XXXX: Updated YANG Module Revision Handling"; 659 } 661 import ietf-datastores { 662 prefix ds; 663 rev:revision-or-derived 2018-02-14; 664 reference 665 "RFC 8342: Network Management Datastore Architecture (NMDA)"; 666 } 668 import ietf-yang-packages { 669 prefix pkgs; 670 rev:revision-or-derived 0.2.0; 671 reference "RFC XXX: YANG Packages."; 672 } 674 organization 675 "IETF NETMOD (Network Modeling) Working Group"; 677 contact 678 "WG Web: 679 WG List: 681 Author: Reshad Rahman 682 684 Author: Rob Wilton 685 687 Author: Joe Clarke 688 690 Author: Jason Sterne 691 693 Author: Bo Wu 694 "; 696 description 697 "This module provide a data model to advertise and allow the 698 selection of schema versions by clients. 700 Copyright (c) 2019 IETF Trust and the persons identified as 701 authors of the code. All rights reserved. 703 Redistribution and use in source and binary forms, with or 704 without modification, is permitted pursuant to, and subject 705 to the license terms contained in, the Simplified BSD License 706 set forth in Section 4.c of the IETF Trust's Legal Provisions 707 Relating to IETF Documents 708 (http://trustee.ietf.org/license-info). 710 This version of this YANG module is part of RFC XXXX; see 711 the RFC itself for full legal notices. 713 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL 714 NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'NOT RECOMMENDED', 715 'MAY', and 'OPTIONAL' in this document are to be interpreted as 716 described in BCP 14 (RFC 2119) (RFC 8174) when, and only when, 717 they appear in all capitals, as shown here."; 719 // RFC Ed.: update the date below with the date of RFC publication 720 // and remove this note. 721 // RFC Ed.: replace XXXX with actual RFC number and remove this 722 // note. 723 revision 2020-02-29 { 724 description 725 "Initial revision"; 726 reference 727 "RFC XXXX: YANG Schema Selection"; 728 } 730 /* 731 * Features 732 */ 733 feature "custom-schema-set" { 734 description 735 "Feature to choose whether clients may configurable custom 736 schema definitions."; 737 } 739 /* 740 * Top level data nodes. 741 */ 743 container schema-set-selection { 744 presence "Enable schema selection"; 746 description 747 "YANG schema-set selection. 749 Contains configuration and state related to client selectable 750 YANG schema-sets."; 752 leaf-list selectable { 753 type leafref { 754 path "/schema-set-selection/schema-set/name"; 755 require-instance false; 756 } 757 min-elements 1; 759 description 760 "Specifies the selectable schema used by this server, that 761 can be selected by clients (either through NETCONF 762 capability negotiation or RESTCONF schema specific path)."; 763 } 765 leaf default { 766 type leafref { 767 path "/schema-set-selection/selectable"; 768 } 769 mandatory true; 770 description 771 "Defines the default schema-set used by this server. 773 This is the schema-set that is chosen if a NETCONF client 774 doesn't select a schema during capability negotiation, or if 775 the standard RESTCONF (or NMDA datastore URLs) are used."; 776 } 778 list custom { 779 if-feature "custom-schema-set"; 780 key "name"; 782 description 783 "Defines a custom selectable schema constructed from 784 compatible schema"; 786 leaf name { 787 type "string"; 788 description 789 "Name of custom schema. 791 Format can either be the form of a YANG identifer, or 792 '@'. 794 The selectable-schema name is used in NETCONF capabilties 795 negotiation and also the RESTCONF path (XXX, is encoding 796 required, e.g. for '@'?)"; 797 } 799 leaf description { 800 type string; 801 description 802 "The description associated with this custom package."; 803 } 805 leaf-list included-schema { 806 type leafref { 807 path "/schema-set-selection/schema-set/name"; 808 require-instance false; 809 } 810 description 811 "Lists the schema that are combined together into a single 812 selectable schema (i.e. via a union operation on each 813 datastore schema package)."; 814 } 815 } 817 list schema-set { 818 key "name"; 819 config false; 821 description 822 "Lists all available schema-set's that can be used in schema 823 selection."; 825 leaf name { 826 type string; 828 description 829 "Name of the schema. 831 Do we restrict what is allowed, specifically, do we allow 832 '@'"; 833 } 835 leaf partial { 836 type empty; 838 description 839 "Indicates that this schema-set only represents a subset of 840 the full configurable schema of the device."; 841 } 843 list datastore { 844 key "name"; 846 description 847 "The list of datastores supported for this pan-datastore 848 selectable-package, along with the package schema 849 associated with that datastore."; 851 leaf name { 852 type ds:datastore-ref; 853 description 854 "The datastore that this datastore schema is associated 855 with."; 856 reference 857 "RFC 8342: Network Management Datastore Architecture 858 (NMDA)"; 859 } 861 leaf read-only { 862 type empty; 863 description 864 "For datastores that are normally writable, the read-only 865 flag indicates that the datastore cannot be written 866 using this schema-set. E.g., if was a 867 supported datastore then it could be read, but not 868 written. 870 This flag is not required for datastores, like 871 operational, that are defined as being read-only."; 872 } 874 uses pkgs:yang-ds-pkg-ref; 875 } 877 leaf-list selectable-with { 878 type leafref { 879 path "/schema-set-selection/schema-set/name"; 880 } 881 description 882 "Lists other schema-sets that MAY be selected at the same 883 time as this schema."; 884 } 886 container custom-selectable { 887 if-feature "custom-schema-set"; 888 presence 889 "This schema MAY be selected as part of a custom 890 schema-set."; 891 description 892 "Indicates that this schema-set is selectable as part of a 893 custom schema-set and also lists other schema-sets that 894 may be combined together into a custom schema-set."; 896 leaf-list combinable-with { 897 type leafref { 898 path "/schema-set-selection/schema-set/name"; 899 } 900 description 901 "Lists the schema-sets that MAY be combined with this 902 schema into a single custom schema-set'."; 903 } 904 } 905 } 906 } 907 } 908 910 11. Security Considerations 912 To be defined. 914 12. IANA Considerations 916 This document requests IANA to registers a URI in the "IETF XML 917 Registry" [RFC3688]. Following the format in RFC 3688, the following 918 registrations are requested. 920 URI: urn:ietf:params:xml:ns:yang:ietf-schema-selection 921 Registrant Contact: The IESG. 922 XML: N/A, the requested URI is an XML namespace. 924 This document requests that the following YANG modules are added in 925 the "YANG Module Names" registry [RFC6020]: 927 Name: ietf-schema-selection.yang 928 Namespace: urn:ietf:params:xml:ns:yang:ietf-schema-selection 929 Prefix: schema 930 Reference: RFC XXXX 932 This document registers a URI. 934 12.1. NETCONF Capability URNs 936 This document registers a URI in the IETF XML registry [RFC3688]. 937 The IANA registry "Network Configuration Protocol (NETCONF) 938 Capability URNs" needs to be updated to include the following 939 capability. 941 Index 942 Capability Identifier 943 ------------------------- 944 :schema-sets 945 urn:ietf:params:netconf:capability:schema-sets:1.0 947 13. Open Questions/Issues 949 All issues, along with the draft text, are currently being tracked 950 at: https://github.com/netmod-wg/yang-ver-dt/labels/version- 951 selection-solution 953 14. Acknowledgements 955 The ideas that formed this draft are based on discussions with the 956 YANG versioning design team, and other members of the NETMOD WG. 958 15. References 960 15.1. Normative References 962 [I-D.ietf-netmod-yang-instance-file-format] 963 Lengyel, B. and B. Claise, "YANG Instance Data File 964 Format", draft-ietf-netmod-yang-instance-file-format-07 965 (work in progress), February 2020. 967 [I-D.rwilton-netmod-yang-packages] 968 Wilton, R., Rahman, R., Clarke, J., Sterne, J., and W. Bo, 969 "YANG Packages", draft-rwilton-netmod-yang-packages-03 970 (work in progress), February 2020. 972 [I-D.verdt-netmod-yang-module-versioning] 973 Claise, B., Clarke, J., Rahman, R., Wilton, R., Lengyel, 974 B., Sterne, J., and K. D'Souza, "Updated YANG Module 975 Revision Handling", draft-verdt-netmod-yang-module- 976 versioning-01 (work in progress), October 2019. 978 [I-D.verdt-netmod-yang-semver] 979 Claise, B., Clarke, J., Rahman, R., Wilton, R., Lengyel, 980 B., Sterne, J., and K. D'Souza, "YANG Semantic 981 Versioning", draft-verdt-netmod-yang-semver-01 (work in 982 progress), October 2019. 984 [I-D.verdt-netmod-yang-versioning-reqs] 985 Clarke, J., "YANG Module Versioning Requirements", draft- 986 verdt-netmod-yang-versioning-reqs-02 (work in progress), 987 November 2018. 989 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 990 Requirement Levels", BCP 14, RFC 2119, 991 DOI 10.17487/RFC2119, March 1997, 992 . 994 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 995 DOI 10.17487/RFC3688, January 2004, 996 . 998 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 999 the Network Configuration Protocol (NETCONF)", RFC 6020, 1000 DOI 10.17487/RFC6020, October 2010, 1001 . 1003 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 1004 and A. Bierman, Ed., "Network Configuration Protocol 1005 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 1006 . 1008 [RFC6536] Bierman, A. and M. Bjorklund, "Network Configuration 1009 Protocol (NETCONF) Access Control Model", RFC 6536, 1010 DOI 10.17487/RFC6536, March 2012, 1011 . 1013 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 1014 RFC 7950, DOI 10.17487/RFC7950, August 2016, 1015 . 1017 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 1018 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 1019 . 1021 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1022 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1023 May 2017, . 1025 [RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 1026 and R. Wilton, "Network Management Datastore Architecture 1027 (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018, 1028 . 1030 [RFC8525] Bierman, A., Bjorklund, M., Schoenwaelder, J., Watsen, K., 1031 and R. Wilton, "YANG Library", RFC 8525, 1032 DOI 10.17487/RFC8525, March 2019, 1033 . 1035 [RFC8527] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 1036 and R. Wilton, "RESTCONF Extensions to Support the Network 1037 Management Datastore Architecture", RFC 8527, 1038 DOI 10.17487/RFC8527, March 2019, 1039 . 1041 15.2. Informative References 1043 [I-D.ietf-netmod-artwork-folding] 1044 Watsen, K., Auerswald, E., Farrel, A., and Q. WU, 1045 "Handling Long Lines in Inclusions in Internet-Drafts and 1046 RFCs", draft-ietf-netmod-artwork-folding-12 (work in 1047 progress), January 2020. 1049 [I-D.verdt-netmod-yang-solutions] 1050 Wilton, R., "YANG Versioning Solution Overview", draft- 1051 verdt-netmod-yang-solutions-03 (work in progress), 1052 February 2020. 1054 Appendix A. Schema selection examples 1056 Some common simplifications have been made to examples in this 1057 section: 1059 Simplified package definitions have been defined, e.g., the 1060 packages do not include other packages, and the module lists have 1061 been elided. 1063 Package and module checksums have been omitted to minimize line 1064 wrapping. 1066 A.1. Supporting older versions of a schema 1068 To facilitate an easier migration path for clients, a server may 1069 choose to support older versions of a schema, for example this might 1070 be done to minimize impact on clients if non-backwards-compatible 1071 changes have been made between schema versions. 1073 It is expected that the server can dynamically translate from the 1074 older schema version to the latest, but this is not possible in all 1075 cases (e.g., if support for some functionality has been removed from 1076 the server), when deviations against the old schema version may be 1077 required to accurately describe the supported functionality. 1079 This example illustrates a device that is capable of supporting three 1080 different versions of its vendor-schema, reported in '/schema-set- 1081 selection/schema-set': 1083 vendor-schema@3.0.0, the device defaults to the latest version of 1084 the schema 1086 vendor-schema@2.1.0, a preceding NBC software version 1088 vendor-schema@1.4.5, a preceding NBC software version 1090 Schema selection data from the operational state datastore: 1092 1093 1095 1096 1097 1098 vendor-schema 1099 3.0.0 1100 1101 1102 1103 vendor-schema 1104 2.1.0 1105 1106 1107 1108 vendor-schema 1109 1.4.5 1110 1111 1112 1113 1114 1115 vendor-schema@3.0.0 1116 1117 ds:running 1118 1119 vendor-schema 1120 3.0.0 1121 1122 1123 1124 ds:operational 1125 1126 vendor-schema 1127 3.0.0 1128 1129 1130 vendor-schema@1.4.5 1131 vendor-schema@2.1.0 1132 1133 1134 vendor-schema@2.1.0 1135 1136 ds:running 1137 1138 vendor-schema 1139 2.1.0 1140 1141 1142 1143 ds:operational 1144 1145 vendor-schema 1146 2.1.0 1147 1148 1149 vendor-schema@1.4.5 1150 vendor-schema@3.0.0 1151 1152 1153 vendor-schema@1.4.5 1154 1155 ds:running 1156 1157 vendor-schema 1158 1.4.5 1159 1160 1161 1162 ds:operational 1163 1164 vendor-schema 1165 1.4.5 1166 1167 1168 vendor-schema@2.1.0 1169 vendor-schema@3.0.0 1170 1171 1172 1173 1175 The client may configure the device to instead use an earlier version 1176 of the schema-set, 'vendor-schema@1.4.5'. By configuring only a 1177 single selectable schema-set, and making it the default, means that 1178 this can be the only schema-set that clients use to interact to the 1179 device using. On committing this configuration change, all existing 1180 NETCONF sessions (that were previously interacting using vendor- 1181 schema@3.0.0) will be closed, and clients need to reconnect, at which 1182 point they will interact with schema-set vendor-schema@1.4.5, and 1183 also see the contents of YANG library updated to reflect the 1184 datastore-schema reported in vendor-schema@1.4.5. 1186 Configuration a new default selectable schema: 1188 1189 1190 1191 vendor-schema@1.4.5 1192 vendor-schema@1.4.5 1193 1194 1196 A.1.1. Variation - Multiple selectable schema-sets 1198 The client may wish to interact with multiple different versions of 1199 the schema at the same time. E.g., this could be achieved with the 1200 following configuration: 1202 Configuring multiple selectable schema: 1204 1205 1206 1207 vendor-schema@1.4.5 1208 vendor-schema@3.0.0 1209 vendor-schema@1.4.5 1210 1211 1213 As before, by default clients will use the vendor-schema@1.4.5, but 1214 by using NETCONF capabilities exchange, or through use of the 1215 RESTCONF path that may select version-schema@3.0.0 instead. Clients 1216 could also explicitly select vendor-schema@1.4.5, even though it is 1217 also the default schema-set. 1219 A.2. Supporting different schema families 1221 Some devices may allow clients to configure the device using 1222 different YANG schema (e.g. vendor native, vs IETF, vs OpenConfig). 1224 This example illustrates a device is that capable of supporting 3 1225 different schema families (native, oc, ietf). 1227 1228 1230 1231 1232 1233 vendor-schema 1234 1.0.0 1235 1236 vendor-interfaces 1237 1238 1239 1240 1241 ietf-schema 1242 1.0.0 1243 1244 ietf-interfaces 1245 1246 1247 1248 1249 oc-schema 1250 1.0.0 1251 1252 openconfig-interfaces 1253 1254 1255 1256 1257 1258 1259 combined-schema 1260 1261 ds:running 1262 1263 vendor-schema 1264 1.0.0 1265 1266 1267 ietf-schema 1268 1.0.0 1269 1270 1271 oc-schema 1272 1.0.0 1273 1274 1275 1276 ds:operational 1277 1278 vendor-schema 1279 1.0.0 1280 1281 1282 ietf-schema 1283 1.0.0 1284 1285 1286 oc-schema 1287 1.0.0 1288 1289 1290 1291 1292 vendor-schema 1293 1294 1295 ds:running 1296 1297 vendor-schema 1298 1.0.0 1299 1300 1301 1302 ds:operational 1303 1304 vendor-schema 1305 1.0.0 1306 1307 1308 combined-schema 1309 ietf-schema 1310 oc-schema 1311 1312 ietf-schema 1313 oc-schema 1315 1316 1317 1318 ietf-schema 1319 1320 1321 ds:running 1322 1323 ietf-schema 1324 1.0.0 1325 1326 1327 1328 ds:operational 1329 1330 ietf-schema 1331 1.0.0 1332 1333 1334 combined-schema 1335 vendor-schema 1336 oc-schema 1337 1338 vendor-schema 1339 1340 1341 1342 oc-schema 1343 1344 1345 ds:running 1346 1347 oc-schema 1348 1.0.0 1349 1350 1351 1352 ds:operational 1353 1354 oc-schema 1355 1.0.0 1356 1357 1358 combined-schema 1359 vendor-schema 1360 ietf-schema 1361 1362 vendor-schema 1364 1365 1366 1367 1368 1370 The clients may configure the device in three different ways. 1372 A.2.1. Choosing a single schema family 1374 A client that wishes to use a single schema family for all 1375 interactions with the device can choose a single schema-set and 1376 configure it as the default schema-set: 1378 1379 1380 1381 oc-schema 1382 oc-schema 1383 1384 1386 A.2.2. Restricting some sessions to particular schema family 1388 If a client wishes to use multiple schema families for configuration, 1389 but restrict some sessions to a particular schema family, then they 1390 may configure the default schema as "combined-schema", but also 'oc- 1391 schema' that can be selected via client sessions as a named schema- 1392 set. 1394 1395 1396 1397 combined-schema 1398 oc-schema 1399 combined-schema 1400 1401 1403 A.2.3. Custom combinable schema-set 1405 If there is a need for the client to use IETF or OC schema alongside 1406 the vendor schema, then this can be achieved by configuring a custom 1407 schema-set. Two custom schema-sets can be configured, either "vendor 1408 + ietf schema", or "vendor + oc schema". The example below defines 1409 and selects a custom schema-set that combines the vendor and OC 1410 schema-sets. 1412 1413 1414 1415 1416 my-custom-schema 1417 Vendor and OC schema-sets only 1418 vendor-schema 1419 oc-schema 1420 1421 my-custom-schema 1422 my-custom-schema 1423 1424 1426 Note, for the last case, rather than requiring the client to 1427 configure custom schema, the device could predefine "vendor + ietf" 1428 and "vendor + oc" as named schema-sets available for selection. 1430 Authors' Addresses 1432 Robert Wilton 1433 Cisco Systems, Inc. 1435 Email: rwilton@cisco.com 1437 Reshad Rahman 1438 Cisco Systems, Inc. 1440 Email: rrahman@cisco.com 1442 Joe Clarke 1443 Cisco Systems, Inc. 1445 Email: jclarke@cisco.com 1446 Jason Sterne 1447 Nokia 1449 Email: jason.sterne@nokia.com 1451 Bo Wu 1452 Huawei 1454 Email: lana.wubo@huawei.com