YANG Metadata Annotation for Immutable Flag
draft-ietf-netmod-immutable-flag-14

netmod                                                        Q. Ma, Ed.
Internet-Draft                                                     Q. Wu
Updates: 8040, 8526 (if approved)                                 Huawei
Intended status: Standards Track                         B. Lengyel, Ed.
Expires: 3 January 2027                                         Ericsson
                                                                   H. Li
                                                                     HPE
                                                             2 July 2026

              YANG Metadata Annotation for Immutable Flag
                  draft-ietf-netmod-immutable-flag-14

Abstract

   This document defines a mechanism to formally document an existing
   behavior, implemented by servers of YANG-driven network management
   protocols (e.g., NETCONF and RESTCONF), on the immutability of some
   system-provided nodes, using a YANG metadata annotation called
   "immutable" to flag which nodes are immutable.

   Clients may use "immutable" annotations provided by the server, to
   know beforehand why certain otherwise valid configuration requests
   will cause the server to return an error.

   The immutable flag is descriptive, documenting an existing behavior,
   not prescriptive, dictating server behaviors.

   This document updates RFC 8040 and RFC 8526.

Discussion Venues

   This note is to be removed before publishing as an RFC.

   Discussion of this document takes place on the Network Modeling
   Working Group mailing list (netmod@ietf.org), which is archived at
   https://mailarchive.ietf.org/arch/browse/netmod/.

   Source for this draft and an issue tracker can be found at
   https://github.com/netmod-wg/immutable-flag.

Status of This Memo

   This Internet-Draft is submitted in full conformance with the
   provisions of BCP 78 and BCP 79.

Ma, et al.               Expires 3 January 2027                 [Page 1]
Internet-Draft               immutable flag                    July 2026

   Internet-Drafts are working documents of the Internet Engineering
   Task Force (IETF).  Note that other groups may also distribute
   working documents as Internet-Drafts.  The list of current Internet-
   Drafts is at https://datatracker.ietf.org/drafts/current/.

   Internet-Drafts are draft documents valid for a maximum of six months
   and may be updated, replaced, or obsoleted by other documents at any
   time.  It is inappropriate to use Internet-Drafts as reference
   material or to cite them other than as "work in progress."

   This Internet-Draft will expire on 3 January 2027.

Copyright Notice

   Copyright (c) 2026 IETF Trust and the persons identified as the
   document authors.  All rights reserved.

   This document is subject to BCP 78 and the IETF Trust's Legal
   Provisions Relating to IETF Documents (https://trustee.ietf.org/
   license-info) in effect on the date of publication of this document.
   Please review these documents carefully, as they describe your rights
   and restrictions with respect to this document.  Code Components
   extracted from this document must include Revised BSD License text as
   described in Section 4.e of the Trust Legal Provisions and are
   provided without warranty as described in the Revised BSD License.

Table of Contents

   1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   3
     1.1.  Updates to RFC 8040 . . . . . . . . . . . . . . . . . . .   4
     1.2.  Updates to RFC 8526 . . . . . . . . . . . . . . . . . . .   4
     1.3.  Editorial Note (To be removed by RFC Editor)  . . . . . .   4
   2.  Conventions and Definitions . . . . . . . . . . . . . . . . .   5
   3.  Applicability . . . . . . . . . . . . . . . . . . . . . . . .   6
   4.  "Immutable" Metadata Annotation . . . . . . . . . . . . . . .   6
     4.1.  Definition  . . . . . . . . . . . . . . . . . . . . . . .   6
     4.2.  "with-immutability" Parameter . . . . . . . . . . . . . .   7
       4.2.1.  NETCONF Extensions to Support "with-immutability" . .   7
       4.2.2.  RESTCONF Extensions to Support "with-immutability"  .   8
   5.  Use of Immutable Flag for Different Statements  . . . . . . .   8
     5.1.  The "leaf" Statement  . . . . . . . . . . . . . . . . . .   8
     5.2.  The "leaf-list" Statement . . . . . . . . . . . . . . . .   9
     5.3.  The "container" Statement . . . . . . . . . . . . . . . .   9
     5.4.  The "list" Statement  . . . . . . . . . . . . . . . . . .   9
     5.5.  The "anydata" Statement . . . . . . . . . . . . . . . . .  10
     5.6.  The "anyxml" Statement  . . . . . . . . . . . . . . . . .  10
   6.  Immutability of Interior Nodes  . . . . . . . . . . . . . . .  10
   7.  System Configuration Datastore Interactions . . . . . . . . .  11

Ma, et al.               Expires 3 January 2027                 [Page 2]
Internet-Draft               immutable flag                    July 2026

   8.  NACM Interactions . . . . . . . . . . . . . . . . . . . . . .  11
   9.  YANG Module . . . . . . . . . . . . . . . . . . . . . . . . .  11
   10. IANA Considerations . . . . . . . . . . . . . . . . . . . . .  14
     10.1.  The "IETF XML" Registry  . . . . . . . . . . . . . . . .  14
     10.2.  The "YANG Module Names" Registry . . . . . . . . . . . .  14
     10.3.  RESTCONF Capability URN Registry . . . . . . . . . . . .  14
   11. Operational Considerations  . . . . . . . . . . . . . . . . .  14
   12. Security Considerations . . . . . . . . . . . . . . . . . . .  15
   13. References  . . . . . . . . . . . . . . . . . . . . . . . . .  15
     13.1.  Normative References . . . . . . . . . . . . . . . . . .  15
     13.2.  Informative References . . . . . . . . . . . . . . . . .  17
   Appendix A.  Sample Use Cases . . . . . . . . . . . . . . . . . .  18
     A.1.  UC1: Modeling of Server Capabilities  . . . . . . . . . .  18
     A.2.  UC2: Hardware-based Auto-configuration - Interface
           Example . . . . . . . . . . . . . . . . . . . . . . . . .  19
     A.3.  UC3: Predefined Administrator Roles . . . . . . . . . . .  19
     A.4.  UC4: Declaring Immutable System Configuration from the
           Perspective of a Logical Network Element (LNE)  . . . . .  20
   Appendix B.  Examples of Server's Immutable Behavior  . . . . . .  20
     B.1.  NETCONF Example to Retrieve Immutable Configuration . . .  22
     B.2.  RESTCONF Example to Retrieve Immutable Configuration  . .  23
     B.3.  The Inheritance of Immutability . . . . . . . . . . . . .  25
     B.4.  Immutability of the list  . . . . . . . . . . . . . . . .  25
     B.5.  Immutability of the leaf-list . . . . . . . . . . . . . .  26
     B.6.  Error Responses to Clients Overriding Immutable
           Configuration . . . . . . . . . . . . . . . . . . . . . .  26
   Appendix C.  Existing Implementations . . . . . . . . . . . . . .  28
   Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . .  29
   Authors' Addresses  . . . . . . . . . . . . . . . . . . . . . . .  29

