Skip to content

Latest commit

 

History

History
213 lines (191 loc) · 5.89 KB

gnmi-path-strings.md

File metadata and controls

213 lines (191 loc) · 5.89 KB

Representing gNMI Paths as Strings

Authors: robjs, aashaikh, csl, hines.
@google.com

October 2018

Overview

This document provides a specification for the representation of a gNMI Path message as a string. String encoding MUST NOT be used within the protocol, but provides means to simplify human interaction with gNMI paths - for example, in device or daemon configuration.

String Representation of a Single Element

A gNMI path consists of a series of PathElem messages. These messages consist of a name and a map of keys. Each PathElem is represented as a string in the form:

name[key1=val1][key2=val2]

Where name is the PathElem name field, key1 represents a key of the keys map, and val1 represents the value corresponding to key1 within the map. Where multiple keys are present (as shown with key1 and key2) the values are encoded in the form:

[key=value]

and appended to the string. If the key value contains a ] character, it is escaped by preceding it with the backslash (\) character. Only ] and \ characters must be escaped. Newlines and carriage returns are encoded as \n and \r respectively. Unicode characters are encoded as \u1234 or \U1234.

If multiple keys exist for a particular element, they MUST be specified sorted alphabetically by the key name.

String Representation of an Entire Path

Using the format for each PathElem described above, the entire path is formed by concatenating the series of strings with a / character between each PathElem. If the path is absolute (i.e., starts at the schema root), it is preceded by a / character. The prefix + path expressed in gNMI is always absolute.

Stringified Path Examples

Path String Encoding
  prefix: <
        elem: <
                name: "a"
        >
  >
  path: <
        elem: <
                name: "b"
        >
        elem: <
                name: "c"
        >
  >
/a/b/c
<
          elem: <
                  name: "interfaces"
          >
            elem: <
                  name: "interface"
                  key: <
                          key: "name"
                          value: "Ethernet1/2/3"
                  >
          >
          elem: <
                  name: "state"
          >
>
/interfaces/interface[name=Ethernet/1/2/3]/state
<
                elem: <
                        name: "interfaces"
                >
                elem: <
                        name: "interface"
                        key: <
                                key: "name"
                                value: "Ethernet1/2/3"
                        >
                >
                elem: <
                        name: "state"
                >
                elem: <
                        name: "counters"
                >
        >
>
/interfaces/interface[name=Ethernet/1/2/3]/state/counters
<
        elem: <
                name: "network-instances"
        >
        elem: <
                name: "network-instance"
                key: <
                        key: "name"
                        value: "DEFAULT"
                >
        >
        elem: <
                name: "protocols"
        >
        elem: <
                name: "protocol"
                key: <
                        key: "identifier"
                        value: "ISIS"
                >
                key: <
                        key: "name"
                        value: "65497"
                >
        >
>
/network-instances/network-instance[name=DEFAULT]/protocols/protocol[identifier=ISIS][name=65497]
<
        elem: <
                name: "foo"
                key: <
                        key: "name"
                        value: "]"
                >
        >
>
/foo[name=\]]
<
        elem: <
                name: "foo"
                key: <
                        key: "name"
                        value: "["
                >
        >
>
/foo[name=[]
<
        elem: <
                name: "foo"
                key: <
                        key: "name"
                        value: "[\]"
                >
        >
>
/foo[name=[\\\]]

A reference implementation of path to string encoding, and string to path can be found in ygot's pathstrings.go.