-
Notifications
You must be signed in to change notification settings - Fork 3
/
draft-wilton-netmod-yang-ver-selection.txt
1792 lines (1239 loc) · 60.8 KB
/
draft-wilton-netmod-yang-ver-selection.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
Network Working Group R. Wilton
Internet-Draft R. Rahman
Intended status: Standards Track J. Clarke
Expires: September 1, 2020 Cisco Systems, Inc.
J. Sterne
Nokia
B. Wu
Huawei
February 29, 2020
YANG Schema Selection
draft-wilton-netmod-yang-ver-selection-02
Abstract
This document defines a mechanism to allow clients, using NETCONF or
RESTCONF, to configure and select YANG schema for interactions with a
server. This functionality can help servers support clients using
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 YANG 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 http://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 on September 1, 2020.
Copyright Notice
Copyright (c) 2020 IETF Trust and the persons identified as the
document authors. All rights reserved.
Wilton, et al. Expires September 1, 2020 [Page 1]
Internet-Draft YANG Schema Selection February 2020
This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents
(http://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 . . . . . . . . . . . . . . . . . 3
2. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
3. Background . . . . . . . . . . . . . . . . . . . . . . . . . 4
4. Objectives . . . . . . . . . . . . . . . . . . . . . . . . . 5
5. Solution . . . . . . . . . . . . . . . . . . . . . . . . . . 6
5.1. Packages . . . . . . . . . . . . . . . . . . . . . . . . 7
5.2. Schema-sets . . . . . . . . . . . . . . . . . . . . . . . 7
5.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. Schema selection from a server perspective . . . . . . . . . 11
7. Schema selection from a client perspective . . . . . . . . . 12
7.1. Examples . . . . . . . . . . . . . . . . . . . . . . . . 12
8. Limitations of the solution . . . . . . . . . . . . . . . . . 13
9. Schema Selection YANG module . . . . . . . . . . . . . . . . 13
10. YANG Module . . . . . . . . . . . . . . . . . . . . . . . . . 14
11. Security Considerations . . . . . . . . . . . . . . . . . . . 20
12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 20
12.1. NETCONF Capability URNs . . . . . . . . . . . . . . . . 20
13. Open Questions/Issues . . . . . . . . . . . . . . . . . . . . 21
14. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 21
15. References . . . . . . . . . . . . . . . . . . . . . . . . . 21
15.1. Normative References . . . . . . . . . . . . . . . . . . 21
15.2. Informative References . . . . . . . . . . . . . . . . . 23
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 . . . . . . . . . . . . . . . . . . . . . . . 31
Wilton, et al. Expires September 1, 2020 [Page 2]
Internet-Draft YANG Schema Selection February 2020
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
requirements [I-D.verdt-netmod-yang-versioning-reqs], YANG Module
Versioning [I-D.verdt-netmod-yang-module-versioning] and YANG
Packages [I-D.rwilton-netmod-yang-packages].
This document makes of the following terminology introduced in the
Network Management Datastore Architecture [RFC8342]:
o datastore schema
This document defines 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].
o schema-set: A named set of datastore schemas for supported
datastores, where every datastore schema is specified as a union
of compatible YANG packages. A schema-set is the basic unit of
client schema selection.
2. Introduction
This document describes how NETCONF and RESTCONF clients can use
protocol extensions, along with a schema selection YANG module, to
choose particular 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], based on 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 all requirements listed
in the YANG versioning requirements document. Of particular
relevance here, requirements 3.1 and 3.2 are not addressed.
Wilton, et al. Expires September 1, 2020 [Page 3]
Internet-Draft YANG Schema Selection February 2020
YANG Packages describes how sets of related YANG module revisions can
be grouped together into a logical entity that defines a YANG 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. Updated versions of these
package definitions can be defined as the contents of these packages
evolve over time, e.g., by using new revisions of YANG modules
included in the package.
This document defines how YANG packages are 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. Without schema
selection, this is what the 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 there are many examples of where
this approach has been used successfully.
Wilton, et al. Expires September 1, 2020 [Page 4]
Internet-Draft YANG Schema Selection February 2020
4. Objectives
The goals of YANG schema selection are:
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 their
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.
Wilton, et al. Expires September 1, 2020 [Page 5]
Internet-Draft YANG Schema Selection February 2020
* Servers may allow clients to combine schema-sets into named
custom schema-sets, or only support predefined schema-sets.
The following points are non objectives 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
particular package, 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 some NBC 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. Where appropriate, deviations SHOULD be
used, and otherwise an out of band mechanism SHOULD be used to
indicate where a mapping has failed.
5. Solution
An outline of the solution is as follows:
1. YANG packages are used 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 a schema-set.
Wilton, et al. Expires September 1, 2020 [Page 6]
Internet-Draft YANG Schema Selection February 2020
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 packages MAY be defined for different families of schema,
e.g., SDO, OpenConfig, or vendor native.
o Separate packages MAY be defined for different versions of schema.
o All packages referenced for schema selection, and any recursively
included package dependencies, MUST be available on the server in
the '/packages' container in the operational state datastore.
o Globally scoped packages used for schema selection SHOULD be made
available offline in YANG instance data documents, as described in
section 6 of YANG 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 the server 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 used in both
the NETCONF capabilities exchange and the 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 is specified as the union of one or more compatible
YANG packages. Writable datastores (e.g., running) can also be
labelled as being read-only if they cannot be written to via client
interactions using the schema-set.
Wilton, et al. Expires September 1, 2020 [Page 7]
Internet-Draft YANG Schema Selection February 2020
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 to allocate resources to support selectable schema-
sets, and the selectable 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 client may select from.
Entries in this list MAY be added by the system without prior
configuration. In addition, the 'default' leaf indicates which
schema-set is used by clients that do not explicitly select a schema-
set.
In configuration, the 'selectable' leaf-list allows clients to
configure the schema-sets that are available for clients to select
from. A client can also choose the 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 the duration of the session. If the server can no longer
support the schema-set in use in a NETCONF session, then it MUST
disconnect the session.
5.4.1.1. schema-sets NETCONF capability
A new NETCONF :schema-sets capability, using base:1.1 defined in
[RFC6241]
This capability is used by the server is advertise selectable schema.
The server sends a comma separated list (with no white spaces) of
selectable schema-sets it supports. For 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.
Wilton, et al. Expires September 1, 2020 [Page 8]
Internet-Draft YANG Schema Selection February 2020
This capability is used by clients 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 following
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>
The client advertises its (abbreviated) <hello> as follows. This
indicates the the client prefers to use the example-ietf-routing
schema version 2.1.0, but can also use version 1.3.1. Because both
the client and server support version 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.
Wilton, et al. Expires September 1, 2020 [Page 9]
Internet-Draft YANG Schema Selection February 2020
<hello xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<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. RESTCONF
For RESTCONF, schema-sets are chosen via use of their name in the
request URI.
Clients select the desired schema-set by choosing the corresponding
RESTCONF root resource. This is done by appending the schema-set
name to the RESTCONF API root [RFC8040]. This updates Section 3.1 of
[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 which 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 for all 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]:
Wilton, et al. Expires September 1, 2020 [Page 10]
Internet-Draft YANG Schema Selection February 2020
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 client meaningful 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 a combination of standard configuration models
along with vendor configuration models to manage functionality not
covered by the standard models.
6. Schema selection from a server perspective
The general premise of this solution is that servers generally
implement one native schema, and the schema 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 minimize NBC 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 validation MAY 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.
Wilton, et al. Expires September 1, 2020 [Page 11]
Internet-Draft YANG Schema Selection February 2020
Depending on the complexity of the mappings between schema versions,
it may be necessary for the mappings to be stateful.
7. Schema selection from a client perspective
Clients can use configuration to choose which schema-sets are
available for selection.
Clients cannot choose arbitrary individual YANG module versions, and
are instead constrained by the versions that the server makes
available via schema-sets.
Each client protocol connection is to one particular schema-set.
From that client session perspective it appears as if the client is
interacting with a regular server using the selected schema. If the
client queries YANG library, then the version of YANG Library that is
returned matches the schema-set that has been selected by the client.
The selection of a schema-set by a client MUST NOT change the
behaviour of the server 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, and the client may have to choose 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 such NBC 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. Deviations SHOULD 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 not expect that all data nodes in later module versions can
always be backported to older schema versions.
7.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
Wilton, et al. Expires September 1, 2020 [Page 12]
Internet-Draft YANG Schema Selection February 2020
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 be done 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 to 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. Schema Selection YANG module
The YANG schema selection YANG module is used by a server to report
the schema-sets that are generally available, and to allow clients to
configure which schema-sets are available for client selection and
which is the default.
Wilton, et al. Expires September 1, 2020 [Page 13]
Internet-Draft YANG Schema Selection February 2020
Custom schema-sets, if supported, allows clients to configure custom
combinations of schema-sets that can then be selected by clients.
The "ietf-schema-selection" YANG module has the following structure:
module: ietf-schema-selection
+--rw schema-set-selection!
+--rw 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]
+--ro name string
+--ro partial? empty
+--ro datastore* [name]
| +--ro name ds:datastore-ref
| +--ro read-only? empty
| +--ro package* [name version]
| +--ro name -> /pkgs:packages/package/name
| +--ro version leafref
| +--ro checksum? leafref
+--ro selectable-with*
| -> /schema-set-selection/schema-set/name
+--ro custom-selectable! {custom-schema-set}?
+--ro combinable-with*
-> /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-selection@2020-02-29.yang"
module ietf-schema-selection {
yang-version 1.1;
namespace
"urn:ietf:params:xml:ns:yang:ietf-schema-selection";
prefix "schema";
import ietf-yang-revisions {
prefix rev;
reference "XXXX: Updated YANG Module Revision Handling";
Wilton, et al. Expires September 1, 2020 [Page 14]
Internet-Draft YANG Schema Selection February 2020
}
import ietf-datastores {
prefix ds;
rev:revision-or-derived 2018-02-14;
reference
"RFC 8342: Network Management Datastore Architecture (NMDA)";
}
import ietf-yang-packages {
prefix pkgs;
rev:revision-or-derived 0.2.0;
reference "RFC XXX: YANG 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>
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
Wilton, et al. Expires September 1, 2020 [Page 15]
Internet-Draft YANG Schema Selection February 2020
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 legal 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.
revision 2020-02-29 {
description
"Initial revision";
reference
"RFC XXXX: YANG Schema Selection";
}
/*
* Features
*/
feature "custom-schema-set" {
description
"Feature to choose whether clients may configurable custom
schema definitions.";
}
/*
* Top level data nodes.
*/
container schema-set-selection {
presence "Enable schema selection";
description
"YANG schema-set selection.
Contains configuration and state related to client selectable
YANG schema-sets.";
leaf-list selectable {
Wilton, et al. Expires September 1, 2020 [Page 16]
Internet-Draft YANG Schema Selection February 2020
type leafref {
path "/schema-set-selection/schema-set/name";
require-instance false;
}
min-elements 1;
description
"Specifies the selectable schema used by this server, that
can be selected by clients (either through NETCONF
capability negotiation or RESTCONF schema specific path).";
}
leaf default {
type leafref {
path "/schema-set-selection/selectable";
}
mandatory true;
description
"Defines the default schema-set used by this server.
This is the schema-set that is chosen if a NETCONF client
doesn't select a schema during 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 be 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 '@'?)";
}
leaf description {
type string;
Wilton, et al. Expires September 1, 2020 [Page 17]
Internet-Draft YANG Schema Selection February 2020
description
"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 schema that are combined together into a single
selectable schema (i.e. via a union operation on each
datastore schema package).";
}
}
list schema-set {
key "name";
config false;
description
"Lists all available schema-set's that can be used in schema
selection.";
leaf name {
type string;
description
"Name of the schema.
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 schema of the device.";
}
list datastore {
key "name";