YANG path format (ypath)

1.1. Applicability

Ypath is a string syntax for identifying locations in a YANG data tree. It is intended for use in specifications and implementations that need to:¶

• enumerate or display paths through a YANG schema;¶

• identify specific nodes in YANG instance data;¶

• express filter expressions that select data subsets; and¶

• convey path information in management protocol error reporting.¶

This document defines the ypath format only. It does not specify how ypaths are carried on the wire, stored, or processed by a particular protocol such as NETCONF [RFC6241] or RESTCONF [RFC8040].¶

1.2. Out of Scope

Ypath identifies nodes in a YANG schema or instance tree. Predicates in filter paths apply only to list key values. The following are out of scope for this document:¶

• selection or matching based on the value of any node other than a list key (for example, matching a description or mtu leaf value);¶

• comparison operators, ranges, or expressions over leaf or leaf-list values;¶

• content-based queries across the datastore (for example, "all interfaces where enabled is true"); and¶

• any form of value predicate attached to a non-key node in the path.¶

Such selection belongs in query languages (for example, XPath or JSONPath) or in protocol-specific filter mechanisms, not in ypath. A ypath MAY identify a leaf node (for example, /.../description), but MUST NOT specify a condition on that leaf's value.¶

**TODO: Whilst this section is the initial position, there are use-cases such as a short-form subtree-filter representation for NETCONF that may be useful to include, for example, all interfaces in a YANG list where the enabled child field is set to True.¶

1.3. Relationship to Other Path Formats

Ypath is closely related to, but not identical with, the lexical representation of the YANG instance-identifier built-in type defined in [RFC7950]. Instance-identifiers are used to reference data tree nodes in instance encodings and require key values for list entries. Ypath additionally defines a schema path form (with key names but not values) and filter forms (including wildcards) that are outside the scope of instance-identifier.¶

Where ypath instance path syntax aligns with instance-identifier, the definitions in [RFC7950] form the basis for interpretation unless this document explicitly specifies otherwise. The principal differences for instance paths are:¶

• module names MAY be inherited along the path rather than repeated on every node (see Section 3.2);¶

• numeric and boolean list key values MAY appear without quotes (see Section 3.10.2); and¶

• filter paths MAY use the wildcard * in key values (see Section 3.14);¶

• filter paths MAY use regular expressions in key values (see Section 3.15); and¶

• filter paths MAY use key value sets to match multiple explicit key values (see Section 3.16).¶

Ypath is not a query language. It does not provide the expression evaluation, node set operations, or document traversal capabilities of XPath or JSONPath.¶

1.4. Document Structure

Section 2 describes terms used in this document. Section 1.2 states what ypath does not cover. Section 3 defines the ypath format. Section 4 provides an ABNF grammar. Section 5 defines conformance requirements. Section 6 gives worked examples. Section 7 discusses security implications. Section 8 specifies IANA actions.¶

2.1. Terminology

The following terms are used in this document:¶

ypath:

A path string conforming to the format defined in this document. Short for YANG path.¶

schema path:

A ypath that identifies a location in a YANG schema tree. List key names appear in square brackets without values (for example, [name]).¶

instance path:

A ypath that identifies a location in a YANG instance data tree. List keys and their values appear in square brackets (for example, [name="eth0"]).¶

filter path:

A ypath used to select a set of instance data nodes. Filter paths use wildcards, regular expressions, or key value sets in one or more list key values only. Predicates on non-key node values are out of scope (see Section 1.2).¶

module-qualified name:

A YANG node identifier prefixed with the defining module name and a colon (for example, ietf-interfaces:interfaces).¶

path segment:

A single component of a ypath, consisting of a node name and optional key predicates, separated from adjacent segments by a / character.¶

The terminology for YANG data nodes (for example, leaf, list, container) is defined in [RFC7950].¶

3.1. Root of the YANG Path

A ypath is always expressed from the root of the YANG data tree. A specification that splits a path into a prefix and a sub-path MUST evaluate both parts together from the root.¶

Approach 1:¶

• Path: /item1/item2/item3/item4¶

Approach 2:¶

• Prefix: /item1/item2¶

• Sub-path: /item3/item4¶

• (Yields) Path: /item1/item2/item3/item4¶

3.2. Module-Qualified Names

A ypath uses a module:identifier form where module is the name of the YANG module that defines the node. For example:¶

/ietf-interfaces:interfaces ¶

