Extending Normalized Forms to String-Derived Types

Status of This Memo

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

Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at 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 May 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

YANG [RFC7950] treats values of type string as lexically distinct; equality and uniqueness are therefore determined by exact string comparison.¶

YANG defines normalized representations for many built-in data types. Canonical or normalized forms provide a unique representation of a value independent of how it may have been entered or encoded.¶

For string-derived types, YANG currently provides no mechanism to define a normalized form distinct from the lexical representation. As a result, semantically equivalent values that have multiple valid lexical representations may not compare equal and may not be detected as duplicates.¶

This issue has been observed in both IETF and IEEE YANG modules, leading to interoperability problems and incorrect duplicate detection. Existing YANG typedefs such as mac-address ([RFC6991], [RFC9911]) define syntax but do not define normalized comparison semantics.¶

A prominent example is the representation of MAC addresses in YANG. IETF and IEEE modules define different lexical forms for MAC addresses, and equivalent values may not compare equal when represented using different valid formats. This problem is described in Appendix A.¶

While MAC addresses provide a clear motivating example, the underlying issue is more general. YANG lacks a mechanism for schema authors to define normalized forms for string-derived types whose lexical space permits multiple representations of the same underlying value.¶

The resulting normalized form is used for equality-based operations. The normalized form is an abstract comparison value and is not a new lexical representation. This extension does not alter the lexical space or encoding requirements of the underlying YANG type.¶

This mechanism is intentionally non-invasive.¶

This extension defines a normalization procedure for determining semantic equivalence between values. Unless explicitly defined by a future extension, it does not alter the relational comparison semantics of the underlying YANG type. Operations based on equality (such as equality tests and uniqueness evaluation) operate on the normalized form. Relational operators (<, <=, >, >=) continue to use the semantics of the underlying type.¶

Existing YANG modules remain valid and unchanged. The extension is applied only where normalized forms are needed and has no effect on implementations that do not support it.¶

2. Terminology

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.¶

3. Problem Statement

When string-derived types permit multiple lexical representations of the same value, the following issues can arise:¶

• Semantically equivalent values may not compare equal.¶

• Duplicate entries may not be detected in keyed lists.¶

• Leaf-list uniqueness constraints may be violated.¶

• XPath equality comparisons may yield incorrect results.¶

Pattern restrictions alone do not solve this problem, because they validate syntax but do not consider comparison semantics.¶

4. Design Goals

The solution defined in this document:¶

• MUST NOT alter the lexical space or encoding requirements of the underlying type.¶

• MUST provide deterministic comparison semantics.¶

• MUST apply to equality and uniqueness operations.¶

• MUST be minimally invasive to existing YANG modules.¶

• MUST be opt-in and backward compatible.¶

• MUST be general across string-derived types.¶

• SHOULD be simple to implement.¶

• SHOULD avoid complex transformation languages.¶

5. Proposed Solution

module ietf-yang-normalized-form {
  yang-version 1.1;
  namespace
    "urn:ietf:params:xml:ns:yang:ietf-yang:normalized-form";
  prefix iynf;
  organization
    "IETF NETMOD Working Group";

  contact
    "WG Web: <https://datatracker.ietf.org/wg/netmod/>
     WG List: <mailto:netmod@ietf.org>";

  description
    "Defines an extension for declaring a normalized
     form for string-derived types.";
  revision 2026-07-01 {
    description "Initial revision.";
    reference "TBD: This document.";
  }
  identity normalized-form {
    description
      "Base identity for normalized forms.";
  }
  identity mac-48 {
    base normalized-form;
    description
      "Normalized form for a 48-bit MAC address.

       The input value MUST first be valid according to the
       lexical space of the type to which this normalized form
       is applied. All separators are removed and hexadecimal
       digits 'a' through 'f' are converted to uppercase. The
       resulting normalized form consists of 12 uppercase
       hexadecimal digits.";
  }
  extension normalized-form {
    argument form;
    description
      "Specifies a deterministic normalization form
       used to derive the normalized form of a value.";
  }
}

