draft-ietf-core-sid-05.txt   draft-ietf-core-sid-06.txt 
Internet Engineering Task Force M. Veillette, Ed. Internet Engineering Task Force M. Veillette, Ed.
Internet-Draft Trilliant Networks Inc. Internet-Draft Trilliant Networks Inc.
Intended status: Standards Track A. Pelov, Ed. Intended status: Standards Track A. Pelov, Ed.
Expires: June 22, 2019 I. Petrov, Ed. Expires: September 29, 2019 I. Petrov, Ed.
Acklio Acklio
December 19, 2018 March 28, 2019
YANG Schema Item iDentifier (SID) YANG Schema Item iDentifier (SID)
draft-ietf-core-sid-05 draft-ietf-core-sid-06
Abstract Abstract
YANG Schema Item iDentifiers (SID) are globally unique 64-bit YANG Schema Item iDentifiers (SID) are globally unique 64-bit
unsigned numbers used to identify YANG items. This document defines unsigned numbers used to identify YANG items. This document defines
the semantics, the registration, and assignment processes of SIDs. the semantics, the registration, and assignment processes of SIDs.
To enable the implementation of these processes, this document also To enable the implementation of these processes, this document also
defines a file format used to persist and publish assigned SIDs. defines a file format used to persist and publish assigned SIDs.
Status of This Memo Status of This Memo
skipping to change at page 1, line 36 skipping to change at page 1, line 36
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at https://datatracker.ietf.org/drafts/current/. Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on June 22, 2019. This Internet-Draft will expire on September 29, 2019.
Copyright Notice Copyright Notice
Copyright (c) 2018 IETF Trust and the persons identified as the Copyright (c) 2019 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(https://trustee.ietf.org/license-info) in effect on the date of (https://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License. described in the Simplified BSD License.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
2. Terminology and Notation . . . . . . . . . . . . . . . . . . 3 2. Terminology and Notation . . . . . . . . . . . . . . . . . . 3
3. ".sid" file lifecycle . . . . . . . . . . . . . . . . . . . . 4 3. ".sid" file lifecycle . . . . . . . . . . . . . . . . . . . . 4
4. ".sid" file format . . . . . . . . . . . . . . . . . . . . . 7 4. ".sid" file format . . . . . . . . . . . . . . . . . . . . . 5
5. Third party registries . . . . . . . . . . . . . . . . . . . 11 5. Security Considerations . . . . . . . . . . . . . . . . . . . 9
6. Security Considerations . . . . . . . . . . . . . . . . . . . 11 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9
7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 11 6.1. Register SID File Format Module . . . . . . . . . . . . . 9
7.1. Module registration . . . . . . . . . . . . . . . . . . . 12 6.2. Create new IANA Registry: "SID Mega-Range" registry . . . 9
7.2. "SID mega-range" registry . . . . . . . . . . . . . . . . 12 6.2.1. Structure . . . . . . . . . . . . . . . . . . . . . . 10
7.2.1. "IANA SID Mega-Range" allocation . . . . . . . . . . 13 6.2.2. Allocation policy . . . . . . . . . . . . . . . . . . 10
7.2.2. "RFC SID range assignment" sub-registry . . . . . . . 14 6.2.2.1. First allocation . . . . . . . . . . . . . . . . 11
7.2.3. "Specification SID range assignment" sub-registry . . 14 6.2.2.2. Consecutive allocations . . . . . . . . . . . . . 11
7.3. "YANG module assignment" registry . . . . . . . . . . . . 15 6.2.3. Initial contents of the Registry . . . . . . . . . . 11
8. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 15 6.3. Create a new IANA Registry: IETF SID Range Registry
9. References . . . . . . . . . . . . . . . . . . . . . . . . . 16 (managed by IANA) . . . . . . . . . . . . . . . . . . . . 11
9.1. Normative References . . . . . . . . . . . . . . . . . . 16 6.3.1. Structure . . . . . . . . . . . . . . . . . . . . . . 11
9.2. Informative References . . . . . . . . . . . . . . . . . 16 6.3.2. Allocation policy . . . . . . . . . . . . . . . . . . 12
Appendix A. ".sid" file example . . . . . . . . . . . . . . . . 17 6.3.3. Initial contents of the registry . . . . . . . . . . 13
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 26 6.4. Create new IANA Registry: "IETF SID Registry" . . . . . . 13
6.4.1. Structure . . . . . . . . . . . . . . . . . . . . . . 13
6.4.2. Allocation policy . . . . . . . . . . . . . . . . . . 14
6.4.3. Initial contents of the registry . . . . . . . . . . 14
7. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 14
8. References . . . . . . . . . . . . . . . . . . . . . . . . . 15
8.1. Normative References . . . . . . . . . . . . . . . . . . 15
8.2. Informative References . . . . . . . . . . . . . . . . . 15
Appendix A. ".sid" file example . . . . . . . . . . . . . . . . 16
Appendix B. SID auto generation . . . . . . . . . . . . . . . . 25
Appendix C. ".sid" file lifecycle . . . . . . . . . . . . . . . 26
C.1. SID File Creation . . . . . . . . . . . . . . . . . . . . 26
C.2. SID File Update . . . . . . . . . . . . . . . . . . . . . 27
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 28
1. Introduction 1. Introduction
Some of the items defined in YANG [RFC7950] require the use of a Some of the items defined in YANG [RFC7950] require the use of a
unique identifier. In both NETCONF [RFC6241] and RESTCONF [RFC8040], unique identifier. In both NETCONF [RFC6241] and RESTCONF [RFC8040],
these identifiers are implemented using names. To allow the these identifiers are implemented using names. To allow the
implementation of data models defined in YANG in constrained devices implementation of data models defined in YANG in constrained devices
and constrained networks, a more compact method to identify YANG and constrained networks, a more compact method to identify YANG
items is required. This compact identifier, called SID, is encoded items is required. This compact identifier, called SID, is encoded
using a 64-bit unsigned integer. The following items are identified using a 64-bit unsigned integer. The following items are identified
skipping to change at page 3, line 4 skipping to change at page 3, line 17
o data nodes (Note: including those part of a YANG template as o data nodes (Note: including those part of a YANG template as
defined by the 'yang-data' extension.) defined by the 'yang-data' extension.)
o RPCs and associated input(s) and output(s) o RPCs and associated input(s) and output(s)
o actions and associated input(s) and output(s) o actions and associated input(s) and output(s)
o notifications and associated information o notifications and associated information
o YANG modules, submodules and features o YANG modules, submodules and features
To minimize their size, SIDs are often represented as a difference
between the current SID and a reference SID. Such difference is To minimize their size, in certain positions, SIDs could be
called "delta", shorthand for "delta-encoded SID". Conversion from represented using a (signed) delta from a reference SID and the
SIDs to deltas and back to SIDs is a stateless process. Each current SID (for example during transmissions). Such difference is
itself called "delta", shorthand for "delta-encoded SID". Conversion
from SIDs to deltas and back to SIDs is a stateless process. Each
protocol implementing deltas must unambiguously define the reference protocol implementing deltas must unambiguously define the reference
SID for each YANG item. SID for each YANG item.
SIDs are globally unique numbers, a registration system is used in SIDs are globally unique numbers, a registration system is used in
order to guarantee their uniqueness. SIDs are registered in blocks order to guarantee their uniqueness. SIDs are registered in blocks
called "SID ranges". called "SID ranges".
Assignment of SIDs to YANG items can be automated, the recommended Assignment of SIDs to YANG items can be automated. For more details
process to assign SIDs is as follows: how this could be achieved, please consult Appendix B.
1. A tool extracts the different items defined for a specific YANG
module.
2. The list of items is sorted in alphabetical order, 'namespace' in
descending order, 'identifier' in ascending order. The
'namespace' and 'identifier' formats are described in the YANG
module 'ietf-sid-file' defined in Section 4.
3. SIDs are assigned sequentially from the entry point up to the
size of the registered SID range. This approach is recommended
to minimize the serialization overhead, especially when delta
encoding is implemented.
4. If the number of items exceeds the SID range(s) allocated to a
YANG module, an extra range is added for subsequent assignments.
SIDs are assigned permanently, items introduced by a new revision of SIDs are assigned permanently, items introduced by a new revision of
a YANG module are added to the list of SIDs already assigned. This a YANG module are added to the list of SIDs already assigned.
process can also be automated using the same method described above,
only unassigned YANG items are processed at step #3.
Section 3 provides more details about the registration process of Section 3 provides more details about the registration process of
YANG modules and associated SIDs. To enable the implementation of YANG modules and associated SIDs. To enable the implementation of
this registry, Section 4 defines a standard file format used to store this registry, Section 4 defines a standard file format used to store
and publish SIDs. and publish SIDs.
2. Terminology and Notation 2. Terminology and Notation
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
skipping to change at page 5, line 12 skipping to change at page 5, line 7
data, including configuration, state data, RPCs, actions and data, including configuration, state data, RPCs, actions and
notifications. notifications.
YANG modules are not necessarily created in the context of YANG modules are not necessarily created in the context of
constrained applications. YANG modules can be implemented using constrained applications. YANG modules can be implemented using
NETCONF [RFC6241] or RESTCONF [RFC8040] without the need to assign NETCONF [RFC6241] or RESTCONF [RFC8040] without the need to assign
SIDs. SIDs.
As needed, authors of YANG modules can assign SIDs to their YANG As needed, authors of YANG modules can assign SIDs to their YANG
modules. In order to do that, they should first obtain a SID range modules. In order to do that, they should first obtain a SID range
from a registry. It could be "RFC SID range assignment" sub-registry from a registry and use that range to assign or generate SIDs to
as defined in Section Section 7.2.2, the "Specification SID range items of their YANG module. For example how this could be achieved,
assignment" sub-registry as defined in Section Section 7.2.3 or please refer to Appendix C.
another one, depending on the particular case. The minimal
information required for this would be a start SID number and a range
size, but might include additional details depending on the registry
policy, which is outside the scope of this document. Once a SID
range is registered, the owner can use it to generate ".sid" file/s
for his YANG module/s. It is recommended to leave some unallocated
SIDs following the allocated range in each ".sid" file in order to
allow better evolution of the YANG module in the future. Generation
of ".sid" files SHOULD be performed using an automated tool. Note
that ".sid" files can only be generated for YANG modules and not for
submodules.
Registration of the .sid file associated to a YANG module is optional Registration of the .sid file associated to a YANG module is optional
but recommended to promote interoperability between devices and to but recommended to promote interoperability between devices and to
avoid duplicate allocation of SIDs to a single YANG module. avoid duplicate allocation of SIDs to a single YANG module.
Different registries might have different requirement for the Different registries might have different requirements for the
registration and publication of the ".sid" files. registration and publication of the ".sid" files. For diagram of one
of the possibilities, please refer to the activity diagram on
The following activity diagram summarizes the creation of a YANG Figure 1 in Appendix C.
module and its associated .sid file.
+---------------+
O | Creation of a |
-|- ->| YANG module |
/ \ +---------------+
|
V
/-------------\
/ Standardized \ yes
\ YANG module ? /-------------+
\-------------/ |
| no |
V V
/-------------\ +---------------+
/ Constrained \ yes | SID range |
+-->\ application ? /---->| registration |<----------+
| \-------------/ +---------------+ |
| | no | |
| V V |
| +---------------+ +---------------+ |
+---| YANG module | | SID sub-range | |
| update | | assignment |<----------+
+---------------+ +---------------+ |
| |
V |
+---------------+ +-------------+
| .sid file | | Rework YANG |
| generation | | model |
+---------------+ +-------------+
| ^
V |
/----------\ yes |
/ Work in \ -----------+
\ progress /
\----------/
| no
V
/-------------\ /-------------\
/ RFC \ no / Open \ no
\ publication? /---->\ specification?/---+
\-------------/ \-------------/ |
| yes | yes |
| +---------------+ |
V V V
+---------------+ +---------------+
| IANA | | Third party |
| registration | | registration |
+-------+-------+ +-------+-------+
| |
+---------------------------------+
V
[DONE]
Each time a YANG module or one of its imported module(s) or included Each time a YANG module or one of its imported module(s) or included
sub-module(s) is updated, the ".sid" file MAY need to be updated. sub-module(s) is updated, the ".sid" file MAY need to be updated.
This update SHOULD also be performed using an automated tool. This update SHOULD also be performed using an automated tool.
If a new revision requires more SIDs than initially allocated, a new If a new revision requires more SIDs than initially allocated, a new
SID range MUST be added to the 'assignment-ranges' as defined in SID range MUST be added to the 'assignment-ranges' as defined in
Section 4. These extra SIDs are used for subsequent assignments. Section 4. These extra SIDs are used for subsequent assignments.
The following activity diagram summarizes the update of a YANG module For an example of this update process, see activity diagram Figure 2
and its associated .sid file. in Appendix C.
+---------------+
O | Update of the |
-|- ->| YANG module |
/ \ | or include(s) |
| or import(s) |
+---------------+
|
V
/-------------\
/ New items \ yes
\ created ? /------+
\-------------/ |
| no V
| /-------------\ +----------------+
| / SID range \ yes | Extra sub-range|
| \ exhausted ? /---->| assignment |
| \-------------/ +----------------+
| | no |
| +---------------------+
| |
| V
| +---------------+
| | .sid file |
| | update based |
| | on previous |
| | .sid file |
| +---------------+
| |
| V
| /-------------\ +---------------+
| / Publicly \ yes | YANG module |
| \ available ? /---->| registration |
| \-------------/ +---------------+
| | no |
+--------------+---------------------+
|
[DONE]
4. ".sid" file format 4. ".sid" file format
".sid" files are used to persist and publish SIDs assigned to the ".sid" files are used to persist and publish SIDs assigned to the
different YANG items of a specific YANG module. The following YANG different YANG items of a specific YANG module. The following YANG
module defined the structure of this file, encoding is performed module defined the structure of this file, encoding is performed
using the rules defined in [RFC7951]. using the rules defined in [RFC7951].
<CODE BEGINS> file "ietf-sid-file@2017-11-26.yang" <CODE BEGINS> file "ietf-sid-file@2017-11-26.yang"
module ietf-sid-file { module ietf-sid-file {
namespace "urn:ietf:params:xml:ns:yang:ietf-sid-file"; namespace "urn:ietf:params:xml:ns:yang:ietf-sid-file";
prefix sid; prefix sid;
import ietf-yang-types { import ietf-yang-types {
prefix yang; prefix yang;
} }
import ietf-comi {
prefix comi;
}
organization organization
"IETF Core Working Group"; "IETF Core Working Group";
contact contact
"Michel Veillette "Michel Veillette
<mailto:michel.veillette@trilliant.com> <mailto:michel.veillette@trilliant.com>
Andy Bierman Andy Bierman
<mailto:andy@yumaworks.com> <mailto:andy@yumaworks.com>
Alexander Pelov Alexander Pelov
<mailto:a@ackl.io>"; <mailto:a@ackl.io>";
description description
"This module defines the structure of the .sid files. "This module defines the structure of the .sid files.
Each .sid file contains the mapping between the different Each .sid file contains the mapping between the different
skipping to change at page 8, line 50 skipping to change at page 6, line 32
} }
typedef revision-identifier { typedef revision-identifier {
type string { type string {
pattern '\d{4}-\d{2}-\d{2}'; pattern '\d{4}-\d{2}-\d{2}';
} }
description description
"Represents a date in YYYY-MM-DD format."; "Represents a date in YYYY-MM-DD format.";
} }
typedef sid {
type uint64;
description
"YANG Schema Item iDentifier";
reference
"[I-D.ietf-core-sid] YANG Schema Item iDentifier (SID)";
}
typedef schema-node-path { typedef schema-node-path {
type string { type string {
pattern pattern
'/[a-zA-Z_][a-zA-Z0-9\-_.]*:[a-zA-Z_][a-zA-Z0-9\-_.]*' + '/[a-zA-Z_][a-zA-Z0-9\-_.]*:[a-zA-Z_][a-zA-Z0-9\-_.]*' +
'(/[a-zA-Z_][a-zA-Z0-9\-_.]*(:[a-zA-Z_][a-zA-Z0-9\-_.]*)?)*'; '(/[a-zA-Z_][a-zA-Z0-9\-_.]*(:[a-zA-Z_][a-zA-Z0-9\-_.]*)?)*';
} }
description description
"Identifies a schema-node path string for use in the "Identifies a schema-node path string for use in the
SID registry. This string format follows the rules SID registry. This string format follows the rules
for an instance-identifier, as defined in RFC 7959, for an instance-identifier, as defined in RFC 7959,
skipping to change at page 9, line 45 skipping to change at page 7, line 36
defined in the YANG module."; defined in the YANG module.";
} }
list assigment-ranges { list assigment-ranges {
key "entry-point"; key "entry-point";
description description
"SID range(s) allocated to the YANG module identified by "SID range(s) allocated to the YANG module identified by
'module-name' and 'module-revision'."; 'module-name' and 'module-revision'.";
leaf entry-point { leaf entry-point {
type comi:sid; type sid;
mandatory true; mandatory true;
description description
"Lowest SID available for assignment."; "Lowest SID available for assignment.";
} }
leaf size { leaf size {
type uint64; type uint64;
mandatory true; mandatory true;
description description
"Number of SIDs available for assignment."; "Number of SIDs available for assignment.";
skipping to change at page 11, line 22 skipping to change at page 9, line 12
If the corresponding 'namespace' field is 'module', If the corresponding 'namespace' field is 'module',
'feature', or 'identity', then this field MUST 'feature', or 'identity', then this field MUST
contain a valid YANG identifier string. contain a valid YANG identifier string.
If the corresponding 'namespace' field is 'data', If the corresponding 'namespace' field is 'data',
then this field MUST contain a valid schema node then this field MUST contain a valid schema node
path."; path.";
} }
leaf sid { leaf sid {
type comi:sid; type sid;
mandatory true; mandatory true;
description description
"SID assigned to the YANG item for this mapping entry."; "SID assigned to the YANG item for this mapping entry.";
} }
} }
} }
<CODE ENDS> <CODE ENDS>
5. Third party registries 5. Security Considerations
The organization and functioning of third party registries is outside
the scope of the current document. The only limitations connected to
those registries are listed in Section 7.2.
6. Security Considerations
The security considerations of [RFC7049] and [RFC7950] apply. The security considerations of [RFC7049] and [RFC7950] apply.
This document defines a new type of identifier used to encode data This document defines a new type of identifier used to encode data
models defined in YANG [RFC7950]. As such, this identifier does not models defined in YANG [RFC7950]. As such, this identifier does not
contribute to any new security issues in addition of those identified contribute to any new security issues in addition of those identified
for the specific protocols or contexts for which it is used. for the specific protocols or contexts for which it is used.
7. IANA Considerations 6. IANA Considerations
In this section are given specifications for an entry into the module
registry and two new registries, a SID-range registry and a SID
module registry.
7.1. Module registration 6.1. Register SID File Format Module
This document registers one YANG modules in the "YANG Module Names" This document registers one YANG modules in the "YANG Module Names"
registry [RFC6020]: registry [RFC6020]:
o name: ietf-sid-file o name: ietf-sid-file
o namespace: urn:ietf:params:xml:ns:yang:ietf-sid-file o namespace: urn:ietf:params:xml:ns:yang:ietf-sid-file
o prefix: sid o prefix: sid
o reference: [[THISRFC]] o reference: [[THISRFC]]
7.2. "SID mega-range" registry 6.2. Create new IANA Registry: "SID Mega-Range" registry
The name of this registry is "SID mega-range". This registry is used The name of this registry is "SID Mega-Range". This registry is used
to record the delegation of the management of a block of SIDs to to record the delegation of the management of a block of SIDs to
third parties (e.g. SDO, registrar). third parties (e.g. SDOs, registrars, etc).
6.2.1. Structure
Each entry in this registry must include: Each entry in this registry must include:
o The entry point (first entry) of the registered SID range. o The entry point (first SID) of the registered SID block.
o The size of the registered SID range. o The size of the registered SID block. The size MUST be one
million (1 000 000) SIDs.
o The contact information of the requesting organization including: o The contact information of the requesting organization including:
o Organization name * The policy of SID range allocations: Public, Private or Both.
o Primary contact name, email address, and phone number * Organization name
o Secondary contact name, email address, and phone number * URL
The initial entry in this registry is allocated to IANA: The information associated to the Organization name should not be
publicly visible in the registry, but should be available. This
information includes contact email and phone number and change
controller email and phone number.
+-------------+---------+-------------------+ 6.2.2. Allocation policy
| Entry Point | Size | Organization name |
+-------------+---------+-------------------+
| 0 | 1000000 | IANA |
+-------------+---------+-------------------+
The IANA policies for future additions to this registry are The IANA policies for future additions to this registry are "Expert
"Hierarchical Allocation, Expert Review" [RFC5226]. Prior to a first Review" [RFC8126].
allocation, the requesting organization must demonstrate a functional
registry infrastructure. On subsequent allocation request(s), the
organization must demonstrate the exhaustion of the prior range.
These conditions need to be asserted by the assigned expert(s).
7.2.1. "IANA SID Mega-Range" allocation An organization requesting to manage a SID Range (and thus have an
entry in the SID Mega-Range Registry), must ensure the following
capacities:
The first million SIDs assigned to IANA is sub-divided as follow: o The capacity to manage and operate a SID Range Registry. A SID
Range Registry MUST provide the following information for all SID
Ranges allocated by the Registry:
o The range of 0 to 999 is reserved for future extensions. The IANA * Entry Point of allocated SID Range
policy for this range is "IETF review" [RFC5226]. This range is
reserved for a future uses and no sub-registries are currently
defined for it.
o The range of 1000 to 59,999 is reserved for YANG modules defined * Size of allocated SID Range
in RFCs. The IANA policy for future additions to this sub-
registry is "RFC required" [RFC5226]. Allocation within this
range requires publishing of the associated ".yang" and ".sid"
files in the YANG module registry. The allocation within this
range is done during IESG review.
o The range of 60,000 to 99,999 is reserved for experimental YANG * Type: Public or Private
modules. This range MUST NOT be used in operational deployments
since these SIDs are not globally unique which limit their
interoperability. The IANA policy for this range is "Experimental
use" [RFC5226].
o The range of 100,000 to 999,999 is reserved for standardized YANG + Public Ranges MUST include at least a reference to the YANG
modules. The IANA policy for future additions to this sub- module and ".sid" files for that SID Range.
registry is "Specification Required" [RFC5226]. Allocation within
this range requires publishing of the associated ".yang" and
".sid" files in the YANG module registry.
+-------------+---------+------------------------+ + Private Ranges MUST be marked as "Private"
| Entry Point | Size | IANA policy |
+-------------+---------+------------------------+
| 0 | 1,000 | IETF review |
| 1,000 | 59,000 | RFC required |
| 60,000 | 40,000 | Experimental use |
| 100,000 | 900,000 | Specification Required |
+-------------+---------+------------------------+
The size of a SID range assigned to a YANG module should be at least o A Policy of allocation, which clearly identifies if the SID Range
33% above the current number of YANG items. This headroom allows allocations would be Private, Public or Both.
assignment within the same range of new YANG items introduced by
subsequent revisions. A larger SID range size may be requested by
the authors if this recommendation is considered insufficient. It is
important to note that an extra SID range can be allocated to an
existing YANG module if the initial range is exhausted.
7.2.2. "RFC SID range assignment" sub-registry o Technical capacity to ensure the sustained operation of the
registry for a period of at least 5 years. If Private
Registrations are allowed, the period must be of at least 10
years.
The name of this sub-registry is "RFC SID range assignment". This 6.2.2.1. First allocation
sub-registry of "IANA SID Mega-Range" allocation Section 7.2.1
corresponds to the SID entry point 1000, size 59000. Each entry in For a first allocation to be provided, the requesting organization
this sub-registry must include: must demonstrate a functional registry infrastructure.
6.2.2.2. Consecutive allocations
On subsequent allocation request(s), the organization must
demonstrate the exhaustion of the prior range. These conditions need
to be asserted by the assigned expert(s).
If that extra-allocation is done within 3 years from the last
allocation, the experts need to discuss this request on the CORE
working group mailing list and consensus needs to be obtained before
allocating new Mega-Range.
6.2.3. Initial contents of the Registry
The initial entry in this registry is allocated to IANA:
+-------------+---------+------------+-------------------+----------+
| Entry Point | Size | Allocation | Organization name | URL |
+-------------+---------+------------+-------------------+----------+
| 0 | 1000000 | Public | IANA | iana.org |
+-------------+---------+------------+-------------------+----------+
6.3. Create a new IANA Registry: IETF SID Range Registry (managed by
IANA)
6.3.1. Structure
Each entry in this registry must include:
o The SID range entry point. o The SID range entry point.
o The SID range size. o The SID range size.
o The YANG module name. o The YANG module name.
o The RFC number. o Document reference.
6.3.2. Allocation policy
The first million SIDs assigned to IANA is sub-divided as follows:
o The range of 0 to 999 (size 1000) is "Reserved" as defined in
[RFC8126].
o The range of 1000 to 59,999 (size 59,000) is reserved for YANG
modules defined in RFCs. The IANA policy for additions to this
registry is "Expert Review" [RFC8126].
* The Expert MUST verify that the YANG module for which this
allocation is made has an RFC (existing RFC) OR is on track to
become RFC (early allocation with a request from the WG
chairs).
o The SID range allocated for a YANG module can follow in one of the
four categories:
* SMALL (50 SIDs)
* MEDIUM (100 SIDs)
* LARGE (250 SIDs)
* CUSTOM (requested by the YANG module author, with a maximum of
1000 SIDs). In all cases, the size of a SID range assigned to
a YANG module should be at least 33% above the current number
of YANG items. This headroom allows assignment within the same
range of new YANG items introduced by subsequent revisions. A
larger SID range size may be requested by the authors if this
recommendation is considered insufficient. It is important to
note that an additional SID range can be allocated to an
existing YANG module if the initial range is exhausted.
o The range of 60,000 to 99,999 (size 40,000)is reserved for
experimental YANG modules. This range MUST NOT be used in
operational deployments since these SIDs are not globally unique
which limit their interoperability. The IANA policy for this
range is "Experimental use" [RFC8126].
o The range of 100,000 to 999,999 (size 900,000) is "Reserved" as
defined in [RFC8126].
+-------------+---------+------------------+
| Entry Point | Size | IANA policy |
+-------------+---------+------------------+
| 0 | 1,000 | Reserved |
| 1,000 | 59,000 | Expert Review |
| 60,000 | 40,000 | Experimental use |
| 100,000 | 900,000 | Reserved |
+-------------+---------+------------------+
6.3.3. Initial contents of the registry
Initial entries in this registry are as follows: Initial entries in this registry are as follows:
+-------------+------+------------------+----------------------+ +-------------+------+------------------+----------------------+
| Entry Point | Size | Module name | RFC number | | Entry Point | Size | Module name | Document reference |
+-------------+------+------------------+----------------------+ +-------------+------+------------------+----------------------+
| 1000 | 100 | ietf-comi | [I-D.ietf-core-comi] | | 1000 | 100 | ietf-comi | [I-D.ietf-core-comi] |
| 1100 | 50 | ietf-yang-types | [RFC6021] | | 1100 | 50 | ietf-yang-types | [RFC6021] |
| 1150 | 50 | ietf-inet-types | [RFC6021] | | 1150 | 50 | ietf-inet-types | [RFC6021] |
| 1200 | 50 | iana-crypt-hash | [RFC7317] | | 1200 | 50 | iana-crypt-hash | [RFC7317] |
| 1250 | 50 | ietf-netconf-acm | [RFC6536] | | 1250 | 50 | ietf-netconf-acm | [RFC6536] |
| 1300 | 50 | ietf-sid-file | RFCXXXX | | 1300 | 50 | ietf-sid-file | RFCXXXX |
| 1500 | 100 | ietf-interfaces | [RFC7223] | | 1500 | 100 | ietf-interfaces | [RFC7223] |
| 1600 | 100 | ietf-ip | [RFC7277] | | 1600 | 100 | ietf-ip | [RFC7277] |
| 1700 | 100 | ietf-system | [RFC7317] | | 1700 | 100 | ietf-system | [RFC7317] |
| 1800 | 400 | iana-if-type | [RFC7224] | | 1800 | 400 | iana-if-type | [RFC7224] |
+-------------+------+------------------+----------------------+ +-------------+------+------------------+----------------------+
// RFC Ed.: replace XXXX with RFC number assigned to this draft. // RFC Ed.: replace XXXX with RFC number assigned to this draft.
For allocation, RFC publication of the module is required as per For allocation, RFC publication of the YANG module is required as per
[RFC5226]. The YANG module must be registered in the "YANG module [RFC8126]. The YANG module must be registered in the "YANG module
Name" registry according to the rules specified in section 14 of Name" registry according to the rules specified in section 14 of
[RFC6020]. [RFC6020].
7.2.3. "Specification SID range assignment" sub-registry 6.4. Create new IANA Registry: "IETF SID Registry"
The name of this sub-registry is "Specification SID range The name of this registry is "IETF SID Registry". This registry is
assignment". This sub-registry of "IANA SID Mega-Range" allocation used to record the allocation of individual SIDs YANG module items.
Section 7.2.1 corresponds to the SID entry point 100000, size 900000.
Each entry in this sub-registry must include:
o The SID range entry point. 6.4.1. Structure
o The SID range size. Each entry in this registry must include:
o The YANG module name. o The YANG module name. This module name must be present in the
"Name" column of the "YANG Module Names" registry.
o The name of the standard organization o A link to the associated ".yang" file. This file link must be
present in the "File" column of the "YANG Module Names" registry.
o The specification identifier or URI o The link to the ".sid" file which defines the allocation.
7.3. "YANG module assignment" registry o The number of actually allocated SIDs in the ".sid" file.
The name of this registry is "YANG module assignment". This registry The ".sid" file is stored by IANA.
is used to track which YANG modules have been assigned and the
specific YANG items assignment. Each entry in this registry must
include:
o The YANG module name. 6.4.2. Allocation policy
o The associated ".yang" file(s) The allocation policy is Expert review. The Expert MUST ensure that
the following conditions are met:
o The associated ".sid" file o The ".sid" file has a valid structure:
The validity of the ".yang" and ".sid" files added to this registry * The ".sid" file MUST be a valid JSON file following the
MUST be verified. structure of the module defined in RFCXXXX (RFC Ed: replace XXX
with RFC number assigned to this draft).
o The syntax of the registered ".yang" and ".sid" files must be o The ".sid" file allocates individual SIDs ONLY in the SID Ranges
valid. for this YANG module (as allocated in the IETF SID Range
Registry):
o Each YANG item defined by the registered ".yang" file must have a * All SIDs in this ".sid" file MUST be within the ranges
corresponding SID assigned in the ".sid" file. allocated to this YANG module in the "IETF SID Range Registry".
o Each SID is assigned to a single YANG item, duplicate assignment o If another ".sid" file has already allocated SIDs for this YANG
is not allowed. module (e.g. for older or newer versions of the YANG module), the
YANG items are assigned the same SIDs as in the the other ".sid"
file.
o The SID range(s) defined in the ".sid" file must be unique, must o SIDs never change.
not conflict with any other SID ranges defined in already
registered ".sid" files.
o The ownership of the SID range(s) should be verified. 6.4.3. Initial contents of the registry
The IANA policy for future additions to this registry is "First Come None.
First Served" as described in [RFC5226].
8. Acknowledgments 7. Acknowledgments
The authors would like to thank Andy Bierman, Carsten Bormann, The authors would like to thank Andy Bierman, Carsten Bormann,
Abhinav Somaraju, Laurent Toutain, Randy Turner and Peter van der Abhinav Somaraju, Laurent Toutain, Randy Turner and Peter van der
Stok for their help during the development of this document and their Stok for their help during the development of this document and their
useful comments during the review process. useful comments during the review process.
9. References 8. References
9.1. Normative References 8.1. Normative References
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997, DOI 10.17487/RFC2119, March 1997,
<https://www.rfc-editor.org/info/rfc2119>. <https://www.rfc-editor.org/info/rfc2119>.
[RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object
Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049,
October 2013, <https://www.rfc-editor.org/info/rfc7049>. October 2013, <https://www.rfc-editor.org/info/rfc7049>.
[RFC7120] Cotton, M., "Early IANA Allocation of Standards Track Code
Points", BCP 100, RFC 7120, DOI 10.17487/RFC7120, January
2014, <https://www.rfc-editor.org/info/rfc7120>.
[RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language",
RFC 7950, DOI 10.17487/RFC7950, August 2016, RFC 7950, DOI 10.17487/RFC7950, August 2016,
<https://www.rfc-editor.org/info/rfc7950>. <https://www.rfc-editor.org/info/rfc7950>.
[RFC7951] Lhotka, L., "JSON Encoding of Data Modeled with YANG", [RFC7951] Lhotka, L., "JSON Encoding of Data Modeled with YANG",
RFC 7951, DOI 10.17487/RFC7951, August 2016, RFC 7951, DOI 10.17487/RFC7951, August 2016,
<https://www.rfc-editor.org/info/rfc7951>. <https://www.rfc-editor.org/info/rfc7951>.
9.2. Informative References 8.2. Informative References
[I-D.ietf-core-comi] [I-D.ietf-core-comi]
Veillette, M., Stok, P., Pelov, A., and A. Bierman, "CoAP Veillette, M., Stok, P., Pelov, A., and A. Bierman, "CoAP
Management Interface", draft-ietf-core-comi-04 (work in Management Interface", draft-ietf-core-comi-04 (work in
progress), November 2018. progress), November 2018.
[RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an
IANA Considerations Section in RFCs", RFC 5226,
DOI 10.17487/RFC5226, May 2008,
<https://www.rfc-editor.org/info/rfc5226>.
[RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for
the Network Configuration Protocol (NETCONF)", RFC 6020, the Network Configuration Protocol (NETCONF)", RFC 6020,
DOI 10.17487/RFC6020, October 2010, DOI 10.17487/RFC6020, October 2010,
<https://www.rfc-editor.org/info/rfc6020>. <https://www.rfc-editor.org/info/rfc6020>.
[RFC6021] Schoenwaelder, J., Ed., "Common YANG Data Types", [RFC6021] Schoenwaelder, J., Ed., "Common YANG Data Types",
RFC 6021, DOI 10.17487/RFC6021, October 2010, RFC 6021, DOI 10.17487/RFC6021, October 2010,
<https://www.rfc-editor.org/info/rfc6021>. <https://www.rfc-editor.org/info/rfc6021>.
[RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed.,
skipping to change at page 17, line 30 skipping to change at page 16, line 30
<https://www.rfc-editor.org/info/rfc7277>. <https://www.rfc-editor.org/info/rfc7277>.
[RFC7317] Bierman, A. and M. Bjorklund, "A YANG Data Model for [RFC7317] Bierman, A. and M. Bjorklund, "A YANG Data Model for
System Management", RFC 7317, DOI 10.17487/RFC7317, August System Management", RFC 7317, DOI 10.17487/RFC7317, August
2014, <https://www.rfc-editor.org/info/rfc7317>. 2014, <https://www.rfc-editor.org/info/rfc7317>.
[RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF
Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017,
<https://www.rfc-editor.org/info/rfc8040>. <https://www.rfc-editor.org/info/rfc8040>.
[RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for
Writing an IANA Considerations Section in RFCs", BCP 26,
RFC 8126, DOI 10.17487/RFC8126, June 2017,
<https://www.rfc-editor.org/info/rfc8126>.
Appendix A. ".sid" file example Appendix A. ".sid" file example
The following .sid file (ietf-system@2014-08-06.sid) have been The following .sid file (ietf-system@2014-08-06.sid) have been
generated using the following yang modules: generated using the following yang modules:
o ietf-system@2014-08-06.yang o ietf-system@2014-08-06.yang
o ietf-yang-types@2013-07-15.yang o ietf-yang-types@2013-07-15.yang
o ietf-inet-types@2013-07-15.yang o ietf-inet-types@2013-07-15.yang
skipping to change at page 26, line 19 skipping to change at page 25, line 24
}, },
{ {
"namespace": "data", "namespace": "data",
"identifier": "/ietf-system:system/radius/server/udp/ "identifier": "/ietf-system:system/radius/server/udp/
shared-secret", shared-secret",
"sid": 1774 "sid": 1774
} }
] ]
} }
Authors' Addresses Appendix B. SID auto generation
Assignment of SIDs to YANG items can be automated, the recommended
process to assign SIDs is as follows:
1. A tool extracts the different items defined for a specific YANG
module.
2. The list of items is sorted in alphabetical order, 'namespace' in
descending order, 'identifier' in ascending order. The
'namespace' and 'identifier' formats are described in the YANG
module 'ietf-sid-file' defined in Section 4.
3. SIDs are assigned sequentially from the entry point up to the
size of the registered SID range. This approach is recommended
to minimize the serialization overhead, especially when delta
encoding is implemented.
4. If the number of items exceeds the SID range(s) allocated to a
YANG module, an extra range is added for subsequent assignments.
Changes of SID files can also be automated using the same method
described above, only unassigned YANG items are processed at step #3.
Appendix C. ".sid" file lifecycle
Before assigning SIDs to their YANG modules, YANG module authors must
acquire a SID range from a "SID Range Registry". If the YANG module
is part of an IETF draft or RFC, the SID range need to be acquired
from the "IETF SID Range Registry" as defined in Section 6.3. For
the other YANG modules, the authors can acquire a SID range from any
"SID Range Registry" of their choice.
Once the SID range is acquired, the owner can use it to generate
".sid" file/s for his YANG module/s. It is recommended to leave some
unallocated SIDs following the allocated range in each ".sid" file in
order to allow better evolution of the YANG module in the future.
Generation of ".sid" files should be performed using an automated
tool. Note that ".sid" files can only be generated for YANG modules
and not for submodules.
C.1. SID File Creation
The following activity diagram summarizes the creation of a YANG
module and its associated .sid file.
+---------------+
O | Creation of a |
-|- ->| YANG module |
/ \ +---------------+
|
V
/-------------\
/ Standardized \ yes
\ YANG module ? /-------------+
\-------------/ |
| no |
V V
/-------------\ +---------------+
/ Constrained \ yes | SID range |
+-->\ application ? /---->| registration |<----------+
| \-------------/ +---------------+ |
| | no | |
| V V |
| +---------------+ +---------------+ |
+---| YANG module | | SID sub-range | |
| update | | assignment |<----------+
+---------------+ +---------------+ |
| |
V |
+---------------+ +-------------+
| .sid file | | Rework YANG |
| generation | | model |
+---------------+ +-------------+
| ^
V |
/----------\ yes |
/ Work in \ -----------+
\ progress /
\----------/
| no
V
/-------------\ /-------------\
/ RFC \ no / Open \ no
\ publication? /---->\ specification?/---+
\-------------/ \-------------/ |
| yes | yes |
| +---------------+ |
V V V
+---------------+ +---------------+
| IANA | | Third party |
| registration | | registration |
+-------+-------+ +-------+-------+
| |
+---------------------------------+
V
[DONE]
Figure 1: SID Lifecycle
C.2. SID File Update
The following Activity diagram summarizes the update of a YANG module
and its associated .sid file.
+---------------+
O | Update of the |
-|- ->| YANG module |
/ \ | or include(s) |
| or import(s) |
+---------------+
|
V
/-------------\
/ New items \ yes
\ created ? /------+
\-------------/ |
| no V
| /-------------\ +----------------+
| / SID range \ yes | Extra sub-range|
| \ exhausted ? /---->| assignment |
| \-------------/ +----------------+
| | no |
| +---------------------+
| |
| V
| +---------------+
| | .sid file |
| | update based |
| | on previous |
| | .sid file |
| +---------------+
| |
| V
| /-------------\ +---------------+
| / Publicly \ yes | YANG module |
| \ available ? /---->| registration |
| \-------------/ +---------------+
| | no |
+--------------+---------------------+
|
[DONE]
Figure 2: YANG and SID file update
Authors' Addresses
Michel Veillette (editor) Michel Veillette (editor)
Trilliant Networks Inc. Trilliant Networks Inc.
610 Rue du Luxembourg 610 Rue du Luxembourg
Granby, Quebec J2J 2V2 Granby, Quebec J2J 2V2
Canada Canada
Phone: +14503750556 Phone: +14503750556
Email: michel.veillette@trilliant.com Email: michel.veillette@trilliant.com
Alexander Pelov (editor) Alexander Pelov (editor)
 End of changes. 72 change blocks. 
285 lines changed or deleted 381 lines changed or added

This html diff was produced by rfcdiff 1.47. The latest version is available from http://tools.ietf.org/tools/rfcdiff/