TODO: Do we need to handle different module versions/semantic versions in the path?¶

The module name is inherited along the path from left to right. If the defining module does not change (as is typical within a single module, and unlike at augment boundaries) the module name does not need to be repeated. For example:¶

/ietf-routing-policy:routing-policy/defined-sets/prefix-sets ¶

It is also valid to provide the module name on every path segment. For example:¶

/ietf-routing-policy:routing-policy/ietf-routing-policy:defined-sets/ietf-routing-policy:prefix-sets ¶

The first path segment of a ypath SHOULD include a module name. This ensures that the path is self-describing without external schema context. A specification that allows omission of the module name on the first segment MUST state the default module to be assumed.¶

TODO: Is the SHOULD correct here or should it be a MUST?¶

3.3. Augmentations

When a node is defined by an augmenting module, the module name in the path MUST change to the augmenting module at the augmented node. For example:¶

/ietf-routing:routing/control-plane-protocols/ietf-ospf:ospf/address-family ¶

In this example, control-plane-protocols is defined in ietf-routing and ospf is defined in ietf-ospf, which augments ietf-routing.¶

The following fully qualified form is equally valid:¶

/ietf-routing:routing/ietf-routing:control-plane-protocols/ietf-ospf:ospf/ietf-ospf:address-family ¶

3.4. Deviations

Deviations do not change the namespace of YANG nodes. The module portion of a ypath therefore does not change at a deviated node.¶

3.5. Import/Include

Imports and includes do not change the namespace of YANG nodes. The module portion of a ypath therefore does not change solely because a node is accessed through an import or include relationship.¶

3.6. Containers

3.7. Leaves

A path to a leaf uses the same final segment in schema and instance paths. The parent path segments differ between schema and instance forms when lists appear above the leaf.¶

Schema example:¶

/ietf-interfaces:interfaces[name]/description ¶

Instance example:¶

/ietf-interfaces:interfaces[name="my_interface"]/description ¶

3.8. Choices

YANG choice nodes are not instantiated in the data tree. A ypath therefore does not include a segment for the choice node itself. The path proceeds directly to the node within the selected case.¶

For example, if protocol is a choice under server and the tcp case is active, the path to the port leaf is:¶

Schema path:¶

/example:server/tcp/port ¶

Instance path:¶

/example:server/tcp/port ¶

When walking a schema tree to enumerate paths, implementations MUST NOT emit a path segment for the choice node.¶

3.9. Identities and Identity References (identityref)

An identityref leaf is referenced by a path to the leaf itself. The identity value is not encoded in the path; it appears in the instance data value.¶

Schema path:¶

/ietf-routing:routing/control-plane-protocols/control-plane-protocol[type]/type ¶

Instance path:¶

/ietf-routing:routing/control-plane-protocols/control-plane-protocol[name="main"]/type ¶

Where the leaf value uses the module-qualified identity name (for example, ietf-ospf:ospf) in the data encoding, that value is not duplicated in the ypath.¶

3.10. Lists

List handling differs between schema paths and instance paths.¶

3.11. Leaf Lists

A schema path to a leaf-list names the leaf-list node:¶

/ietf-system:system/dns/servers ¶

An instance path to a specific leaf-list entry uses the same predicate form as instance-identifier [RFC7950]:¶

/ietf-system:system/dns/servers[.="192.0.2.1"] ¶

An instance path that references the leaf-list node without selecting a particular entry names the leaf-list node without a predicate.¶

A leaf-list-predicate accepts a literal value only (quoted-string or unquoted-value). Wildcards, regular expressions, and key value sets MUST NOT be used in leaf-list predicates.¶

TODO: This is a first approach to this issue. It could be considered out-of-scope to identify specific leaf-list entries or this same approach could be used to allow for matching of other specific values (such as leafs) as a solution to that problem¶

3.12. Metadata Annotations

Metadata annotations defined in [RFC7952] are not part of the ypath syntax. A ypath identifies a data tree node only; it does not reference metadata annotations attached to nodes.¶

3.13. Actions

A ypath to a YANG action names the action node. For example:¶

/example:mycontainer/do-something ¶

The action input and output nodes are not included in the path used to invoke the action. Input parameters are supplied separately in the protocol or API operation that invokes the action.¶

