rfc9595v3.txt | rfc9595.txt | |||
---|---|---|---|---|
skipping to change at line 14 ¶ | skipping to change at line 14 ¶ | |||
Category: Standards Track A. Pelov, Ed. | Category: Standards Track A. Pelov, Ed. | |||
ISSN: 2070-1721 IMT Atlantique | ISSN: 2070-1721 IMT Atlantique | |||
I. Petrov, Ed. | I. Petrov, Ed. | |||
Google Switzerland GmbH | Google Switzerland GmbH | |||
C. Bormann | C. Bormann | |||
Universität Bremen TZI | Universität Bremen TZI | |||
M. Richardson | M. Richardson | |||
Sandelman Software Works | Sandelman Software Works | |||
June 2024 | June 2024 | |||
YANG Schema Item iDentifier (YANG SID) | YANG Data Model for YANG Schema Item iDentifiers (YANG-SIDs) | |||
Abstract | Abstract | |||
YANG Schema Item iDentifiers (YANG SIDs) are globally unique 63-bit | YANG Schema Item iDentifiers (YANG-SIDs) are globally unique 63-bit | |||
unsigned integers used to identify YANG items, as a more compact | unsigned integers used to identify YANG items. SIDs provide a more | |||
method to identify YANG items that can be used for efficiency and in | compact method for identifying those YANG items that can be used | |||
constrained environments (RFC 7228). This document defines the | efficiently, particularly in constrained environments (RFC 7228). | |||
semantics, registration processes, and assignment processes for YANG | This document defines the semantics, registration processes, and | |||
SIDs for IETF-managed YANG modules. To enable the implementation of | assignment processes for YANG-SIDs for IETF-managed YANG modules. To | |||
these processes, this document also defines a file format used to | enable the implementation of these processes, this document also | |||
persist and publish assigned YANG SIDs. | defines a file format used to persist and publish assigned YANG-SIDs. | |||
Status of This Memo | Status of This Memo | |||
This is an Internet Standards Track document. | This is an Internet Standards Track document. | |||
This document is a product of the Internet Engineering Task Force | This document is a product of the Internet Engineering Task Force | |||
(IETF). It represents the consensus of the IETF community. It has | (IETF). It represents the consensus of the IETF community. It has | |||
received public review and has been approved for publication by the | received public review and has been approved for publication by the | |||
Internet Engineering Steering Group (IESG). Further information on | Internet Engineering Steering Group (IESG). Further information on | |||
Internet Standards is available in Section 2 of RFC 7841. | Internet Standards is available in Section 2 of RFC 7841. | |||
skipping to change at line 67 ¶ | skipping to change at line 67 ¶ | |||
1. Introduction | 1. Introduction | |||
1.1. Terminology and Notation | 1.1. Terminology and Notation | |||
2. Objectives | 2. Objectives | |||
2.1. Technical Objectives | 2.1. Technical Objectives | |||
2.2. Module Evolution and Versioning | 2.2. Module Evolution and Versioning | |||
2.3. Solution Components and Derived Objectives | 2.3. Solution Components and Derived Objectives | |||
2.4. Parties and Roles | 2.4. Parties and Roles | |||
3. ".sid" File Lifecycle | 3. ".sid" File Lifecycle | |||
4. ".sid" File Format | 4. ".sid" File Format | |||
5. Security Considerations | 5. ".sid" File YANG Module | |||
6. IANA Considerations | 6. Security Considerations | |||
6.1. YANG Namespace Registration | 7. IANA Considerations | |||
6.2. ".sid" File Format Module Registration | 7.1. YANG Namespace Registration | |||
6.3. New IANA Registry: YANG SID Mega-Range | 7.2. ".sid" File Format Module Registration | |||
6.3.1. Structure | 7.3. New IANA Registry: YANG-SID Mega-Ranges | |||
6.3.2. Allocation Policy | 7.3.1. Structure | |||
6.3.2.1. First Allocation | 7.3.2. Allocation Policy | |||
6.3.2.2. Consecutive Allocations | 7.3.2.1. First Allocation | |||
6.3.3. Initial Contents of the Registry | 7.3.2.2. Consecutive Allocations | |||
6.4. New IANA Registry: IETF YANG SID Range | 7.3.3. Initial Contents of the Registry | |||
6.4.1. Structure | 7.4. New IANA Registry: IETF YANG-SID Ranges | |||
6.4.2. Allocation Policy | 7.4.1. Structure | |||
6.4.3. Publication of the ".sid" File | 7.4.2. Allocation Policy | |||
6.4.4. Initial Contents of the Registry | 7.4.3. Publication of the ".sid" File | |||
6.5. New IANA Registry: IETF YANG SID | 7.4.4. Initial Contents of the Registry | |||
6.5.1. Structure | 7.5. New IANA Registry: IETF YANG-SID Modules | |||
6.5.2. Allocation Policy | 7.5.1. Structure | |||
6.5.3. Recursive Allocation of YANG SID Range at Document | 7.5.2. Allocation Policy | |||
7.5.3. Recursive Allocation of YANG-SID Range at Document | ||||
Adoption | Adoption | |||
6.5.4. Initial Contents of the Registry | 7.5.4. Initial Contents of the Registry | |||
6.6. Media Type and Content-Format Registration | 7.6. Media Type and Content-Format Registration | |||
6.6.1. Media Type application/yang-sid+json | 7.6.1. Media Type application/yang-sid+json | |||
6.6.2. CoAP Content-Format | 7.6.2. CoAP Content-Format | |||
7. References | 8. References | |||
7.1. Normative References | 8.1. Normative References | |||
7.2. Informative References | 8.2. Informative References | |||
Appendix A. ".sid" File Example | Appendix A. ".sid" File Example | |||
Appendix B. SID Autogeneration | Appendix B. SID Autogeneration | |||
Appendix C. ".sid" File Lifecycle | Appendix C. ".sid" File Lifecycle | |||
C.1. ".sid" File Creation | C.1. ".sid" File Creation | |||
C.2. ".sid" File Update | C.2. ".sid" File Update | |||
Appendix D. Keeping a SID File in a YANG Instance Data File | Appendix D. Keeping a ".sid" File in a YANG Instance Data File | |||
Acknowledgments | Acknowledgments | |||
Contributors | Contributors | |||
Authors' Addresses | Authors' Addresses | |||
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 the Network Configuration Protocol | unique identifier. In both the Network Configuration Protocol | |||
(NETCONF) [RFC6241] and RESTCONF [RFC8040], these identifiers are | (NETCONF) [RFC6241] and RESTCONF [RFC8040], these identifiers are | |||
implemented using names. To allow the implementation of data models | implemented using names. To allow the implementation of data models | |||
defined in YANG in constrained devices [RFC7228] and constrained | defined in YANG in constrained devices [RFC7228] and constrained | |||
networks, a more compact method to identify YANG items is required. | networks, a more compact method to identify YANG items is required. | |||
This compact identifier, called the YANG Schema Item iDentifier or | This compact identifier, called the YANG Schema Item iDentifier or | |||
YANG SID (or simply SID in this document and when the context is | YANG-SID (or simply SID in this document and when the context is | |||
clear), is encoded using a 63-bit unsigned integer. The limitation | clear), is encoded using a 63-bit unsigned integer. The limitation | |||
to 63-bit unsigned integers allows SIDs to be manipulated more easily | to 63-bit unsigned integers allows SIDs to be manipulated more easily | |||
on platforms that might otherwise lack 64-bit unsigned arithmetic. | on platforms that might otherwise lack 64-bit unsigned arithmetic. | |||
The loss of a single bit of range is not significant, given the size | The loss of a single bit of range is not significant, given the size | |||
of the remaining space. | of the remaining space. | |||
The following items are identified using SIDs: | The following items are identified using SIDs: | |||
* identities | * identities | |||
skipping to change at line 138 ¶ | skipping to change at line 139 ¶ | |||
* remote procedure calls (RPCs) and associated input(s) and | * remote procedure calls (RPCs) and associated input(s) and | |||
output(s) | output(s) | |||
* actions and associated input(s) and output(s) | * actions and associated input(s) and output(s) | |||
* notifications and associated information | * notifications and associated information | |||
* YANG modules and features | * YANG modules and features | |||
It is possible that some protocols will use only a subset of the | It is possible that some protocols will use only a subset of the | |||
assigned SIDs; for example, for protocols equivalent to NETCONF | assigned SIDs; for example, for protocols that provide extensions to | |||
[RFC6241] like [CORE-COMI], the transport of YANG module SIDs might | NETCONF [RFC6241], such as [CORE-COMI], the transport of YANG module | |||
be unnecessary. Other protocols might need to be able to transport | SIDs might be unnecessary. Other protocols might need to be able to | |||
this information -- for example, protocols related to discovery such | transport this information -- for example, protocols related to | |||
as the Constrained YANG Module Library [YANG-LIBRARY]. | discovery such as the Constrained YANG Module Library [YANG-LIBRARY]. | |||
SIDs are globally unique integers. A registration system is used in | SIDs are globally unique integers. 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". Once they are considered "stable", SIDs are | called "SID ranges". Once they are considered "stable", SIDs are | |||
assigned permanently. Items introduced by a new revision of a YANG | assigned permanently. Items introduced by a new revision of a YANG | |||
module are added to the list of SIDs already assigned. This is | module are added to the list of SIDs already assigned. This is | |||
discussed in more detail in Section 2. | discussed in more detail in Section 2. | |||
The assignment of SIDs to YANG items is usually automated as | The assignment of SIDs to YANG items is usually automated as | |||
discussed in Appendix B, which also discusses some cases where manual | discussed in Appendix B, which also discusses some cases where manual | |||
interventions may be appropriate. | interventions may be appropriate. | |||
Section 3 provides more details about the registration processes for | Section 3 provides more details about the registration processes for | |||
YANG modules and associated SIDs. To enable the implementation of | YANG modules and associated SIDs. To enable the implementation of | |||
these processes, Section 4 defines a standard file format used to | these processes, Section 4 defines a standard file format used to | |||
store and publish SIDs. | store and publish SIDs. | |||
IETF-managed YANG modules that need to allocate SIDs will use the | IETF-managed YANG modules that need to allocate SIDs will use the | |||
IANA mechanism specified in this document. YANG modules created by | IANA mechanisms (e.g., allocation mechanisms) specified in this | |||
other parties allocate SID ranges using the IANA allocation | document. See Section 7 for details. YANG modules created by other | |||
mechanisms via Mega-Ranges (see Section 6.3); within the Mega-Range | parties allocate SID ranges using the IANA allocation mechanisms via | |||
allocation, those other parties are free to make up their own | Mega-Ranges (see Section 7.3); within the Mega-Range allocation, | |||
mechanism. | those other parties are free to make up their own mechanism. | |||
Among other uses, YANG SIDs are particularly useful for obtaining a | Among other uses, YANG-SIDs are particularly useful for obtaining a | |||
compact encoding for YANG-CBOR [RFC9254]. At the time of writing, a | compact encoding for YANG-CBOR [RFC9254]. At the time of writing, a | |||
tool for automated ".sid" file generation is available as part of the | tool for automated ".sid" file generation is available as part of the | |||
open-source project PYANG [PYANG]. | open-source project PYANG [PYANG]. | |||
1.1. Terminology and Notation | 1.1. 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", "NOT RECOMMENDED", "MAY", and | "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and | |||
"OPTIONAL" in this document are to be interpreted as described in | "OPTIONAL" in this document are to be interpreted as described in | |||
BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all | BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all | |||
skipping to change at line 203 ¶ | skipping to change at line 204 ¶ | |||
* schema tree | * schema tree | |||
* submodule | * submodule | |||
This specification also makes use of the following terminology: | This specification also makes use of the following terminology: | |||
item: A schema node, an identity, a module, or a feature defined | item: A schema node, an identity, a module, or a feature defined | |||
using the YANG modeling language. | using the YANG modeling language. | |||
YANG Schema Item iDentifier (YANG SID or simply SID): Unsigned | YANG Schema Item iDentifier (YANG-SID or simply SID): Unsigned | |||
integer used to identify different YANG items (cf. Section 3.2 of | integer used to identify different YANG items (cf. Section 3.2 of | |||
[RFC9254]). | [RFC9254]). | |||
YANG name: Text string used to identify different YANG items | YANG name: Text string used to identify different YANG items | |||
(cf. Section 3.3 of [RFC9254]). | (cf. Section 3.3 of [RFC9254]). | |||
2. Objectives | 2. Objectives | |||
The overriding objective of the SID assignment and registration | The overriding objective of the SID assignment and registration | |||
system is to ensure global interoperability of protocols that employ | system is to ensure global interoperability of protocols that employ | |||
SIDs in order to communicate about data modeled in YANG. This | SIDs in order to communicate about data modeled in YANG [RFC7950]. | |||
objective poses certain requirements on the stability of SIDs while | This objective poses certain requirements on the stability of SIDs | |||
at the same time not hindering active evolution of the YANG modules | while at the same time not hindering active evolution of the YANG | |||
the SIDs are intended to support. | modules the SIDs are intended to support. | |||
Additional objectives include: | Additional objectives include: | |||
* enabling the developer of a YANG module to also be the originating | * enabling the developer of a YANG module to also be the originating | |||
entity for the SIDs pertaining to that module. | entity for the SIDs pertaining to that module. | |||
* making it easy for YANG developers to obtain SIDs. | * making it easy for YANG developers to obtain SIDs. | |||
* enabling other developers to define SIDs for a module where the | * enabling other developers to define SIDs for a module where the | |||
developer of the module is not interested in assigning the SIDs. | developer of the module is not interested in assigning the SIDs. | |||
skipping to change at line 275 ¶ | skipping to change at line 276 ¶ | |||
mapping is defined. | mapping is defined. | |||
This enables a recipient of a data structure employing SIDs to | This enables a recipient of a data structure employing SIDs to | |||
translate them into the globally meaningful YANG names that the | translate them into the globally meaningful YANG names that the | |||
existing encodings of YANG data such as YANG-XML [RFC7950] and YANG- | existing encodings of YANG data such as YANG-XML [RFC7950] and YANG- | |||
JSON [RFC7951] employ today. | JSON [RFC7951] employ today. | |||
The term "YANG name" is not defined outside this document, and YANG | The term "YANG name" is not defined outside this document, and YANG | |||
has a complex system of names and entities that can have those names. | has a complex system of names and entities that can have those names. | |||
Instead of defining the term technically, this set of objectives uses | Instead of defining the term technically, this set of objectives uses | |||
it in such a way that the overall objectives of YANG SID can be | it in such a way that the overall objectives of YANG-SID can be | |||
achieved. | achieved. | |||
A desirable objective is that: | A desirable objective is that: | |||
*Objective 2* (SHOULD): Any YANG name in active use has one SID | *Objective 2* (SHOULD): Any YANG name in active use has one SID | |||
assigned. | assigned. | |||
This means that: | This means that: | |||
1. There should not be YANG names without SIDs assigned. | 1. There should not be YANG names without SIDs assigned. | |||
skipping to change at line 356 ¶ | skipping to change at line 357 ¶ | |||
An entity that uses a module, after obtaining it from the module | An entity that uses a module, after obtaining it from the module | |||
controller or a module repository. | controller or a module repository. | |||
This set of parties needs to evolve to take on the additional roles | This set of parties needs to evolve to take on the additional roles | |||
that the SID assignment process requires: | that the SID assignment process requires: | |||
SID assigner: | SID assigner: | |||
An entity that assigns SIDs for a module. Objective 2 aims at | An entity that assigns SIDs for a module. Objective 2 aims at | |||
having only one SID assigner for each module. SID assigners | having only one SID assigner for each module. SID assigners | |||
preferably stay the same over a module development process; | preferably stay the same over a module development process; | |||
however, this specification provides SID files to ensure an | however, this specification provides ".sid" files to ensure an | |||
organized handover. | organized handover. | |||
SID range registry: | SID range registry: | |||
An entity that supplies a SID assigner with SID ranges that it can | An entity that supplies a SID assigner with SID ranges that it can | |||
use in assigning SIDs for a module. (In this specification, there | use in assigning SIDs for a module. (In this specification, there | |||
is a structure with mega-ranges and individual SID ranges; this is | is a structure with Mega-Ranges and individual SID ranges; this is | |||
not relevant here.) | not relevant here.) | |||
SID repository: | SID repository: | |||
An entity that supplies SID assignments to SID users, usually in | An entity that supplies SID assignments to SID users, usually in | |||
the form of a SID file. | the form of a ".sid" file. | |||
SID user: | SID user: | |||
The module user that uses the SIDs provided by a SID assigner for | The module user that uses the SIDs provided by a SID assigner for | |||
a YANG module. SID users need to find SID assigners (or at least | a YANG module. SID users need to find SID assigners (or at least | |||
their SID assignments). | their SID assignments). | |||
During the introduction of SIDs, the distribution of the SID roles to | As new SIDs are introduced, the distribution of the SID roles to the | |||
the existing parties for a YANG module will evolve. | existing parties for a YANG module will evolve. | |||
The desirable end state of this evolution is shown in Table 1. | The desirable end state of this evolution is shown in Table 1. | |||
+====================+======================================+ | +====================+======================================+ | |||
| Role | Party | | | Role | Party | | |||
+====================+======================================+ | +====================+======================================+ | |||
| SID assigner | module developer | | | SID assigner | module developer | | |||
+--------------------+--------------------------------------+ | +--------------------+--------------------------------------+ | |||
| SID range registry | (as discussed in this specification) | | | SID range registry | (as discussed in this specification) | | |||
+--------------------+--------------------------------------+ | +--------------------+--------------------------------------+ | |||
skipping to change at line 397 ¶ | skipping to change at line 398 ¶ | |||
+--------------------+--------------------------------------+ | +--------------------+--------------------------------------+ | |||
| SID user | module user (naturally) | | | SID user | module user (naturally) | | |||
+--------------------+--------------------------------------+ | +--------------------+--------------------------------------+ | |||
Table 1: Roles and Parties: Desired End State | Table 1: Roles and Parties: Desired End State | |||
This grouping of roles and parties puts the module developer in a | This grouping of roles and parties puts the module developer in a | |||
position where it can achieve the objectives laid out in this section | position where it can achieve the objectives laid out in this section | |||
(a "type-1", "SID-guiding" module controller). (While a third party | (a "type-1", "SID-guiding" module controller). (While a third party | |||
might theoretically assign additional SIDs and conflict with | might theoretically assign additional SIDs and conflict with | |||
Objective 2, there is very little reason to do so if SID files are | Objective 2, there is very little reason to do so if ".sid" files are | |||
always provided by the module developer with the module.) | always provided by the module developer with the module.) | |||
The rest of this section is concerned with the transition to this end | The rest of this section is concerned with the transition to this end | |||
state. | state. | |||
For existing modules, there is no SID file. The entity that stands | For existing modules, there is no ".sid" file. The entity that | |||
in as the SID assigner is not specified. This situation has the | stands in as the SID assigner is not specified. This situation has | |||
highest potential for conflict with Objective 2. | the highest potential for conflict with Objective 2. | |||
Similarly, for new module development, the module owner may not have | Similarly, for new module development, the module owner may not have | |||
heard about SIDs or may not be interested in assigning them (e.g., | heard about SIDs or may not be interested in assigning them (e.g., | |||
because of lack of software or procedures within their organization). | because of lack of software or procedures within their organization). | |||
For these two cases (which we will call "type-3", "SID-oblivious" | For these two cases (which we will call "type-3", "SID-oblivious" | |||
module controllers), module repositories can act as a mediator, | module controllers), module repositories can act as a mediator, | |||
giving SID users access to a SID assigner that is carefully chosen to | giving SID users access to a SID assigner that is carefully chosen to | |||
be a likely choice by other module repositories as well, maximizing | be a likely choice by other module repositories as well, maximizing | |||
the likelihood of achieving Objective 2. | the likelihood of achieving Objective 2. | |||
skipping to change at line 472 ¶ | skipping to change at line 473 ¶ | |||
Items introduced by a new revision of a YANG module are added to the | Items introduced by a new revision of a YANG module are added to the | |||
list of SIDs already assigned. When this is done during the | list of SIDs already assigned. When this is done during the | |||
development of a new protocol document, it may be necessary to make | development of a new protocol document, it may be necessary to make | |||
provisional assignments. They may get changed, revised, or withdrawn | provisional assignments. They may get changed, revised, or withdrawn | |||
during the development of a new standard. These provisional | during the development of a new standard. These provisional | |||
assignments are marked with a status of "unstable", so that they can | assignments are marked with a status of "unstable", so that they can | |||
be removed and the SID number possibly reassigned for a different | be removed and the SID number possibly reassigned for a different | |||
YANG schema name/path later in the development process. When the | YANG schema name/path later in the development process. When the | |||
specification is advanced to a final document, the assignment is | specification is advanced to a final document, the assignment is | |||
marked with a status of "stable". During a period of development | marked with a status of "stable". During a period of development | |||
starting from a published specification, two variants of the SID file | starting from a published specification, two variants of the ".sid" | |||
should be made available by the tooling involved in that development: | file should be made available by the tooling involved in that | |||
(1) a "published" SID file with the existing stable SID assignments | development: (1) a "published" ".sid" file with the existing stable | |||
only (which the development effort should keep stable), as well as | SID assignments only (which the development effort should keep | |||
(2) an "unpublished" SID file that also contains the unstable SID | stable), as well as (2) an "unpublished" ".sid" file that also | |||
assignments. | contains the unstable SID assignments. | |||
Registration of the ".sid" file associated with a YANG module is | Registration of the ".sid" file associated with a YANG module is | |||
optional but recommended, in order to promote interoperability | optional but recommended, in order to promote interoperability | |||
between devices and to avoid duplicate allocation of SIDs to a single | between devices and to avoid duplicate allocation of SIDs to a single | |||
YANG module. Different registries might have different requirements | YANG module. Different registries might have different requirements | |||
for the registration and publication of the ".sid" files. For a | for the registration and publication of the ".sid" files. For a | |||
diagram of one possible scenario, please refer to the activity | diagram of one possible scenario, please refer to the activity | |||
diagram shown in Figure 4 in Appendix C. | diagram shown in Figure 4 in Appendix C. | |||
Each time a YANG module, one or more of its imported modules, or one | Each time a YANG module, one or more of its imported modules, or one | |||
skipping to change at line 506 ¶ | skipping to change at line 507 ¶ | |||
Section 4. These extra SIDs are used for subsequent assignments. | Section 4. These extra SIDs are used for subsequent assignments. | |||
For an example of this update process, see the activity diagram shown | For an example of this update process, see the activity diagram shown | |||
in Figure 5 in Appendix C. | in Figure 5 in Appendix C. | |||
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 in a specific YANG module. | different YANG items in a specific YANG module. | |||
It has the following structure: | The following tree diagram [RFC8340] provides an overview of the data | |||
model: | ||||
module: ietf-sid-file | module: ietf-sid-file | |||
structure sid-file: | structure sid-file: | |||
+-- module-name yang:yang-identifier | +-- module-name yang:yang-identifier | |||
+-- module-revision? revision-identifier | +-- module-revision? revision-identifier | |||
+-- sid-file-version? sid-file-version-identifier | +-- sid-file-version? sid-file-version-identifier | |||
+-- sid-file-status? enumeration | +-- sid-file-status? enumeration | |||
+-- description? string | +-- description? string | |||
+-- dependency-revision* [module-name] | +-- dependency-revision* [module-name] | |||
| +-- module-name yang:yang-identifier | | +-- module-name yang:yang-identifier | |||
| +-- module-revision revision-identifier | | +-- module-revision revision-identifier | |||
+-- assignment-range* [entry-point] | +-- assignment-range* [entry-point] | |||
| +-- entry-point sid | | +-- entry-point sid | |||
| +-- size uint64 | | +-- size uint64 | |||
+-- item* [namespace identifier] | +-- item* [namespace identifier] | |||
+-- status? enumeration | +-- status? enumeration | |||
+-- namespace enumeration | +-- namespace enumeration | |||
+-- identifier union | +-- identifier union | |||
+-- sid sid | +-- sid sid | |||
Figure 1: YANG Tree for 'ietf-sid-file' | Figure 1: YANG Tree for 'ietf-sid-file' | |||
5. ".sid" File YANG Module | ||||
The following YANG module defines the structure of this file. | The following YANG module defines the structure of this file. | |||
Encoding is performed in JSON [RFC8259] using the rules defined in | Encoding is performed in JSON [RFC8259] using the rules defined in | |||
[RFC7951]. This module imports 'ietf-yang-types' [RFC6991] and | [RFC7951]. This module imports 'ietf-yang-types' [RFC6991] and | |||
'ietf-yang-structure-ext' [RFC8791]. It also references [RFC7950] | 'ietf-yang-structure-ext' [RFC8791]. It also references [RFC7950] | |||
and [RFC8407]. | and [RFC8407]. | |||
<CODE BEGINS> file "ietf-sid-file@2024-06-17.yang" | <CODE BEGINS> file "ietf-sid-file@2024-06-17.yang" | |||
module ietf-sid-file { | module ietf-sid-file { | |||
yang-version 1.1; | yang-version 1.1; | |||
namespace "urn:ietf:params:xml:ns:yang:ietf-sid-file"; | namespace "urn:ietf:params:xml:ns:yang:ietf-sid-file"; | |||
skipping to change at line 574 ¶ | skipping to change at line 578 ¶ | |||
Editor: Andy Bierman | Editor: Andy Bierman | |||
<mailto:andy@yumaworks.com> | <mailto:andy@yumaworks.com> | |||
Editor: Alexander Pelov | Editor: Alexander Pelov | |||
<mailto:a@ackl.io> | <mailto:a@ackl.io> | |||
Editor: Ivaylo Petrov | Editor: Ivaylo Petrov | |||
<mailto:ivaylopetrov@google.com>"; | <mailto:ivaylopetrov@google.com>"; | |||
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 each | Each '.sid' file contains the mapping between each | |||
string identifier defined by a YANG module and a | string identifier defined by a YANG module and a | |||
corresponding numeric value called a YANG SID. | corresponding numeric value called a YANG-SID. | |||
The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL | The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL | |||
NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'NOT RECOMMENDED', | NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'NOT RECOMMENDED', | |||
'MAY', and 'OPTIONAL' in this document are to be interpreted as | 'MAY', and 'OPTIONAL' in this document are to be interpreted as | |||
described in BCP 14 (RFC 2119) (RFC 8174) when, and only when, | described in BCP 14 (RFC 2119) (RFC 8174) when, and only when, | |||
they appear in all capitals, as shown here. | they appear in all capitals, as shown here. | |||
Copyright (c) 2024 IETF Trust and the persons identified as | Copyright (c) 2024 IETF Trust and the persons identified as | |||
authors of the code. All rights reserved. | authors of the code. All rights reserved. | |||
skipping to change at line 600 ¶ | skipping to change at line 604 ¶ | |||
without modification, is permitted pursuant to, and subject to | without modification, is permitted pursuant to, and subject to | |||
the license terms contained in, the Revised BSD License set | the license terms contained in, the Revised BSD License set | |||
forth in Section 4.c of the IETF Trust's Legal Provisions | forth in Section 4.c of the IETF Trust's Legal Provisions | |||
Relating to IETF Documents | Relating to IETF Documents | |||
(https://trustee.ietf.org/license-info)."; | (https://trustee.ietf.org/license-info)."; | |||
revision 2024-06-17 { | revision 2024-06-17 { | |||
description | description | |||
"Initial revision."; | "Initial revision."; | |||
reference | reference | |||
"RFC 9595: YANG Schema Item iDentifier (YANG SID)"; | "RFC 9595: YANG Data Model for YANG Schema Item iDentifiers | |||
(YANG-SIDs)"; | ||||
} | } | |||
typedef revision-identifier { | typedef revision-identifier { | |||
type string { | type string { | |||
pattern '[0-9]{4}-[0-9]{2}-[0-9]{2}'; | pattern '[0-9]{4}-[0-9]{2}-[0-9]{2}'; | |||
} | } | |||
description | description | |||
"Represents a date in YYYY-MM-DD format."; | "Represents a date in YYYY-MM-DD format."; | |||
} | } | |||
typedef sid-file-version-identifier { | typedef sid-file-version-identifier { | |||
type uint32; | type uint32; | |||
description | description | |||
"Represents the version of a .sid file."; | "Represents the version of a '.sid' file."; | |||
} | } | |||
typedef sid { | typedef sid { | |||
type uint64 { | type uint64 { | |||
range "0..9223372036854775807"; | range "0..9223372036854775807"; | |||
} | } | |||
description | description | |||
"YANG Schema Item iDentifier."; | "YANG Schema Item iDentifier."; | |||
reference | reference | |||
"RFC 9595: YANG Schema Item iDentifier (YANG SID)"; | "RFC 9595: YANG Data Model for YANG Schema Item iDentifiers | |||
(YANG-SIDs)"; | ||||
} | } | |||
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 | |||
"A schema-node path is an absolute YANG schema node | "A schema-node path is an absolute YANG schema-node | |||
identifier as defined by the YANG ABNF rule | identifier as defined by the YANG ABNF rule | |||
'absolute-schema-nodeid', except that module names are used | 'absolute-schema-nodeid', except that module names are used | |||
instead of prefixes. | instead of prefixes. | |||
This string additionally follows the following rules: | This string additionally follows the following rules: | |||
- The leftmost (top-level) data node name is always in the | - The leftmost (top-level) data node name is always in the | |||
namespace-qualified form. | namespace-qualified form. | |||
- Any subsequent schema node name is in the | - Any subsequent schema-node name is in the | |||
namespace-qualified form if the node is defined in a | namespace-qualified form if the node is defined in a | |||
module other than its parent node. Otherwise, the | module other than its parent node. Otherwise, the | |||
simple form is used. No predicates are allowed."; | simple form is used. No predicates are allowed."; | |||
reference | reference | |||
"RFC 7950: The YANG 1.1 Data Modeling Language, | "RFC 7950: The YANG 1.1 Data Modeling Language, | |||
Section 6.5: Schema Node Identifier"; | Section 6.5: Schema Node Identifier"; | |||
} | } | |||
sx:structure sid-file { | sx:structure sid-file { | |||
uses sid-file-contents; | uses sid-file-contents; | |||
} | } | |||
grouping sid-file { | grouping sid-file { | |||
description | description | |||
"A grouping that contains a YANG container | "A grouping that contains a YANG container | |||
representing the file structure of a .sid files."; | representing the file structure of a '.sid' file."; | |||
container sid-file { | container sid-file { | |||
description | description | |||
"A wrapper container that together with the 'sx:structure' | "A wrapper container that together with the 'sx:structure' | |||
extension marks the YANG data structures inside as not | extension marks the YANG data structures inside as not | |||
being intended to be implemented as part of a | being intended to be implemented as part of a | |||
configuration datastore or as an operational state within | configuration datastore or as an operational state within | |||
the server."; | the server."; | |||
uses sid-file-contents; | uses sid-file-contents; | |||
} | } | |||
} | } | |||
grouping sid-file-contents { | grouping sid-file-contents { | |||
description | description | |||
"A grouping that defines the contents of a container that | "A grouping that defines the contents of a container that | |||
represents the file structure of a .sid files."; | represents the file structure of a '.sid' file."; | |||
leaf module-name { | leaf module-name { | |||
type yang:yang-identifier; | type yang:yang-identifier; | |||
mandatory true; | mandatory true; | |||
description | description | |||
"Name of the YANG module associated with this .sid file."; | "Name of the YANG module associated with this | |||
'.sid' file."; | ||||
} | } | |||
leaf module-revision { | leaf module-revision { | |||
type revision-identifier; | type revision-identifier; | |||
description | description | |||
"Revision of the YANG module associated with this .sid | "Revision of the YANG module associated with this '.sid' | |||
file. | file. | |||
This leaf is not present if no revision statement is | This leaf is not present if no revision statement is | |||
defined in the YANG module."; | defined in the YANG module."; | |||
} | } | |||
leaf sid-file-version { | leaf sid-file-version { | |||
type sid-file-version-identifier; | type sid-file-version-identifier; | |||
default "0"; | default "0"; | |||
description | description | |||
"Optional leaf that specifies the version number of the | "Optional leaf that specifies the version number of the | |||
.sid file. .sid files and the version sequence are | '.sid' file. '.sid' files and the version sequence are | |||
specific to a given YANG module revision. This number | specific to a given YANG module revision. This number | |||
starts at zero when there is a new YANG module revision | starts at zero when there is a new YANG module revision | |||
and increases monotonically. This number can distinguish | and increases monotonically. This number can distinguish | |||
updates to the .sid file that are the result of new | updates to the '.sid' file that are the result of new | |||
processing or reported errata."; | processing or reported errata."; | |||
} | } | |||
leaf sid-file-status { | leaf sid-file-status { | |||
type enumeration { | type enumeration { | |||
enum unpublished { | enum unpublished { | |||
description | description | |||
"This .sid file is unpublished (RFC 8407) and is | "This '.sid' file is unpublished (RFC 8407) and is | |||
also called a work in progress or workfile. | also called a work-in-progress or workfile. | |||
This may be when it accompanies an unpublished YANG | This may be when it accompanies an unpublished YANG | |||
module or when only the .sid file itself is | module or when only the '.sid' file itself is | |||
unpublished. | unpublished. | |||
The 'item' list MAY contain entries with a status | The 'item' list MAY contain entries with a status | |||
value of 'unstable'."; | value of 'unstable'."; | |||
reference | reference | |||
"RFC 8407: Guidelines for Authors and Reviewers of | "RFC 8407: Guidelines for Authors and Reviewers of | |||
Documents Containing YANG Data Models"; | Documents Containing YANG Data Models"; | |||
} | } | |||
enum published { | enum published { | |||
description | description | |||
"This .sid file is published, for a published YANG | "This '.sid' file is published, for a published YANG | |||
module. The 'item' list MUST NOT contain entries | module. The 'item' list MUST NOT contain entries | |||
with a status value of 'unstable'."; | with a status value of 'unstable'."; | |||
} | } | |||
} | } | |||
default "published"; | default "published"; | |||
description | description | |||
"Optional leaf that specifies the status of the | "Optional leaf that specifies the status of the | |||
.sid file."; | '.sid' file."; | |||
} | } | |||
leaf description { | leaf description { | |||
type string; | type string; | |||
description | description | |||
"Free-form meta-information about the generated file. It | "Free-form meta-information about the generated file. It | |||
might include a .sid file generation tool and time, among | might include a '.sid' file generation tool and time, | |||
other things."; | among other things."; | |||
} | } | |||
list dependency-revision { | list dependency-revision { | |||
key "module-name"; | key "module-name"; | |||
description | description | |||
"Information about the revision used during the .sid file | "Information about the revision used during the | |||
generation of each YANG module that the module in | '.sid' file generation of each YANG module that the | |||
'module-name' imported."; | module in 'module-name' imported."; | |||
leaf module-name { | leaf module-name { | |||
type yang:yang-identifier; | type yang:yang-identifier; | |||
description | description | |||
"Name of the YANG module, dependency of 'module-name', | "Name of the YANG module, dependency of 'module-name', | |||
for which revision information is provided."; | for which revision information is provided."; | |||
} | } | |||
leaf module-revision { | leaf module-revision { | |||
type revision-identifier; | type revision-identifier; | |||
mandatory true; | mandatory true; | |||
description | description | |||
"Revision of the YANG module, dependency of | "Revision of the YANG module, dependency of | |||
'module-name', for which revision information is | 'module-name', for which revision information is | |||
provided."; | provided."; | |||
} | } | |||
} | } | |||
list assignment-range { | list assignment-range { | |||
key "entry-point"; | key "entry-point"; | |||
description | description | |||
"YANG SID range(s) allocated to the YANG module | "YANG-SID Range(s) allocated to the YANG module | |||
identified by 'module-name' and 'module-revision'. | identified by 'module-name' and 'module-revision'. | |||
- The first available value in the YANG SID range is | - The first available value in the YANG-SID Range is | |||
'entry-point', and the last available value in the | 'entry-point', and the last available value in the | |||
range is ('entry-point' + size - 1). | range is ('entry-point' + size - 1). | |||
- The YANG SID ranges specified by all | - The YANG-SID Ranges specified by all | |||
'assignment-range' entries MUST NOT overlap."; | 'assignment-range' entries MUST NOT overlap."; | |||
leaf entry-point { | leaf entry-point { | |||
type sid; | type sid; | |||
description | description | |||
"Lowest YANG SID available for assignment."; | "Lowest YANG-SID available for assignment."; | |||
} | } | |||
leaf size { | leaf size { | |||
type uint64; | type uint64; | |||
mandatory true; | mandatory true; | |||
description | description | |||
"Number of YANG SIDs available for assignment."; | "Number of YANG-SIDs available for assignment."; | |||
} | } | |||
} | } | |||
list item { | list item { | |||
key "namespace identifier"; | key "namespace identifier"; | |||
unique "sid"; | unique "sid"; | |||
description | description | |||
"Each entry within this list defines the mapping between | "Each entry within this list defines the mapping between | |||
a YANG item string identifier and a YANG SID. This list | a YANG item string identifier and a YANG-SID. This list | |||
MUST include a mapping entry for each YANG item defined | MUST include a mapping entry for each YANG item defined | |||
by the YANG module identified by 'module-name' and | by the YANG module identified by 'module-name' and | |||
'module-revision'."; | 'module-revision'."; | |||
leaf status { | leaf status { | |||
type enumeration { | type enumeration { | |||
enum stable { | enum stable { | |||
value 0; | value 0; | |||
description | description | |||
"This SID allocation has been published as the | "This SID allocation has been published as the | |||
skipping to change at line 861 ¶ | skipping to change at line 868 ¶ | |||
description | description | |||
"All feature names defined in a module and its | "All feature names defined in a module and its | |||
submodules share the same feature identifier | submodules share the same feature identifier | |||
namespace."; | namespace."; | |||
} | } | |||
enum data { | enum data { | |||
value 3; | value 3; | |||
description | description | |||
"The namespace for all data nodes, as defined in | "The namespace for all data nodes, as defined in | |||
YANG."; | YANG."; | |||
reference | ||||
"RFC 7950: The YANG 1.1 Data Modeling Language"; | ||||
} | } | |||
} | } | |||
description | description | |||
"Namespace of the YANG item for this mapping entry."; | "Namespace of the YANG item for this mapping entry."; | |||
} | } | |||
leaf identifier { | leaf identifier { | |||
type union { | type union { | |||
type yang:yang-identifier; | type yang:yang-identifier; | |||
type schema-node-path; | type schema-node-path; | |||
skipping to change at line 889 ¶ | skipping to change at line 898 ¶ | |||
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 sid; | type sid; | |||
mandatory true; | mandatory true; | |||
description | description | |||
"YANG SID assigned to the YANG item for this mapping | "YANG-SID assigned to the YANG item for this mapping | |||
entry."; | entry."; | |||
} | } | |||
} | } | |||
} | } | |||
} | } | |||
<CODE ENDS> | <CODE ENDS> | |||
Figure 2: YANG Module 'ietf-sid-file' | Figure 2: YANG Module 'ietf-sid-file' | |||
5. Security Considerations | 6. Security Considerations | |||
This document defines a new type of identifier used to encode data | This document defines a new type of identifier used to encode data | |||
that are modeled in YANG [RFC7950]. This new identifier maps | that are modeled in YANG [RFC7950]. This new identifier maps | |||
semantic concepts to integers, and if the source of this mapping is | semantic concepts to integers, and if the source of this mapping is | |||
not trusted, then new security risks might occur if an attacker can | not trusted, then new security risks might occur if an attacker can | |||
control the mapping. | control the mapping. | |||
At the time of writing, it is expected that the SID files will be | At the time of writing, it is expected that the ".sid" files will be | |||
processed by a software developer, within a software development | processed by a software developer, within a software development | |||
environment. Developers are advised to only import SID files from | environment. Developers are advised to only import ".sid" files from | |||
authoritative sources. IANA is the authoritative source for IETF- | authoritative sources. IANA is the authoritative source for IETF- | |||
managed YANG modules. | managed YANG modules. | |||
Conceptually, SID files could be processed by less-constrained target | Conceptually, ".sid" files could be processed by less-constrained | |||
systems such as network management systems. Such systems need to | target systems such as network management systems. Such systems need | |||
take extra care to make sure that they are only processing SID files | to take extra care to make sure that they are only processing ".sid" | |||
from authoritative sources that are as authoritative as the YANG | files from authoritative sources that are as authoritative as the | |||
modules that they are using. | YANG modules that they are using. | |||
SID files are identified with and can employ _dereferenceable | ".sid" files are identified with and can employ _dereferenceable | |||
identifiers_, i.e., identifiers that could lead implementations in | identifiers_, i.e., identifiers that could lead implementations in | |||
certain situations to automatically perform remote access, the target | certain situations to automatically perform remote access, the target | |||
of which is indicated at least partially by those identifiers. This | of which is indicated at least partially by those identifiers. This | |||
can give an attacker information from and/or control over such | can give an attacker information from and/or control over such | |||
accesses, which can have security and privacy implications. Please | accesses, which can have security and privacy implications. Please | |||
also see Sections 6 and 7 of [DEREF-ID] for further considerations | also see Sections 6 and 7 of [DEREF-ID] for further considerations | |||
that may be applicable. | that may be applicable. | |||
6. IANA Considerations | 7. IANA Considerations | |||
6.1. YANG Namespace Registration | 7.1. YANG Namespace Registration | |||
This document registers the following XML namespace URN in the "IETF | This document registers the following XML namespace URN in the "IETF | |||
XML Registry", following the format defined in [RFC3688]: | XML Registry", following the format defined in [RFC3688]: | |||
URI: urn:ietf:params:xml:ns:yang:ietf-sid-file | URI: urn:ietf:params:xml:ns:yang:ietf-sid-file | |||
Registrant Contact: The IESG. | Registrant Contact: The IESG. | |||
XML: N/A; the requested URI is an XML namespace. | XML: N/A; the requested URI is an XML namespace. | |||
Reference: RFC 9595 | Reference: RFC 9595 | |||
6.2. ".sid" File Format Module Registration | 7.2. ".sid" File Format Module Registration | |||
This document registers one YANG module in the "YANG Module Names" | This document registers one YANG module in the "YANG Module Names" | |||
registry [RFC6020]: | registry [RFC6020]: | |||
Name: ietf-sid-file | Name: 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 | |||
Reference: RFC 9595 | Reference: RFC 9595 | |||
6.3. New IANA Registry: YANG SID Mega-Range | 7.3. New IANA Registry: YANG-SID Mega-Ranges | |||
The name of this registry is "YANG SID Mega-Range". This registry is | The name of this registry is "YANG-SID Mega-Ranges". This registry | |||
used to record the delegation of the management of a block of SIDs to | is used to record the delegation of the management of a block of SIDs | |||
third parties (such as Standards Development Organizations (SDOs) or | to third parties (such as Standards Development Organizations (SDOs) | |||
registrars). | or registrars). | |||
6.3.1. Structure | 7.3.1. Structure | |||
Each entry in this registry must include: | Each entry in this registry must include: | |||
* The entry point (first SID) of the registered SID block. | * The entry point (first SID) of the registered SID block. | |||
* The size of the registered SID block. The size SHOULD be one | * The size of the registered SID block. The size SHOULD be one | |||
million (1 000 000) SIDs; it MAY exceptionally be a multiple of 1 | million (1,000,000) SIDs, but in exceptional cases, it MAY be a | |||
000 000. | multiple of 1,000,000. | |||
* The policy of SID range allocations: Public, Private, or Both. | * The policy of SID range allocations: Public, Private, or both. | |||
* The contact information of the requesting organization, including | * The contact information of the requesting organization, including | |||
the following: | the following: | |||
- Organization name. | - Organization name. | |||
- URL. | - URL. | |||
6.3.2. Allocation Policy | 7.3.2. Allocation Policy | |||
The IANA policy for future additions to this registry is "Expert | The IANA policy for future additions to this registry is "Expert | |||
Review" [RFC8126]. | Review" [RFC8126]. | |||
An organization requesting to manage a YANG SID Range (and thus have | An organization requesting to manage a YANG-SID Range (and thus have | |||
an entry in the "YANG SID Mega-Range" registry) must ensure the | an entry in the "YANG-SID Mega-Ranges" registry) must ensure the | |||
following capacities: | following capacities: | |||
* The capacity to manage and operate a registry of YANG SID ranges. | * The capacity to manage and operate a registry of YANG-SID Ranges. | |||
A registry of YANG SID ranges MUST provide the following | A registry of YANG-SID Ranges MUST provide the following | |||
information for all YANG SID Ranges allocated by the registry: | information for all YANG-SID Ranges allocated by the registry: | |||
- The entry point of the allocated YANG SID Range. | - The entry point of the allocated YANG-SID Range. | |||
- The size of the allocated YANG SID Range. | - The size of the allocated YANG-SID Range. | |||
- Type: Public or Private. | - Type: Public or Private. | |||
o Public ranges MUST include at least a reference to the YANG | o Public ranges MUST include at least a reference to the YANG | |||
module and ".sid" files for that YANG SID Range (e.g., | module and ".sid" files for that YANG-SID Range (e.g., | |||
compare Section 6.4.3 for the "IETF YANG SID" registry). | compare Section 7.4.3 for the "IETF YANG-SID Modules" | |||
registry). | ||||
o Private ranges MUST be marked as "Private". | o Private ranges MUST be marked as "Private". | |||
* A policy of allocation, which clearly identifies whether the YANG | * A policy of allocation, which clearly identifies whether the YANG- | |||
SID Range allocations would be Private, Public, or Both. | SID Range allocations would be Private, Public, or both. | |||
* Technical capacity to provide or refer to ".sid" files in a way | * Technical capacity to provide or refer to ".sid" files in a way | |||
that meets the security objective of data integrity for these | that meets the security objective of data integrity for these | |||
files (see also Section 5). | files (see also Section 6). | |||
* Technical capacity to ensure the sustained operation of the | * Technical capacity to ensure the sustained operation of the | |||
registry for a period of at least 5 years. If Private | registry for a period of at least 5 years. If registrations in | |||
Registrations are allowed, the period must be at least 10 years. | the Private category are allowed, the period must be at least 10 | |||
years. | ||||
If a size of the allocation beyond 1 000 000 is desired, the | If a size of the allocation beyond 1,000,000 is desired, the | |||
organization must demonstrate the sustainability of the technical | organization must demonstrate the sustainability of the technical | |||
approach for utilizing this size of allocation and how it does not | approach for utilizing this size of allocation and how it does not | |||
negatively impact the overall usability of the SID allocation | negatively impact the overall usability of the SID allocation | |||
mechanisms; such allocations are preferably placed in the space above | mechanisms; such allocations are preferably placed in the space above | |||
4 295 000 000 (64-bit space). | 4,295,000,000 (64-bit space). | |||
6.3.2.1. First Allocation | 7.3.2.1. First Allocation | |||
For a first allocation to be provided, the requesting organization | For a first allocation to be provided, the requesting organization | |||
must demonstrate a functional registry infrastructure. | must demonstrate a functional registry infrastructure. | |||
6.3.2.2. Consecutive Allocations | 7.3.2.2. Consecutive Allocations | |||
On one or more subsequent allocation requests, the organization must | On one or more subsequent allocation requests, the organization must | |||
demonstrate the exhaustion of the prior range. These conditions need | demonstrate the exhaustion of the prior range. These conditions need | |||
to be asserted by the assigned expert(s). | to be asserted by the assigned expert(s). | |||
If such a request for an additional allocation is made within 3 years | If such a request for an additional allocation is made within 3 years | |||
of the last allocation, the experts need to discuss this request on | of the last allocation, the experts need to discuss this request on | |||
the CORE Working Group mailing list and consensus needs to be | the CORE Working Group mailing list and consensus needs to be | |||
obtained before allocating a new Mega-Range. | obtained before allocating a new Mega-Range. | |||
6.3.3. Initial Contents of the Registry | 7.3.3. Initial Contents of the Registry | |||
This registry contains the following initial entry: | This registry contains the following initial entry: | |||
+=====+=======+==========+==============+=========================+ | +=====+=========+==========+============+=========================+ | |||
|Entry|Size |Allocation| Organization | URL | | |Entry|Size |Allocation|Organization| URL | | |||
|Point| | | Name | | | |Point| | |Name | | | |||
+=====+=======+==========+==============+=========================+ | +=====+=========+==========+============+=========================+ | |||
|0 |1000000|Public | IANA | <https://www.iana.org/> | | |0 |1,000,000|Public |IANA | <https://www.iana.org/> | | |||
+-----+-------+----------+--------------+-------------------------+ | +-----+---------+----------+------------+-------------------------+ | |||
Table 2 | Table 2: YANG-SID Mega-Ranges Registry: Initial Assignment | |||
6.4. New IANA Registry: IETF YANG SID Range | 7.4. New IANA Registry: IETF YANG-SID Ranges | |||
6.4.1. Structure | 7.4.1. Structure | |||
Each entry in this registry must include: | Each entry in this registry must include: | |||
* The SID range entry point. | * The SID range entry point. | |||
* The SID range size. | * The SID range size. | |||
* The YANG module name. | * The YANG module name. | |||
* A document reference (the document making the registration). | * A document reference (the document making the registration). | |||
6.4.2. Allocation Policy | 7.4.2. Allocation Policy | |||
The first million SIDs assigned to IANA is subdivided as follows: | The first million SIDs assigned to IANA is subdivided as follows: | |||
* The range of 0 to 999 (size 1000) is subject to "IESG Approval" as | * The range of 0 to 999 (size 1,000) is subject to "IESG Approval" | |||
defined in [RFC8126]; of these, SID value 0 has been reserved for | as defined in [RFC8126]; of these, SID value 0 has been reserved | |||
implementations to internally signify the absence of a SID number | for implementations to internally signify the absence of a SID | |||
and does not occur in interchange. | number and does not occur in interchange. | |||
* The ranges of 1000 to 59,999 (size 59,000) and 100,000 to 299,999 | * The ranges of 1,000 to 59,999 (size 59,000) and 100,000 to 299,999 | |||
(size 200,000) are designated for YANG modules defined in RFCs. | (size 200,000) are designated for YANG modules defined in RFCs. | |||
- The IANA policy for additions to this registry is: | - The IANA policy for additions to this registry is: | |||
o "Expert Review" [RFC8126] if the ".sid" file comes from a | o "Expert Review" [RFC8126] if the ".sid" file comes from a | |||
YANG module from an existing RFC. | YANG module from an existing RFC. | |||
o "RFC Required" [RFC8126] otherwise. | o "RFC Required" [RFC8126] otherwise. | |||
- The expert MUST verify that the YANG module for which this | - The expert MUST verify that the YANG module for which this | |||
allocation is made has an RFC (existing RFC) OR is on track to | allocation is made has an RFC (existing RFC) OR is on track to | |||
become an RFC (early allocation with a request from the working | become an RFC (Early Allocation with a request from the working | |||
group chairs as defined by [BCP100]). | group chairs as defined by [BCP100]). | |||
* The range of 60,000 to 99,999 (size 40,000) is reserved for | * The range of 60,000 to 99,999 (size 40,000) is reserved for | |||
experimental YANG modules. This range MUST NOT be used in | experimental YANG modules. This range MUST NOT be used in | |||
operational deployments, since these SIDs are not globally unique | operational deployments, since these SIDs are not globally unique | |||
which limit their interoperability. The IANA policy for this | and their interoperability is therefore limited. The IANA policy | |||
range is "Experimental Use" [RFC8126]. | for this range is "Experimental Use" [RFC8126]. | |||
* The range of 300,000 to 999,999 (size 700,000) is "Reserved" as | * The range of 300,000 to 999,999 (size 700,000) is "Reserved" as | |||
defined in [RFC8126]. | defined in [RFC8126]. | |||
+=============+=========+==========================+ | +=============+=========+==========================+ | |||
| Entry Point | Size | IANA Policy | | | Entry Point | Size | IANA Policy | | |||
+=============+=========+==========================+ | +=============+=========+==========================+ | |||
| 0 | 1,000 | IESG Approval | | | 0 | 1,000 | IESG Approval | | |||
+-------------+---------+--------------------------+ | +-------------+---------+--------------------------+ | |||
| 1,000 | 59,000 | RFC Required | | | 1,000 | 59,000 | RFC Required | | |||
+-------------+---------+--------------------------+ | +-------------+---------+--------------------------+ | |||
| 60,000 | 40,000 | Experimental/Private Use | | | 60,000 | 40,000 | Experimental/Private Use | | |||
+-------------+---------+--------------------------+ | +-------------+---------+--------------------------+ | |||
| 100,000 | 200,000 | RFC Required | | | 100,000 | 200,000 | RFC Required | | |||
+-------------+---------+--------------------------+ | +-------------+---------+--------------------------+ | |||
| 300,000 | 700,000 | Reserved | | | 300,000 | 700,000 | Reserved | | |||
+-------------+---------+--------------------------+ | +-------------+---------+--------------------------+ | |||
Table 3 | Table 3: IETF YANG-SID Ranges Registry: Ranges | |||
The size of the SID range allocated for a YANG module is recommended | The size of the SID range allocated for a YANG module is recommended | |||
to be a multiple of 50 and to be at least 33% above the current | to be a multiple of 50 and to be at least 33% above the current | |||
number of YANG items. This headroom allows assignments within the | number of YANG items. This headroom allows assignments within the | |||
same range of new YANG items introduced by subsequent revisions. The | same range of new YANG items introduced by subsequent revisions. The | |||
SID range size SHOULD NOT exceed 1000; a larger size may be requested | SID range size SHOULD NOT exceed 1,000; a larger size may be | |||
by the authors if this recommendation is considered insufficient. It | requested by the authors if this recommendation is considered | |||
is important to note that an additional SID range can be allocated to | insufficient. It is important to note that an additional SID range | |||
an existing YANG module if the initial range is exhausted; this then | can be allocated to an existing YANG module if the initial range is | |||
just leads to a slightly less efficient representation. | exhausted; this then just leads to a slightly less efficient | |||
representation. | ||||
If a SID range is allocated for an existing RFC through the "Expert | If a SID range is allocated for an existing RFC through the "Expert | |||
Review" policy, the Reference field for the given allocation should | Review" policy, the Reference field for the given allocation should | |||
point to the RFC that the YANG module is defined in. | point to the RFC that the YANG module is defined in. | |||
If a SID range is required before publishing the RFC due to | If a SID range is required before publishing the RFC due to | |||
implementations needing stable SID values, early allocation as | implementations needing stable SID values, Early Allocation as | |||
defined in [BCP100] can be employed for the "RFC Required" range | defined in [BCP100] can be employed for the "RFC Required" range | |||
(Section 2 of RFC 7120 [BCP100]). | (Section 2 of RFC 7120 [BCP100]). | |||
6.4.3. Publication of the ".sid" File | 7.4.3. Publication of the ".sid" File | |||
During an RFC's publication process, IANA contacts the designated | During an RFC's publication process, IANA contacts the designated | |||
expert team ("the team"), who are responsible for delivering a final | expert team ("the team"), who are responsible for delivering a final | |||
SID file for each module defined by the RFC. For a type-3 developer | ".sid" file for each module defined by the RFC. For a type-3 | |||
(SID-oblivious; see Section 2.4), the team creates a new SID file | developer (SID-oblivious; see Section 2.4), the team creates a new | |||
from each YANG module; see below. For a type-2 (SID-aware) | ".sid" file from each YANG module; see below. For a type-2 (SID- | |||
developer, the team first obtains the existing draft SID file from a | aware) developer, the team first obtains the existing draft ".sid" | |||
stable reference in the approved draft; for a type-1 (SID-guiding) | file from a stable reference in the approved draft; for a type-1 | |||
developer, the team extracts the SID file from the approved draft. | (SID-guiding) developer, the team extracts the ".sid" file from the | |||
approved draft. | ||||
The team uses a tool to generate a final SID file from each YANG | The team uses a tool to generate a final ".sid" file from each YANG | |||
module; the final SID file has all SID assignments set to "stable" | module; the final ".sid" file has all SID assignments set to "stable" | |||
and the SID file status set to "published". A published ".sid" file | and the ".sid" file status set to "published". A published ".sid" | |||
MUST NOT contain SID assignments with a status of "unstable". | file MUST NOT contain SID assignments with a status of "unstable". | |||
For the cases other than type-3 (SID-oblivious), the team feeds the | For the cases other than type-3 (SID-oblivious), the team feeds the | |||
existing draft SID file as an input ("reference SID file") to the | existing draft ".sid" file as an input ("reference ".sid" file") to | |||
tool so that the changes resulting from regeneration are minimal. | the tool so that the changes resulting from regeneration are minimal. | |||
For YANG modules that are revisions of previously published modules, | For YANG modules that are revisions of previously published modules, | |||
any existing published SID file needs to serve as a reference SID | any existing published ".sid" file needs to serve as a reference | |||
file for the tool, during generation of either the revised draft SID | ".sid" file for the tool, during generation of either the revised | |||
file (type-1, type-2) or the final SID file (type-3). | draft ".sid" file (type-1, type-2) or the final ".sid" file (type-3). | |||
In any case, the team checks the generated file, including checking | In any case, the team checks the generated file, including checking | |||
for validity as a SID file, for consistency with the SID range | for validity as a ".sid" file, for consistency with the SID range | |||
allocations, for full coverage of the YANG items in the YANG module, | allocations, for full coverage of the YANG items in the YANG module, | |||
and for the best achievable consistency with the existing draft SID | and for the best achievable consistency with the existing draft | |||
file. | ".sid" file. | |||
The designated experts then give the SID file to IANA to publish in | The designated experts then give the ".sid" file to IANA to publish | |||
the "IETF YANG SID" registry (Section 6.5) along with the YANG | in the "IETF YANG-SID Modules" registry (Section 7.5) along with the | |||
module. | YANG module. | |||
The ".sid" file MUST NOT be published as part of the RFC: the IANA | The ".sid" file MUST NOT be published as part of the RFC: the IANA | |||
registry is authoritative, and a link to it is to be inserted in the | registry is authoritative, and a link to it is to be inserted in the | |||
RFC. (Note that the present RFC is an exception to this rule, as the | RFC. (Note that the present RFC is an exception to this rule, as the | |||
SID file also serves as an example for exposition.) RFCs that need | ".sid" file also serves as an example for exposition.) RFCs that | |||
SIDs assigned to their new modules for use in the text of the | need SIDs assigned to their new modules for use in the text of the | |||
document, e.g., for examples, need to alert the RFC Editor in the | document, e.g., for examples, need to alert the RFC Editor in the | |||
draft text that this is the case. Such RFCs cannot be produced by | draft text that this is the case. Such RFCs cannot be produced by | |||
type-3 (SID-oblivious) developers: the SIDs used in the text need to | type-3 (SID-oblivious) developers: the SIDs used in the text need to | |||
be assigned in the existing draft SID file, and the designated expert | be assigned in the existing draft ".sid" file, and the designated | |||
team needs to check that the assignments in the final SID file are | expert team needs to check that the assignments in the final ".sid" | |||
consistent with the usage in the RFC text or that the approved draft | file are consistent with the usage in the RFC text or that the | |||
text is changed appropriately. | approved draft text is changed appropriately. | |||
6.4.4. Initial Contents of the Registry | 7.4.4. Initial Contents of the Registry | |||
Initial entries in this registry are as follows: | Initial entries in this registry are as follows: | |||
+=====+====+================================+=====================+ | +=====+====+================================+=====================+ | |||
|Entry|Size|Module Name |Reference | | |Entry|Size|Module Name |Reference | | |||
|Point| | | | | |Point| | | | | |||
+=====+====+================================+=====================+ | +=====+====+================================+=====================+ | |||
| 0| 1|(Reserved: not a valid SID) |RFC 9595 | | | 0| 1|(Reserved: not a valid SID) |RFC 9595 | | |||
+-----+----+--------------------------------+---------------------+ | +-----+----+--------------------------------+---------------------+ | |||
| 1000| 100|ietf-coreconf |[CORE-COMI] | | |1,000| 100|ietf-coreconf |[CORE-COMI] | | |||
+-----+----+--------------------------------+---------------------+ | +-----+----+--------------------------------+---------------------+ | |||
| 1100| 50|ietf-yang-types |[RFC6991] | | |1,100| 50|ietf-yang-types |[RFC6991] | | |||
+-----+----+--------------------------------+---------------------+ | +-----+----+--------------------------------+---------------------+ | |||
| 1150| 50|ietf-inet-types |[RFC6991] | | |1,150| 50|ietf-inet-types |[RFC6991] | | |||
+-----+----+--------------------------------+---------------------+ | +-----+----+--------------------------------+---------------------+ | |||
| 1200| 50|iana-crypt-hash |[RFC7317] | | |1,200| 50|iana-crypt-hash |[RFC7317] | | |||
+-----+----+--------------------------------+---------------------+ | +-----+----+--------------------------------+---------------------+ | |||
| 1250| 50|ietf-netconf-acm |[RFC8341] | | |1,250| 50|ietf-netconf-acm |[RFC8341] | | |||
+-----+----+--------------------------------+---------------------+ | +-----+----+--------------------------------+---------------------+ | |||
| 1300| 50|ietf-sid-file |RFC 9595 | | |1,300| 50|ietf-sid-file |RFC 9595 | | |||
+-----+----+--------------------------------+---------------------+ | +-----+----+--------------------------------+---------------------+ | |||
| 1500| 100|ietf-interfaces |[RFC8343] | | |1,500| 100|ietf-interfaces |[RFC8343] | | |||
+-----+----+--------------------------------+---------------------+ | +-----+----+--------------------------------+---------------------+ | |||
| 1600| 100|ietf-ip |[RFC8344] | | |1,600| 100|ietf-ip |[RFC8344] | | |||
+-----+----+--------------------------------+---------------------+ | +-----+----+--------------------------------+---------------------+ | |||
| 1700| 100|ietf-system |[RFC7317] | | |1,700| 100|ietf-system |[RFC7317] | | |||
+-----+----+--------------------------------+---------------------+ | +-----+----+--------------------------------+---------------------+ | |||
| 1800| 400|iana-if-type |[RFC7224] | | |1,800| 400|iana-if-type |[RFC7224] | | |||
+-----+----+--------------------------------+---------------------+ | +-----+----+--------------------------------+---------------------+ | |||
| 2400| 50|ietf-voucher |[RFC8366] | | |2,400| 50|ietf-voucher |[RFC8366] | | |||
+-----+----+--------------------------------+---------------------+ | +-----+----+--------------------------------+---------------------+ | |||
| 2450| 50|ietf-constrained-voucher |[CONSTRAINED-VOUCHER]| | |2,450| 50|ietf-constrained-voucher |[CONSTRAINED-VOUCHER]| | |||
+-----+----+--------------------------------+---------------------+ | +-----+----+--------------------------------+---------------------+ | |||
| 2500| 50|ietf-constrained-voucher-request|[CONSTRAINED-VOUCHER]| | |2,500| 50|ietf-constrained-voucher-request|[CONSTRAINED-VOUCHER]| | |||
+-----+----+--------------------------------+---------------------+ | +-----+----+--------------------------------+---------------------+ | |||
Table 4 | Table 4: IETF YANG-SID Ranges Registry: Initial Range Assignments | |||
For allocation, RFC publication of the YANG module is required as per | For allocation, RFC publication of the YANG module is required as per | |||
[RFC8126]. The YANG module must be registered in the "YANG Module | [RFC8126]. The YANG module must be registered in the "YANG Module | |||
Names" registry according to the rules specified in Section 14 of | Names" registry according to the rules specified in Section 14 of | |||
[RFC6020]. | [RFC6020]. | |||
6.5. New IANA Registry: IETF YANG SID | 7.5. New IANA Registry: IETF YANG-SID Modules | |||
The name of this registry is "IETF YANG SID". This registry is used | The name of this registry is "IETF YANG-SID Modules". This registry | |||
to record the allocation of SIDs for individual YANG module items. | is used to record the allocation of SIDs for individual YANG module | |||
items. | ||||
6.5.1. Structure | 7.5.1. Structure | |||
Each entry in this registry must include: | Each entry in this registry must include: | |||
* The YANG module name. This module name must be present in the | * The YANG module name. This module name must be present in the | |||
"Name" column of the "YANG Module Names" registry. | "Name" column of the "YANG Module Names" registry. | |||
* A URI for the associated ".yang" file. This file link must be | * A URI for the associated ".yang" file. This file link must be | |||
present in the "File" column of the "YANG Module Names" registry. | present in the "File" column of the "YANG Module Names" registry. | |||
* The URI for the ".sid" file that defines the allocation. The | * The URI for the ".sid" file that defines the allocation. The | |||
".sid" file is stored by IANA. | ".sid" file is stored by IANA. | |||
* The number of actually allocated SIDs in the ".sid" file. | * The number of actually allocated SIDs in the ".sid" file. | |||
6.5.2. Allocation Policy | 7.5.2. Allocation Policy | |||
The allocation policy is "Expert Review" [RFC8126]. The expert MUST | The allocation policy is "Expert Review" [RFC8126]. The expert MUST | |||
ensure that the following conditions are met: | ensure that the following conditions are met: | |||
* The ".sid" file has a valid structure: | * The ".sid" file has a valid structure: | |||
- The ".sid" file MUST be a valid JSON file following the | - The ".sid" file MUST be a valid JSON file following the | |||
structure of the module defined in this document. | structure of the module defined in this document. | |||
* The ".sid" file allocates individual SIDs ONLY in the YANG SID | * The ".sid" file allocates individual SIDs ONLY in the YANG-SID | |||
Ranges for this YANG module (as allocated in the "IETF YANG SID | Ranges for this YANG module (as allocated in the "IETF YANG-SID | |||
Range" registry): | Ranges" registry): | |||
- All SIDs in this ".sid" file MUST be within the ranges | - All SIDs in this ".sid" file MUST be within the ranges | |||
allocated to this YANG module in the "IETF YANG SID Range" | allocated to this YANG module in the "IETF YANG-SID Ranges" | |||
registry. | registry. | |||
* If another ".sid" file has already allocated SIDs for this YANG | * If another ".sid" file has already allocated SIDs for this YANG | |||
module (e.g., for older or newer versions of the YANG module), the | module (e.g., for older or newer versions of the YANG module), the | |||
YANG items are assigned the same SIDs as those in the other ".sid" | YANG items are assigned the same SIDs as those in the other ".sid" | |||
file. | file. | |||
* If there is an older version of the ".sid" file, all allocated | * If there is an older version of the ".sid" file, all allocated | |||
SIDs from that version are still present in the current version of | SIDs from that version are still present in the current version of | |||
the ".sid" file. | the ".sid" file. | |||
6.5.3. Recursive Allocation of YANG SID Range at Document Adoption | 7.5.3. Recursive Allocation of YANG-SID Range at Document Adoption | |||
Due to the difficulty in changing SID values during IETF document | Due to the difficulty in changing SID values during IETF document | |||
processing, it is expected that most documents will ask for SID range | processing, it is expected that most documents will ask for SID range | |||
allocations using early allocations [BCP100]. The details of the | allocations using Early Allocations [BCP100]. The details of the | |||
early allocation to be requested, including the timeline envisioned, | Early Allocation to be requested, including the timeline envisioned, | |||
should be included in any working group adoption call. Prior to | should be included in any working group adoption call. Prior to | |||
working group adoption, an Internet-Draft author can use the | working group adoption, an Internet-Draft author can use the | |||
experimental SID range (as per Section 6.4.2) for their SID | experimental SID range (as per Section 7.4.2) for their SID | |||
allocations or other values that do not create ambiguity with other | allocations or other values that do not create ambiguity with other | |||
SID uses (for example, they can use a range that comes from a non- | SID uses (for example, they can use a range that comes from a non- | |||
IANA-managed registry of YANG SID mega-ranges). | IANA-managed registry of YANG-SID Mega-Ranges). | |||
After working group adoption, any modification of a ".sid" file is | After working group adoption, any modification of a ".sid" file is | |||
expected to be discussed on the mailing lists of the appropriate | expected to be discussed on the mailing lists of the appropriate | |||
working groups. Specific attention should be paid to implementers' | working groups. Specific attention should be paid to implementers' | |||
opinions after Working Group Last Call if a SID value is to change | opinions after Working Group Last Call if a SID value is to change | |||
its meaning. In all cases, a ".sid" file and the SIDs associated | its meaning. In all cases, a ".sid" file and the SIDs associated | |||
with it are subject to change before the publication of an Internet- | with it are subject to change before the publication of an Internet- | |||
Draft as an RFC. | Draft as an RFC. | |||
During the early use of SIDs, many existing, previously published | As new SIDs are first used, many existing, previously published YANG | |||
YANG modules will not have SID allocations. For an allocation to be | modules will not have SID allocations. For an allocation to be | |||
useful, the included YANG modules may also need to have SID | useful, the included YANG modules may also need to have SID | |||
allocations made, in a process that will generally be analogous to | allocations made, in a process that will generally be analogous to | |||
that in Section 6.4.3 for the type-3 (SID-oblivious) case. | that in Section 7.4.3 for the type-3 (SID-oblivious) case. | |||
The expert reviewer who performs the (early) allocation analysis will | The expert reviewer who performs the (Early) Allocation analysis will | |||
need to go through the list of included YANG modules and perform SID | need to go through the list of included YANG modules and perform SID | |||
allocations for those modules as well. | allocations for those modules as well. | |||
* If the document is a published RFC, then the allocation of SIDs | * If the document is a published RFC, then the allocation of SIDs | |||
for its referenced YANG modules is permanent. The expert reviewer | for its referenced YANG modules is permanent. The expert reviewer | |||
provides the generated ".sid" file to IANA for registration. | provides the generated ".sid" file to IANA for registration. | |||
* If the document is an unprocessed Internet-Draft adopted in a | * If the document is an unprocessed Internet-Draft adopted in a | |||
working group, then an early allocation is performed for this | working group, then an Early Allocation is performed for this | |||
document as well. Early allocations require approval by an IESG | document as well. Early Allocations require approval by an IESG | |||
area director. An early allocation that requires additional | area director. An Early Allocation that requires additional | |||
allocations will list the other allocations in its description and | allocations will list the other allocations in its description and | |||
will be cross-posted to the mailing lists of any other working | will be cross-posted to the mailing lists of any other working | |||
groups concerned. | groups concerned. | |||
* A YANG module that references a module in a document that has not | * A YANG module that references a module in a document that has not | |||
yet been adopted by any working group will be unable to perform an | yet been adopted by any working group will be unable to perform an | |||
early allocation for that other document until it is adopted by a | Early Allocation for that other document until it is adopted by a | |||
working group. As described in [BCP100], an AD-sponsored document | working group. As described in [BCP100], an AD-sponsored document | |||
acts as if it had a working group. The approving AD may also | acts as if it had a working group. The approving AD may also | |||
exempt a document from this policy by agreeing to AD-sponsor the | exempt a document from this policy by agreeing to AD-sponsor the | |||
document. | document. | |||
At the end of the IETF process, all the dependencies of a given | At the end of the IETF process, all the dependencies of a given | |||
module for which SIDs are assigned should also have SIDs assigned. | module for which SIDs are assigned should also have SIDs assigned. | |||
Those dependencies' assignments should be permanent (not early | Those dependencies' assignments should be permanent (not Early | |||
allocation). | Allocation). | |||
A previously SID-allocated YANG module that changes its references to | A previously SID-allocated YANG module that changes its references to | |||
include a YANG module for which there is no SID allocation needs to | include a YANG module for which there is no SID allocation needs to | |||
repeat the early allocation process. | repeat the Early Allocation process. | |||
[BCP100] defines a time limit for the validity of early allocations, | [BCP100] defines a time limit for the validity of Early Allocations, | |||
after which they expire unless they are renewed. Section 3.3 of RFC | after which they expire unless they are renewed. Section 3.3 of RFC | |||
7120 [BCP100] also says: | 7120 [BCP100] also says: | |||
| Note that if a document is submitted for review to the IESG, and | | Note that if a document is submitted for review to the IESG, and | |||
| at the time of submission some early allocations are valid (not | | at the time of submission some Early Allocations are valid (not | |||
| expired), these allocations must not be considered to have expired | | expired), these allocations must not be considered to have expired | |||
| while the document is under IESG consideration or is awaiting | | while the document is under IESG consideration or is awaiting | |||
| publication in the RFC Editor's queue after approval by the IESG. | | publication in the RFC Editor's queue after approval by the IESG. | |||
6.5.4. Initial Contents of the Registry | 7.5.4. Initial Contents of the Registry | |||
At the time of writing, this registry does not contain any entries. | At the time of writing, this registry does not contain any entries. | |||
6.6. Media Type and Content-Format Registration | 7.6. Media Type and Content-Format Registration | |||
6.6.1. Media Type application/yang-sid+json | 7.6.1. Media Type application/yang-sid+json | |||
This document adds the following media type to the "Media Types" | This document adds the following media type to the "Media Types" | |||
registry. | registry. | |||
+===============+===========================+===========+ | +===============+===========================+===========+ | |||
| Name | Template | Reference | | | Name | Template | Reference | | |||
+===============+===========================+===========+ | +===============+===========================+===========+ | |||
| yang-sid+json | application/yang-sid+json | RFC 9595 | | | yang-sid+json | application/yang-sid+json | RFC 9595 | | |||
+---------------+---------------------------+-----------+ | +---------------+---------------------------+-----------+ | |||
Table 5: SID File Media Type Registration | Table 5: ".sid" File Media Type Registration | |||
Type name: application | Type name: application | |||
Subtype name: yang-sid+json | Subtype name: yang-sid+json | |||
Required parameters: N/A | Required parameters: N/A | |||
Optional parameters: N/A | Optional parameters: N/A | |||
Encoding considerations: binary (UTF-8) | Encoding considerations: binary (UTF-8) | |||
Security considerations: See Section 5 of RFC 9595. | Security considerations: See Section 6 of RFC 9595. | |||
Published specification: RFC 9595 | Published specification: RFC 9595 | |||
Applications that use this media type: Applications that need to | Applications that use this media type: Applications that need to | |||
obtain YANG SIDs to interchange YANG-modeled data in a concise and | obtain YANG-SIDs to interchange YANG-modeled data in a concise and | |||
efficient representation. | efficient representation. | |||
Fragment identifier considerations: The syntax and semantics of | Fragment identifier considerations: The syntax and semantics of | |||
fragment identifiers specified for "application/yang-sid+json" is | fragment identifiers specified for "application/yang-sid+json" is | |||
as specified for "application/json". (At publication of this | as specified for "application/json". (At publication of this | |||
document, there is no fragment identification syntax defined for | document, there is no fragment identification syntax defined for | |||
"application/json".) | "application/json".) | |||
Additional information: | Additional information: | |||
skipping to change at line 1397 ¶ | skipping to change at line 1411 ¶ | |||
Person & email address to contact for further information: CORE WG | Person & email address to contact for further information: CORE WG | |||
mailing list (core@ietf.org) or IETF Applications and Real-Time | mailing list (core@ietf.org) or IETF Applications and Real-Time | |||
Area (art@ietf.org) | Area (art@ietf.org) | |||
Intended usage: COMMON | Intended usage: COMMON | |||
Restrictions on usage: none | Restrictions on usage: none | |||
Author/Change controller: IETF | Author/Change controller: IETF | |||
6.6.2. CoAP Content-Format | 7.6.2. CoAP Content-Format | |||
This document adds the following Content-Format to the "CoAP Content- | This document adds the following Content-Format to the "CoAP Content- | |||
Formats" registry within the "Constrained RESTful Environments (CoRE) | Formats" registry within the "Constrained RESTful Environments (CoRE) | |||
Parameters" group of registries, where 260 has been assigned from the | Parameters" group of registries, where 260 has been assigned from the | |||
"IETF Review" (256-9999) range. | "IETF Review" (256-9,999) range. | |||
+===========================+================+=====+===========+ | +===========================+================+=====+===========+ | |||
| Content Type | Content Coding | ID | Reference | | | Content Type | Content Coding | ID | Reference | | |||
+===========================+================+=====+===========+ | +===========================+================+=====+===========+ | |||
| application/yang-sid+json | - | 260 | RFC 9595 | | | application/yang-sid+json | - | 260 | RFC 9595 | | |||
+---------------------------+----------------+-----+-----------+ | +---------------------------+----------------+-----+-----------+ | |||
Table 6: SID File Content-Format Registration | Table 6: ".sid" File Content-Format Registration | |||
7. References | 8. References | |||
7.1. Normative References | 8.1. Normative References | |||
[BCP100] Best Current Practice 100, | [BCP100] Best Current Practice 100, | |||
<https://www.rfc-editor.org/info/bcp100>. | <https://www.rfc-editor.org/info/bcp100>. | |||
At the time of writing, this BCP comprises the following: | At the time of writing, this BCP comprises the following: | |||
Cotton, M., "Early IANA Allocation of Standards Track Code | Cotton, M., "Early IANA Allocation of Standards Track Code | |||
Points", BCP 100, RFC 7120, DOI 10.17487/RFC7120, January | Points", BCP 100, RFC 7120, DOI 10.17487/RFC7120, January | |||
2014, <https://www.rfc-editor.org/info/rfc7120>. | 2014, <https://www.rfc-editor.org/info/rfc7120>. | |||
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate | [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate | |||
skipping to change at line 1472 ¶ | skipping to change at line 1486 ¶ | |||
[RFC8341] Bierman, A. and M. Bjorklund, "Network Configuration | [RFC8341] Bierman, A. and M. Bjorklund, "Network Configuration | |||
Access Control Model", STD 91, RFC 8341, | Access Control Model", STD 91, RFC 8341, | |||
DOI 10.17487/RFC8341, March 2018, | DOI 10.17487/RFC8341, March 2018, | |||
<https://www.rfc-editor.org/info/rfc8341>. | <https://www.rfc-editor.org/info/rfc8341>. | |||
[RFC8791] Bierman, A., Björklund, M., and K. Watsen, "YANG Data | [RFC8791] Bierman, A., Björklund, M., and K. Watsen, "YANG Data | |||
Structure Extensions", RFC 8791, DOI 10.17487/RFC8791, | Structure Extensions", RFC 8791, DOI 10.17487/RFC8791, | |||
June 2020, <https://www.rfc-editor.org/info/rfc8791>. | June 2020, <https://www.rfc-editor.org/info/rfc8791>. | |||
7.2. Informative References | 8.2. Informative References | |||
[CONSTRAINED-VOUCHER] | [CONSTRAINED-VOUCHER] | |||
Richardson, M., van der Stok, P., Kampanakis, P., and E. | Richardson, M., van der Stok, P., Kampanakis, P., and E. | |||
Dijk, "Constrained Bootstrapping Remote Secure Key | Dijk, "Constrained Bootstrapping Remote Secure Key | |||
Infrastructure (cBRSKI)", Work in Progress, Internet- | Infrastructure (cBRSKI)", Work in Progress, Internet- | |||
Draft, draft-ietf-anima-constrained-voucher-24, 3 March | Draft, draft-ietf-anima-constrained-voucher-24, 3 March | |||
2024, <https://datatracker.ietf.org/doc/html/draft-ietf- | 2024, <https://datatracker.ietf.org/doc/html/draft-ietf- | |||
anima-constrained-voucher-24>. | anima-constrained-voucher-24>. | |||
[CORE-COMI] | [CORE-COMI] | |||
skipping to change at line 1523 ¶ | skipping to change at line 1537 ¶ | |||
[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>. | |||
[RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for | [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for | |||
Writing an IANA Considerations Section in RFCs", BCP 26, | Writing an IANA Considerations Section in RFCs", BCP 26, | |||
RFC 8126, DOI 10.17487/RFC8126, June 2017, | RFC 8126, DOI 10.17487/RFC8126, June 2017, | |||
<https://www.rfc-editor.org/info/rfc8126>. | <https://www.rfc-editor.org/info/rfc8126>. | |||
[RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", | ||||
BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, | ||||
<https://www.rfc-editor.org/info/rfc8340>. | ||||
[RFC8343] Bjorklund, M., "A YANG Data Model for Interface | [RFC8343] Bjorklund, M., "A YANG Data Model for Interface | |||
Management", RFC 8343, DOI 10.17487/RFC8343, March 2018, | Management", RFC 8343, DOI 10.17487/RFC8343, March 2018, | |||
<https://www.rfc-editor.org/info/rfc8343>. | <https://www.rfc-editor.org/info/rfc8343>. | |||
[RFC8344] Bjorklund, M., "A YANG Data Model for IP Management", | [RFC8344] Bjorklund, M., "A YANG Data Model for IP Management", | |||
RFC 8344, DOI 10.17487/RFC8344, March 2018, | RFC 8344, DOI 10.17487/RFC8344, March 2018, | |||
<https://www.rfc-editor.org/info/rfc8344>. | <https://www.rfc-editor.org/info/rfc8344>. | |||
[RFC8366] Watsen, K., Richardson, M., Pritikin, M., and T. Eckert, | [RFC8366] Watsen, K., Richardson, M., Pritikin, M., and T. Eckert, | |||
"A Voucher Artifact for Bootstrapping Protocols", | "A Voucher Artifact for Bootstrapping Protocols", | |||
skipping to change at line 1591 ¶ | skipping to change at line 1609 ¶ | |||
For purposes of exposition, per [RFC8792], line breaks have been | For purposes of exposition, per [RFC8792], line breaks have been | |||
introduced below in some JSON strings that represent overly long | introduced below in some JSON strings that represent overly long | |||
identifiers. | identifiers. | |||
=============== NOTE: '\' line wrapping per RFC 8792 ================ | =============== NOTE: '\' line wrapping per RFC 8792 ================ | |||
{ | { | |||
"ietf-sid-file:sid-file": { | "ietf-sid-file:sid-file": { | |||
"module-name": "ietf-system", | "module-name": "ietf-system", | |||
"module-revision": "2014-08-06", | "module-revision": "2014-08-06", | |||
"description": "Example sid file", | "description": "Example '.sid' file", | |||
"dependency-revision": [ | "dependency-revision": [ | |||
{ | { | |||
"module-name": "ietf-yang-types", | "module-name": "ietf-yang-types", | |||
"module-revision": "2013-07-15" | "module-revision": "2013-07-15" | |||
}, | }, | |||
{ | { | |||
"module-name": "ietf-inet-types", | "module-name": "ietf-inet-types", | |||
"module-revision": "2013-07-15" | "module-revision": "2013-07-15" | |||
}, | }, | |||
{ | { | |||
skipping to change at line 2023 ¶ | skipping to change at line 2041 ¶ | |||
{ | { | |||
"namespace": "data", | "namespace": "data", | |||
"identifier": "/ietf-system:system/radius/server/udp/shared-\ | "identifier": "/ietf-system:system/radius/server/udp/shared-\ | |||
secret", | secret", | |||
"sid": "1774" | "sid": "1774" | |||
} | } | |||
] | ] | |||
} | } | |||
} | } | |||
Figure 3: Example .sid File ('ietf-system', with Extra Line Breaks) | Figure 3: Example ".sid" File ('ietf-system', with Extra Line Breaks) | |||
Appendix B. SID Autogeneration | Appendix B. SID Autogeneration | |||
The assignment of SIDs to YANG items SHOULD be automated. The | The assignment of SIDs to YANG items SHOULD be automated. The | |||
recommended process to assign SIDs is as follows: | recommended process to assign SIDs is as follows: | |||
1. A tool extracts the different items defined for a specific YANG | 1. A tool extracts the different items defined for a specific YANG | |||
module. | module. | |||
2. The list of items is sorted in alphabetical order. 'namespace' | 2. The list of items is sorted in alphabetical order. 'namespace' | |||
skipping to change at line 2054 ¶ | skipping to change at line 2072 ¶ | |||
4. If the number of items exceeds the SID range(s) allocated to a | 4. If the number of items exceeds the SID range(s) allocated to a | |||
YANG module, an extra range is added for subsequent assignments. | YANG module, an extra range is added for subsequent assignments. | |||
5. The 'dependency-revision' list item should reflect the revision | 5. The 'dependency-revision' list item should reflect the revision | |||
numbers of each YANG module that the YANG module imports at the | numbers of each YANG module that the YANG module imports at the | |||
moment of file generation. | moment of file generation. | |||
When updating a YANG module that is in active use, the existing SID | When updating a YANG module that is in active use, the existing SID | |||
assignments are maintained. (In contrast, when evolving an early | assignments are maintained. (In contrast, when evolving an early | |||
draft that has not yet been adopted by a community of developers, SID | version of an Internet-Draft that has not yet been adopted by a | |||
assignments are often better done from scratch after a revision.) If | community of developers, SID assignments are often better done from | |||
the name of a schema node changes but the data remain structurally | scratch after a revision.) If the name of a schema node changes but | |||
and semantically similar to what was previously available under an | the data remain structurally and semantically similar to what was | |||
old name, the SID that was used for the old name MAY continue to be | previously available under an old name, the SID that was used for the | |||
used for the new name. If the meaning of an item changes, a new SID | old name MAY continue to be used for the new name. If the meaning of | |||
MAY be assigned to it; this is particularly useful for allowing the | an item changes, a new SID MAY be assigned to it; this is | |||
new SID to identify the new structure or semantics of the item. If | particularly useful for allowing the new SID to identify the new | |||
the YANG data type changes in a new revision of a published module | structure or semantics of the item. If the YANG data type changes in | |||
such that the resulting CBOR encoding is changed, then | a new revision of a published module such that the resulting CBOR | |||
implementations will be aided significantly if a new SID is assigned. | encoding is changed, then implementations will be aided significantly | |||
Note that these decisions are generally at the discretion of the YANG | if a new SID is assigned. Note that these decisions are generally at | |||
module author, who should decide if the benefits of a manual | the discretion of the YANG module author, who should decide if the | |||
intervention are worth the deviation from automatic assignment. | benefits of a manual intervention are worth the deviation from | |||
automatic assignment. | ||||
In the case of an update to an existing ".sid" file, an additional | In the case of an update to an existing ".sid" file, an additional | |||
step is needed that increments the ".sid" file version number. If | step is needed that increments the ".sid" file version number. If | |||
there was no version number in the previous version of the ".sid" | there was no version number in the previous version of the ".sid" | |||
file, 0 is assumed to be the version number of the old version of the | file, 0 is assumed to be the version number of the old version of the | |||
".sid" file and the version number is 1 for the new ".sid" file. | ".sid" file and the version number is 1 for the new ".sid" file. | |||
Apart from that, changes to ".sid" files can also be automated using | Apart from that, changes to ".sid" files can also be automated using | |||
the same method as that described above, except that in step #3, only | the same method as that described above, except that in step #3, only | |||
unassigned YANG items are processed. Already-existing items in the | unassigned YANG items are processed. Already-existing items in the | |||
".sid" file should not be given new SIDs. | ".sid" file should not be given new SIDs. | |||
skipping to change at line 2092 ¶ | skipping to change at line 2111 ¶ | |||
either (1) should be 0 or (2) should not be present. | either (1) should be 0 or (2) should not be present. | |||
Note also that RPC or action "input" and "output" YANG items MUST | Note also that RPC or action "input" and "output" YANG items MUST | |||
always be assigned SIDs even if they don't contain further YANG | always be assigned SIDs even if they don't contain further YANG | |||
items. The reason for this requirement is that other modules can | items. The reason for this requirement is that other modules can | |||
augment the given module and those SIDs might be necessary. | augment the given module and those SIDs might be necessary. | |||
Appendix C. ".sid" File Lifecycle | Appendix C. ".sid" File Lifecycle | |||
Before assigning SIDs to their YANG modules, YANG module authors must | Before assigning SIDs to their YANG modules, YANG module authors must | |||
acquire a SID range from a registry of YANG SID ranges. If the YANG | acquire a SID range from a registry of YANG-SID Ranges. If the YANG | |||
module is part of an IETF Internet-Draft or RFC, the SID range needs | module is part of an IETF Internet-Draft or RFC, the SID range needs | |||
to be acquired from the "IETF YANG SID Range" registry as defined in | to be acquired from the "IETF YANG-SID Ranges" registry as defined in | |||
Section 6.4. For the other YANG modules, the authors can choose to | Section 7.4. For the other YANG modules, the authors can choose to | |||
acquire a SID range from any registry of YANG SID ranges. | acquire a SID range from any registry of YANG-SID Ranges. | |||
Once the SID range is acquired, owners can use it to generate one or | Once the SID range is acquired, owners can use it to generate one or | |||
more ".sid" files for their YANG module or modules. It is | more ".sid" files for their YANG module or modules. It is | |||
recommended to leave some unallocated SIDs following the allocated | recommended to leave some unallocated SIDs following the allocated | |||
range in each ".sid" file in order to allow better evolution of the | range in each ".sid" file in order to allow better evolution of the | |||
owners' YANG modules in the future. Generation of ".sid" files | owners' YANG modules in the future. Generation of ".sid" files | |||
should be performed using an automated tool. Note that ".sid" files | should be performed using an automated tool. Note that ".sid" files | |||
can only be generated for YANG modules and not for submodules. | can only be generated for YANG modules and not for submodules. | |||
C.1. ".sid" File Creation | C.1. ".sid" File Creation | |||
skipping to change at line 2142 ¶ | skipping to change at line 2161 ¶ | |||
+---------------+ +-------+-------+ | | +---------------+ +-------+-------+ | | |||
| | | | | | |||
v | | v | | |||
+---------------+ +------+------+ | +---------------+ +------+------+ | |||
| ".sid" file | | Rework YANG | | | ".sid" file | | Rework YANG | | |||
| generation | | module | | | generation | | module | | |||
+-------+-------+ +-------------+ | +-------+-------+ +-------------+ | |||
| ^ | | ^ | |||
v | | v | | |||
.----------. yes | | .----------. yes | | |||
/ Work in \ ------------+ | / Work-in- \ ------------+ | |||
\ progress? / | \ progress? / | |||
'----+-----' | '----+-----' | |||
| no | | no | |||
v | v | |||
.-------------. | .-------------. | |||
/ RFC \ no | / RFC \ no | |||
\ publication? /--------------+ | \ publication? /--------------+ | |||
'------+------' | | '------+------' | | |||
yes | | | yes | | | |||
v v | v v | |||
skipping to change at line 2210 ¶ | skipping to change at line 2229 ¶ | |||
| \ available? /---->| registration | | | \ available? /---->| registration | | |||
| '------+------' +-------+-------+ | | '------+------' +-------+-------+ | |||
| | no | | | | no | | |||
+--------------+---------------------+ | +--------------+---------------------+ | |||
| | | | |||
v | v | |||
[DONE] | [DONE] | |||
Figure 5: YANG and ".sid" File Update | Figure 5: YANG and ".sid" File Update | |||
Appendix D. Keeping a SID File in a YANG Instance Data File | Appendix D. Keeping a ".sid" File in a YANG Instance Data File | |||
[RFC9195] defines a format for "YANG instance data". This | [RFC9195] defines a format for "YANG instance data". This | |||
essentially leads to an encapsulation of the instance data within | essentially leads to an encapsulation of the instance data within | |||
some metadata envelope. | some metadata envelope. | |||
If a SID file needs to be stored in a YANG instance data file, this | If a ".sid" file needs to be stored in a YANG instance data file, | |||
can be achieved by embedding the value of the SID file as the value | this can be achieved by embedding the value of the ".sid" file as the | |||
of the content-data member in the following template and copying over | value of the content-data member in the following template and | |||
the second-level members as indicated with the angle brackets: | copying over the second-level members as indicated with the angle | |||
brackets: | ||||
{ | { | |||
"ietf-yang-instance-data:instance-data-set": { | "ietf-yang-instance-data:instance-data-set": { | |||
"name": "<module-name>@<module-revision>.sid", | "name": "<module-name>@<module-revision>.sid", | |||
"description": ["<description>"], | "description": ["<description>"], | |||
"content-schema": { | "content-schema": { | |||
"module": "ietf-sid-file@2023-10-27" | "module": "ietf-sid-file@2023-10-27" | |||
}, | }, | |||
"content-data": { <replace this object> | "content-data": { <replace this object> | |||
"ietf-sid-file:sid-file" : { | "ietf-sid-file:sid-file" : { | |||
End of changes. 154 change blocks. | ||||
286 lines changed or deleted | 306 lines changed or added | |||
This html diff was produced by rfcdiff 1.48. |