aa:bb:cc:dd:ee:ff
AA:BB:CC:DD:EE:FF
aa-bb-cc-dd-ee-ff
AA-BB-CC-DD-EE-FF

AABBCCDDEEFF

6. Design Rationale

A normalized-form identity names a normalization algorithm rather than a regular-expression pattern. Pattern restrictions can constrain lexical syntax, but they cannot in general express normalization procedures such as case folding, separator removal, IPv6 textual normalization, or other procedural transformations. The identity therefore provides a stable name for a fully specified normalization procedure. A pattern may be useful as part of the description of a simple normalization, but it is not sufficient as the general mechanism defined by this document.¶

7. Example Usage

The definition should be in a top level YANG module. While new types with the normalized form could be created it is also valid to just modify in place IEEE mac-address to support the normalized form.¶

8. IEEE MAC Address example

The following example show that the normalized form can be added to any definition. Below is an IEEE example.¶

      leaf address {
        type ieee:mac-address;
        iynf:normalized-form "iynf:mac-48";
        mandatory true;
        description
          "A sample IEEE MAC address format.";
      }

9. IETF MAC Address example

The following example show that the normalized form can be added to any definition. Below is an IETF example.¶

      leaf address {
        type ietf:mac-address;
        iynf:normalized-form "iynf:mac-48";
        mandatory true;
        description
          "A sample IETF MAC address format.";
      }

10. Comparison Example

The following values use different lexical representations but identify the same underlying 48-bit MAC address:¶

aa:bb:cc:dd:ee:ff
AA-BB-CC-DD-EE-FF

Because both types declare the same mac-48 normalized form, both values yield the same normalized form:¶

   AABBCCDDEEFF

Implementations that support this extension compare the values using the normalized form for equality and uniqueness operations, while preserving each type's lexical requirements.¶

11. List Key Example

list fdb-entry {
    key "mac vlan";
    leaf mac {
      type mac-address;
      iynf:normalized-form "iynf:mac-48";
    }
    leaf vlan {
        type uint16;
    }
    leaf port {
        type string;
    }
}

A list key using the IETF typedef continues to accept only the IETF colon-separated lexical form. A corresponding IEEE model can use the IEEE typedef and preserve the IEEE dash-separated lexical form. In both cases, the shared mac-48 normalized form enables consistent equality and duplicate detection across representations.¶

12. Backward Compatibility

Existing YANG models are unaffected unless the extension is used. The lexical space and encoding requirements of the underlying type are unchanged. Behavior changes only for operations whose semantics depend on equality or identity.¶

13. Applicability

While motivated by MAC addresses, this mechanism can apply to any string-derived type with multiple equivalent representations, including case-insensitive identifiers, formatted identifiers, and normalized encodings.¶

14. Security Considerations

Normalization reduces ambiguity and helps prevent duplicate or conflicting configuration entries.¶

Implementations MUST ensure that normalization algorithms are deterministic and unambiguous.¶

15. IANA Considerations

This document has no IANA actions.¶

16. References

Appendix A. MAC Address Representation Background

   90:10:00:01:02:aa

   90-10-00-01-02-AA

typedef mac-address {
 type string {
   pattern '[0-9a-fA-F]{2}(:[0-9a-fA-F]{2}){5}';
 }
 description
  "The mac-address type represents an IEEE 802 MAC address.
   The canonical representation uses lowercase characters.

   In the value set and its semantics, this type is equivalent
   to the MacAddress textual convention of the SMIv2.";
 reference
  "IEEE 802: IEEE Standard for Local and Metropolitan Area
             Networks: Overview and Architecture
   RFC 2579: Textual Conventions for SMIv2";
}

typedef mac-address {
 type string {
   pattern "[0-9a-fA-F]{2}(-[0-9a-fA-F]{2}){5}";
 }
 description
   "The mac-address type represents a MAC address in the canonical
    format and hexadecimal format specified by IEEE Std 802. The
    hexadecimal representation uses uppercase characters.";
 reference
   "3.1, 8.1 of IEEE Std 802";
}

Acknowledgments

The authors would like to thank Balazs Lengyel and Joe Clarke for their comments.¶

Authors' Addresses