TODO: Consider how input/output paths should be displayed. One solution is to add a new notation to show input and output. This is needed as input and output fields to an action may have name collisions, for example, the input name and the output name which would appear as /example:mycontainer/do-something/name for both despite being distinctly separate fields. A proposal might be the :: notation to signify that the name before it specifies whether it is input or output with these being the only supported options, for example,¶

/example:mycontainer/do-something/input::name and /example:mycontainer/do-something/output::name ¶

3.14. Wildcards

Filter paths MAY use a wildcard, a regular expression (see Section 3.15), or a key value set (see Section 3.16) in list key predicates. These forms apply only to filter paths; they are not used in schema paths.¶

For string-typed keys, the wildcard MUST appear inside double quotes:¶

/ietf-interfaces:interfaces[name="*"] ¶

For numeric or boolean keys, the unquoted form MAY be used:¶

/example:items/item[index=*] ¶

TODO: Need to rethink whether * alone is sufficient or whether it needs to be inside double-quotes for string types, or whether it would be better inside single quotes in case * is a string value that might be confused with a wildcard¶

If any key in a multi-key list uses a wildcard, all keys in that list entry MUST use wildcards. Mixing wildcards and specific values for different keys of the same list entry is not permitted. For example:¶

Valid:¶

/module:list[key1="*"][key2="*"] ¶

Not valid:¶

/module:list[key1="foo"][key2="*"] ¶

3.15. Regular Expressions

Filter paths MAY use a regular expression as a list key value to match multiple list entries. Regular expressions apply only to list key predicates in filter paths. They MUST NOT be used in schema paths or in instance paths that identify a single known node.¶

A regular expression key value uses the form r'pattern', where pattern is the regular expression body enclosed in single quotes. For example, to select the description leaf on all interfaces whose name begins with a or A:¶

/ietf-interfaces:interfaces/interface[name=r'^[aA].*']/description ¶

The r prefix distinguishes a regular expression from a literal string value. The pattern is matched against the string representation of the list key value in the data encoding used by the implementation (for example, the JSON encoding defined in [RFC7951]).¶

Regular expression key values MUST use the r'...' form. Double-quoted strings MUST NOT be used to encode regular expressions.¶

3.16. Key Value Sets

Filter paths MAY use a key value set to match a list entry when the key value equals any one of a given set of explicit values. Key value sets apply only to list key predicates in filter paths. They MUST NOT be used in schema paths or in instance paths that identify a single known node.¶

A key value set uses curly braces enclosing a comma-separated list of key values. For example, to select the description leaf on interfaces named ethernet1 or ethernet3:¶

/ietf-interfaces:interfaces/interface[name={"ethernet1", "ethernet3"}]/description ¶

An implementation matches the list entry if the key value is equal to any member of the set. The comparison uses the same string representation of key values as instance paths (see Section 3.10.2).¶

3.17. Relationship to JSON Encoding

Considering the instance path /ietf-routing:routing/control-plane-protocols/ietf-ospf:ospf/address-family with a value of ipv4, the corresponding JSON based on [RFC7951] is:¶

{ "ietf-routing:routing": { "control-plane-protocols": { "ietf-ospf:ospf": { "address-family": "ipv4" } } } } ¶

5.1. Producers

A ypath producer (for example, a tool that emits schema paths or an interface that returns the current context path) MUST:¶

• generate paths that conform to the grammar in Section 4;¶

• use a leading / on every path;¶

• include a module name on the first path segment unless a specification defines a default module for the context; and¶

• use schema predicates for schema paths and value predicates for instance paths.¶

A producer generating filter paths MUST use * only as specified in Section 3.14, regular expressions only as specified in Section 3.15, and key value sets only as specified in Section 3.16.¶

5.2. Consumers

A ypath consumer (for example, a management API or path parser) MUST:¶

• reject paths that do not conform to the grammar in Section 4;¶

• resolve module inheritance from left to right along the path; and¶

• apply module name changes at augment boundaries.¶

A consumer that does not support filter paths MUST reject paths containing the wildcard *, a regex-value, or a key-value-set in key predicates.¶

5.3. Path Enumeration

An implementation that walks a YANG schema and returns ypaths MUST return schema paths with list key names in bracket pairs and MUST NOT return paths that address list keys as child node segments.¶

6.1. Referencing YANG Paths in NETCONF Filters

NETCONF subtree filters [RFC6241] select data by structure rather than by a single path string. A ypath can nonetheless identify the subtree root that a filter targets. For example, to retrieve all interfaces, a client might use the filter path:¶