1.  Introduction

   This document defines a YANG metadata annotation [RFC7952] to
   formally document an existing model handling behavior that has been
   used by multiple standard organizations (e.g., 3GPP TS 32.156
   [TS32.156], 28.623 [TS28.623], and ONF TR-531 [TR-531]) and vendors.

   YANG [RFC7950] is a data modeling language used to model both state
   and configuration data, based on the "config" statement.  However,
   there exists some system configuration data that cannot be modified
   by clients (that is, it is immutable), but still needs to be declared
   as "config true" to:

   *  allow configuration of data nodes under immutable lists or
      containers;

   *  place "when", "must" and "leafref" constraints between
      configuration and immutable nodes;

Ma, et al.               Expires 3 January 2027                 [Page 3]
Internet-Draft               immutable flag                    July 2026

   *  ensure the existence of specific list entries that are provided
      and needed by the system, while additional list entries can be
      created, modified or deleted.

   If a server always rejects a client's attempt to override some
   system-provided data because it internally thinks the data is
   immutable, it should document it towards the clients in a machine-
   readable way rather than writing as plain text in the "description"
   statement.

   This document defines an approach to formally document an existing
   behavior, implemented by servers in production, on the immutability
   of some system-provided data, using a YANG metadata annotation
   [RFC7952] called "immutable" to flag which nodes are immutable.  A
   server MUST NOT set the immutable flag to true for configuration data
   that is not system-provided.  This document does not regulate server
   behaviors.  That said, it is expected that a server will return an
   error with an error-tag value of "invalid-value" if a client attempts
   to modify an immutable node.

   A non-exhaustive list of already implemented and potential use cases
   is provided below:

   *  UC1: Modeling of server capabilities (Appendix A.1)

   *  UC2: Hardware based auto-configuration (Appendix A.2)

   *  UC3: Predefined administrator roles (Appendix A.3)

   *  UC4: Declaring immutable system configuration from the perspective
      of a Logical Network Element (LNE) (Appendix A.4)

1.1.  Updates to RFC 8040

   This document updates Sections 4.8 and 9.1.1 of [RFC8040] to add an
   additional query parameter named "with-immutability", as specified in
   Section 4.2.2.

1.2.  Updates to RFC 8526

   This document updates Section 3.1.1 of [RFC8526] to add an additional
   input parameter named "with-immutability" for the <get-data>
   operation, as specified in Section 4.2.1.

1.3.  Editorial Note (To be removed by RFC Editor)

   Note to the RFC Editor: This section is to be removed prior to
   publication.

Ma, et al.               Expires 3 January 2027                 [Page 4]
Internet-Draft               immutable flag                    July 2026

   This document contains placeholder values that need to be replaced
   with finalized values at the time of publication.  This note
   summarizes all of the substitutions that are needed.  No other RFC
   Editor instructions are specified elsewhere in this document.

   Please apply the following replacements:

   *  XXXX --> the assigned RFC number for this draft

   *  YYYY --> RFC number assigned to [I-D.ietf-netmod-system-config]

   *  2026-05-26 --> the actual date of the publication of this document

2.  Conventions and Definitions

   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
   "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
   "OPTIONAL" in this document are to be interpreted as described in
   BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all
   capitals, as shown here.

   The document uses the following term defined in [RFC6241]:

   *  configuration data

   The document uses the following terms defined in [RFC7950]:

   *  data node

   *  leaf

   *  leaf-list

   *  container

   *  list

   *  anydata

   *  anyxml

   *  interior node

   *  data tree

   The document uses the following term defined in [RFC8341]:

   *  access operation

Ma, et al.               Expires 3 January 2027                 [Page 5]
Internet-Draft               immutable flag                    July 2026

   The document uses the following terms defined in [RFC8342]:

   *  client

   *  server

   The document uses the following term defined in
   [I-D.ietf-netmod-system-config]:

   *  system configuration

   This document defines the following term:

   immutable flag:  A read-only server-provided metadata value that
      describes the immutability of the configuration, which is conveyed
      via a YANG metadata annotation called "immutable" with a boolean
      value.

3.  Applicability

   While the immutable flag applies to all configuration nodes, its
   value MUST NOT be set to true for configuration data that is not
   system configuration.

   The immutable flag is only visible in read-only datastores (i.e.,
   <system> [I-D.ietf-netmod-system-config], <intended>, and
   <operational>) when a "with-immutability" parameter is carried
   (Section 4.2).  However, this only serves as descriptive information
   about the instance node itself, but has no effect on the handling of
   the read-only datastore.  If the immutable flag is requested to be
   returned for an invalid datastore (i.e., any datastore other than
   <system>, <intended>, or <operational>), then the server MUST return
   an error response with the error-tag value "unknown-element".

   Configuration data has the same immutability if it appears in
   different datastores.  The immutability of configuration data is
   protocol and user independent.

4.  "Immutable" Metadata Annotation

4.1.  Definition

   The immutable flag which is defined as the metadata annotation takes
   a boolean value, and it is returned as requested by the client using
   a "with-immutability" parameter (Section 4.2).  If the "immutable"
   metadata annotation for a configuration node is not specified, the
   default "immutable" value is the same as the value of its parent node
   in the data tree (Section 6).  The "immutable" metadata annotation

Ma, et al.               Expires 3 January 2027                 [Page 6]
Internet-Draft               immutable flag                    July 2026

   value for a top-level instance node is "false" if not specified.

   A node annotated as immutable indicates that the server does not
   allow it to be changed by configuring a different value in read-write
   configuration datastores (e.g., <running>), or deleted from the
   intended datastore, which is the merged result of <running> and
   <system> as defined in Section 4 of [I-D.ietf-netmod-system-config].
   The node MAY be explicitly configured by a client in <running> with
   the same value and that configuration in <running> may subsequently
   be removed, but neither of these edits will change the configuration
   in <intended> (if implemented) on the device.

   Note that "immutable" metadata annotations are used to annotate data
   node instances.  A list may have multiple instances in the data tree,
   servers may annotate some of the instances as immutable, while others
   as mutable.

   Servers MUST ignore any immutable annotations sent from the client.

