| rfc9907v2.txt | rfc9907.txt | |||
|---|---|---|---|---|
| skipping to change at line 149 ¶ | skipping to change at line 149 ¶ | |||
| 4.29. Modeling Abstract Data Structures | 4.29. Modeling Abstract Data Structures | |||
| 4.30. IANA-Maintained YANG Modules | 4.30. IANA-Maintained YANG Modules | |||
| 4.30.1. Context | 4.30.1. Context | |||
| 4.30.2. Guidelines for IANA-Maintained YANG Modules | 4.30.2. Guidelines for IANA-Maintained YANG Modules | |||
| 4.30.3. Guidance for Writing the IANA Considerations for RFCs | 4.30.3. Guidance for Writing the IANA Considerations for RFCs | |||
| Defining IANA-Maintained YANG Modules | Defining IANA-Maintained YANG Modules | |||
| 5. IANA Considerations | 5. IANA Considerations | |||
| 5.1. YANG Modules | 5.1. YANG Modules | |||
| 5.2. Update in YANG Parameters Registry Group | 5.2. Update in YANG Parameters Registry Group | |||
| 5.3. IANA-Maintained YANG Modules | 5.3. IANA-Maintained YANG Modules | |||
| 6. Operations and Manageability Considerations | 6. Operational Considerations | |||
| 7. Security Considerations | 7. Security Considerations | |||
| 8. References | 8. References | |||
| 8.1. Normative References | 8.1. Normative References | |||
| 8.2. Informative References | 8.2. Informative References | |||
| Appendix A. Module Review Checklist | Appendix A. Module Review Checklist | |||
| Appendix B. Template for IETF Modules | Appendix B. Template for IETF Modules | |||
| Appendix C. Template for IANA-Maintained YANG Modules | Appendix C. Template for IANA-Maintained YANG Modules | |||
| Acknowledgments | Acknowledgments | |||
| Authors' Addresses | Authors' Addresses | |||
| skipping to change at line 212 ¶ | skipping to change at line 212 ¶ | |||
| addition to these RFCs. | addition to these RFCs. | |||
| Section 4.30.3 updates [RFC8126] by providing guidance for writing | Section 4.30.3 updates [RFC8126] by providing guidance for writing | |||
| the IANA Considerations sections for RFCs that specify IANA- | the IANA Considerations sections for RFCs that specify IANA- | |||
| maintained YANG modules. | maintained YANG modules. | |||
| Note that this document is not a YANG tutorial; the reader is | Note that this document is not a YANG tutorial; the reader is | |||
| expected to know the YANG data modeling language before implementing | expected to know the YANG data modeling language before implementing | |||
| the guidance in this document. | the guidance in this document. | |||
| This RFC contains text intended for use as a template as designated | ||||
| below by the markers <BEGIN TEMPLATE TEXT> and <END TEMPLATE TEXT> or | ||||
| other clear designation. Such Template Text is subject to the | ||||
| provisions of Section 9(b) of the Trust Legal Provisions. | ||||
| 1.1. Changes Since RFC 8407 | 1.1. Changes Since RFC 8407 | |||
| The following changes have been made to the guidelines published in | The following changes have been made to the guidelines published in | |||
| [RFC8407]: | [RFC8407]: | |||
| * Implemented the following errata reports: [Err5693], [Err5800], | * Implemented the following errata reports: [Err5693], [Err5800], | |||
| [Err6899], and [Err7416]. | [Err6899], and [Err7416]. | |||
| * Updated the terminology. | * Updated the terminology. | |||
| skipping to change at line 715 ¶ | skipping to change at line 720 ¶ | |||
| concerns MUST be explicitly listed by name, and the reasons for | concerns MUST be explicitly listed by name, and the reasons for | |||
| the sensitivity/privacy concerns MUST be explained. | the sensitivity/privacy concerns MUST be explained. | |||
| Documents that exclusively define modules that follow the extension | Documents that exclusively define modules that follow the extension | |||
| in [RFC8791] are not required to include the security template in | in [RFC8791] are not required to include the security template in | |||
| Section 3.7.1. Likewise, following the template is not required for | Section 3.7.1. Likewise, following the template is not required for | |||
| modules that define YANG extensions such as [RFC7952]. | modules that define YANG extensions such as [RFC7952]. | |||
| 3.7.1. Security Considerations Section Template | 3.7.1. Security Considerations Section Template | |||
| <CODE BEGINS> | <BEGIN TEMPLATE TEXT> | |||
| X. Security Considerations | X. Security Considerations | |||
| This section is modeled after the template described in Section 3.7.1 | This section is modeled after the template described in Section 3.7.1 | |||
| of [RFC9907]. | of [RFC9907]. | |||
| The "<module-name>" YANG module defines a data model that is | The "<module-name>" YANG module defines a data model that is | |||
| designed to be accessed via YANG-based management protocols, | designed to be accessed via YANG-based management protocols, | |||
| such as Network Configuration Protocol (NETCONF) [RFC6241] | such as Network Configuration Protocol (NETCONF) [RFC6241] | |||
| and RESTCONF [RFC8040]. These YANG-based management protocols | and RESTCONF [RFC8040]. These YANG-based management protocols | |||
| (1) have to use a secure transport layer (e.g., Secure Shell (SSH) | (1) have to use a secure transport layer (e.g., Secure Shell (SSH) | |||
| [RFC4252], TLS [RFC8446], and QUIC [RFC9000]) and (2) have to use | [RFC4252], TLS [RFC8446], and QUIC [RFC9000]) and (2) have to use | |||
| mutual authentication. | mutual authentication. | |||
| The Network Configuration Access Control Model (NACM) [RFC8341] | The Network Configuration Access Control Model (NACM) [RFC8341] | |||
| provides the means to restrict access for particular NETCONF or | provides the means to restrict access for particular NETCONF or | |||
| RESTCONF users to a preconfigured subset of all available NETCONF or | RESTCONF users to a preconfigured subset of all available NETCONF or | |||
| RESTCONF protocol operations and content. | RESTCONF protocol operations and content. | |||
| Note: RFC 8341 (or a future RFC that replaces it) MUST be listed | -- Note: RFC 8341 (or a future RFC that replaces it) MUST be listed | |||
| as a normative reference. | -- as a normative reference. | |||
| By default, RFC 4252, RFC 6241, RFC 8040, RFC 8446, RFC 9000, and | -- By default, RFC 4252, RFC 6241, RFC 8040, RFC 8446, RFC 9000, and | |||
| RFC 9907 (or future RFCs that replace any of them) are listed as | -- RFC 9907 (or future RFCs that replace any of them) are listed as | |||
| informative references unless normatively cited in other sections | -- informative references unless normatively cited in other sections | |||
| of the document that specifies the YANG module. | -- of the document that specifies the YANG module. | |||
| -- Writable nodes section: | -- Writable nodes section: | |||
| -- | -- | |||
| -- If the data model contains any writable data nodes (those are all | -- If the data model contains any writable data nodes (those are all | |||
| -- the "config true" nodes), then include the following text: | -- the "config true" nodes), then include the following text: | |||
| There are a number of data nodes defined in this YANG module that are | There are a number of data nodes defined in this YANG module that are | |||
| writable/creatable/deletable (i.e., "config true", which is the | writable/creatable/deletable (i.e., "config true", which is the | |||
| default). All writable data nodes are likely to be sensitive or | default). All writable data nodes are likely to be sensitive or | |||
| vulnerable in some network environments. Write | vulnerable in some network environments. Write | |||
| skipping to change at line 844 ¶ | skipping to change at line 849 ¶ | |||
| modules. The module by itself does not expose any data nodes that | modules. The module by itself does not expose any data nodes that | |||
| are writable, data nodes that contain read-only state, or RPCs. | are writable, data nodes that contain read-only state, or RPCs. | |||
| As such, there are no additional security issues related to | As such, there are no additional security issues related to | |||
| the YANG module that need to be considered. | the YANG module that need to be considered. | |||
| Modules that use the groupings that are defined in this document | Modules that use the groupings that are defined in this document | |||
| should identify the corresponding security considerations. For | should identify the corresponding security considerations. For | |||
| example, reusing some of these groupings will expose privacy-related | example, reusing some of these groupings will expose privacy-related | |||
| information (e.g., 'node-example'). | information (e.g., 'node-example'). | |||
| <CODE ENDS> | <END TEMPLATE TEXT> | |||
| 3.8. IANA Considerations Section | 3.8. IANA Considerations Section | |||
| Each normative YANG module MUST be registered in both the "IETF XML | Each normative YANG module MUST be registered in both the "IETF XML | |||
| Registry" group [RFC3688] [IANA-XML] and the "YANG Module Names" | Registry" group [RFC3688] [IANA-XML] and the "YANG Module Names" | |||
| registry [RFC6020] [IANA-MOD-NAMES]. The registration request in the | registry [RFC6020] [IANA-MOD-NAMES]. The registration request in the | |||
| "YANG Module Names" registry should indicate whether or not the | "YANG Module Names" registry should indicate whether or not the | |||
| module is IANA-maintained. This applies to new modules and updated | module is IANA-maintained. This applies to new modules and updated | |||
| modules. An example of an update registration for the "ietf- | modules. An example of an update registration for the "ietf- | |||
| template" module can be found in Section 5. | template" module can be found in Section 5. | |||
| skipping to change at line 1437 ¶ | skipping to change at line 1442 ¶ | |||
| "description" statement for the grouping. | "description" statement for the grouping. | |||
| 4.6.2. Function Library | 4.6.2. Function Library | |||
| The "position" and "last" functions SHOULD NOT be used. This applies | The "position" and "last" functions SHOULD NOT be used. This applies | |||
| to implicit use of the "position" function as well (e.g., | to implicit use of the "position" function as well (e.g., | |||
| '//chapter[42]'). A server is only required to maintain the relative | '//chapter[42]'). A server is only required to maintain the relative | |||
| XML document order of all instances of a particular user-ordered list | XML document order of all instances of a particular user-ordered list | |||
| or leaf-list. The "position" and "last" functions MAY be used if | or leaf-list. The "position" and "last" functions MAY be used if | |||
| they are evaluated in a context where the context node is a user- | they are evaluated in a context where the context node is a user- | |||
| ordered "list" or "leaf-list". | ordered list or leaf-list. | |||
| The "id" function SHOULD NOT be used. The "ID" attribute is not | The "id" function SHOULD NOT be used. The "ID" attribute is not | |||
| present in YANG documents, so this function has no meaning. The | present in YANG documents, so this function has no meaning. The | |||
| XPath execution environment SHOULD return an empty string for this | XPath execution environment SHOULD return an empty string for this | |||
| function. | function. | |||
| The "namespace-uri" and "name" functions SHOULD NOT be used. | The "namespace-uri" and "name" functions SHOULD NOT be used. | |||
| Expanded names in XPath are different than YANG. A specific | Expanded names in XPath are different than YANG. A specific | |||
| canonical representation of a YANG-expanded name does not exist. | canonical representation of a YANG-expanded name does not exist. | |||
| skipping to change at line 1461 ¶ | skipping to change at line 1466 ¶ | |||
| function. | function. | |||
| The "local-name", "namespace-uri", "name", "string", and "number" | The "local-name", "namespace-uri", "name", "string", and "number" | |||
| functions SHOULD NOT be used if the argument is a node-set. If so, | functions SHOULD NOT be used if the argument is a node-set. If so, | |||
| the function result will be determined by the document order of the | the function result will be determined by the document order of the | |||
| node-set. Since this order can be different on each server, the | node-set. Since this order can be different on each server, the | |||
| function results can also be different. Any function call that | function results can also be different. Any function call that | |||
| implicitly converts a node-set to a string will also have this issue. | implicitly converts a node-set to a string will also have this issue. | |||
| The "local-name" function SHOULD NOT be used to reference local names | The "local-name" function SHOULD NOT be used to reference local names | |||
| outside of the YANG module that defines the must or when expression | outside of the YANG module that defines the "must" or "when" | |||
| containing the "local-name" function. Example of a "local-name" | expression containing the "local-name" function. Example of a | |||
| function that should not be used: | "local-name" function that should not be used: | |||
| /*[local-name()='foo'] | /*[local-name()='foo'] | |||
| The "derived-from-or-self" function SHOULD be used instead of an | The "derived-from-or-self" function SHOULD be used instead of an | |||
| equality expression for identityref values. This allows the | equality expression for identityref values. This allows the | |||
| identities to be conceptually augmented. | identities to be conceptually augmented. | |||
| Example: | Example: | |||
| // assume "ex" is the prefix of the module where the identity | // assume "ex" is the prefix of the module where the identity | |||
| skipping to change at line 1731 ¶ | skipping to change at line 1736 ¶ | |||
| revision. | revision. | |||
| revision 2013-07-15 { | revision 2013-07-15 { | |||
| description | description | |||
| "This revision adds the following new data types: | "This revision adds the following new data types: | |||
| - yang:yang-identifier | - yang:yang-identifier | |||
| - yang:hex-string | - yang:hex-string | |||
| - yang:uuid | - yang:uuid | |||
| - yang:dotted-quad"; | - yang:dotted-quad"; | |||
| reference | reference | |||
| "RFC 9911: Common YANG Data Types"; | "RFC 6991: Common YANG Data Types"; | |||
| } | } | |||
| revision 2010-09-24 { | revision 2010-09-24 { | |||
| description | description | |||
| "Initial revision."; | "Initial revision."; | |||
| reference | reference | |||
| "RFC 6021: Common YANG Data Types"; | "RFC 6021: Common YANG Data Types"; | |||
| } | } | |||
| For an unpublished module, a complete history of each unpublished | For an unpublished module, a complete history of each unpublished | |||
| skipping to change at line 1789 ¶ | skipping to change at line 1794 ¶ | |||
| } | } | |||
| revision 2013-07-15 { | revision 2013-07-15 { | |||
| description | description | |||
| "This revision adds the following new data types: | "This revision adds the following new data types: | |||
| - yang:yang-identifier | - yang:yang-identifier | |||
| - yang:hex-string | - yang:hex-string | |||
| - yang:uuid | - yang:uuid | |||
| - yang:dotted-quad"; | - yang:dotted-quad"; | |||
| reference | reference | |||
| "RFC 9911: Common YANG Data Types"; | "RFC 6991: Common YANG Data Types"; | |||
| } | } | |||
| revision 2010-09-24 { | revision 2010-09-24 { | |||
| description | description | |||
| "Initial revision."; | "Initial revision."; | |||
| reference | reference | |||
| "RFC 6021: Common YANG Data Types"; | "RFC 6021: Common YANG Data Types"; | |||
| } | } | |||
| 4.9. Namespace Assignments | 4.9. Namespace Assignments | |||
| skipping to change at line 1908 ¶ | skipping to change at line 1913 ¶ | |||
| type for the particular application. | type for the particular application. | |||
| The signed numeric data types (i.e., "int8", "int16", "int32", and | The signed numeric data types (i.e., "int8", "int16", "int32", and | |||
| "int64") SHOULD NOT be used unless negative values are allowed for | "int64") SHOULD NOT be used unless negative values are allowed for | |||
| the desired semantics. | the desired semantics. | |||
| 4.11.1. Fixed-Value Extensibility | 4.11.1. Fixed-Value Extensibility | |||
| If the set of values is fixed and the data type contents are | If the set of values is fixed and the data type contents are | |||
| controlled by a single naming authority (e.g., IANA), then an | controlled by a single naming authority (e.g., IANA), then an | |||
| enumeration data type SHOULD be used. | "enumeration" data type SHOULD be used. | |||
| leaf foo { | leaf foo { | |||
| type enumeration { | type enumeration { | |||
| enum one; | enum one; | |||
| enum two; | enum two; | |||
| } | } | |||
| } | } | |||
| If distributed extensibility or hierarchical organization of | If distributed extensibility or hierarchical organization of | |||
| enumerated values is required, then the "identityref" data type | enumerated values is required, then the "identityref" data type | |||
| SHOULD be used instead of an enumeration or other built-in type. | SHOULD be used instead of an "enumeration" or other built-in type. | |||
| identity foo-type { | identity foo-type { | |||
| description "Base for the extensible type"; | description "Base for the extensible type"; | |||
| } | } | |||
| identity one { | identity one { | |||
| base f:foo-type; | base f:foo-type; | |||
| } | } | |||
| identity two { | identity two { | |||
| skipping to change at line 2757 ¶ | skipping to change at line 2762 ¶ | |||
| used on servers supporting the operational state datastore. With | used on servers supporting the operational state datastore. With | |||
| this in mind, YANG modules SHOULD define "config false" nodes | this in mind, YANG modules SHOULD define "config false" nodes | |||
| wherever they make sense to the data model. "Config false" nodes | wherever they make sense to the data model. "Config false" nodes | |||
| SHOULD NOT be defined to provide the operational value for | SHOULD NOT be defined to provide the operational value for | |||
| configuration nodes, except when the value space of a configured and | configuration nodes, except when the value space of a configured and | |||
| operational value may differ, in which case a distinct "config false" | operational value may differ, in which case a distinct "config false" | |||
| node SHOULD be defined to hold the operational value for the | node SHOULD be defined to hold the operational value for the | |||
| configured node. | configured node. | |||
| The following guidelines are meant to help modelers develop YANG | The following guidelines are meant to help modelers develop YANG | |||
| modules that will maximize the utility of the model with both current | modules that will maximize the utility of the module with both | |||
| and new implementations. | current and new implementations. | |||
| New modules and modules that are not concerned with the operational | New modules and modules that are not concerned with the operational | |||
| state of configuration information SHOULD immediately be structured | state of configuration information SHOULD immediately be structured | |||
| to be NMDA compatible, as described in Section 4.23.1. This | to be NMDA compatible, as described in Section 4.23.1. This | |||
| transition MAY be deferred if the module does not contain any | transition MAY be deferred if the module does not contain any | |||
| configuration datastore objects. | configuration datastore objects. | |||
| The remaining are options that MAY be followed during the time that | The remaining are options that MAY be followed during the time that | |||
| NMDA mechanisms are being defined. | NMDA mechanisms are being defined. | |||
| (a) Modules that require immediate support for the NMDA features | (a) Modules that require immediate support for the NMDA features | |||
| SHOULD be structured for NMDA. A temporary non-NMDA version of | SHOULD be structured for NMDA. A temporary non-NMDA version of | |||
| this type of module MAY exist, as either an existing model or a | this type of module MAY exist, as either an existing module or a | |||
| model created by hand or with suitable tools that mirror the | module created by hand or with suitable tools that mirror the | |||
| current modeling strategies. Both the NMDA and the non-NMDA | current modeling strategies. Both the NMDA and the non-NMDA | |||
| modules SHOULD be published in the same document, with NMDA | modules SHOULD be published in the same document, with NMDA | |||
| modules in the document main body and the non-NMDA modules in a | modules in the document main body and the non-NMDA modules in a | |||
| non-normative appendix. The use of the non-NMDA module will | non-normative appendix. The use of the non-NMDA module will | |||
| allow temporary bridging of the time period until NMDA | allow temporary bridging of the time period until NMDA | |||
| implementations are available. | implementations are available. | |||
| (b) For published models, the model should be republished with an | (b) For published modules, the module should be republished with an | |||
| NMDA-compatible structure, deprecating non-NMDA constructs. For | NMDA-compatible structure, deprecating non-NMDA constructs. For | |||
| example, the "ietf-interfaces" model in [RFC7223] has been | example, the "ietf-interfaces" module in [RFC7223] has been | |||
| restructured as an NMDA-compatible model in [RFC8343] (which | restructured as an NMDA-compatible module in [RFC8343] (which | |||
| obsoletes [RFC7223]). The "/interfaces-state" hierarchy has | obsoletes [RFC7223]). The "/interfaces-state" hierarchy has | |||
| been marked "status deprecated". Models that mark their "/foo- | been marked "status deprecated". Modules that mark their "/foo- | |||
| state" hierarchy with "status deprecated" will allow NMDA- | state" hierarchy with "status deprecated" will allow NMDA- | |||
| capable implementations to avoid the cost of duplicating the | capable implementations to avoid the cost of duplicating the | |||
| state nodes, while enabling non-NMDA-capable implementations to | state nodes, while enabling non-NMDA-capable implementations to | |||
| utilize them for access to the operational values. | utilize them for access to the operational values. | |||
| (c) For models that augment models that have not been structured | (c) For modules that augment modules that have not been structured | |||
| with the NMDA, the modeler will have to consider the structure | with the NMDA, the modeler will have to consider the structure | |||
| of the base model and the guidelines listed above. Where | of the base module and the guidelines listed above. Where | |||
| possible, such models should move to new revisions of the base | possible, such modules should move to new revisions of the base | |||
| model that are NMDA compatible. When that is not possible, | module that are NMDA compatible. When that is not possible, | |||
| augmenting "state" containers SHOULD be avoided, with the | augmenting "state" containers SHOULD be avoided, with the | |||
| expectation that the base model will be re-released with the | expectation that the base module will be re-released with the | |||
| state containers marked as deprecated. It is RECOMMENDED to | state containers marked as "deprecated". It is RECOMMENDED to | |||
| augment only the "/foo" hierarchy of the base model. Where this | augment only the "/foo" hierarchy of the base module. Where | |||
| recommendation cannot be followed, any new "state" elements | this recommendation cannot be followed, any new "state" elements | |||
| SHOULD be included in their own module. | SHOULD be included in their own module. | |||
| 4.23.3.1. Temporary Non-NMDA Modules | 4.23.3.1. Temporary Non-NMDA Modules | |||
| A temporary non-NMDA module allows a non-NMDA-aware client to access | A temporary non-NMDA module allows a non-NMDA-aware client to access | |||
| operational state from an NMDA-compliant server. It contains the | operational state from an NMDA-compliant server. It contains the | |||
| top-level "config false" data nodes that would have been defined in a | top-level "config false" data nodes that would have been defined in a | |||
| legacy YANG module (before NMDA). | legacy YANG module (before NMDA). | |||
| A server that needs to support both NMDA and non-NMDA clients can | A server that needs to support both NMDA and non-NMDA clients can | |||
| advertise both the new NMDA module and the temporary non-NMDA module. | advertise both the new NMDA module and the temporary non-NMDA module. | |||
| A non-NMDA client can use separate "foo" and "foo-state" subtrees, | A non-NMDA client can use separate "foo" and "foo-state" subtrees, | |||
| except the "foo-state" subtree is located in a different (temporary) | except the "foo-state" subtree is located in a different (temporary) | |||
| module. The NMDA module can be used by a non-NMDA client to access | module. The NMDA module can be used by a non-NMDA client to access | |||
| the conventional configuration datastores and the deprecated <get> | the conventional configuration datastores and the deprecated <get> | |||
| operation to access nested "config false" data nodes. | operation to access nested "config false" data nodes. | |||
| To create the temporary non-NMDA model from an NMDA model, the | To create the temporary non-NMDA module from an NMDA module, the | |||
| following steps can be taken: | following steps can be taken: | |||
| * Change the module name by appending "-state" to the original | * Change the module name by appending "-state" to the original | |||
| module name. | module name. | |||
| * Change the namespace by appending "-state" to the original | * Change the namespace by appending "-state" to the original | |||
| namespace value. | namespace value. | |||
| * Change the prefix by appending "-s" to the original prefix value. | * Change the prefix by appending "-s" to the original prefix value. | |||
| skipping to change at line 2958 ¶ | skipping to change at line 2963 ¶ | |||
| 4.26. Guidelines for Constructs Specific to YANG 1.1 | 4.26. Guidelines for Constructs Specific to YANG 1.1 | |||
| The set of guidelines for YANG 1.1 will grow as operational | The set of guidelines for YANG 1.1 will grow as operational | |||
| experience is gained with the new language features. This section | experience is gained with the new language features. This section | |||
| contains an initial set of guidelines for YANG 1.1 language features. | contains an initial set of guidelines for YANG 1.1 language features. | |||
| 4.26.1. Importing Multiple Revisions | 4.26.1. Importing Multiple Revisions | |||
| Standard modules SHOULD NOT import multiple revisions of the same | Standard modules SHOULD NOT import multiple revisions of the same | |||
| module into a module. This MAY be done if independent definitions | module into a module. This MAY be done if independent definitions | |||
| (e.g., enumeration typedefs) from specific revisions are needed in | (e.g., "enumeration" typedefs) from specific revisions are needed in | |||
| the importing module. | the importing module. | |||
| 4.26.2. Using Feature Logic | 4.26.2. Using Feature Logic | |||
| The YANG 1.1 feature logic is much more expressive than YANG 1.0. A | The YANG 1.1 feature logic is much more expressive than YANG 1.0. A | |||
| "description" statement SHOULD describe the "if-feature" logic in | "description" statement SHOULD describe the "if-feature" logic in | |||
| text, to help readers understand the module. | text, to help readers understand the module. | |||
| YANG features SHOULD be used instead of the "when" statement, if | YANG features SHOULD be used instead of the "when" statement, if | |||
| possible. Features are advertised by the server, and objects | possible. Features are advertised by the server, and objects | |||
| skipping to change at line 3135 ¶ | skipping to change at line 3140 ¶ | |||
| When one or multiple registries are available under the same registry | When one or multiple registries are available under the same registry | |||
| group, it is RECOMMENDED to define an IANA-maintained YANG module for | group, it is RECOMMENDED to define an IANA-maintained YANG module for | |||
| each registry. However, module designers MAY consider defining one | each registry. However, module designers MAY consider defining one | |||
| single IANA-maintained YANG module that covers all registries if | single IANA-maintained YANG module that covers all registries if | |||
| maintaining that single module is manageable (e.g., very few values | maintaining that single module is manageable (e.g., very few values | |||
| are present or expected to be present for each registry). An example | are present or expected to be present for each registry). An example | |||
| of such a module is documented in Section 5.2 of [RFC9132]. | of such a module is documented in Section 5.2 of [RFC9132]. | |||
| An IANA-maintained YANG module may use the "identityref" data type | An IANA-maintained YANG module may use the "identityref" data type | |||
| approach (e.g., [RFC8675]) or an enumeration data type approach | approach (e.g., [RFC8675]) or an "enumeration" data type approach | |||
| (e.g., [RFC9108]). See Section 4.11.1 for a guidance on which data | (e.g., [RFC9108]). See Section 4.11.1 for a guidance on which data | |||
| type to use. The decision about which type to use should be made | type to use. The decision about which type to use should be made | |||
| based upon specifics related to the intended use of the IANA- | based upon specifics related to the intended use of the IANA- | |||
| maintained YANG module. For example, identities are useful if the | maintained YANG module. For example, identities are useful if the | |||
| registry entries are organized hierarchically, possibly including | registry entries are organized hierarchically, possibly including | |||
| multiple inheritances. The reasoning for the design choice MUST be | multiple inheritances. The reasoning for the design choice MUST be | |||
| documented in the companion specification that registers an IANA- | documented in the companion specification that registers an IANA- | |||
| maintained YANG module. For example, [RFC9244] defines an IANA- | maintained YANG module. For example, [RFC9244] defines an IANA- | |||
| maintained YANG module that uses enumerations for the following | maintained YANG module that uses enumerations for the following | |||
| reason: | reason: | |||
| skipping to change at line 3217 ¶ | skipping to change at line 3222 ¶ | |||
| * https://www.iana.org/assignments/iana-pseudowire-types, and | * https://www.iana.org/assignments/iana-pseudowire-types, and | |||
| * https://www.iana.org/assignments/iana-bfd-types. | * https://www.iana.org/assignments/iana-bfd-types. | |||
| "IANA_FOO_URL" is used in the following to refer to such URLs. These | "IANA_FOO_URL" is used in the following to refer to such URLs. These | |||
| URLs are expected to be sufficiently permanent and stable. | URLs are expected to be sufficiently permanent and stable. | |||
| Whenever referencing a specific version of an IANA-maintained YANG | Whenever referencing a specific version of an IANA-maintained YANG | |||
| module is needed, then URLs such as the following are used: | module is needed, then URLs such as the following are used: | |||
| * https://www.iana.org/assignments/iana-bgp-l2-encaps | * https://www.iana.org/assignments/iana-bgp- | |||
| l2-encaps@2022-09-20.yang | ||||
| "IANA_FOO_URL_With_REV" is used in the following to refer to such | "IANA_FOO_URL_With_REV" is used in the following to refer to such | |||
| URLs. | URLs. | |||
| A template for IANA-maintained YANG modules is provided in | A template for IANA-maintained YANG modules is provided in | |||
| Appendix C. | Appendix C. | |||
| 4.30.3. Guidance for Writing the IANA Considerations for RFCs Defining | 4.30.3. Guidance for Writing the IANA Considerations for RFCs Defining | |||
| IANA-Maintained YANG Modules | IANA-Maintained YANG Modules | |||
| skipping to change at line 3648 ¶ | skipping to change at line 3654 ¶ | |||
| following notes to: | following notes to: | |||
| The YANG Module Names registry: | The YANG Module Names registry: | |||
| New values must not be directly added to the "iana-foo" YANG | New values must not be directly added to the "iana-foo" YANG | |||
| module. They must instead be added to the "foo" registry. | module. They must instead be added to the "foo" registry. | |||
| The underlying registry: | The underlying registry: | |||
| When this registry is modified, the YANG module "iana-foo" | When this registry is modified, the YANG module "iana-foo" | |||
| [IANA_FOO_URL] must be updated as defined in RFC IIII. | [IANA_FOO_URL] must be updated as defined in RFC IIII. | |||
| 6. Operations and Manageability Considerations | 6. Operational Considerations | |||
| Although the document focuses on YANG data modeling language | Although the document focuses on YANG data modeling language | |||
| guidance, the document does not define a protocol or a protocol | guidance, the document does not define a protocol or a protocol | |||
| extension. As such, there are no new operations or manageability | extension. As such, there are no new operations or manageability | |||
| requirements introduced by this document. | requirements introduced by this document. | |||
| 7. Security Considerations | 7. Security Considerations | |||
| This document defines guidelines for NETCONF or RESTCONF content | This document defines guidelines for NETCONF or RESTCONF content | |||
| defined with the YANG data modeling language. It does not introduce | defined with the YANG data modeling language. It does not introduce | |||
| End of changes. 25 change blocks. | ||||
| 38 lines changed or deleted | 44 lines changed or added | |||
This html diff was produced by rfcdiff 1.48. | ||||