Network Modeling D. Fedyk
Internet-Draft LabN Consulting, L.L.C.
Intended status: Standards Track S. Mansfield
Expires: 3 May 2027 Ericsson
30 October 2026
Extending Normalized Forms to String-Derived Types
draft-fedyk-netmod-yang-normal-form-01
Abstract
YANG models frequently define identifiers using string or string-
derived types whose lexical space permits multiple representations of
the same underlying value. This can lead to incorrect behavior when
semantically equivalent values are compared lexically.
This document adds an optional extension to the existing YANG concept
of normalized form to string-derived types whose lexical space
permits multiple representations of the same underlying value.
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
Fedyk & Mansfield Expires 3 May 2027 [Page 1]
Internet-Draft YANG String Normalized Form October 2026
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 . . . . . . . . . . . . . . . . . . . . . . . . 2
2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4
3. Problem Statement . . . . . . . . . . . . . . . . . . . . . . 4
4. Design Goals . . . . . . . . . . . . . . . . . . . . . . . . 4
5. Proposed Solution . . . . . . . . . . . . . . . . . . . . . . 5
5.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . 5
5.2. YANG Extension Definition . . . . . . . . . . . . . . . . 6
5.3. Semantics . . . . . . . . . . . . . . . . . . . . . . . . 7
5.4. Normalized identity . . . . . . . . . . . . . . . . . . . 8
5.4.1. mac-48 . . . . . . . . . . . . . . . . . . . . . . . 8
6. Design Rationale . . . . . . . . . . . . . . . . . . . . . . 9
7. Example Usage . . . . . . . . . . . . . . . . . . . . . . . . 9
8. IEEE MAC Address example . . . . . . . . . . . . . . . . . . 9
9. IETF MAC Address example . . . . . . . . . . . . . . . . . . 10
10. Comparison Example . . . . . . . . . . . . . . . . . . . . . 10
11. List Key Example . . . . . . . . . . . . . . . . . . . . . . 10
12. Backward Compatibility . . . . . . . . . . . . . . . . . . . 11
13. Applicability . . . . . . . . . . . . . . . . . . . . . . . . 11
14. Security Considerations . . . . . . . . . . . . . . . . . . . 11
15. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 11
16. References . . . . . . . . . . . . . . . . . . . . . . . . . 11
16.1. Normative References . . . . . . . . . . . . . . . . . . 11
16.2. Informative References . . . . . . . . . . . . . . . . . 12
Appendix A. MAC Address Representation Background . . . . . . . 12
A.1. Background . . . . . . . . . . . . . . . . . . . . . . . 12
A.2. Current State . . . . . . . . . . . . . . . . . . . . . . 12
A.3. Detail . . . . . . . . . . . . . . . . . . . . . . . . . 13
A.3.1. IETF Format . . . . . . . . . . . . . . . . . . . . . 13
A.3.2. IEEE Format . . . . . . . . . . . . . . . . . . . . . 13
A.4. Why Normalized Form Helps . . . . . . . . . . . . . . . . 13
Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 14
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 14
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.
Fedyk & Mansfield Expires 3 May 2027 [Page 2]
Internet-Draft YANG String Normalized Form October 2026
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.
Fedyk & Mansfield Expires 3 May 2027 [Page 3]
Internet-Draft YANG String Normalized Form October 2026
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.
Fedyk & Mansfield Expires 3 May 2027 [Page 4]
Internet-Draft YANG String Normalized Form October 2026
5. Proposed Solution
5.1. Overview
This document defines a YANG extension that allows a string-derived
type to specify a normalization algorithm.
The resulting normalized form is used for equality-based operations,
including equality comparisons, list-key identity, leaf-list
uniqueness, and evaluation of the YANG unique statement. The
normalized representation is not required to appear in an encoding or
retrieval operation.
This extension does not modify the lexical space of an existing YANG
type and does not require changes to existing typedef definitions.
The extension may be attached to existing types, derived types, or
schema nodes where normalized form behavior is desired.
Implementations that do not understand the extension continue to
process the lexical type normally. Implementations that advertise
support for the extension apply the specified normalization algorithm
for equality and uniqueness operations.
Use of this extension does not, by itself, change the behavior of
implementations that do not support it.
A leafref whose target type has a normalized form MUST use that
normalized form when determining whether its value identifies an
existing target instance. When evaluating an instance-identifier,
predicate values corresponding to list keys or leaf-list values
having a normalized form MUST be validated according to the
corresponding schema node's type and compared using normalized
equality. The normalized representation is not required to appear in
the instance-identifier lexical value.
For NETCONF insertion before or after an existing user-ordered list
or leaf-list entry, values carried in yang:key or yang:value MUST
conform to the lexical space of the corresponding schema node. When
the server resolves the target entry, it MUST use normalized equality
if the corresponding schema node has a normalized form. The
normalized representation itself is not required to appear in
yang:key or yang:value.
Fedyk & Mansfield Expires 3 May 2027 [Page 5]
Internet-Draft YANG String Normalized Form October 2026
When a NETCONF subtree-filter content-match node corresponds to a
schema node having a normalized form, the filter value MUST first be
valid according to the target node's YANG type. The server MUST
compare the filter value and datastore value using their normalized
forms. Normalization does not expand the lexical space accepted by
the type, and a retrieved value continues to use the encoding rules
of the underlying type.
5.2. YANG Extension Definition
Fedyk & Mansfield Expires 3 May 2027 [Page 6]
Internet-Draft YANG String Normalized Form October 2026
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:
WG List: ";
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.";
}
}
5.3. Semantics
If a type includes the normalized-form extension:
1. A normalized form MUST be derived using the specified identity.
Fedyk & Mansfield Expires 3 May 2027 [Page 7]
Internet-Draft YANG String Normalized Form October 2026
2. Equality comparisons, including = and !=, MUST use the normalized
form.
3. List-key identity and list-key uniqueness MUST be evaluated using
the normalized form.
4. Leaf-list uniqueness MUST be enforced using the normalized form.
5. Evaluation of the YANG unique statement MUST use the normalized
form for each referenced descendant schema node that has a
normalized form.
6. A leafref whose target type has a normalized form MUST use that
normalized form when determining whether its value identifies an
existing target instance.
7. When evaluating an instance-identifier, predicates that identify
list-key or leaf-list values having a normalized form MUST use
normalized equality after validating the predicate value against
the corresponding schema node's lexical space.
8. Relational operators (<, <=, >, >=) are not changed by this
extension and continue to use the semantics of the underlying
YANG type.
9. The lexical representation MUST NOT be modified solely to satisfy
this extension.
5.4. Normalized identity
Normalized forms are identified by identity and are associated with a
deterministic algorithm.
5.4.1. mac-48
The mac-48 identity applies to 48-bit MAC addresses represented as
six hexadecimal octets. The lexical representation is defined by the
type that uses the extension.
The normalization procedure is:
1. Validate the input against the lexical space of the type to which
the normalized form is applied.
2. Remove the separator characters permitted by the lexical
representation of the underlying type.
3. Convert hexadecimal digits to uppercase.
Fedyk & Mansfield Expires 3 May 2027 [Page 8]
Internet-Draft YANG String Normalized Form October 2026
4. Use the resulting 12 hexadecimal digits as the normalized form of
the MAC address.
Equivalent inputs include:
aa:bb:cc:dd:ee:ff
AA:BB:CC:DD:EE:FF
aa-bb-cc-dd-ee-ff
AA-BB-CC-DD-EE-FF
These values yield the same normalized form:
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.";
}
Fedyk & Mansfield Expires 3 May 2027 [Page 9]
Internet-Draft YANG String Normalized Form October 2026
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;
}
}
Fedyk & Mansfield Expires 3 May 2027 [Page 10]
Internet-Draft YANG String Normalized Form October 2026
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
16.1. Normative References
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997,
.
[RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types",
RFC 6991, DOI 10.17487/RFC6991, July 2013,
.
[RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language",
RFC 7950, DOI 10.17487/RFC7950, August 2016,
.
Fedyk & Mansfield Expires 3 May 2027 [Page 11]
Internet-Draft YANG String Normalized Form October 2026
[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
May 2017, .
[RFC9911] Schönwälder, J., Ed., "Common YANG Data Types", RFC 9911,
DOI 10.17487/RFC9911, December 2025,
.
16.2. Informative References
[IEEE-802-1Qcw]
IEEE, "IEEE Standard for Local and Metropolitan Area
Networks--Bridges and Bridged Networks Amendment 36: YANG
Data Models for Scheduled Traffic, Frame Preemption, and
Per-Stream Filtering and Policing", IEEE 802.1Qcw-2023, 17
November 2023,
.
Appendix A. MAC Address Representation Background
A.1. Background
MAC Address Formats in the IETF and IEEE YANG modules are different.
A.2. Current State
The IETF and IEEE YANG modules define MAC-address types derived from
the YANG string type, but use different lexical patterns and
canonical representations. The issue is that the IETF and IEEE use
different patterns and have different canonical forms, which leads to
a situation where equivalent MAC Addresses will not match.
Both organizations have a long history of supporting these formats.
This appendix is meant to document the issue, and support the
solution proposed in this document.
For example, the following MAC Address is in IETF Canonical Format
90:10:00:01:02:aa
For example, the following MAC Address is in IEEE Canonical Format
90-10-00-01-02-AA
The MAC addresses are equivalent, but will not match if used in an
XPath, or as a key, or any string comparison.
Fedyk & Mansfield Expires 3 May 2027 [Page 12]
Internet-Draft YANG String Normalized Form October 2026
There are several potential trouble spots in published IETF YANG
modules.
A.3. Detail
A.3.1. IETF Format
The IETF Format (from ietf-yang-types@2013-07-15.yang) [RFC9911] used
in the mac-address typedef is found below.
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";
}
A.3.2. IEEE Format
The IEEE Format used in the mac-address typedef [IEEE-802-1Qcw] is
found below.
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";
}
A.4. Why Normalized Form Helps
Normal form allows these definitions to remain. The YANG extension
described in this document enables comparison of MAC addresses
regardless of the format.
Fedyk & Mansfield Expires 3 May 2027 [Page 13]
Internet-Draft YANG String Normalized Form October 2026
Acknowledgments
The authors would like to thank Balazs Lengyel and Joe Clarke for
their comments.
Authors' Addresses
Don Fedyk
LabN Consulting, L.L.C.
Email: dfedyk@labn.net
Scott Mansfield
Ericsson
Email: scott.mansfield@ericsson.com
Fedyk & Mansfield Expires 3 May 2027 [Page 14]
.