4.2.  "with-immutability" Parameter

   This section specifies the NETCONF [RFC6241] [RFC8526] and RESTCONF
   [RFC8040] protocol extensions to support the "with-immutability"
   parameter.  The "immutable" metadata annotations are not returned in
   a response unless explicitly requested by the client using this
   parameter.

4.2.1.  NETCONF Extensions to Support "with-immutability"

   This document updates [RFC8526] to augment the <get-data> operation
   with an additional parameter named "with-immutability" when
   interacting with read-only datastores.  If present, this parameter
   requests that the server includes the "immutable" metadata
   annotations in its response.

   Figure 1 provides the tree structure [RFC8340] of augmentations to
   NETCONF operations, as defined in the "ietf-immutable-annotation"
   module (Section 9).

   module: ietf-immutable-annotation
     augment /ncds:get-data/ncds:input:
       +---w with-immutability?   empty

               Figure 1: Augmentations to NETCONF Operations

Ma, et al.               Expires 3 January 2027                 [Page 7]
Internet-Draft               immutable flag                    July 2026

   To discover if the "with-immutability" parameter is supported by a
   server, a NETCONF client can query if the server implements "ietf-
   immutable-annotation" module (Section 9) by reading the YANG library
   information from the operational state datastore, as per [RFC8526].

   Refer to Appendix B.1 for an example of a NETCONF operation with
   "with-immutability" input parameter.

4.2.2.  RESTCONF Extensions to Support "with-immutability"

   This document extends Sections 4.8 and 9.1.1 of [RFC8040] to add a
   query parameter named "with-immutability" to the GET operation.  If
   present, this parameter requests that the server includes the
   "immutable" metadata annotations in its response.  This parameter is
   only allowed with no values carried when interacting with read-only
   datastores.  If it has any unexpected value, then a "400 Bad Request"
   status-line MUST be returned.  The error-tag value "invalid-value" is
   used in this case.  RESTCONF protocol operations for the datastore
   resources are defined in [RFC8527].

   To enable a RESTCONF client to discover if the "with-immutability"
   query parameter is supported by a server, the following capability
   URI is defined:

       urn:ietf:params:restconf:capability:with-immutability:1.0

   If the "with-immutability" query parameter URI is listed in the
   "capability" leaf-list defined in Section 9.3 of [RFC8040], then the
   server supports the "with-immutability" query parameter.

   Refer to Appendix B.2 for an example of a RESTCONF operation with
   "with-immutability" query parameter.

5.  Use of Immutable Flag for Different Statements

   This section defines what the immutable flag means to the client for
   each instance of YANG data node statements.

5.1.  The "leaf" Statement

   When a leaf node instance is immutable, it cannot be configured with
   a different value in read-write configuration datastores (e.g.,
   <running>) or removed from <intended> (if implemented).  Though it
   can be created/deleted in read-write configuration datastores (see
   Sections 4.1 and 7).

Ma, et al.               Expires 3 January 2027                 [Page 8]
Internet-Draft               immutable flag                    July 2026

5.2.  The "leaf-list" Statement

   When a leaf-list entry is immutable, it cannot be removed from
   <intended> (if implemented).  Though it can be created/deleted in
   read-write configuration datastores (see Sections 4.1 and 7).

   The immutable annotation attached to an individual leaf-list entry
   provides immutability with respect to the entry itself.  As per the
   restrictions in [RFC7952], annotations cannot be attached to an
   entire leaf-list instance and only to individual leaf-list entries,
   which implies a leaf-list as a whole can only inherit immutability
   from a parent node (e.g., container).

   If a leaf-list as a whole is immutable via inheritance from a parent
   node, any leaf-list entries cannot be added, modified, or reordered
   (if it is ordered-by user).

   Refer to Appendix B.5 for an example of immutability of leaf-lists.

5.3.  The "container" Statement

   When a container node instance is immutable, it cannot be removed
   from <intended> (if implemented).  Though it can be created/deleted
   in read-write configuration datastores (see Sections 4.1 and 7).

   Descendant nodes of a container recursively inherit the immutability
   of the container, unless the immutability is overridden by an
   "immutable" annotation on a descendant node (Section 6).

5.4.  The "list" Statement

   When a list entry is immutable, it cannot be removed from <intended>
   (if implemented).  Though it can be created/deleted in read-write
   configuration datastores (see Sections 4.1 and 7).

   Descendant nodes of a list entry recursively inherit the immutability
   of the list entry, unless the immutability is overridden by an
   "immutable" annotation on a descendant node (Section 6).

   The immutable annotation attached to an individual list entry
   provides immutability with respect to the entry itself.  As per the
   restrictions in [RFC7952], annotations cannot be attached to an
   entire list instance and only to individual list entries, which
   implies a list as a whole can only inherit immutability from a parent
   node (e.g., container).

Ma, et al.               Expires 3 January 2027                 [Page 9]
Internet-Draft               immutable flag                    July 2026

   If a list as a whole is immutable via inheritance from a parent node,
   any list entries cannot be added, removed, or reordered (if it is
   ordered-by user).  Each list entry inherits the immutability of the
   list by default, unless the immutability is overridden by an
   "immutable" annotation on a list entry.

   Refer to Appendix B.4 for an example of immutability of lists.

5.5.  The "anydata" Statement

   When an "anydata" node instance is immutable, it cannot be removed
   from <intended> (if implemented).  Though it can be created/deleted
   in read-write configuration datastores (see Sections 4.1 and 7).

   Additionally, as with all interior nodes, immutability is recursively
   applied to descendants (Section 6).

5.6.  The "anyxml" Statement

   When an "anyxml" node instance is immutable, it cannot be removed
   from <intended> (if implemented).  Though it can be created/deleted
   in read-write configuration datastores (see Sections 4.1 and 7).

   Additionally, as with all interior nodes, immutability is recursively
   applied to descendants (Section 6).

6.  Immutability of Interior Nodes

   Immutability is a property of a configuration data node instance,
   conveyed as metadata [RFC7952].  It is recursively applied to
   descendants, which may reset the immutability state as needed,
   thereby affecting their descendants.  There is no limit to the number
   of times the immutability state may change in a data tree.

   If the "immutable" metadata annotation for a returned child node is
   omitted, it has the same immutability as its parent node.  For each
   top-level returned node, the default "immutable" annotation value is
   false unless explicitly annotated.  Servers may suppress the
   annotation if it is inherited from its parent node or uses the
   default value as the top-level node, but are not precluded from
   returning the annotation on every single element.

   Refer to Appendix B.3 for an example of how immutability is
   recursively inherited or explicitly reset by descendants.

Ma, et al.               Expires 3 January 2027                [Page 10]
Internet-Draft               immutable flag                    July 2026