/ietf-interfaces:interfaces[name="*"] ¶

The enclosing specification or implementation maps this ypath to the appropriate NETCONF filter payload.¶

6.2. Filter Paths with Regular Expressions

A filter path can use a regular expression in a key predicate to match a subset of list entries. For example, to retrieve the description leaf for all interfaces whose name starts with a or A:¶

/ietf-interfaces:interfaces/interface[name=r'^[aA].*']/description ¶

An implementation evaluates the regular expression against each candidate list key value and includes matching entries in the result set.¶

6.3. Filter Paths with Key Value Sets

A filter path can use a key value set to match multiple list entries with explicit key values. For example, to retrieve the description leaf for interfaces ethernet1 and ethernet3:¶

/ietf-interfaces:interfaces/interface[name={"ethernet1", "ethernet3"}]/description ¶

An implementation includes each list entry whose key value equals any member of the set.¶

6.4. Referencing YANG Paths in NETCONF rpc-error Messages

NETCONF rpc-error replies include an error-path element [RFC6241] that identifies the node associated with the error. An implementation may populate error-path using ypath instance syntax. For example:¶

/ietf-interfaces:interfaces[name="eth0"]/mtu ¶

6.5. Checking Existence

An implementation can test whether a node exists in a datastore by resolving an instance path. For example, the path:¶

/ietf-interfaces:interfaces[name="eth0"] ¶

identifies a specific list entry. If the path resolves to an existing node, the entry is present; if resolution fails, the entry is absent. The mechanism by which resolution is performed is defined by the enclosing API or protocol.¶

7.1. Path Parsing and Ambiguity

Implementations that parse ypath strings MUST treat parsing as security sensitive when the resulting path is used to access or modify managed data. Ambiguous, malformed, or unexpectedly complex paths could cause an implementation to resolve a different node than the operator or application intended. Specifications that use ypath SHOULD define error handling for invalid paths and SHOULD NOT silently accept ambiguous forms (for example, inconsistent module prefix usage that could identify more than one schema node).¶

7.2. Wildcards and Pattern Matching

Filter paths that use wildcards, regular expressions, or key value sets in key predicates can match large sets of instance data. An implementation that expands such a path into concrete instance paths or data retrieval operations MUST consider the cost of expansion and SHOULD enforce limits on the number of matched nodes. Implementations SHOULD enforce a reasonable upper bound on the number of members in a key value set.¶

Regular expression evaluation can be subject to excessive resource consumption (including regular expression denial of service) if arbitrary patterns are accepted from untrusted input. Implementations SHOULD enforce limits on evaluation time and SHOULD reject patterns that are not valid POSIX ERE expressions. Specifications that expose regular expression filter paths to untrusted clients SHOULD document these limits.¶

7.3. Information Disclosure

Path enumeration (for example, listing all valid ypaths for a schema or datastore) can reveal the structure of deployed models and, for instance paths, the values of list keys. Interfaces that expose path lists SHOULD apply the same access controls as the underlying data access mechanism so that a client cannot use path enumeration to discover information it is not authorized to retrieve directly.¶

7.4. Use in Authorization Policies

If ypaths are used to express authorization rules (for example, permitting access only to a given subtree), care is required to ensure that equivalent paths using different but valid module prefix forms receive consistent treatment. Authorization systems SHOULD define a canonical comparison rule or SHOULD normalize paths before evaluation.¶

7.5. Privacy

Instance paths embed key values that may identify subscribers, endpoints, or other privacy-sensitive entities. Logs, error messages, and telemetry that include ypath strings SHOULD be protected commensurate with the sensitivity of the referenced data.¶

9.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, <https://www.rfc-editor.org/rfc/rfc2119>.

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

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

9.2. Informative References

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

[RFC7951]

Lhotka, L., "JSON Encoding of Data Modeled with YANG", RFC 7951, DOI 10.17487/RFC7951, August 2016, <https://www.rfc-editor.org/rfc/rfc7951>.

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

[RFC9535]

Gössner, S., Ed., Normington, G., Ed., and C. Bormann, Ed., "JSONPath: Query Expressions for JSON", RFC 9535, DOI 10.17487/RFC9535, February 2024, <https://www.rfc-editor.org/rfc/rfc9535>.

[XPATH]

W3C, "XML Path Language (XPath) Version 1.0", <https://www.w3.org/TR/1999/REC-xpath-19991116/>.