Network Working Group R. Wilton Internet-Draft R. RahmanUpdates: 6241,8040 (if approved) J. ClarkeIntended status: Standards Track J. Clarke Expires: August 31, 2020 Cisco Systems, Inc.Expires: May 4,J. Sterne Nokia B. Wu Huawei February 28, 2020November 1, 2019YANG SchemaVersionSelectiondraft-wilton-netmod-yang-ver-selection-01draft-wilton-netmod-yang-ver-selection-02 Abstract This document definesprotocol mechanismsa mechanism to allow clients, using NETCONF or RESTCONF, tochoose whichconfigure and select YANG schemato usefor interactions with aserver, out of the available YANG schemas supported by aserver.The providedThis functionalityallowcan help serverstosupport clientsin a backwards compatible way, at the same time allowing for non-backwards-compatible updatesusing older revisions of YANG modules even if later revisions contain non- backwards-compatible changes. It can also be used to allow clients to select between YANGmodules.schema defined by different organizations. This draft provides a solution to YANG versioning requirements 3.1 and 3.2. Status of This Memo This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at https://datatracker.ietf.org/drafts/current/. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." This Internet-Draft will expire onMay 4,August 31, 2020. Copyright Notice Copyright (c)20192020 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. Table of Contents 1. Terminology and Conventions . . . . . . . . . . . . . . . . .23 2. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 3. Background . . . . . . . . . . . . . . . . . . . . . . . . . 4 4. Objectives . . . . . . . . . . . . . . . . . . . . . . . . .45 5. SolutionOverview. . . . . . . . . . . . . . . . . . . . . .5. . . . 6 5.1.NETCONFPackages . . . . . . . . . . . . . . . . . . . . . . . . 7 5.2. Schema-sets . . . . . . . . . .6 5.1.1. New capability to advertise schema sets supported. .6 5.1.2. <select-schema-sets> operation. . . . . . . . . . . 75.2. RESTCONF5.3. Defining and changing client selectable schema-sets . . . 8 5.4. Schema selection protocol operations . . . . . . . . . . 8 5.4.1. NETCONF . . . . . . . . . . . . . . . . . . . . . . . 8 5.4.1.1. schema-sets NETCONF capability . . . . . . . . . 8 5.4.2. RESTCONF . . . . . . . . . . . . . . . . . . . . . . 10 5.5. Custom schema-sets . . . . . . . . . . . . . . . . . . . 11 6.VersionSchema selection from a server perspective . . . . . . . . .811 7.VersionSchema selection from aclient'sclient perspective . . . . . . . .9. 12 7.1. Examples . . . . . . . . . . . . . . . . . . . . . . . . 12 8. Limitations of the solution . . . . . . . . . . . . . . . . .1013 9. SchemaVersionSelection YANG module . . . . . . . . . . . .10. . . . 13 10. YANG Module . . . . . . . . . . . . . . . . . . . . . . . . .1114 11. Security Considerations . . . . . . . . . . . . . . . . . . .1620 12. IANA Considerations . . . . . . . . . . . . . . . . . . . . .1620 12.1. NETCONF Capability URNs . . . . . . . . . . . . . . . .1620 13. Open Questions/Issues . . . . . . . . . . . . . . . . . . . .1621 14. Acknowledgements . . . . . . . . . . . . . . . . . . . . . .1621 15. References . . . . . . . . . . . . . . . . . . . . . . . . .1721 15.1. Normative References . . . . . . . . . . . . . . . . . .1721 15.2. Informative References . . . . . . . . . . . . . . . . .1823 Appendix A. Schema selection examples . . . . . . . . . . . . . 23 A.1. Supporting older versions of a schema . . . . . . . . . . 23 A.1.1. Variation - Multiple selectable schema-sets . . . . . 26 A.2. Supporting different schema families . . . . . . . . . . 27 A.2.1. Choosing a single schema family . . . . . . . . . . . 30 A.2.2. Restricting some sessions to particular schema family 30 A.2.3. Custom combinable schema-set . . . . . . . . . . . . 31 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . .1931 1. Terminology and Conventions The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here. This document uses terminology introduced in the YANG versioning requirementsdocument[I-D.verdt-netmod-yang-versioning-reqs],theYANG Module Versioningdocument[I-D.verdt-netmod-yang-module-versioning] andthe YANgYANG Packagesdocument[I-D.rwilton-netmod-yang-packages]. This documentalsomakes of the following terminology introduced in the Network Management Datastore Architecture [RFC8342]: o datastore schemaIn addition, thisThis documentmakes use ofdefines the following terminology: o YANG schema: The combined set of schema nodes for a set of YANG module revisions, taking into consideration any deviations and enabled features. o versioned schema: A YANG schema with an associated YANG semantic version number, e.g., as might be described by a YANG package[I-D.rwilton-netmod-yang-packages]. oschema set:schema-set: A named set ofrelated versioned YANG schema, onedatastore schemas foreachsupported datastores, where every datastorethatschema is specified as a union of compatible YANG packages. A schema-set issupported. TODO - 'schema' and 'versioned schema' could be defined inthepackages draft.basic unit of client schema selection. 2. Introduction This document describes how NETCONF and RESTCONF clients canchooseuse protocol extensions, along with aparticular YANGschemathey wishselection YANG module, to chooseto interactparticular YANG schema for interactions with a server. [I-D.verdt-netmod-yang-versioning-reqs] defines requirements that any solution to YANG versioning must have. YANG Semver [I-D.verdt-netmod-yang-semver],which isbased on[I-D.verdt-netmod-yang-module-versioning],YANG Module Versioning, specifies a partial solution to the YANG versioning requirements that focuses on using semantic versioning within individual YANG modules, but does not address alltherequirements listed in the YANG versioning requirements document. Of particular relevance here, requirements 3.1 and 3.2 are not addressed.[I-D.rwilton-netmod-yang-packages]YANG Packages describes how sets of related YANGmodulesmodule revisions can be grouped together into a logical entity thatis versioned using thedefines a YANGsemantic versioning number scheme.schema. Different packages can be defined for different sets of YANG modules, e.g., packages could be defined for the IETF YANG modules, OpenConfig YANG modules, or a vendor's YANG modules.DifferentUpdated versions of these package definitions can be defined as the contents of these packages evolve over time,and as the versionse.g., by using new revisions oftheYANG modules included in thepackage evolve.package. This document defines how YANG packagescan beare used to represent versioned datastore schema, and how clients can choose which versioned schemas to use during protocol interactions with a device. 3. Background There are three ways that the lifecycle of a data model can be managed: 1. Disallow all non-backwards-compatible updates to a YANG module. Broadly this is the approach adopted by [RFC7950], but it has been shown to be too inflexible in some cases. E.g. it makes it hard to fix bugs in a clean fashion - it is not clear that allowing two independent data nodes (one deprecated, one current) to configure the same underlying property is robustly backwards compatible in all scenarios, particularly if the value space and/ or default values differ between the module revisions. 2. Allow non-backwards-compatible updates to YANG modules, and use a mechanism such as semantic version numbers to communicate the likely impact of any changes to module users, but require that clients handle non-backwards-compatible changes in servers by migrating to new versions of the modules. Withoutversionschema selection, this is what the[I-D.verdt-netmod-yang-semver]YANG Semver approach likely achieves. 3. Allow non-backwards-compatible updates to YANG modules, but also provide mechanisms to allow servers to support multiple versions of YANG modules, and provide clients with some ability to select which versions of YANG modules they wish to interact with, subject to some reasonable constraints. This is the approach that this document aims to address. It is worth noting that the idea of supporting multiple versions of an API is not new in the wider software industry, and thereanyare many examples of where this approach has beensuccessfully used.used successfully. 4. Objectives The goals oftheYANG schemaversionselectiondocumentare: o To provide a mechanism where non-backwards-compatible changes and bug fixes can be made to YANG modules without forcing clients to immediately migrate to new versions of those modules as they get implemented. o To allow servers to support multiple versions of a particular YANG schema, and to allow clients to choose which YANG schema version to use when interoperating with the server. The aim here is to give operators more flexibility as to when they update theirsoftware.management clients. o To provide a mechanism to allow different YANG schema families (e.g., SDO models, OpenConfig models, Vendor models) to be supported by a server, and to allow clients to choose which YANG schema family is used to interoperate with the server. o To closely align with existing NETCONF/RESTCONF protocol semantics. I.e., with the exception of the optional mechanism that allows selection of the schema-set at the beginning of a NETCONF session or RESTCONF request, protocol interactions between client and server are the same as when schema selection is not being used. o To allow considerable freedom for server implementations to decide how to implement schema selection, and choose the schema selection capabilities they support. In particular: * Servers determine which schema-sets can be selected by clients, and which combinations of schema-sets are compatible with each other during concurrent sessions/operations. * Servers can make some schema-sets automatically available for client selection, or require clients to configure the selectable schema-sets before they can be used. * Servers can limit clients to selecting only a single schema-set for all client connections, i.e., replacing the devices default schema-set, or allow clients to use different schema for concurrent sessions/operations. * Servers can restrict some read-write datastores to be read-only when accessed via a particular schema-set, i.e., providing a read-only view of configuration. * Servers may allow clients to combine schema-sets into named custom schema-sets, or only support predefined schema-sets. The following points are nonobjectiveobjectives of this document: o This document does not provide a mechanism to allow clients to choose arbitrary sets of YANG module versions to interoperate with the server. o Servers are not required to concurrently support clients using different YANG schema families or versioned schema. A server MAY choose to only allow a single schema family or single versioned schema to be used by all clients. o There is no requirement for a server to support every published version of a YANG package, particularly if some package versions are backwards compatible. Clients are required to interoperate with backwards compatible updates of YANG modules. E.g., if a particularpackagepackage, using YANG Semver versioning rules, was available in versions 1.0.0, 1.1.0, 1.2.0, 2.0.0, 3.0.0 and 3.1.0, then a server may choose to only support versions 1.2.0, 2.0.0, and 3.1.0, with the knowledge that all clients should be able to interoperate with the server. o There is no requirement to support all parts of all versioned schemas. For somenbcNBC changes in modules, it is not possible for a server to support both the old and new module versions, and to convert between the two. Whereappropriateappropriate, deviationscanSHOULD be used, and otherwise an out of band mechanismisSHOULD be used to indicate where a mapping has failed. 5. SolutionOverviewAnoverviewoutline of the solution is as follows: 1. YANGpackages, specified in [I-D.rwilton-netmod-yang-packages],packages aredefined for the differentused to define versioned schema that represent a partial or full datastore schema for one or more datastores. 2. Schema-sets are named structures that define a set of supported datastores, along with the schema associated with each of those datastores, specified via leaf references to YANG packages. 3. The configurable 'selectable' leaf-list defines which schema-sets may be selected by clients, and the associated configurable 'default' leaf defines the schema-set used by clients that do not select aserver: *schema-set. 4. Clients choose which selectable schema-set to use via NETCONF capability exchange during session initiation, or RESTCONF path. 5. Optionally, the configurable 'custom-schema-set' list allows clients to combine schema-sets together into new named schema- sets for selection. 5.1. Packages Section 5.3 of YANG Packages specifies how packages SHOULD be used to represent datastore schema. Additional guidance on how YANG packages are specified for schema selection are: o Separate packagescanMAY be defined for different families of schema, e.g., SDO, OpenConfig, or vendor native.* Separate packages can be defined for each versioned schema within a schema family. *o Separate packagesmayMAY be defined for differentdatastores, if the datastores use different datastoreversions of schema.For example, a different datastore schema,o All packages referenced for schema selection, andhence package, mightany recursively included package dependencies, MUST beused for <operational> vsavailable on theconventional datastores. 2. Eachserveradvertises, via an operational data model: * All ofin theYANG'/packages' container in the operational state datastore. o Globally scoped packagesthat may beusedduring version selection. The packages can alsofor schema selection SHOULD be made availableforofflineconsumption viain YANG instance data documents, as described in[I-D.rwilton-netmod-yang-packages]. * Grouped setssection 6 ofversioned schema, where each setYANG Packages. 5.2. Schema-sets A schema-set defines a set of datastore schema(s) that could potentially be used for client schema selection. The schema-sets supported by theversionedserver are available at '/schema- set-selection/schema-set' in the operational state datastore. Each schema-set has a unique name that identifies the schema-set during schema selection protocol operations, e.g., it is usedby each supported datastore,in both the NETCONF capabilities exchange andeach versionedthe RESTCONF path. A schema-set defines the set of supported datastores that are available when clients use the selected schema-set. The schema for each datastore isrepresented by aspecified as the union of one or more compatible YANGpackage instance. 3. Each server supportspackages. Writable datastores (e.g., running) can also be labelled as being read-only if they cannot be written to via client interactions using theoperations to: * Allow aschema-set. Not all schema-sets are necessarily compatible with each other, allowing one schema-set to be selected may prevent other schema-sets from being selected at the same time. Hence, each schema-set lists the other schema-sets that it is compatible with. 5.3. Defining and changing client selectable schema-sets A device may have toconfigure which schema version setallocate resources touse forsupport selectable schema- sets, and thedefault NETCONF/RESTCONF connections. * Allowselectable leaf-list '/schema-set-selection/selectable' is the mechanism to constrain the set of schema-sets that can be selected by clients. In the operational state datastore, the 'selectable' leaf-list contains the names of all schema-sets that a clientto configure additional separate RESTCONF protocol instances,may select from. Entries in this list MAY be added by the system without prior configuration. In addition, the 'default' leaf indicates whichuse different schema version sets on those protocol instances. See Section 5.2. * Allowschema-set is used by clients that do not explicitly select aclient using NETCONFschema- set. In configuration, the 'selectable' leaf-list allows clients touseconfigure the"select-schema-sets" RPCschema-sets that are available for clients to select from. A client can also choosewhich schema sets it wants to usethe default schema-set that is used by any client that connects without naming a schema-set. 5.4. Schema selection protocol operations 5.4.1. NETCONF The schema-set being used in a NETCONF session is established at the start of the session through the exchange of capabilities and never changes for thelifetimeduration of thecurrent NECONFsession.See Section 5.1. 4. TheIf the serverinternally maps requests betweencan no longer support thedifferent protocol instances toschema-set in use in a NETCONF session, then it MUST disconnect theinternal device implementation. 5.1.session. 5.4.1.1. schema-sets NETCONF5.1.1. Newcapabilityto advertise schema sets supportedA new NETCONF :schema-sets capability, using base:1.1 defined in[RFC6241],[RFC6241] This capability is usedto indicate what schema setsby the server iswilling to support.advertise selectable schema. The server sendsan unordereda comma separated list (with no white spaces) ofschema setsselectable schema-sets it supports.A server MAY concurrently supportFor consistency, the list SHOULD contain the default selectable schema-set first, followed by the remaining selectable schema-sets, matching the order in the '/schema- set-selection/selectable' leaf-list. This capability is used by clientsusing different YANG package versions.to select a particular schema. The client sends an ordered list of selectable schema that it is willing to use. The selected schema is the first entry in the client schema-set list that is also contained in the server schema-set list. If there is no common entry then the session is terminated with an error. If the client does not include the schema-set capability during the capability exchange then the default selectable schema-set is used. The :schema-sets capability is identified by the following capability string: urn:ietf:params:netconf:capability:schema-sets:1.0 In this example, the server advertises its (abbreviated) <hello> as follows. This indicates that the server supports the followingschema sets:schema-sets: example-ietf-routing: Versions 2.1.0 (default) and 1.3.1 example-vendor-xxx: Versions 9.2.3 and 8.4.2 Some extra white spaces have been added for display purposes only. <hello xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> <capabilities> <capability>urn:ietf:params:netconf:base:1.0</capability> <capability>urn:ietf:params:netconf:base:1.1</capability> <capability> urn:ietf:params:netconf:capability:schema-sets:1.0?list= example-ietf-routing@2.1.0,example-ietf-routing@1.3.1, example-vendor-xxx@9.2.3,example-vendor-xxx@8.4.2 </capability> </capabilities> </hello>TODO - add mechanism to indicate default version 5.1.2. <select-schema-sets> operation Description: Used by a client to select schema-sets which have been advertised by the server via the mechanism described above in Section 5.1.1.Theschema-sets are selected forclient advertises its (abbreviated) <hello> as follows. This indicates thelifetime of the NETCONF session, unless new schema-sets are subsequently selected via this operation. Parameters: schema-set: Schema-set(s)thatthe clientwantsprefers to usefor this session. Positive response: if the server was able to satisfy the request, an <rpc-reply> is sent that includes an <ok> element. Negative response: An <rpc-error> element is included in the <rpc- reply> iftherequest cannot be completed for any reason. A <select- schema-sets> operationexample-ietf-routing schema version 2.1.0, but canfail for a number of reasons, such as a YANG packagealso use versionis not supported by1.3.1. Because both theserver, or a different version of a YANG package has already been selected by another client. Example: aclientselects schema sets example-ietf-routing version 1.3.1andexample-vendor-xxxserver support version9.2.3: <rpc message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> <select-schema-sets> <schema-sets> <schema-set>example-ietf-routing@1.3.1</schema-set> <schema-set>example-vendor-xxx@9.2.3</schema-set> </schema-sets> </select-schema-sets> </rpc> <rpc-reply message-id="101"2.1.0, and because the client listed it first, the selected schema-set is example-ietf- routing@2.1.0: Some extra white spaces have been added for display purposes only. <hello xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"><ok/> <!-- Schema set selection succeeded --> </rpc-reply> TODO - add error indication 5.2.<capabilities> <capability>urn:ietf:params:netconf:base:1.1</capability> <capability> urn:ietf:params:netconf:capability:schema-sets:1.0?list= example-ietf-routing@2.1.0,example-ietf-routing@1.3.1 </capability> </capabilities> </hello> 5.4.2. RESTCONFTo enable servers which can support different versionsFor RESTCONF, schema-sets are chosen via use ofYANG packages: o On servers, a unique RESTCONF root resource can be configured to map to each schema-set o A default schema-set can be configured.their name in the request URI. Clients select the desired schema-set by choosing the corresponding RESTCONF rootresourceresource. This is done by appending the schema-set name to the RESTCONF API root [RFC8040]. This updates Section 3.1 of[RFC8040]. For example, consider[RFC8040] and Section 3 of [RFC8527]. Clients will use RESTCONF root resource {+restconf}/schema/<schema- name> for all requests pertaining to resources specific to a schema- set. Consider a device whichhas been configured with root-path "/restconf/example- ietf-routing-1.3.1"supports schema-sets vendor- schema@3.0.0, vendor-schema@2.1.0 and vendor-schema@1.4.5: clients will use RESTCONF root resource {+restconf}/schema/vendor- schema@X.Y.Z forsecondary schema set "example-ietf-routing- 1.3.1". Any operationsall requests pertaining to resources defined in schema-set vendor-schema@X.Y.Z. This applies to all RESTCONF resources defined in vendor-schema@X.Y.Z. Here are some examples where {+restconf} is /restconf/. Examples for servers which are NOT NMDA-compliant as per [RFC8527]: 1. /restconf/schema/vendor-schema@X.Y.Z/data for datastore resources. 2. /restconf/schema/vendor-schema@X.Y.Z/data/module-A:data-X for data resource "data-X" defined in module "module-A". 3. /restconf/schema/vendor-schema@X.Y.Z/operations/module-B:op-Y for RPC "op-Y" defined in module "module-B" 4. /restconf/schema/vendor-schema@X.Y.Z/data/module-C:containerZ/ myaction for action "myaction" defined in top-container "containerZ" of module "module-C" Examples for servers which are NMDA-compliant as per [RFC8527]: 1. /restconf/schema/vendor-schema@X.Y.Z/ds/<datastore>/ for datastore resources, e.g. /restconf/schema/vendor- schema@X.Y.Z/ds/ietf-datastores:running refers to the Running configuration datastore. 2. /restconf/schema/vendor-schema@X.Y.Z/ds/ietf- datastores:operational for YANG actions. If the chosen schema-set is not available then an error response containing a "404 Not Found" status-line MUST be returned by the server. 5.5. Custom schema-sets Custom schema-sets, if supported by the server, allow clients to: o Configure clienton schema set "example-ietf- routing-1.3.1" wouldmeaningful names for selectable schema-sets. o Combine compatible schema-sets together into a combined named schema-set that is then selectable by clients. E.g. a client might want to use"/restconf/example-ietf-routing-1.3.1" asa combination of standard configuration models along with vendor configuration models to manage functionality not covered by theRESTCONF root resource.standard models. 6.VersionSchema selection from a server perspective The general premise of this solution is that servers generally implement one native schema, and theversionschema selection scheme is used to support older version of that native schema and also foreign schema specified by external entities. Overall the solution relies on the ability to map instance data between different schema versions. Depending on the scope of difference between the schema versions then some of these mappings may be very hard, or even impossible, to implement. Hence, there is still a strong incentive to try and minimizenbcNBC changes between schema versions to minimize the mapping complexity. Server implementations MUST serialize configuration requests across the different schema. The expectation is that this would be achieved by mapping all requests to the device's native schema version. Datastore validationneedsMAY need to be performed in two places, firstly in whichever schema a client is interacting in, and secondly in the native schema for the device. This could have a negative performance impact. Depending on the complexity of the mappings between schema versions, it may be necessary for the mappings to be stateful.TODO - Figure out how hot fixes that slightly modify the schema are handled.7.VersionSchema selection from aclient'sclient perspective Clients can use configuration to choose whichschema setsschema-sets areavailable.available for selection. Clients cannot choose arbitrary individual YANG module versions, and are instead constrained by the versions that the server makesavailable.available via schema-sets. Each client protocol connection is to one particularschema set.schema-set. From that client session perspective it appears as if the client is interacting with a regularserver.server using the selected schema. If the client queries YANGlibrary thatlibrary, then the version of YANG Library that is returned matches theschema set that is being used forschema-set that has been selected by the client. The selection of a schema-set by a client MUST NOT change the behaviour of the serverinstance.experienced by other clients. For example, the get-data response to one client MUST be the same before and after another client selects a schema-set. The server may not support a schema with the exact version desired by the client, andtheythe client may have toacceptchoose a later version that is backwards compatible with their desired version. Clients may also have to accept later schema versions that contain NBC fixes, although the assumption is that suchnbcNBC fixes should be designed to minimize the impact on clients. There is no guarantee that servers will always be able to support all older schema versions. DeviationsshouldSHOULD be used where necessary to indicate that the server is unable to faithfully implement the older schema version. If clients interact with a server using multiple versions, they should notexactexpect that all data nodes in later module versions can always be backported to older schema versions.TODO - Specify how mapping errors7.1. Examples Here is a simple example of a NETCONF client migrating to a new schema-set with a server that has multiple schema-sets in the 'selectable' leaf-list: 1. Disconnect the current session 2. Reconnect and select a new schema-set from the 'selectable' leaf- list If a server, for example, only supports a single schema-set at a time by only allowing a single entry in the 'selectable' leaf-list (the default), then a change of the schema-set in the 'selectable' leaf- list (and default) would cause all previously established NETCONF sessions (using the previous 'selectable' schema-set) to be disconnected. If a server only supports a single schema-set at a time (across all sessions), a NETCONF client can migrate to a new schema-set by using the following sequence of steps: 1. Configure a new schema-set in the 'selectable' leaf-list, remove the old schema-set, and set the 'default' leaf to that new schema-set. Other configuration can also bereporteddone in the same request (using the current schema-set in use on the session). 2. The server will process the request and then disconnect the session (since the current schema-set of the session can no longer be supported). All other NETCONF sessions would also be disconnected at this point. 3. The client reconnects using the new schema-set (either by selecting it during capability exchange, or by using no selection and relying on the new default schema-set). 4. The client can then optionally send a complete new configuration using the new schema (i.e. if the client knows that the server can't perfectly convert everything from the old schema toclient.the new schema). 8. Limitations of the solution Not all schema conversions are possible. E.g. an impossible type conversion, or something has been removed. The solution is fundamentally limited by how the schemas actually change, this solution does not provide a magic bullet that can solve all versioning issues. 9. SchemaVersionSelection YANG module The YANG schemaversionselection YANG module is used by adeviceserver to report the schema-sets that are generally available, and to allow clients tochooseconfigure whichschema-set they wish to use. Feature are used to allow servers to decide whether they allow the primary schema-set to be changed, and/or allow secondary schema-sets to be configured. The primary schema-set is the datastore schema reported by YANG Library. If secondaryschema-sets areconfigured: With NETCONF, the "select-schema-sets" RPC is used by theavailable for clientto chosseselection and whichschema set(s) it wants to use for the current NETCONF session. With RESTCONF, the configured root path prefixisused bytheclient for a particular schema set. Differentdefault. Custom schema-sets, if supported, allows clients to configure custom combinations of schema-setsmay support different datastores.that can then be selected by clients. The"ietf-schema-version-selection""ietf-schema-selection" YANG module has the following structure: module:ietf-schema-version-selectionietf-schema-selection +--rwschema-selectionschema-set-selection! +--rwschema-sets*selectable* -> /schema-set-selection/schema-set/name +--rw default -> /schema-set-selection/selectable +--rw custom* [name] {custom-schema-set}? | +--rw name string | +--rw description? string | +--rw included-schema* | -> /schema-set-selection/schema-set/name +--ro schema-set* [name] +--rodatastores* [datastore]name string +--ro partial? empty +--ro datastore* [name] | +--rodatastorename ds:datastore-ref | +--ropackages* [package]read-only? empty | +--ropackage -> /yanglib:yang-library/pkg:package/namepackage* [name version] | +--roversion?name ->/yanglib:yang-library/pkg:package[pkg:name = current() | /../package]/version +--rw restconf {secondary-schema-set}?/pkgs:packages/package/name |+--rw schema-sets* [schema-set]+--ro version leafref |+--rw schema-set -> /schema-selection/schema-sets/name+--ro checksum? leafref +--ro selectable-with* |+--rw root-path inet:uri +--rw default-schema-set?->/schema-selection/schema-sets/name {default-schema-set}? rpcs: +---x select-schema-sets +---w input +---w schema-sets* [schema-set] +---w schema-set/schema-set-selection/schema-set/name +--ro custom-selectable! {custom-schema-set}? +--ro combinable-with* ->/schema-selection/schema-sets/name/schema-set-selection/schema-set/name 10. YANG Module The YANG module definition for the module described in the previous sections. <CODE BEGINS> file"ietf-schema-version-selection@2019-10-31.yang""ietf-schema-selection@2020-02-29.yang" moduleietf-schema-version-selectionietf-schema-selection { yang-version 1.1; namespace"urn:ietf:params:xml:ns:yang:ietf-schema-version-selection";"urn:ietf:params:xml:ns:yang:ietf-schema-selection"; prefix"ver-sel";"schema"; importietf-inet-typesietf-yang-revisions { prefixinet;rev; reference"RFC 6991: Common"XXXX: Updated YANGData Types.";Module Revision Handling"; } import ietf-datastores { prefix ds; rev:revision-or-derived 2018-02-14; reference "RFC 8342: Network Management Datastore Architecture (NMDA)"; } importietf-yang-libraryietf-yang-packages { prefixyanglib;pkgs; rev:revision-or-derived 0.2.0; reference "RFC8525:XXX: YANGLibrary"; } import ietf-yl-packages { prefix pkg; reference "draft-rwilton-netmod-yang-packages-02";Packages."; } organization "IETF NETMOD (Network Modeling) Working Group"; contact "WG Web: <http://tools.ietf.org/wg/netmod/> WG List: <mailto:netmod@ietf.org> Author: Reshad Rahman <mailto:rrahman@cisco.com> Author: Rob Wilton<mailto:rwilton@cisco.com>";<mailto:rwilton@cisco.com> Author: Joe Clarke <mailto:jclarke@cisco.com> Author: Jason Sterne <mailto:jason.sterne@nokia.com> Author: Bo Wu <mailto:lana.wubo@huawei.com>"; description "This module provide a data model to advertise and allow the selection of schema versions by clients. Copyright (c) 2019 IETF Trust and the persons identified as authors of the code. All rights reserved. Redistribution and use in source and binary forms, with or without modification, is permitted pursuant to, and subject to the license terms contained in, the Simplified BSD License set forth in Section 4.c of the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info). This version of this YANG module is part of RFC XXXX; see the RFC itself for full legalnotices.";notices. The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document are to be interpreted as described in BCP 14 (RFC 2119) (RFC 8174) when, and only when, they appear in all capitals, as shown here."; // RFC Ed.: update the date below with the date of RFC publication // and remove this note. // RFC Ed.: replace XXXX with actual RFC number and remove this // note. revision2019-10-312020-02-29 { description "Initial revision"; reference "RFC XXXX: YANG SchemaVersionSelection"; } /* * Features */ feature"default-schema-set""custom-schema-set" { description "Featurethat allows clientsto choosethe defaultwhether clients may configurable custom schemasetdefinitions."; } /* * Top level data nodes. */ container schema-set-selection { presence "Enable schema selection"; description "YANG schema-set selection. Contains configuration and state related tobeclient selectable YANG schema-sets."; leaf-list selectable { type leafref { path "/schema-set-selection/schema-set/name"; require-instance false; } min-elements 1; description "Specifies the selectable schema usedfor clients. Implementations may choose to only supportby thisfeature in <operational> to report the default-schema-set without allowing it toserver, that can beconfigured.";selected by clients (either through NETCONF capability negotiation or RESTCONF schema specific path)."; }feature "secondary-schema-set"leaf default { type leafref { path "/schema-set-selection/selectable"; } mandatory true; description"Feature to choose if secondary schema sets may be configured"Defines the default schema-set used byclients. Implementations may choose to only supportthisfeature in <operational> to report secondaryserver. This is the schema-set that is chosen if a NETCONF client doesn't select a schemasets without allowing them toduring capability negotiation, or if the standard RESTCONF (or NMDA datastore URLs) are used."; } list custom { if-feature "custom-schema-set"; key "name"; description "Defines a custom selectable schema constructed from compatible schema"; leaf name { type "string"; description "Name of custom schema. Format can either beconfigured.";the form of a YANG identifer, or '<name>@<rev-label>'. The selectable-schema name is used in NETCONF capabilties negotiation and also the RESTCONF path (XXX, is encoding required, e.g. for '@'?)"; }container schema-selectionleaf description { type string; description"YANG"The description associated with this custom package."; } leaf-list included-schema { type leafref { path "/schema-set-selection/schema-set/name"; require-instance false; } description "Lists the schemaversion selection";that are combined together into a single selectable schema (i.e. via a union operation on each datastore schema package)."; } } listschema-setsschema-set { key "name"; config false; description"All schema-sets that are"Lists all availablefor selection by clients.";schema-set's that can be used in schema selection."; leaf name { type"string" { length "1..255"; }string; description"The server assigned name"Name of theschema-set. This should includeschema. Do we restrict what is allowed, specifically, do we allow '@'"; } leaf partial { type empty; description "Indicates that this schema-set only represents a subset of the full configurable schemafamily, and appropriate versioning or release information";of the device."; } listdatastoresdatastore {config false;key"datastore";"name"; description "The list of datastores supported for this pan-datastore selectable-package, along with the package schemaset";associated with that datastore."; leafdatastorename { type ds:datastore-ref; description "The datastore that this datastore schema is associatedwith";with."; reference "RFC 8342: Network Management Datastore Architecture (NMDA)"; }list packages { key "package"; description "YANG packages associated with this datastore schema";leafpackageread-only { typeleafref { path "/yanglib:yang-library/pkg:package/pkg:name"; }empty; description"The name of"For datastores that are normally writable, theYANG packageread-only flag indicates that the datastore cannot be written using thisschema relates to";schema-set. E.g., if <running> was a supported datastore then it could be read, but not written. This flag is not required for datastores, like operational, that are defined as being read-only."; }leaf versionuses pkgs:yang-ds-pkg-ref; } leaf-list selectable-with { type leafref { path'/yanglib:yang-library/' + 'pkg:package[pkg:name = current()/../package]/' + 'pkg:version';"/schema-set-selection/schema-set/name"; } description"The version of"Lists other schema-sets that MAY be selected at theYANG packagesame time as thisschema relates to"; } } }schema."; } containerrestconfcustom-selectable { if-feature"secondary-schema-set"; description "RESTCONF protocol settings for"custom-schema-set"; presence "This schemasets"; list schema-sets { key "schema-set"; unique "root-path";MAY be selected as part of a custom schema-set."; description"The schema-sets accessed via RESTCONF"; leaf"Indicates that this schema-set{ type leafref { path '/schema-selection/schema-sets/name'; } description "Ais selectable as part of a custom schema-setbeing used by RESTCONF"; } leaf root-path { type inet:uri; mandatory true; description "The root path to use to access the RESTCONF protocol instance for this schema-set"; reference "RFC8040"; } } } leaf default-schema-setand also lists other schema-sets that may be combined together into a custom schema-set."; leaf-list combinable-with {if-feature "default-schema-set";type leafref { path'/schema-selection/schema-sets/name';"/schema-set-selection/schema-set/name"; } description"Specifies"Lists thedefault schema-set used byschema-sets that MAY be combined with thisdevice. This is the set of datastoreschemathat is used if a client connects using the standard URLs"; } } /* * RPCs */ rpc select-schema-sets { description "This RPC allowsinto aNETCONF client to select which schema-sets, among the ones advertised by the server, the clients wants to use for this session"; input { list schema-sets { key "schema-set"; leaf schema-set { type leafref { path '/schema-selection/schema-sets/name'; }single custom schema-set'."; } } } } } <CODE ENDS> 11. Security Considerations To be defined. 12. IANA ConsiderationsTODO - AddThis document requests IANA to registers a URI in the "IETF XML Registry" [RFC3688]. Following the format in RFC 3688, the following registrationsforare requested. URI: urn:ietf:params:xml:ns:yang:ietf-schema-selection Registrant Contact: The IESG. XML: N/A, the requested URI is an XML namespace. This document requests that the following YANG modulesdefinedare added inthis document.the "YANG Module Names" registry [RFC6020]: Name: ietf-schema-selection.yang Namespace: urn:ietf:params:xml:ns:yang:ietf-schema-selection Prefix: schema Reference: RFC XXXX This document registers a URI. 12.1. NETCONF Capability URNs This document registers a URI in the IETF XML registry [RFC3688]. The IANA registry "Network Configuration Protocol (NETCONF) Capability URNs" needs to be updated to include the following capability. Index Capability Identifier ------------------------- :schema-sets urn:ietf:params:netconf:capability:schema-sets:1.0 13. Open Questions/Issues All issues, along with the draft text, are currently being tracked at: https://github.com/netmod-wg/yang-ver-dt/labels/version- selection-solution 14. Acknowledgements The ideas that formed this draft are based on discussions with the YANG versioning design team, and other members of the NETMOD WG. 15. References 15.1. Normative References[I-D.ietf-netconf-rfc7895bis] Bierman, A., Bjorklund, M., Schoenwaelder, J., Watsen, K., and R. Wilton, "YANG Library", draft-ietf-netconf- rfc7895bis-07 (work in progress), October 2018. [I-D.ietf-netmod-module-tags] Hopps, C., Berger, L., and D. Bogdanovic, "YANG Module Tags", draft-ietf-netmod-module-tags-09 (work in progress), September 2019.[I-D.ietf-netmod-yang-instance-file-format] Lengyel, B. and B. Claise, "YANG Instance Data File Format",draft-ietf-netmod-yang-instance-file-format-04draft-ietf-netmod-yang-instance-file-format-07 (work in progress),August 2019.February 2020. [I-D.rwilton-netmod-yang-packages] Wilton, R., Rahman, R., Clarke, J., Sterne, J., and W. Bo, "YANG Packages",draft-rwilton-netmod-yang- packages-02draft-rwilton-netmod-yang-packages-03 (work in progress),October 2019.February 2020. [I-D.verdt-netmod-yang-module-versioning] Claise, B., Clarke, J., Rahman, R., Wilton, R., Lengyel, B., Sterne, J., and K. D'Souza, "Updated YANG Module Revision Handling", draft-verdt-netmod-yang-module- versioning-01 (work in progress), October 2019. [I-D.verdt-netmod-yang-semver] Claise, B., Clarke, J., Rahman, R., Wilton, R., Lengyel, B., Sterne, J., and K. D'Souza, "YANG Semantic Versioning", draft-verdt-netmod-yang-semver-01 (work in progress), October 2019. [I-D.verdt-netmod-yang-versioning-reqs] Clarke, J., "YANG Module Versioning Requirements", draft- verdt-netmod-yang-versioning-reqs-02 (work in progress), November 2018. [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, <https://www.rfc-editor.org/info/rfc2119>. [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, DOI 10.17487/RFC3688, January 2004, <https://www.rfc-editor.org/info/rfc3688>.[RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security (TLS)[RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for the Network Configuration ProtocolVersion 1.2",(NETCONF)", RFC5246,6020, DOI10.17487/RFC5246, August 2008, <https://www.rfc-editor.org/info/rfc5246>.10.17487/RFC6020, October 2010, <https://www.rfc-editor.org/info/rfc6020>. [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., and A. Bierman, Ed., "Network Configuration Protocol (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, <https://www.rfc-editor.org/info/rfc6241>.[RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011, <https://www.rfc-editor.org/info/rfc6242>.[RFC6536] Bierman, A. and M. Bjorklund, "Network Configuration Protocol (NETCONF) Access Control Model", RFC 6536, DOI 10.17487/RFC6536, March 2012, <https://www.rfc-editor.org/info/rfc6536>. [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", RFC 7950, DOI 10.17487/RFC7950, August 2016, <https://www.rfc-editor.org/info/rfc7950>. [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, <https://www.rfc-editor.org/info/rfc8040>. [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017, <https://www.rfc-editor.org/info/rfc8174>. [RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., and R. Wilton, "Network Management Datastore Architecture (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018, <https://www.rfc-editor.org/info/rfc8342>. [RFC8525] Bierman, A., Bjorklund, M., Schoenwaelder, J., Watsen, K., and R. Wilton, "YANG Library", RFC 8525, DOI 10.17487/RFC8525, March 2019, <https://www.rfc-editor.org/info/rfc8525>. [RFC8527] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., and R. Wilton, "RESTCONF Extensions to Support the Network Management Datastore Architecture", RFC 8527, DOI 10.17487/RFC8527, March 2019, <https://www.rfc-editor.org/info/rfc8527>. 15.2. Informative References[I-D.bierman-netmod-yang-package] Bierman, A., "The YANG Package Statement", draft-bierman- netmod-yang-package-00 (work in progress), July 2015.[I-D.ietf-netmod-artwork-folding] Watsen, K., Auerswald, E., Farrel, A., and Q. WU, "Handling Long Lines in Inclusions in Internet-Drafts and RFCs",draft-ietf- netmod-artwork-folding-10draft-ietf-netmod-artwork-folding-12 (work in progress),September 2019. [RFC8199] Bogdanovic, D., Claise, B., and C. Moberg,January 2020. [I-D.verdt-netmod-yang-solutions] Wilton, R., "YANGModule Classification", RFC 8199, DOI 10.17487/RFC8199, July 2017, <https://www.rfc-editor.org/info/rfc8199>.Versioning Solution Overview", draft- verdt-netmod-yang-solutions-03 (work in progress), February 2020. Appendix A. Schema selection examples Some common simplifications have been made to examples in this section: Simplified package definitions have been defined, e.g., the packages do not include other packages, and the module lists have been elided. Package and module checksums have been omitted to minimize line wrapping. A.1. Supporting older versions of a schema To facilitate an easier migration path for clients, a server may choose to support older versions of a schema, for example this might be done to minimize impact on clients if non-backwards-compatible changes have been made between schema versions. It is expected that the server can dynamically translate from the older schema version to the latest, but this is not possible in all cases (e.g., if support for some functionality has been removed from the server), when deviations against the old schema version may be required to accurately describe the supported functionality. This example illustrates a device that is capable of supporting three different versions of its vendor-schema, reported in '/schema-set- selection/schema-set': vendor-schema@3.0.0, the device defaults to the latest version of the schema vendor-schema@2.1.0, a preceding NBC software version vendor-schema@1.4.5, a preceding NBC software version Schema selection data from the operational state datastore: <?xml version="1.0" encoding="utf-8"?> <rpc-reply xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="101"> <data> <packages> <package> <name>vendor-schema</name> <version>3.0.0</version> <!-- package modules elided --> </package> <package> <name>vendor-schema</name> <version>2.1.0</version> <!-- package modules elided --> </package> <package> <name>vendor-schema</name> <version>1.4.5</version> <!-- package modules elided --> </package> </packages> <schema-set-selection> <schema-set> <name>vendor-schema@3.0.0</name> <datastore> <name>ds:running</name> <package> <name>vendor-schema</name> <version>3.0.0</version> </package> </datastore> <datastore> <name>ds:operational</name> <package> <name>vendor-schema</name> <version>3.0.0</version> </package> </datastore> <selectable-with>vendor-schema@1.4.5</selectable-with> <selectable-with>vendor-schema@2.1.0</selectable-with> </schema-set> <schema-set> <name>vendor-schema@2.1.0</name> <datastore> <name>ds:running</name> <package> <name>vendor-schema</name> <version>2.1.0</version> </package> </datastore> <datastore> <name>ds:operational</name> <package> <name>vendor-schema</name> <version>2.1.0</version> </package> </datastore> <selectable-with>vendor-schema@1.4.5</selectable-with> <selectable-with>vendor-schema@3.0.0</selectable-with> </schema-set> <schema-set> <name>vendor-schema@1.4.5</name> <datastore> <name>ds:running</name> <package> <name>vendor-schema</name> <version>1.4.5</version> </package> </datastore> <datastore> <name>ds:operational</name> <package> <name>vendor-schema</name> <version>1.4.5</version> </package> </datastore> <selectable-with>vendor-schema@2.1.0</selectable-with> <selectable-with>vendor-schema@3.0.0</selectable-with> </schema-set> </schema-set-selection> </data> </rpc-reply> The client may configure the device to instead use an earlier version of the schema-set, 'vendor-schema@1.4.5'. By configuring only a single selectable schema-set, and making it the default, means that this can be the only schema-set that clients use to interact to the device using. On committing this configuration change, all existing NETCONF sessions (that were previously interacting using vendor- schema@3.0.0) will be closed, and clients need to reconnect, at which point they will interact with schema-set vendor-schema@1.4.5, and also see the contents of YANG library updated to reflect the datastore-schema reported in vendor-schema@1.4.5. Configuration a new default selectable schema: <?xml version="1.0" encoding="utf-8"?> <config xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> <schema-set-selection> <selectable>vendor-schema@1.4.5</selectable> <default>vendor-schema@1.4.5</default> </schema-set-selection> </config> A.1.1. Variation - Multiple selectable schema-sets The client may wish to interact with multiple different versions of the schema at the same time. E.g., this could be achieved with the following configuration: Configuring multiple selectable schema: <?xml version="1.0" encoding="utf-8"?> <config xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> <schema-set-selection> <selectable>vendor-schema@1.4.5</selectable> <selectable>vendor-schema@3.0.0</selectable> <default>vendor-schema@1.4.5</default> </schema-set-selection> </config> As before, by default clients will use the vendor-schema@1.4.5, but by using NETCONF capabilities exchange, or through use of the RESTCONF path that may select version-schema@3.0.0 instead. Clients could also explicitly select vendor-schema@1.4.5, even though it is also the default schema-set. A.2. Supporting different schema families Some devices may allow clients to configure the device using different YANG schema (e.g. vendor native, vs IETF, vs OpenConfig). This example illustrates a device is that capable of supporting 3 different schema families (native, oc, ietf). <?xml version="1.0" encoding="utf-8"?> <rpc-reply xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="101"> <data> <packages> <package> <name>vendor-schema</name> <version>1.0.0</version> <module> <name>vendor-interfaces</name> </module> <!--Module list of vendor YANG modules elided --> </package> <package> <name>ietf-schema</name> <version>1.0.0</version> <module> <name>ietf-interfaces</name> </module> <!--Module list of IETF YANG modules elided --> </package> <package> <name>oc-schema</name> <version>1.0.0</version> <module> <name>openconfig-interfaces</name> </module> <!--Module list of OpenConfig YANG modules elided --> </package> </packages> <schema-set-selection> <schema-set> <name>combined-schema</name> <datastore> <name>ds:running</name> <package> <name>vendor-schema</name> <version>1.0.0</version> </package> <package> <name>ietf-schema</name> <version>1.0.0</version> </package> <package> <name>oc-schema</name> <version>1.0.0</version> </package> </datastore> <datastore> <name>ds:operational</name> <package> <name>vendor-schema</name> <version>1.0.0</version> </package> <package> <name>ietf-schema</name> <version>1.0.0</version> </package> <package> <name>oc-schema</name> <version>1.0.0</version> </package> </datastore> </schema-set> <schema-set> <name>vendor-schema</name> <partial/> <datastore> <name>ds:running</name> <package> <name>vendor-schema</name> <version>1.0.0</version> </package> </datastore> <datastore> <name>ds:operational</name> <package> <name>vendor-schema</name> <version>1.0.0</version> </package> </datastore> <selectable-with>combined-schema</selectable-with> <selectable-with>ietf-schema</selectable-with> <selectable-with>oc-schema</selectable-with> <custom-selectable> <combinable-with>ietf-schema</combinable-with> <combinable-with>oc-schema</combinable-with> </custom-selectable> </schema-set> <schema-set> <name>ietf-schema</name> <partial/> <datastore> <name>ds:running</name> <package> <name>ietf-schema</name> <version>1.0.0</version> </package> </datastore> <datastore> <name>ds:operational</name> <package> <name>ietf-schema</name> <version>1.0.0</version> </package> </datastore> <selectable-with>combined-schema</selectable-with> <selectable-with>vendor-schema</selectable-with> <selectable-with>oc-schema</selectable-with> <custom-selectable> <combinable-with>vendor-schema</combinable-with> </custom-selectable> </schema-set> <schema-set> <name>oc-schema</name> <partial/> <datastore> <name>ds:running</name> <package> <name>oc-schema</name> <version>1.0.0</version> </package> </datastore> <datastore> <name>ds:operational</name> <package> <name>oc-schema</name> <version>1.0.0</version> </package> </datastore> <selectable-with>combined-schema</selectable-with> <selectable-with>vendor-schema</selectable-with> <selectable-with>ietf-schema</selectable-with> <custom-selectable> <combinable-with>vendor-schema</combinable-with> </custom-selectable> </schema-set> </schema-set-selection> </data> </rpc-reply> The clients may configure the device in three different ways. A.2.1. Choosing a single schema family A client that wishes to use a single schema family for all interactions with the device can choose a single schema-set and configure it as the default schema-set: <?xml version="1.0" encoding="utf-8"?> <config xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> <schema-set-selection> <selectable>oc-schema</selectable> <default>oc-schema</default> </schema-set-selection> </config> A.2.2. Restricting some sessions to particular schema family If a client wishes to use multiple schema families for configuration, but restrict some sessions to a particular schema family, then they may configure the default schema as "combined-schema", but also 'oc- schema' that can be selected via client sessions as a named schema- set. <?xml version="1.0" encoding="utf-8"?> <config xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> <schema-set-selection> <selectable>combined-schema</selectable> <selectable>oc-schema</selectable> <default>combined-schema</default> </schema-set-selection> </config> A.2.3. Custom combinable schema-set If there is a need for the client to use IETF or OC schema alongside the vendor schema, then this can be achieved by configuring a custom schema-set. Two custom schema-sets can be configured, either "vendor + ietf schema", or "vendor + oc schema". The example below defines and selects a custom schema-set that combines the vendor and OC schema-sets. <?xml version="1.0" encoding="utf-8"?> <config xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> <schema-set-selection> <custom> <name>my-custom-schema</name> <description>Vendor and OC schema-sets only</description> <included-schema>vendor-schema</included-schema> <included-schema>oc-schema</included-schema> </custom> <selectable>my-custom-schema</selectable> <default>my-custom-schema</default> </schema-set-selection> </config> Note, for the last case, rather than requiring the client to configure custom schema, the device could predefine "vendor + ietf" and "vendor + oc" as named schema-sets available for selection. Authors' Addresses Robert Wilton Cisco Systems, Inc. Email: rwilton@cisco.com Reshad Rahman Cisco Systems, Inc. Email: rrahman@cisco.com Joe Clarke Cisco Systems, Inc. Email: jclarke@cisco.com Jason Sterne Nokia Email: jason.sterne@nokia.com Bo Wu Huawei Email: lana.wubo@huawei.com