7.  System Configuration Datastore Interactions

   Immutable configuration can only be created, updated and deleted by
   the server, and it is present in <system>, if implemented.  That
   said, the existence of immutable configuration is independent of
   whether <system> is implemented or not.  For example, a server that
   does not support <system> may have predefined hardware-specific
   configuration in use that cannot be overridden or removed by clients.
   Not all system configuration data is immutable.  Immutable
   configuration does not appear in <running> unless it is explicitly
   configured.

   As specified in Section 4.1, a client MAY create/delete immutable
   nodes with same values as defined by server in read-write
   configuration datastore (e.g., <candidate>, <running>), which merely
   makes immutable nodes visible/invisible in the datastore.

8.  NACM Interactions

   The server rejects an operation request due to immutability when it
   tries to perform the operation on the request data.  Any immutability
   checking MUST be performed after access control decisions, if the
   Network Configuration Access Control Model (NACM) [RFC8341] is
   implemented on a server.  For example, if an operation requests to
   override an immutable configuration node, but the server checks the
   user is not authorized to perform the requested access operation on
   the request data, the request is rejected with an "access-denied"
   error.

9.  YANG Module

   This module imports definitions from [RFC7952], [RFC8342], [RFC8526],
   and [I-D.ietf-netmod-system-config].

   <CODE BEGINS> file "ietf-immutable-annotation@2026-05-26.yang"
   module ietf-immutable-annotation {
     yang-version 1.1;
     namespace "urn:ietf:params:xml:ns:yang:ietf-immutable-annotation";
     prefix imma;

     import ietf-yang-metadata {
       prefix md;
       reference
         "RFC 7952: Defining and Using Metadata with YANG";
     }
     import ietf-netconf-nmda {
       prefix ncds;
       reference

Ma, et al.               Expires 3 January 2027                [Page 11]
Internet-Draft               immutable flag                    July 2026

         "RFC 8526: NETCONF Extensions to Support the Network
                    Management Datastore Architecture";
     }
     import ietf-system-datastore {
       prefix sysds;
       reference
         "RFC YYYY: System-defined Configuration";
     }
     import ietf-datastores {
       prefix ds;
       reference
         "RFC 8342: Network Management Datastore Architecture
                    (NMDA)";
     }

     organization
       "IETF Network Modeling (NETMOD) Working Group";
     contact
       "WG Web:  https://datatracker.ietf.org/wg/netmod/
        WG List: NETMOD <mailto:netmod@ietf.org>

        Editor: Qiufang Ma
                <mailto:maqiufang1@huawei.com>
        Editor: Qin Wu
                <mailto:bill.wu@huawei.com>
        Editor: Balazs Lengyel
                <mailto:balazs.lengyel@ericsson.com>
        Editor: Hongwei Li
                <mailto:flycoolman@gmail.com>";
     description
       "This module defines a metadata annotation called 'immutable'
        to allow the server to formally document existing behavior on
        the mutability of some system configuration. Clients may use
        'immutable' metadata annotation provided by the server to know
        beforehand why certain otherwise valid configuration requests
        will cause the server to return an error.

        Copyright (c) 2026 IETF Trust and the persons identified
        as authors of the code. All rights reserved.

        Redistribution and use in source and binary forms, with
        or without modification, is permitted pursuant to, and
        subject to the license terms contained in, the Revised
        BSD License set forth in Section 4.c of the IETF Trust's
        Legal Provisions Relating to IETF Documents
        (https://trustee.ietf.org/license-info).

        All revisions of IETF and IANA published modules can be found

Ma, et al.               Expires 3 January 2027                [Page 12]
Internet-Draft               immutable flag                    July 2026

        at the YANG Parameters registry group
        (https://www.iana.org/assignments/yang-parameters).

        This version of this YANG module is part of RFC XXXX; see
        the RFC itself for full legal notices.";

     revision 2026-05-26 {
       description
         "Initial revision.";
       reference
         "RFC XXXX: YANG Metadata Annotation for Immutable Flag";
     }

     md:annotation immutable {
       type boolean;
       description
         "The 'immutable' metadata annotation indicates the
          immutability of an instantiated data node. It takes as a
          value 'true' or 'false'. An immutable node cannot be changed
          via configuring a different value in read-write configuration
          datastores (e.g., <running>), though it can be created/deleted
          in read-write configuration datastores. If not specified for
          a given configuration data node, the immutability is the
          same as the value of its parent node in the data tree. The
          default value of 'immutable' annotation for a top-level
          instance node is false if not specified.";
     }

     augment "/ncds:get-data/ncds:input" {
       description
         "Allows the server to include 'immutable' metadata
          annotations in its response to get-data operation.";
       leaf with-immutability {
         when
           "derived-from-or-self(../ncds:datastore,'sysds:system') "
         + "or derived-from-or-self(../ncds:datastore,'ds:intended') "
         + "or derived-from-or-self(../ncds:datastore,'ds:operational')";
         type empty;
         description
           "Requests that immutable metadata annotations be returned.

            This parameter is only valid when the datastore is system,
            intended, or operational. See RFC XXXX Section 3 for the
            required error behavior when used with other datastores.";
       }
     }
   }
   <CODE ENDS>

Ma, et al.               Expires 3 January 2027                [Page 13]
Internet-Draft               immutable flag                    July 2026

10.  IANA Considerations

10.1.  The "IETF XML" Registry

   IANA is requested to register the following URI in the "ns" registry
   within the "IETF XML Registry" group [RFC3688]:

   URI: urn:ietf:params:xml:ns:yang:ietf-immutable-annotation
   Registrant Contact: The IESG
   XML: N/A; the requested URI is an XML namespace.

10.2.  The "YANG Module Names" Registry

   IANA is requested to register the following YANG module in the "YANG
   Module Names" registry [RFC6020] within the "YANG Parameters"
   registry group.

   Name: ietf-immutable-annotation
   Maintained by IANA?  N
   Namespace: urn:ietf:params:xml:ns:yang:ietf-immutable-annotation
   Prefix: imma
   Reference: RFC XXXX

10.3.  RESTCONF Capability URN Registry

   IANA is requested to register the following capability identifier
   URNs in the "RESTCONF Capability URNs" registry defined in [RFC8040]:

   Index:  :with-immutability

   Capability Identifier:  urn:ietf:params:restconf:capability:with-
      immutability:1.0

11.  Operational Considerations

   This document specifies a mechanism for clients to discover immutable
   system configuration before attempting modifications.  Clients can
   leverage this information to avoid sending edit requests that would
   otherwise fail due to immutable nodes.

Ma, et al.               Expires 3 January 2027                [Page 14]
Internet-Draft               immutable flag                    July 2026

   The mechanism defined in this document is backward compatible with
   existing implementations.  A legacy client unware of this mechanism
   will not include the "with-immutability" query parameter in its
   retrieval requests.  Consequently, servers will process the request
   normally without returning any "immutable" metadata annotations.
   Conversely, a client explicitly requesting the immutable flag from a
   legacy server may either receive an error response for unsupported
   query parameter or have the parameter ignored, depending on the
   server's implementation.

12.  Security Considerations

   This section is modeled after the template described in Section 3.7.1
   of [RFC9907].

   The "ietf-immutable-annotation" YANG module defines a data model that
   is designed to be accessed via YANG-based management protocols, such
   as the Network Configuration Protocol (NETCONF) [RFC6241] and
   RESTCONF [RFC8040].  These YANG-based management protocols (1) have
   to use a secure transport layer (e.g., Secure Shell (SSH) [RFC4252],
   TLS [I-D.ietf-tls-rfc8446bis], and QUIC [RFC9000]) and (2) have to
   use mutual authentication.

   The Network Configuration Access Control Model (NACM) [RFC8341]
   provides the means to restrict access for particular NETCONF or
   RESTCONF users to a preconfigured subset of all available NETCONF or
   RESTCONF protocol operations and content.

   The YANG module specified in this document defines a metadata
   annotation, it also extends the RPC operations of the NETCONF
   protocol in [RFC6241] and [RFC8526].

   The "immutable" metadata annotation exposes the immutability of
   configuration data, which may provide hints for attackers to find
   vulnerabilities in the network, e.g., to leverage the immutability of
   some configuration to better craft an attack.  Since immutable
   annotations are attached to the instances of configuration data
   nodes, it is only accessible to clients that have the permissions to
   read the annotated configuration nodes.

   The security considerations for the NETCONF protocol operations (see
   Section 9 of [RFC6241] and Section 6 of [RFC8526]) also apply to the
   operations extended in this document.

13.  References

13.1.  Normative References

Ma, et al.               Expires 3 January 2027                [Page 15]
Internet-Draft               immutable flag                    July 2026

   [I-D.ietf-netmod-system-config]
              Ma, Q., Wu, Q., and C. Feng, "System-defined
              Configuration", Work in Progress, Internet-Draft, draft-
              ietf-netmod-system-config-20, 28 January 2026,
              <https://datatracker.ietf.org/doc/html/draft-ietf-netmod-
              system-config-20>.

   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
              Requirement Levels", BCP 14, RFC 2119,
              DOI 10.17487/RFC2119, March 1997,
              <https://www.rfc-editor.org/rfc/rfc2119>.

   [RFC3688]  Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688,
              DOI 10.17487/RFC3688, January 2004,
              <https://www.rfc-editor.org/rfc/rfc3688>.

   [RFC6020]  Bjorklund, M., Ed., "YANG - A Data Modeling Language for
              the Network Configuration Protocol (NETCONF)", RFC 6020,
              DOI 10.17487/RFC6020, October 2010,
              <https://www.rfc-editor.org/rfc/rfc6020>.

   [RFC6241]  Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed.,
              and A. Bierman, Ed., "Network Configuration Protocol
              (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011,
              <https://www.rfc-editor.org/rfc/rfc6241>.

   [RFC7950]  Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language",
              RFC 7950, DOI 10.17487/RFC7950, August 2016,
              <https://www.rfc-editor.org/rfc/rfc7950>.

   [RFC7952]  Lhotka, L., "Defining and Using Metadata with YANG",
              RFC 7952, DOI 10.17487/RFC7952, August 2016,
              <https://www.rfc-editor.org/rfc/rfc7952>.

   [RFC8040]  Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF
              Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017,
              <https://www.rfc-editor.org/rfc/rfc8040>.

   [RFC8174]  Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
              2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
              May 2017, <https://www.rfc-editor.org/rfc/rfc8174>.

   [RFC8341]  Bierman, A. and M. Bjorklund, "Network Configuration
              Access Control Model", STD 91, RFC 8341,
              DOI 10.17487/RFC8341, March 2018,
              <https://www.rfc-editor.org/rfc/rfc8341>.

Ma, et al.               Expires 3 January 2027                [Page 16]
Internet-Draft               immutable flag                    July 2026

   [RFC8342]  Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K.,
              and R. Wilton, "Network Management Datastore Architecture
              (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018,
              <https://www.rfc-editor.org/rfc/rfc8342>.

   [RFC8526]  Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K.,
              and R. Wilton, "NETCONF Extensions to Support the Network
              Management Datastore Architecture", RFC 8526,
              DOI 10.17487/RFC8526, March 2019,
              <https://www.rfc-editor.org/rfc/rfc8526>.

   [RFC8527]  Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K.,
              and R. Wilton, "RESTCONF Extensions to Support the Network
              Management Datastore Architecture", RFC 8527,
              DOI 10.17487/RFC8527, March 2019,
              <https://www.rfc-editor.org/rfc/rfc8527>.

13.2.  Informative References

   [I-D.ietf-tls-rfc8446bis]
              Rescorla, E., "The Transport Layer Security (TLS) Protocol
              Version 1.3", Work in Progress, Internet-Draft, draft-
              ietf-tls-rfc8446bis-14, 13 September 2025,
              <https://datatracker.ietf.org/doc/html/draft-ietf-tls-
              rfc8446bis-14>.

   [RFC4252]  Ylonen, T. and C. Lonvick, Ed., "The Secure Shell (SSH)
              Authentication Protocol", RFC 4252, DOI 10.17487/RFC4252,
              January 2006, <https://www.rfc-editor.org/rfc/rfc4252>.

   [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/rfc/rfc8340>.

   [RFC8343]  Bjorklund, M., "A YANG Data Model for Interface
              Management", RFC 8343, DOI 10.17487/RFC8343, March 2018,
              <https://www.rfc-editor.org/rfc/rfc8343>.

   [RFC8530]  Berger, L., Hopps, C., Lindem, A., Bogdanovic, D., and X.
              Liu, "YANG Model for Logical Network Elements", RFC 8530,
              DOI 10.17487/RFC8530, March 2019,
              <https://www.rfc-editor.org/rfc/rfc8530>.

   [RFC8792]  Watsen, K., Auerswald, E., Farrel, A., and Q. Wu,
              "Handling Long Lines in Content of Internet-Drafts and
              RFCs", RFC 8792, DOI 10.17487/RFC8792, June 2020,
              <https://www.rfc-editor.org/rfc/rfc8792>.

Ma, et al.               Expires 3 January 2027                [Page 17]
Internet-Draft               immutable flag                    July 2026

   [RFC9000]  Iyengar, J., Ed. and M. Thomson, Ed., "QUIC: A UDP-Based
              Multiplexed and Secure Transport", RFC 9000,
              DOI 10.17487/RFC9000, May 2021,
              <https://www.rfc-editor.org/rfc/rfc9000>.

   [RFC9907]  Bierman, A., Boucadair, M., Ed., and Q. Wu, "Guidelines
              for Authors and Reviewers of Documents Containing YANG
              Data Models", BCP 216, RFC 9907, DOI 10.17487/RFC9907,
              March 2026, <https://www.rfc-editor.org/rfc/rfc9907>.

   [TR-531]   ONF, "UML to YANG Mapping Guidelines", July 2018,
              <https://opennetworking.org/wp-content/uploads/2018/08/TR-
              531_UML-YANG_Mapping_Gdls_v1.1-1-
              1.pdfhttps://opennetworking.org/wp-
              content/uploads/2018/08/TR-531_UML-
              YANG_Mapping_Gdls_v1.1-1-1.pdf>.

   [TS28.623] 3GPP, "Telecommunication management; Generic Network
              Resource Model (NRM) Integration Reference Point (IRP);
              Solution Set (SS) definitions",
              <https://www.3gpp.org/ftp/Specs/
              archive/28_series/28.623/28623-i02.zip>.

   [TS32.156] 3GPP, "Telecommunication management; Fixed Mobile
              Convergence (FMC) Model repertoire",
              <https://www.3gpp.org/ftp/Specs/
              archive/32_series/32.156/32156-h10.zip>.

Appendix A.  Sample Use Cases

A.1.  UC1: Modeling of Server Capabilities

   System capabilities might be represented as immutable configuration.
   Configurable data nodes might need constraints specified using
   "when", "must", or "path" statements to ensure that configuration is
   set according to the system's capabilities.  For example,
   configurable timer (e.g., for an "interface-timer" or a "bfd-
   interval-timer") values are dependent on the underlying system timer
   resource limits.

   *  A timer might only support the values 1, 5, and 8 seconds,
      determined by the system capabilities.  This is defined in the
      leaf-list 'supported-timer'.

   *  When the configurable 'interface-timer' leaf is set by a client,
      it should be ensured that one of the supported values is used.
      The natural solution would be to make the "interface-timer" a
      leafref pointing at the "supported-timer".

Ma, et al.               Expires 3 January 2027                [Page 18]
Internet-Draft               immutable flag                    July 2026

   However, this is not possible as "supported-timer" must be read-only
   thus "config false" while 'interface-timer' must be writable thus
   "config true".  According to the rules of YANG it is not allowed to
   put a constraint between "config true" and "config false" data nodes
   (Section 9.9 of [RFC7950]).

   A solution is that the 'supported-timer' data node in the YANG Model
   shall be defined as "config true" and shall also be marked with the
   "immutable" annotation making it unchangeable.  After this the
   'interface-timer' shall be defined as a leafref pointing at the
   'supported-timer-values'.

A.2.  UC2: Hardware-based Auto-configuration - Interface Example

   [RFC8343] defines a YANG data model for the management of network
   interfaces.  When a system-controlled interface is physically
   present, the system creates an interface entry with valid name and
   type values in <system> (if exists, see
   [I-D.ietf-netmod-system-config]).

   The system-generated type value is dependent on and represents the
   hardware present, and as a consequence cannot be changed by clients.
   If a client tries to set the type of an interface to a value that can
   never be used by the system, the request will be rejected by the
   server.  The data is modeled as "config true" and thus should be
   annotated as immutable.

   An alternative would be to model the list and these leafs as "config
   false", but that does not work because:

   *  The list cannot be marked as "config false", because it needs to
      contain configurable child nodes, e.g., IP address or enabled;

   *  The key leaf (name) cannot be marked as "config false" as the list
      itself is "config true";

   *  The type cannot be marked "config false", because we may need to
      reference the type to make different configuration nodes
      conditionally available.

A.3.  UC3: Predefined Administrator Roles

   User and group management is fundamental for setting up access
   control rules (see Section 2.5 of [RFC8341]).

   A device may provide a predefined user account (e.g., a system
   administrator that is always available and has full privileges) for
   initial system set up and management of other users/groups.  It is

Ma, et al.               Expires 3 January 2027                [Page 19]
Internet-Draft               immutable flag                    July 2026

   possible that a new user/group can be defined granted particular
   privileges, but the predefined administrator account and its granted
   access are immutable.

A.4.  UC4: Declaring Immutable System Configuration from the Perspective
      of a Logical Network Element (LNE)

   An LNE, as described in [RFC8530], is an independently managed
   virtual network device made up of resources allocated to it from its
   host or parent network device.  The host device may allocate some
   resources to an LNE, which from an LNE's perspective is provided by
   the system and may not be modifiable.

   For example, a host may allocate an interface to an LNE with a valid
   MTU value as its management interface, so that the allocated
   interface should then be accessible as the LNE-specific instance of
   the interface model.  The assigned MTU value is system-created and
   immutable from the context of the LNE.

Appendix B.  Examples of Server's Immutable Behavior

   This section provides some examples to illustrate the server's
   behavior with immutable flag.  These examples are not intended as
   recommendations for real-world deployments.  Long lines within
   examples are handled in accordance with the line-wrapping specified
   in [RFC8792].

   The following fictional module is used throughout this section:

   module example-user-group {
     yang-version 1.1;
     namespace "urn:example:user-group";
     prefix ex-urp;

     import iana-crypt-hash {
       prefix ianach;
     }

     organization
       "Example, Inc.";

     contact
       "Support at example.com";

     description
       "An example module for basic user and group management.";

     revision "2026-05-26" {

Ma, et al.               Expires 3 January 2027                [Page 20]
Internet-Draft               immutable flag                    July 2026

       description
         "Initial version.";
       reference
         "RFC XXXX: YANG Metadata Annotation for Immutable Flag";
     }

     container user-groups {
       description
         "A container for user and group management.";
       list group {
         key "name";
         description
           "Specifies the list of access user-groups.";
         leaf name {
           type string;
           description
             "Indicates a unique name identifier for the user-group.";
         }
         leaf description {
           type string;
           description
             "Provides a human-readable description of the group.";
         }
         leaf access-level {
           type enumeration {
             enum admin;
             enum power;
             enum normal;
             enum guest;
           }
           description
             "Indicates permission level assigned to the group.";
         }
         list user {
           key "name";
           description
             "A list of users that belong to a group.";
           leaf name {
             type string;
             description
               "Specifies a unique name identifier for the user.";
           }
           leaf password {
             type ianach:crypt-hash;
             description
               "Records a cryptographically-hashed user password.";
           }
           leaf full-name {

Ma, et al.               Expires 3 January 2027                [Page 21]
Internet-Draft               immutable flag                    July 2026

             type string;
             description
               "Indicates a human-readable full name of the user.";
           }
         }
         leaf-list tag {
           type string;
           ordered-by user;
           description
             "Indicates user-ordered tags for categorizing the
              user-group.";
         }
       }
     }
   }

B.1.  NETCONF Example to Retrieve Immutable Configuration

   Figure 2 illustrates a NETCONF request example to retrieve "user-
   groups" configuration in <system> with "with-immutability" parameter
   and the response that a server might return if it supports this query
   parameter.  For illustrative clarity, some annotations that could
   otherwise be omitted are shown explicitly in the response.

   =============== NOTE: '\' line wrapping per RFC 8792 ================

   <rpc message-id="101"
        xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
     <get-data xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-nmda"
               xmlns:sysds="urn:ietf:params:xml:ns:yang:ietf-system-\
                                                             datastore">
       <datastore>sysds:system</datastore>
       <subtree-filter>
         <user-groups xmlns="urn:example:user-group"/>
       </subtree-filter>
       <with-immutability/>
     </get-data>
   </rpc>

   <rpc-reply message-id="101"
          xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
     <data xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-nmda">
       <user-groups xmlns="urn:example:user-group"
         xmlns:imma="urn:ietf:params:xml:ns:yang:ietf-immutable-\
                                                             annotation"
         imma:immutable="false">
         <group imma:immutable="true">
           <name>administrator</name>

Ma, et al.               Expires 3 January 2027                [Page 22]
Internet-Draft               immutable flag                    July 2026

           <description imma:immutable="false">administrator group</\
                                                            description>
           <access-level>admin</access-level>
           <user>
             <name>ex-username-1</name>
             <password>$5$rounds=10000$mysalt123456789$l4BjA1p/8q.qCYJ.\
                                  2pLqjR5mCJf2bP7cLpYWmnC7Hq8</password>
           </user>
           <user imma:immutable="false">
             <name>ex-username-2</name>
             <password>$1$/h1234q$abcdef1234567890abcdef</password>
           </user>
           <tag>system</tag>
           <tag>non-editable</tag>
         </group>
         <group imma:immutable="false">
           <name>power-users</name>
           <description>Power user group</description>
           <access-level>power</access-level>
           <user>
             <name>ex-username-3</name>
             <password>$1$/h4567q$abcdef2345678901abcdef</password>
           </user>
           <tag>system</tag>
           <tag>editable</tag>
         </group>
       </user-groups>
     </data>
   </rpc-reply>

      Figure 2: A NETCONF Example to Retrieve Immutable Configuration

B.2.  RESTCONF Example to Retrieve Immutable Configuration

   Figure 3 illustrates a RESTCONF request example to retrieve "user-
   groups" configuration in <system> with "with-immutability" query
   parameter and the response a server might return if it supports this
   query parameter.  The JSON representation of the metadata annotations
   in the response follows the encoding specified in Section 5.2 of
   [RFC7952].  For illustrative clarity, some annotations that could
   otherwise be omitted are shown explicitly in the response.

   =============== NOTE: '\' line wrapping per RFC 8792 ================

   GET /restconf/ds/ietf-system-datastore:system/example-user-group:\
                                  user-groups?with-immutability HTTP/1.1
   Host: example.com
   Accept: application/yang-data+json

Ma, et al.               Expires 3 January 2027                [Page 23]
Internet-Draft               immutable flag                    July 2026

   HTTP/1.1 200 OK
   Date: Fri, 9 Jan 2026 15:56:30 GMT
   Server: example-server
   Content-Type: application/yang-data+json
   Cache-Control: no-cache
   ETag: "a74eefc993a2b"
   Last-Modified: Mon, 5 Jan 2026 14:02:14 GMT

   {
     "example-user-group:user-groups": {
       "@": {
         "ietf-immutable-annotation:immutable": false
       },
       "group": [
         {
           "@": {
             "ietf-immutable-annotation:immutable": true
           },
           "name": "administrator",
           "description": "administrator group",
           "@description": {
             "ietf-immutable-annotation:immutable": false
           },
           "access-level": "admin",
           "user": [
             {
               "name": "ex-username-1",
               "password": "$5$rounds=10000$mysalt123456789$l4BjA1p/8q.\
                                       qCYJ.2pLqjR5mCJf2bP7cLpYWmnC7Hq8"
             },
             {
               "@": {
                 "ietf-immutable-annotation:immutable": false
               },
               "name": "ex-username-2",
               "password": "$1$/h1234q$abcdef1234567890abcdef"
             }
           ],
           "tag": ["system", "non-editable"]
         },
         {
           "@": {
             "ietf-immutable-annotation:immutable": false
           },
           "name": "power-users",
           "description": "Power user group",
           "access-level": "power",
           "user": [

Ma, et al.               Expires 3 January 2027                [Page 24]
Internet-Draft               immutable flag                    July 2026

             {
               "name": "ex-username-3",
               "password": "$1$/h4567q$abcdef2345678901abcdef"
             }
           ],
           "tag": ["system", "editable"]
         }
       ]
     }
   }

      Figure 3: A RESTCONF Example to Retrieve Immutable Configuration

B.3.  The Inheritance of Immutability

   In the example in Figure 2 and Figure 3, there are two "group" list
   entries inside "user-groups" container node.  The "immutable"
   metadata attribute for "user-groups" container instance is "false",
   which is also its default value as the top-level element, and thus
   can be omitted.  The "administrator" list entry is immutable with the
   immutability of its descendant nodes "description" and "user" list
   entry of "ex-username-2" being explicitly toggled.  Other descendant
   nodes (e.g., "access-level", "ex-username-1" user list entry, and
   "tag" leaf-list) inside "administrator" list entry inherit the
   immutability of the list entry, thus are also immutable.

   The "immutable" metadata attribute for "power-users" list entry is
   "false", which is also the same value as its parent node (i.e., the
   "user-groups" container), and thus can be omitted.  Descendant nodes
   (e.g., "description", "access-level", "user" list, and "tag" leaf-
   list) inside "power-users" group inherit the immutability of the list
   entry, thus are also mutable.

B.4.  Immutability of the list

   In the example in Figure 2 and Figure 3, the "group" list as a whole
   inherits immutability from the container "user-groups", which is
   mutable.  One of the list entry named "administrator" is immutable,
   and the other entry named "power-user" is mutable.  The client is
   able to copy the entire "user-groups" container in <running>, add new
   "group" entries, modify the values of descendant nodes of "power-
   users" list entry, but the values of descendant nodes of
   "administrator" list entry cannot be overridden with different values
   except for the "description" and "ex-username-2" user list entry
   nodes, which is explicitly reset to be mutable.  The client may also
   subsequently delete any copied "group" entries or the entire "user-
   groups" container, which will not prevent the deleted data being
   present in <intended> (if implemented) assuming it is still contained

Ma, et al.               Expires 3 January 2027                [Page 25]
Internet-Draft               immutable flag                    July 2026

   in <system>.

   The "user" list inside the "administrator" group list entry as a
   whole inherits immutability from the list entry, which is immutable.
   Thus the client cannot add new user entries inside "administrator"
   group.  As one of the user entry named "ex-username-1" is immutable
   through inheritance, and the other "ex-username-2" user entry is
   explicitly set to be mutable.  The client cannot modify the
   "password" parameter, or add a "full-name" value for user "ex-
   username-1".  but is allowed to update (e.g., modify the "password"
   value, or add a "full-name" value) the list entry for user "ex-
   username-2".  The client may copy or subsequently delete any of the
   two list entries in <running>, but there is no way to delete the
   nodes from <intended> (if implemented).

B.5.  Immutability of the leaf-list

   In the example in Figure 2 and Figure 3, the user-ordered "tag" leaf-
   list node inside the "administrator" group entry as a whole inherits
   immutability from the list entry, which is immutable.  Thus the
   client cannot add, modify, or reorder entries, the client may copy or
   subsequently delete any of the two leaf-list entries in <running>,
   but there is no way to delete the nodes from <intended> if those
   entries appear in <system>.

   The leaf-list node instance inside the "power-users" group entry as a
   whole inherits immutability from the list entry, which is mutable.
   Thus the client can add or reorder entries, the client may copy or
   subsequently delete any of the two leaf-list entries in <running>,
   but there is no way to delete the nodes from <intended> if those
   entries appear in <system>.

B.6.  Error Responses to Clients Overriding Immutable Configuration

   This section provides examples of a client's attempts to override
   immutable configuration and error responses that the server might
   return.  Separate examples are provided for NETCONF and RESTCONF
   protocols, in Figure 4 and Figure 5 respectively.

Ma, et al.               Expires 3 January 2027                [Page 26]
Internet-Draft               immutable flag                    July 2026

   =============== NOTE: '\' line wrapping per RFC 8792 ================

   <rpc message-id="102"
        xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
     <edit-config>
       <target>
         <running/>
       </target>
       <config>
         <user-groups xmlns="urn:example:user-group">
           <group>
             <name>administrator</name>
             <access-level>guest</access-level>
           </group>
         </user-groups>
       </config>
     </edit-config>
   </rpc>

   <rpc-reply message-id="102"
          xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
     <rpc-error>
       <error-type>application</error-type>
       <error-tag>invalid-value</error-tag>
       <error-severity>error</error-severity>
       <error-path xmlns="urn:example:user-group">
         /user-groups/group[name="administrator"]/access-level
       </error-path>
       <error-message xml:lang="en">
         Invalid access-level value because the target node is marked \
                                                            as immutable
       </error-message>
     </rpc-error>
   </rpc-reply>

      Figure 4: A NETCONF Example to Override Immutable Configuration
                            with Error Response

Ma, et al.               Expires 3 January 2027                [Page 27]
Internet-Draft               immutable flag                    July 2026

   =============== NOTE: '\' line wrapping per RFC 8792 ================

   PATCH /restconf/ds/ietf-datastores:running/example-user-group:user-\
                        groups/group=administrator/access-level HTTP/1.1
   Host: example.com
   Content-Type: application/yang-data+json

   {
     "example-user-group:access-level": "guest"
   }

   HTTP/1.1 400 Bad Request
   Content-Type: application/yang-data+json

   {
     "ietf-restconf:errors": {
       "error": [
         {
           "error-type": "application",
           "error-tag": "invalid-value",
           "error-severity": "error",
           "error-path": "/example-user-group:user-groups/group[name='\
                                          administrator']/access-level",
           "error-message": "Invalid access-level value because the \
                                     target node is marked as immutable"
         }
       ]
     }
   }

      Figure 5: A RESTCONF Example to Override Immutable Configuration
                            with Error Response

Appendix C.  Existing Implementations

   Note to the RFC Editor: Please remove this section prior to
   publication.

   There are already a number of full or partial implementations of
   immutability:

   *  3GPP TS 32.156 [TS32.156] and 28.623 [TS28.623]: Requirements and
      a partial solution

   *  ITU-T using ONF TR-531 [TR-531] concept on information model level
      but no YANG representation.

   *  Ericsson: requirements and solution

Ma, et al.               Expires 3 January 2027                [Page 28]
Internet-Draft               immutable flag                    July 2026

   *  YumaPro: requirements and solution

   *  Nokia: partial requirements and solution

   *  Huawei: partial requirements and solution

   *  Cisco using the concept at least in some YANG modules

   *  Junos OS provides a hidden and immutable configuration group
      called junos-defaults

Acknowledgments

   Thanks to Kent Watsen, Jan Lindblad, Jason Sterne, Robert Wilton,
   Andy Bierman, Juergen Schoenwaelder, Reshad Rahman, Anthony Somerset,
   Lou Berger, Joe Clarke, and Scott Mansfield for reviewing, and
   providing important inputs to this document.

   Thanks to Per Andersson for the YANGDOCTORS review.

   Thanks to Mahesh Jethanandani for the AD review.

Authors' Addresses

   Qiufang Ma (editor)
   Huawei
   101 Software Avenue, Yuhua District
   Nanjing, Jiangsu
   210012
   China
   Email: maqiufang1@huawei.com

   Qin Wu
   Huawei
   101 Software Avenue, Yuhua District
   Nanjing, Jiangsu
   210012
   China
   Email: bill.wu@huawei.com

   Balazs Lengyel (editor)
   Ericsson
   Email: balazs.lengyel@ericsson.com

Ma, et al.               Expires 3 January 2027                [Page 29]
Internet-Draft               immutable flag                    July 2026

   Hongwei Li
   HPE
   Email: flycoolman@gmail.com

Ma, et al.               Expires 3 January 2027                [Page 30]