From 4fbdb7434a29e04827fccbbf65baefef19f61f5d Mon Sep 17 00:00:00 2001 From: ElodinLaarz Date: Thu, 5 Mar 2026 09:06:02 -0800 Subject: [PATCH 1/7] chore: format --- rpc/gnmi/gnmi-specification.md | 651 +++++++++++++++++---------------- 1 file changed, 331 insertions(+), 320 deletions(-) diff --git a/rpc/gnmi/gnmi-specification.md b/rpc/gnmi/gnmi-specification.md index 024763e..d46d40f 100644 --- a/rpc/gnmi/gnmi-specification.md +++ b/rpc/gnmi/gnmi-specification.md @@ -25,7 +25,7 @@ May 25, 2023 - [2.2.2.1 Path Target](#2221-path-target) - [2.2.3 Node Values](#223-node-values) - [2.3 Structured data types](#23-structured-data-types) - - [2.3.1 JSON and JSON\_IETF](#231-json-and-json_ietf) + - [2.3.1 JSON and JSON_IETF](#231-json-and-json_ietf) - [2.3.2 Bytes](#232-bytes) - [2.3.3 Protobuf](#233-protobuf) - [2.3.4 ASCII](#234-ascii) @@ -35,7 +35,7 @@ May 25, 2023 - [2.5 Error handling](#25-error-handling) - [2.6 Schema Definition Models](#26-schema-definition-models) - [2.6.1 The ModelData message](#261-the-modeldata-message) - - [2.7 gNMI Origin in `Path`](#27-gnmi-origin--in-path) + - [2.7 gNMI Origin in `Path`](#27-gnmi-origin--in-path) - [2.7.1 Special Values of `origin`](#271-special-values-of-origin) - [2.7.2 Definition of `origin` for YANG-modelled Data](#272-definition-of-origin-for-yang-modelled-data) - [2.7.3 Partial Specifications of Origin in Set](#273-partial-specifications-of-origin-in-set) @@ -92,7 +92,7 @@ telemetry and configuration RPCs. All messages within the gRPC service definition are defined as [protocol buffers](https://developers.google.com/protocol-buffers/) (specifically proto3). gRPC service definitions are expected to be described using the relevant -features of the protobuf IDL. The [protobuf definition of +features of the protobuf IDL. The [protobuf definition of gNMI](https://github.com/openconfig/gnmi/blob/master/proto/gnmi/gnmi.proto) is maintained in the [openconfig/gnmi](https://github.com/openconfig/gnmi) GitHub repository. @@ -102,8 +102,8 @@ contain data instances of [OpenConfig](http://www.openconfig.net/) YANG schemas, but can be used for any data with the following characteristics: 1. structure can be represented by a tree structure where nodes can be uniquely - identified by a path consisting of node names, or node names coupled with - attributes; + identified by a path consisting of node names, or node names coupled with + attributes; 1. values can be serialised into a scalar object. Currently, values may be serialised to a scalar object through encoding as a @@ -113,15 +113,15 @@ is possible. Throughout this specification the following terminology is used: - *Telemetry* - refers to streaming data relating to underlying - characteristics of the device - either operational state or configuration. + characteristics of the device - either operational state or configuration. - *Configuration* - elements within the data schema which are read/write and - can be manipulated by the client. + can be manipulated by the client. - *Target* - the device within the protocol which acts as the owner of the - data that is being manipulated or reported on. Typically this will be a - network device. + data that is being manipulated or reported on. Typically this will be a + network device. - *Client* - the device or system using the protocol described in this - document to query/modify data on the target, or act as a collector for - streamed data. Typically this will be a network management system. + document to query/modify data on the target, or act as a collector for + streamed data. Typically this will be a network management system. # 2 Common Message Types and Encodings @@ -129,43 +129,42 @@ Throughout this specification the following terminology is used: When a target wishes to communicate data relating to the state of its internal database to an interested client, it does so via means of a common -`Notification` message. `Notification` messages are reused in other +`Notification` message. `Notification` messages are reused in other higher-layer messages for various purposes. The exact use of the `Notification` message is described on a per-RPC basis. The fields of the Notification message are as follows: - `timestamp` - The time at which the data was collected by the device from - the underlying source, or the time that the target generated the - Notification message (in the case that the data does not reflect an - underlying data source). This value is always represented according to the - definition in [2.2.1](#221-timestamps). + the underlying source, or the time that the target generated the + Notification message (in the case that the data does not reflect an + underlying data source). This value is always represented according to the + definition in [2.2.1](#221-timestamps). - `prefix` - a prefix which is applied to all path fields (encoded as per - [2.2.2](#222-paths)) included in the `Notification` message. The paths - expressed within the message are formed by the concatenation of `prefix + - path`. The `prefix` always precedes the `path` elements. Further semantics - of prefixes are described in [2.4.1](#241-path-prefixes). + [2.2.2](#222-paths)) included in the `Notification` message. The paths + expressed within the message are formed by the concatenation of `prefix + path`. The `prefix` always precedes the `path` elements. Further semantics + of prefixes are described in [2.4.1](#241-path-prefixes). - `update` - a list of update messages that indicate changes in the underlying - data of the target. Both modification and creation of data is expressed - through the update message. + data of the target. Both modification and creation of data is expressed + through the update message. - An `Update` message has three subfields: - `path` - a path encoded as per [2.2.2](#222-paths). - `val` - a value encoded as per [2.2.3](#223-node-values). - `duplicates` - a counter value that indicates the number of - coalesced duplicates. If a client is unable to keep up with the - server, coalescion can occur on a per update (i.e., per path) basis - such that the server can discard previous values for a given update - and return only the latest. In this case the server SHOULD increment - a count associated with the update such that a client can detect - that transitions in the state of the path have occurred, but were - suppressed due to its inability to keep up. + coalesced duplicates. If a client is unable to keep up with the + server, coalescion can occur on a per update (i.e., per path) basis + such that the server can discard previous values for a given update + and return only the latest. In this case the server SHOULD increment + a count associated with the update such that a client can detect + that transitions in the state of the path have occurred, but were + suppressed due to its inability to keep up. - The set of paths that are specified within the list of updates MUST be - unique. In this context, the path is defined to be the fully resolved - path (including the prefix). In the case that there is a duplicate path - specified within an update, only the final update should be processed by - the receiving entity. -- `delete` - a list of paths (encoded as per [2.2.2](#222-paths)) that - indicate the deletion of data nodes on the target. + unique. In this context, the path is defined to be the fully resolved + path (including the prefix). In the case that there is a duplicate path + specified within an update, only the final update should be processed by + the receiving entity. +- `delete` - a list of paths (encoded as per [2.2.2](#222-paths)) that + indicate the deletion of data nodes on the target. The creator of a Notification message MUST include the `timestamp` field. All other fields are optional. @@ -195,13 +194,13 @@ encoded as a string. A path is represented by the `Path` message with the following fields: - `origin` - a field which MAY be used to assert the schema the path belongs to. - A detailed description of origin is provided in - [2.7](#27-gnmi-origin-in-path). + A detailed description of origin is provided in + [2.7](#27-gnmi-origin-in-path). - `elem` - an array of `PathElem` messages, each containing the name of the - element, and any associated keys. + element, and any associated keys. - `target` - the name of the target for which the path is a member. Only set in - `prefix` for a path. Elaboration of this field is in - [2.2.2.1](#2221-path-target). + `prefix` for a path. Elaboration of this field is in + [2.2.2.1](#2221-path-target). Each `Path` element should correspond to a node in the data tree. For example, the path `/a/b/c/d` is encoded as: @@ -264,7 +263,7 @@ paths should be generated. The `target` field within a path is name for the target. This field MUST only ever be present on `prefix` paths in the corresponding request and response -messages. This field is optional for clients. When set in the `prefix` in a +messages. This field is optional for clients. When set in the `prefix` in a request, `GetRequest`, `SetRequest` or `SubscribeRequest`, the field MUST be reflected in the `prefix` of the corresponding `GetResponse`, `SetResponse` or `SubscribeResponse` by a server. This field is used to allow a name to be @@ -279,7 +278,7 @@ multiple clients. The value of a data node (or subtree) is encoded in a `TypedValue` message as a [`oneof`](https://developers.google.com/protocol-buffers/docs/proto3#oneof) field to allow selection of the data type by setting exactly one of the member -fields. The possible data types include: +fields. The possible data types include: - scalar types - structured data types (e.g., to encode objects or subtrees) @@ -287,25 +286,25 @@ fields. The possible data types include: Several native scalar protobuf types are included in the `TypedValue` message: - `string` in the `string_val` field - defined to carry all string values - (including enumerated values represented as a string) + (including enumerated values represented as a string) - `int64` in the `int_val` field (storing all signed integer types - i.e., - `int8`, `int16`, `int32`, `int64`). + `int8`, `int16`, `int32`, `int64`). - `uint64` in the `uint_val` field (used to store all unsigned integer types - - i.e., `uint8`, `uint16`, `uint32`, `uint64`). + i.e., `uint8`, `uint16`, `uint32`, `uint64`). - `bool` in the `bool_val` field, used to store boolean values. - `bytes` (see [2.3.2](#232-bytes)) - `float` in the `double_val` field, used to store floating-point values (i.e., - `float32`, `float64`). + `float32`, `float64`). - Note: All values defined using the YANG `decimal64` datatype should also be - encoded as `double_val` when PROTO encoding is requested. Direct support of - [Decimal64 has been deprecated](https://github.com/openconfig/reference/blob/master/rpc/gnmi/decimal64-deprecation.md). + encoded as `double_val` when PROTO encoding is requested. Direct support of + [Decimal64 has been deprecated](https://github.com/openconfig/reference/blob/master/rpc/gnmi/decimal64-deprecation.md). Additional defined data types include: - `ScalarArray` in the `leaflist_val` field -- a message encoding a mixed-type scalar array; contains single repeated field: - - `element` -- a `TypedValue` element within the array. The type of each - element MUST be a scalar type (i.e., one of the scalar types). + - `element` -- a `TypedValue` element within the array. The type of each + element MUST be a scalar type (i.e., one of the scalar types). The remaining fields in the `TypedValue` message define structured data types. Section [2.3](#23-structured-data-types) describes these further. @@ -314,19 +313,19 @@ Section [2.3](#23-structured-data-types) describes these further. When structured data is sent by the client or the target in an `Update` message, it MUST be serialized according to one of the supported encodings listed in the -`Encoding` enumeration. The table below lists the supported encodings and their +`Encoding` enumeration. The table below lists the supported encodings and their corresponding `TypedValue` fields, followed by further details on each encoding type. It should be noted that the target never utilises the `Encoding` enumeration to declare to the client the type of encoding utilised, hence the client must infer the encoding from the populated `TypedValue` field. -| Name | Description | `TypedValue` field | `Encoding` Value | +| Name | Description | `TypedValue` field | `Encoding` Value | | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | ---------------- | -| JSON | A JSON encoded string as per [2.3.1](#231-json-and-json_ietf). | `json_val` | 0 | -| Bytes | An arbitrary sequence of bytes as per [2.3.2](#232-bytes). | `bytes_val` | 1 | -| Proto | A [Protobuf](https://developers.google.com/protocol-buffers/) encoded message using scalar values as per [Section 2.3.3](#233-protobuf). | `string_val`, `int_val`, `uint_val`, `bool_val`, `bytes_val`, `float_val`, `leaflist_val` | 2 | -| ASCII | An ASCII encoded string representing text formatted according to a target-defined convention (described in [Section 2.3.4](#234-ascii)). | `ascii_val` | 3 | -| JSON_IETF | A JSON encoded string as per [2.3.1](#231-json-and-json_ietf) using JSON encoding compatible with [RFC 7951](https://tools.ietf.org/html/rfc7951). | `json_ietf_val` | 4 | +| JSON | A JSON encoded string as per [2.3.1](#231-json-and-json_ietf). | `json_val` | 0 | +| Bytes | An arbitrary sequence of bytes as per [2.3.2](#232-bytes). | `bytes_val` | 1 | +| Proto | A [Protobuf](https://developers.google.com/protocol-buffers/) encoded message using scalar values as per [Section 2.3.3](#233-protobuf). | `string_val`, `int_val`, `uint_val`, `bool_val`, `bytes_val`, `float_val`, `leaflist_val` | 2 | +| ASCII | An ASCII encoded string representing text formatted according to a target-defined convention (described in [Section 2.3.4](#234-ascii)). | `ascii_val` | 3 | +| JSON_IETF | A JSON encoded string as per [2.3.1](#231-json-and-json_ietf) using JSON encoding compatible with [RFC 7951](https://tools.ietf.org/html/rfc7951). | `json_ietf_val` | 4 | ### 2.3.1 JSON and JSON_IETF @@ -340,12 +339,12 @@ YANG-modeled data). For any JSON encoding: - In the case that the data item at the specified path is a leaf node (i.e., - has no children, and an associated value) the value of that leaf is encoded - directly - i.e., the "bare" value is specified (i.e., a JSON object is not - required, and a bare JSON value is included). + has no children, and an associated value) the value of that leaf is encoded + directly - i.e., the "bare" value is specified (i.e., a JSON object is not + required, and a bare JSON value is included). - Where the data item referred to has child nodes, the `val` field contains a - serialised JSON entity (object or array) corresponding to the referenced - item. + serialised JSON entity (object or array) corresponding to the referenced + item. Using the following example data tree: @@ -494,14 +493,15 @@ byte sequence whose semantics is opaque to the protocol. + Data encoded using the `PROTOBUF` type should use the TypedValue message using primitive types as described in [Section 2.2.3](#223-node-values). ### 2.3.4 ASCII The `ASCII` type indicates that the data contains system-formatted ASCII encoded -text. For configuration data, for example, this may consist of semi-structured -CLI configuration data formatted according to the target platform. The gNMI +text. For configuration data, for example, this may consist of semi-structured +CLI configuration data formatted according to the target platform. The gNMI protocol does not define the format of the text – this must be established out-of-band. @@ -518,8 +518,7 @@ prefix and the list of path elements in the `path` field. For example, again considering the data tree shown in Section [2.3.1](#231-json-and-json_ietf) if a `Notification` message updating values, a -prefix could be used to refer to the `/a/b[name=b1]/c/d` and `/a/b[name=b1]/c/e -`data nodes: +prefix could be used to refer to the `/a/b[name=b1]/c/d` and `/a/b[name=b1]/c/e `data nodes: ``` notification: < @@ -568,9 +567,9 @@ notification: < When a client specifies a path within an RPC message which indicates a read, or retrieval of data, the path MUST be interpreted such that it refers to the node -directly corresponding with the path **and** all its children. The path refers +directly corresponding with the path **and** all its children. The path refers to the direct node and all descendent branches which originate from the node, -recursively down to each leaf element. If specific nodes are expected to be +recursively down to each leaf element. If specific nodes are expected to be excluded then an RPC MAY provide means to filter nodes, such as regular-expression based filtering, lists of excluded paths, or metadata-based filtering (based on annotations of the data schema being manipulated, should @@ -634,12 +633,12 @@ documentation --> The `Status` message consists of three fields: - `code` - a 32-bit integer value corresponding to the canonical gRPC error - code + code - `message` - a human-readable string describing the error condition. This - string is not expected to be machine-parsable, but rather provide contextual - information which may be passed to upstream systems. + string is not expected to be machine-parsable, but rather provide contextual + information which may be passed to upstream systems. - `details` - a repeated field of `protobuf.Any` messages that carry error - details. + details. @@ -663,7 +662,7 @@ In order to allow the client to restrict the set of data models to be used when interacting with the target, the client MAY discover the set of models that are supported by the target using the `Capabilities` RPC described in [Section 3.2](#32-capability-discovery). For subsequent `Get` and `Subscribe` RPCs, the -client MAY specify the models to be used by the target. The set of models to +client MAY specify the models to be used by the target. The set of models to use is expressed as a `ModelData` message, as specified in [Section 2.6.1](#261-the-modeldata-message). @@ -683,7 +682,7 @@ target and used by the client. The fields of the `ModelData` message identify a data model registered in a model catalog, as described in [[MODEL_CATALOG_DOC]](https://datatracker.ietf.org/doc/draft-openconfig-netmod-model-catalog/) (the schema of the catalog itself - expressed in YANG - is described in -[[MODEL_CATALOG_YANG](https://github.com/openconfig/public/tree/master/release/models/catalog)]). +\[[MODEL_CATALOG_YANG](https://github.com/openconfig/public/tree/master/release/models/catalog)\]). Each model specified by a `ModelData` message may refer to a specific schema module, a bundle of modules, or an augmentation or deviation, as described by the catalog entry. @@ -692,9 +691,9 @@ Each `ModelData` message contains the following fields: - `name` - name of the model expressed as a string. - `organization` - the organization publishing the model, expressed as a - string. + string. - `version` - the supported (or requested) version of the model, expressed as - a string which represents the semantic version of the catalog entry. + a string which represents the semantic version of the catalog entry. The combination of `name`, `organization`, and `version` uniquely identifies an entry in the model catalog. @@ -708,13 +707,13 @@ The `origin` field is valid in any context of a `Path` message. Typically it is used: - In a `SetRequest` to indicate a particular schema is being used to modify - the target configuration. + the target configuration. - In a `GetRequest` to retrieve the contents of a particular schema, or in - a `GetResponse` to indicate that the payload contains data from a - particular `` schema. + a `GetResponse` to indicate that the payload contains data from a + particular `` schema. - In a `SubscribeRequest` to subscribe to paths within a particular schema, - or `SubscribeResponse` to indicate an update corresponds to a particular - `` tuple. + or `SubscribeResponse` to indicate an update corresponds to a particular + `` tuple. If more than one `origin` is to be used within any message, a path in the `prefix` MUST NOT be specified, since a prefix applies to all paths within the @@ -736,9 +735,9 @@ should be ignored and the value specified within the `Update` considered as CLI input. CLI configuration is defined as the command line interface text used for -configuration. In gNMI, this is encoded as ASCII text. The format of the ASCII -text is agreed to out of band from gNMI. The string used to identify the CLI -origin must be formatted as `origin:`. Example values might include: +configuration. In gNMI, this is encoded as ASCII text. The format of the ASCII +text is agreed to out of band from gNMI. The string used to identify the CLI +origin must be formatted as `origin:`. Example values might include: `xros_cli`, `junos_cli`, `srlinux_cli` or any string which indicates the NOS name and the CLI designation. @@ -804,15 +803,15 @@ NOT make assumptions that limit to a single service definition. The service consists of the following RPCs: - `Capabilities` - defined in [Section 3.2](#32-capability-discovery) and used - by the client and target as an initial handshake to exchange capability - information + by the client and target as an initial handshake to exchange capability + information - `Get` - defined in [Section - 3.3](#33-retrieving-snapshots-of-state-information), used to retrieve - snapshots of the data on the target by the client. + 3.3](#33-retrieving-snapshots-of-state-information), used to retrieve + snapshots of the data on the target by the client. - `Set` - defined in [Section 3.4](#34-modifying-state) and used by the client - to modify the state of the target. + to modify the state of the target. - `Subscribe` - defined in [Section 3.5](#35-subscribing-to-telemetry-updates) - and used to control subscriptions to data on the target by the client. + and used to control subscriptions to data on the target by the client. A target implementing the gNMI service SHOULD register against the gRPC server [reflection @@ -831,15 +830,15 @@ and authorized to connect to the local system. If the target is expected to authenticate an RPC operation, the client MUST supply a username and password in the metadata of the RPC message (e.g., -`SubscribeRequest`, `GetRequest` or `SetRequest`). If the client supplies +`SubscribeRequest`, `GetRequest` or `SetRequest`). If the client supplies username/password credentials, the target MUST authenticate the RPC per its local authentication functionality. Authorization is also performed per-RPC by the server, through validating client-provided metadata. The client MAY include the appropriate AAA metadata, which MUST contain a username, and MAY include a password in the context of each -RPC call it generates. If the client includes both username and password, the -target MUST authenticate and authorize the request. If the client only supplies +RPC call it generates. If the client includes both username and password, the +target MUST authenticate and authorize the request. If the client only supplies the username, the target MUST authorize the RPC request. A more detailed discussion of the requirements for authentication and encryption @@ -848,24 +847,24 @@ used for gNMI is in ## 3.2 Capability Discovery -A client MAY discover the capabilities of the target using the `Capabilities` -RPC. The `CapabilityRequest` message is sent by the client to interrogate the -target. The target MUST reply with a `CapabilityResponse` message that +A client MAY discover the capabilities of the target using the `Capabilities` +RPC. The `CapabilityRequest` message is sent by the client to interrogate the +target. The target MUST reply with a `CapabilityResponse` message that includes its gNMI service version, the versioned data models it supports, and -the supported data encodings. This information is used in subsequent RPC +the supported data encodings. This information is used in subsequent RPC messages from the client to indicate the set of models that the client will use (for `Get`, `Subscribe` as described in [Section 2.6](#26-schema-definition-models)) , and the encoding to be used for the data. When the client does not specify the models it is using, the target SHOULD use all data schema modules that it supports when considering the data tree to be -addressed. If the client does not specify the encoding in an RPC message, it +addressed. If the client does not specify the encoding in an RPC message, it MUST send JSON encoded values (the default encoding). ### 3.2.1 The CapabilityRequest message The `CapabilityRequest` message is sent by the client to request capability -information from the target. The `CapabilityRequest` message carries a single +information from the target. The `CapabilityRequest` message carries a single repeated `extension` field, which is used as per the definition in [Section 2.8](#28-extensions-to-gnmi). @@ -874,16 +873,16 @@ repeated `extension` field, which is used as per the definition in [Section The `CapabilityResponse` message has the following fields: - `supported_models` - a set of `ModelData` messages (as defined in [Section - 2.6.1](#261-the-modeldata-message)) describing each of the models supported - by the target + 2.6.1](#261-the-modeldata-message)) describing each of the models supported + by the target - `supported_encodings` - an enumeration field describing the data encodings - supported by the target, as described in [Section - 2.3](#23-structured-data-types). + supported by the target, as described in [Section + 2.3](#23-structured-data-types). - `gNMI_version` - the semantic version of the gNMI service supported by the - target, specified as a string. The version should be interpreted as per - [[OPENCONFIG-SEMVER](http://www.openconfig.net/documentation/semantic-versioning/)]. + target, specified as a string. The version should be interpreted as per + \[[OPENCONFIG-SEMVER](http://www.openconfig.net/documentation/semantic-versioning/)\]. - `extension` - a repeated field to carry gNMI extensions, which is used as - per the definition in [Section 2.8](#28-extensions-to-gnmi). + per the definition in [Section 2.8](#28-extensions-to-gnmi). ## 3.3 Retrieving Snapshots of State Information @@ -912,31 +911,31 @@ message. The `GetRequest` message contains the following fields: - `prefix` - a path (specified as per [Section 2.2.2](#222-paths)), and used - as described in [Section 2.4.1](#241-path-prefixes). The prefix is applied - to all paths within the `GetRequest` message. + as described in [Section 2.4.1](#241-path-prefixes). The prefix is applied + to all paths within the `GetRequest` message. - `path` - a set of paths (expressed as per [Section 2.2.2](#222-paths)) for - which the client is requesting a data snapshot from the target. The path - specified MAY utilize wildcards. In the case that the path specified is not - valid, the target MUST return an RPC response indicating an error code of - `InvalidArgument` and SHOULD provide information about the invalid path in - the error message or details. + which the client is requesting a data snapshot from the target. The path + specified MAY utilize wildcards. In the case that the path specified is not + valid, the target MUST return an RPC response indicating an error code of + `InvalidArgument` and SHOULD provide information about the invalid path in + the error message or details. - `type` - the type of data that is requested from the target. The valid - values for type are described below. + values for type are described below. - `encoding` - the encoding that the target should utilise to serialise the - subtree of the data tree requested. The type MUST be one of the encodings - specified in [Section 2.3](#23-structured-data-types). If the - `Capabilities` RPC has been utilised, the client SHOULD use an encoding - advertised as supported by the target. If the encoding is not specified, - JSON MUST be used. If the target does not support the specified encoding, - the target MUST return an error of `Unimplemented`. The error message MUST - indicate that the specified encoding is unsupported. + subtree of the data tree requested. The type MUST be one of the encodings + specified in [Section 2.3](#23-structured-data-types). If the + `Capabilities` RPC has been utilised, the client SHOULD use an encoding + advertised as supported by the target. If the encoding is not specified, + JSON MUST be used. If the target does not support the specified encoding, + the target MUST return an error of `Unimplemented`. The error message MUST + indicate that the specified encoding is unsupported. - `use_models` - a set of `ModelData` messages (defined in [Section - 2.6.1](#261-the-modeldata-message)) indicating the schema definition modules - that define the data elements that should be returned in response to the Get - RPC call. The semantics of the `use_models` field are defined in [Section - 2.6](#26-schema-definition-models). + 2.6.1](#261-the-modeldata-message)) indicating the schema definition modules + that define the data elements that should be returned in response to the Get + RPC call. The semantics of the `use_models` field are defined in [Section + 2.6](#26-schema-definition-models). - `extension` - a repeated field to carry gNMI extensions, used as per the - definition in [Section 2.8](#28-extensions-to-gnmi). + definition in [Section 2.8](#28-extensions-to-gnmi). Since the data tree stored by the target may consist of different types of data (e.g., values that are operational in nature, such as protocol statistics) - the @@ -948,31 +947,31 @@ subtrees of the data tree. The types of data currently defined are: - `CONFIG` - specified to be data that the target considers to be read/write. - If the data schema is described in YANG, this corresponds to the "config - true" set of leaves on the target. + If the data schema is described in YANG, this corresponds to the "config + true" set of leaves on the target. - `STATE` - specified to be the read-only data on the target. If the data - schema is described in YANG, `STATE` data is the "config false" set of - leaves on the target. + schema is described in YANG, `STATE` data is the "config false" set of + leaves on the target. - `OPERATIONAL` - specified to be the read-only data on the target that is - related to software processes operating on the device, or external - interactions of the device. + related to software processes operating on the device, or external + interactions of the device. -If the `type` field is not specified, the target MUST return CONFIG, STATE and +If the `type` field is not specified, the target MUST return CONFIG, STATE and OPERATIONAL data fields in the tree resulting from the client's query. ### 3.3.2 The GetResponse Message The `GetResponse` message consists of: -- `notification` - a set of `Notification` messages, as defined in [Section - 2.1](#21-reusable-notification-message-format). The target MUST generate a - `Notification` message for each path specified in the client's `GetRequest`, - and hence MUST NOT collapse data from multiple paths into a single - `Notification` within the response. The `timestamp` field of the - `Notification` message MUST be set to the time at which the target's - snapshot of the relevant path was taken. +- `notification` - a set of `Notification` messages, as defined in [Section + 2.1](#21-reusable-notification-message-format). The target MUST generate a + `Notification` message for each path specified in the client's `GetRequest`, + and hence MUST NOT collapse data from multiple paths into a single + `Notification` within the response. The `timestamp` field of the + `Notification` message MUST be set to the time at which the target's + snapshot of the relevant path was taken. - `extension` - a repeated field used to carry gNMI extensions, as per the - description in [Section 2.8](#28-extensions-to-gnmi). + description in [Section 2.8](#28-extensions-to-gnmi). ### 3.3.3 Considerations for using Get @@ -987,7 +986,7 @@ operations, the `Subscribe` RPC is the recommended mechanism, e.g. using the Another consideration for `Get` is that the timestamp returned is associated with entire set of data requested, although individual data items may have been -sampled by the target at different times. If the client requires higher +sampled by the target at different times. If the client requires higher accuracy for individual data items, the `Subscribe` RPC is recommended to request a telemetry stream (see [Section 3.5.2](#352-sending-telemetry-updates)). @@ -996,12 +995,12 @@ request a telemetry stream (see [Section The following table clarifies the target behaviors for `Get` for certain scenarios: -| GetRequest Scenario | Target Behavior | +| GetRequest Scenario | Target Behavior | | ------------------------------------------------------------------------------------------------------------------------ | ------------------------- | -| Requested paths exist or a YANG default value is [in use](https://datatracker.ietf.org/doc/html/rfc7950#section-7.6.1). | Value(s) are returned | -| Requested paths are syntactically correct but one or more paths neither exist (yet) nor has a YANG default value in use. | Return `NOT_FOUND` | -| Requested paths are syntactically correct but one or more paths is not implemented by the server. | Return `UNIMPLEMENTED` | -| One or more requested paths is syntactically incorrect. | Return `INVALID_ARGUMENT` | +| Requested paths exist or a YANG default value is [in use](https://datatracker.ietf.org/doc/html/rfc7950#section-7.6.1). | Value(s) are returned | +| Requested paths are syntactically correct but one or more paths neither exist (yet) nor has a YANG default value in use. | Return `NOT_FOUND` | +| Requested paths are syntactically correct but one or more paths is not implemented by the server. | Return `UNIMPLEMENTED` | +| One or more requested paths is syntactically incorrect. | Return `INVALID_ARGUMENT` | ## 3.4 Modifying State @@ -1015,15 +1014,15 @@ within it - which are treated as a transaction (see [Section update fields, the server MUST process paths in the following order: 1. deleted paths (within the `delete` field of the `SetRequest`) -2. replaced paths (within the `replace` field) -3. updated paths (within the `update` field) +1. replaced paths (within the `replace` field) +1. updated paths (within the `update` field) A SetRequest containing [union_replace](https://github.com/openconfig/reference/blob/master/rpc/gnmi/gnmi-union_replace.md) operations MUST NOT contain delete, replace and update operations. The order of the fields MUST be treated as significant within a -single `SetRequest` message. If a single path is specified multiple times for a +single `SetRequest` message. If a single path is specified multiple times for a single operation (i.e., within `update` or `replace`), then the state of the target MUST reflect the application of all of the operations in order, even if they overwrite each other. A `SetRequest` specifying an empty set of paths MUST @@ -1048,20 +1047,20 @@ the success or failure of the set of operations within the `SetRequest` message A `SetRequest` message consists of the following fields: - `prefix` - specified as per [Section 2.4.1](#241-path-prefixes). The prefix - specified is applied to all paths defined within other fields of the - message. + specified is applied to all paths defined within other fields of the + message. - `delete` - A set of paths, specified as per [Section 2.2.2](#222-paths), - which are to be removed from the data tree. A specification of the behavior - of a delete is defined in [Section 3.4.6](#346-deleting-configuration). + which are to be removed from the data tree. A specification of the behavior + of a delete is defined in [Section 3.4.6](#346-deleting-configuration). - `union_replace` - A set of `Update` messages specifying elements to union and - then replace the data tree. See the [gNMI union_replace specification](https://github.com/openconfig/reference/blob/master/rpc/gnmi/gnmi-union_replace.md) - for details. -- `replace` - A set of `Update` messages indicating elements of the data tree - whose content is to be replaced. + then replace the data tree. See the [gNMI union_replace specification](https://github.com/openconfig/reference/blob/master/rpc/gnmi/gnmi-union_replace.md) + for details. +- `replace` - A set of `Update` messages indicating elements of the data tree + whose content is to be replaced. - `update` - A set of `Update` messages indicating elements of the data tree - whose content is to be updated. + whose content is to be updated. - `extension` - a repeated field used to carry gNMI extensions, as per the - description in [Section 2.8](#28-extensions-to-gnmi). + description in [Section 2.8](#28-extensions-to-gnmi). The semantics of "updating" versus "replacing" content are defined in [Section 3.4.4.](#344-modes-of-update-replace-versus-update) @@ -1070,40 +1069,40 @@ A re-usable `Update` message is utilised to indicate changes to paths where a new value is required. The `Update` message contains two fields: - `path` - a path encoded as per [Section 2.2.2](#222-paths) indicating the - path of the element to be modified. + path of the element to be modified. - `value` - a value encoded as per [Section 2.2.3](#223-node-values) - indicating the value applied to the specified node. The semantics of how the - node is updated is dependent upon the context of the update message, as - specified in [Section 3.4.4](#344-modes-of-update-union_replace,-replace-update). + indicating the value applied to the specified node. The semantics of how the + node is updated is dependent upon the context of the update message, as + specified in [Section 3.4.4](#344-modes-of-update-union_replace,-replace-update). ### 3.4.2 The SetResponse Message A `SetResponse` consists of the following fields: - `prefix` - specified as per [Section 2.4.1](#241-path-prefixes). The prefix - specified is applied to all paths defined within other fields of the - message. The target MUST return an RPC response when the change is - successfully applied. In cases where an update was not successfully applied, - the contents of the status message used in the RPC response MUST be - specified as per [Section 3.4.7](#347-error-handling). -- `response` - containing a list of responses, one per operation specified - within the `SetRequest` message. Each response consists of an `UpdateResult` - message with the following fields: + specified is applied to all paths defined within other fields of the + message. The target MUST return an RPC response when the change is + successfully applied. In cases where an update was not successfully applied, + the contents of the status message used in the RPC response MUST be + specified as per [Section 3.4.7](#347-error-handling). +- `response` - containing a list of responses, one per operation specified + within the `SetRequest` message. Each response consists of an `UpdateResult` + message with the following fields: - `timestamp` - a timestamp (encoded as per [Section - 2.2.1](#221-timestamps)) at which the set request message was accepted - by the system. + 2.2.1](#221-timestamps)) at which the set request message was accepted + by the system. - `path` - the path (encoded as per [Section 2.2.2](#222-paths)) specified - within the `SetRequest`. In the case that a common prefix was not used - within the `SetRequest`, the target MAY specify a `prefix` to reduce - repetition of path elements within multiple `UpdateResult` messages in - the `request` field. + within the `SetRequest`. In the case that a common prefix was not used + within the `SetRequest`, the target MAY specify a `prefix` to reduce + repetition of path elements within multiple `UpdateResult` messages in + the `request` field. - `op` - the operation corresponding to the path. This value MUST be one - of `DELETE`, `REPLACE`, or `UPDATE`. + of `DELETE`, `REPLACE`, or `UPDATE`. - `message` - a status message (as specified in [Section - 2.5](#25-error-handling)). This field follows the same rules as the - status field returned with the `SetResponse` message specified above. + 2.5](#25-error-handling)). This field follows the same rules as the + status field returned with the `SetResponse` message specified above. - `extension` - a repeated field used to carry gNMI extensions, as per the - description in [Section 2.8](#28-extensions-to-gnmi). + description in [Section 2.8](#28-extensions-to-gnmi). ### 3.4.3 Transactions @@ -1112,8 +1111,8 @@ All changes to the state of the target that are included in an individual modifications within the request are applied, or the target MUST rollback the state changes to reflect its state before any changes were applied. The state of the target MUST NOT appear to be changed until such time as all changes have -been accepted successfully. Hence, telemetry update messages MUST NOT reflect -a change in state until such time as the intended modifications have been +been accepted successfully. Hence, telemetry update messages MUST NOT reflect +a change in state until such time as the intended modifications have been accepted. As per the specification in [Section 3.4](#34-modifying-state), within an @@ -1144,18 +1143,18 @@ update operation MUST be considered to add new entries to the collection if they do not exist. For `union_replace` operations, the contents shall be merged (unioned) -and then applied as a replacement of the configuration. See the +and then applied as a replacement of the configuration. See the [gNMI union_replace specification](https://github.com/openconfig/reference/blob/master/rpc/gnmi/gnmi-union_replace.md). For `replace` operations: - If a particular path-value is specified in the client-supplied data, it is - replaced with the client-specified value. + replaced with the client-specified value. - If a particular path-value is NOT specified in the client-supplied data and - the path does not have a specified default value in the corresponding schema, - it should be deleted. + the path does not have a specified default value in the corresponding schema, + it should be deleted. - If a path-value is NOT specified in the client-supplied data and the path does - have a default value, it takes on the schema-specified default value. + have a default value, it takes on the schema-specified default value. For example, consider the following tree, where a schema defines the boolean `b` as having a default value of True and boolean `c` as having no default value. @@ -1193,9 +1192,9 @@ the target MUST reject the operation by returning `INVALID_ARGUMENT`. For `update` operations: - Only the value of those data elements that are specified explicitly should be - treated as changed. + treated as changed. - It is only possible to update or create new leaf elements, and not possible - to delete leaf elements using an `update` operation. + to delete leaf elements using an `update` operation. For example, if an `update` operation to the root element `/` is done on the following data tree, where `f[k=20]` and `f[k=30]` are the elements that are in @@ -1252,14 +1251,14 @@ identify an element (i.e., the path within the schema represents a list, map, or array), the following considerations apply: - In the case that multiple attribute values are required to uniquely address - an element - e.g., `/a/f[k1=10][k2=20]`- and a replace or update - operation's path specifies a subset of the attributes (e.g., `/a/f[k1=10]`) - then this MUST be considered an error by the target system - and an status - code of`InvalidArgument (3)` specified. + an element - e.g., `/a/f[k1=10][k2=20]`- and a replace or update + operation's path specifies a subset of the attributes (e.g., `/a/f[k1=10]`) + then this MUST be considered an error by the target system - and an status + code of`InvalidArgument (3)` specified. - In the case that key values are specified both as attributes of a node, and - as their own elements within the data tree, update or replace operations - that modify instances of the key in conflicting ways MUST be considered an - error. The target MUST return a status code of `InvalidArgument (3)`. + as their own elements within the data tree, update or replace operations + that modify instances of the key in conflicting ways MUST be considered an + error. The target MUST return a status code of `InvalidArgument (3)`. For example, consider a tree corresponding to the examples above, as illustrated below. @@ -1306,9 +1305,9 @@ specified changes, an error status MUST be reported to the client. The error is specified in multiple places: - The status returned with the `SetResponse` message indicates the completion - status of the entire transaction. + status of the entire transaction. - With a `UpdateResult` message, where the message field indicates the - completion status of the individual operation. + completion status of the individual operation. The RPC status supplied with the `SetResponse` message MUST reflect the overall result of the transaction. @@ -1319,7 +1318,7 @@ specified changes, and MUST consider the transaction as failed. The target SHOULD set the status code of the `SetResponse` message to `Aborted (10)`, along with an appropriate error message, and MUST set the `message` field of the `UpdateResult` corresponding to the failed operation to an `Error` message -indicating failure. In the case that the processed operation is not the only +indicating failure. In the case that the processed operation is not the only operation within the `SetRequest` the target MUST set the `message` field of the `UpdateResult` messages for all other operations, setting the code field to `Aborted (10)`. @@ -1330,22 +1329,22 @@ error code indicating the reason for failure based on the following mappings to canonical gRPC error codes: - When the client has specified metadata requiring authentication (see [Section - 3.1](#31-session-security-authentication-and-rpc-authorization)), and the - authentication fails - `Unauthenticated (16)`. + 3.1](#31-session-security-authentication-and-rpc-authorization)), and the + authentication fails - `Unauthenticated (16)`. - When the client does not have permission to modify the path specified by the - operation - `PermissionDenied (7)`. + operation - `PermissionDenied (7)`. - When the operation specifies a path that cannot be parsed by the target - - `InvalidArgument (3)`. In this case, the `message` field of the returned - status specified SHOULD specify human-readable text indicating that the path - could not be parsed. + `InvalidArgument (3)`. In this case, the `message` field of the returned + status specified SHOULD specify human-readable text indicating that the path + could not be parsed. - When the operation is an `update`, `replace` or `union_replace` operation that - corresponds to a path that is not valid - `NotFound (5)`. In this case the - `message` field of the returned status message SHOULD specify human-readable - text indicating the path that was invalid. + corresponds to a path that is not valid - `NotFound (5)`. In this case the + `message` field of the returned status message SHOULD specify human-readable + text indicating the path that was invalid. - When the operation is an `update`, `replace` or `union_replace` operation that - includes an invalid value within the `Update` message specified - - `InvalidArgument (3)`. This error SHOULD be used in cases where the payload - specifies scalar values that do not correspond to the correct schema type. + includes an invalid value within the `Update` message specified - + `InvalidArgument (3)`. This error SHOULD be used in cases where the payload + specifies scalar values that do not correspond to the correct schema type. - When the client specifies a payload utilising an encoding that is not supported by the target (e.g., JSON) - `Unimplemented (12)` SHOULD be used to indicate that the encoding is not supported. @@ -1382,19 +1381,19 @@ snapshot of the data tree at a particular point in time. Subscriptions therefore allow a client to: - Receive ongoing updates from a target which allow synchronization between - the client and target for the state of elements within the data tree. In - this case (i.e., a `STREAM` subscription), a client creating a subscription - receives an initial set of updates, terminated by a message indicating that - initial synchronisation has completed, and then receives subsequent updates - indicating changes to the initial state of those elements. + the client and target for the state of elements within the data tree. In + this case (i.e., a `STREAM` subscription), a client creating a subscription + receives an initial set of updates, terminated by a message indicating that + initial synchronisation has completed, and then receives subsequent updates + indicating changes to the initial state of those elements. - Receive a single view (polled, or one-off) for elements of the data tree on - a per-data element basis according to the state that they are in at the time - that the message is transmitted. This can be more resource efficient for - both target and client than a `GetRequest` for large subtrees within the - data tree. The target does not need to coalesce values into a single - snapshot view, or create an in-memory representation of the subtree at the - time of the request, and subsequently transmit this entire view to the - client. + a per-data element basis according to the state that they are in at the time + that the message is transmitted. This can be more resource efficient for + both target and client than a `GetRequest` for large subtrees within the + data tree. The target does not need to coalesce values into a single + snapshot view, or create an in-memory representation of the subtree at the + time of the request, and subsequently transmit this entire view to the + client. Based on the fact that subsequent update messages are considered to be independent, and to ensure that the efficiencies described above can be @@ -1437,15 +1436,15 @@ target for a specified set of paths. The fields of the `SubscribeRequest` are as follows: - A group of fields, only one of which may be specified, which indicate the - type of operation that the `SubscribeRequest` relates to. These are: + type of operation that the `SubscribeRequest` relates to. These are: - `subscribe` - a `SubscriptionList` message specifying a new set of paths - that the client wishes to subscribe to. + that the client wishes to subscribe to. - `poll`- a `Poll` message used to specify (on an existing RPC) that the - client wishes to receive a polled update for the paths specified within - the subscription. The semantics of the `Poll` message are described in - [Section 3.5.1.5.3](#35153-poll-subscriptions). + client wishes to receive a polled update for the paths specified within + the subscription. The semantics of the `Poll` message are described in + [Section 3.5.1.5.3](#35153-poll-subscriptions). - `extension` - a repeated field used to carry gNMI extensions, as per the - description in [Section 2.8](#28-extensions-to-gnmi). + description in [Section 2.8](#28-extensions-to-gnmi). In order to create a new subscription a client MUST initiate a `Subscribe` RPC with a `SubscribeRequest` message specifying the `subscribe` field. The @@ -1457,7 +1456,7 @@ Subscriptions are set once, and subsequently not modified by a client. If a client wishes to subscribe to additional paths from a target, it MUST do so by sending an additional `Subscribe` RPC call, specifying a new `SubscriptionList` message. In order to end an existing subscription, a client simply cancels the -`Subscribe` RPC that relates to that subscription. If an RPC is initiated with +`Subscribe` RPC that relates to that subscription. If an RPC is initiated with a `SubscribeRequest` message that does not specify a `SubscriptionList` message with the `request` field, the target MUST consider this an error. If an additional `SubscribeRequest` message specifying a `SubscriptionList` is sent @@ -1467,7 +1466,7 @@ via an existing RPC, the target MUST respond to this message with modified or terminated. If a client initiates a `Subscribe` RPC with a `SubscribeRequest` message which -does not contain a `SubscriptionList` message, this is an error. A +does not contain a `SubscriptionList` message, this is an error. A `SubscribeResponse` message with the status indicating a error code of `InvalidArgument` MUST be sent, and the RPC closed. The status message SHOULD indicate that an out-of-order operation was requested on a non-existent @@ -1479,42 +1478,42 @@ A `SubscriptionList` message is used to indicate a set of paths for which common subscription behavior are required. The fields of the message are: - `subscription` - a set of `Subscription` messages that indicate the set of - paths associated with the subscription list. -- `mode` - the type of subscription that is being created. This may be `ONCE` - (described in [3.5.1.5.1](#35151-once-subscriptions)); `STREAM` (described - in [3.5.1.5.2](#35152-stream-subscriptions)); or `POLL` (described in - [3.5.1.5.3](#35153-poll-subscriptions)). The default value for the mode - field is `STREAM`. -- `prefix`- a common prefix that is applied to all paths specified within the - message as per the definition in [Section 2.4.1](#241-path-prefixes). The - default prefix is null. + paths associated with the subscription list. +- `mode` - the type of subscription that is being created. This may be `ONCE` + (described in [3.5.1.5.1](#35151-once-subscriptions)); `STREAM` (described + in [3.5.1.5.2](#35152-stream-subscriptions)); or `POLL` (described in + [3.5.1.5.3](#35153-poll-subscriptions)). The default value for the mode + field is `STREAM`. +- `prefix`- a common prefix that is applied to all paths specified within the + message as per the definition in [Section 2.4.1](#241-path-prefixes). The + default prefix is null. - `qos` - a field describing the packet marking that is to be utilised for the - responses to the subscription that is being created. This field has a single - sub-value, `marking`, which indicates the DSCP value as a 32-bit unsigned - integer. If the `qos` field is not specified, the device should export - telemetry traffic using its default DSCP marking for management-plane - traffic. + responses to the subscription that is being created. This field has a single + sub-value, `marking`, which indicates the DSCP value as a 32-bit unsigned + integer. If the `qos` field is not specified, the device should export + telemetry traffic using its default DSCP marking for management-plane + traffic. - `allow_aggregation` - a boolean value used by the client to allow schema - elements that are marked as eligible for aggregation to be combined into - single telemetry update messages. By default, aggregation MUST NOT be used. + elements that are marked as eligible for aggregation to be combined into + single telemetry update messages. By default, aggregation MUST NOT be used. - `use_models` - a `ModelData` message (as specified in [Section - 2.6.1](#261-the-modeldata-message)) specifying the schema definition modules - that the target should use when creating a subscription. When specified, the - target MUST only consider data elements within the defined set of schema - models as defined in [Section 2.6](#26-schema-definition-models). When - `use_models` is not specified, the target MUST consider all data elements - that are defined in all schema modules that it supports. + 2.6.1](#261-the-modeldata-message)) specifying the schema definition modules + that the target should use when creating a subscription. When specified, the + target MUST only consider data elements within the defined set of schema + models as defined in [Section 2.6](#26-schema-definition-models). When + `use_models` is not specified, the target MUST consider all data elements + that are defined in all schema modules that it supports. - `updates_only` - a boolean that causes the server to send only updates to - the current state. When set to true, the target MUST not transmit the - current state of the paths that the client has subscribed to, but rather - should send only updates to them. For `STREAM` subscriptions, an update - occurs upon the next sample (in the case of `SAMPLE` subscriptions), or upon - the next value change for `ON_CHANGE` subscriptions. For `POLL` and `ONCE` - subscriptions, the target should send only the `sync_response` message, - before proceeding to process poll requests (in the case of `POLL`) or - closing the RPC (in the case of `ONCE`)." + the current state. When set to true, the target MUST not transmit the + current state of the paths that the client has subscribed to, but rather + should send only updates to them. For `STREAM` subscriptions, an update + occurs upon the next sample (in the case of `SAMPLE` subscriptions), or upon + the next value change for `ON_CHANGE` subscriptions. For `POLL` and `ONCE` + subscriptions, the target should send only the `sync_response` message, + before proceeding to process poll requests (in the case of `POLL`) or + closing the RPC (in the case of `ONCE`)." - `extension` - a repeated field used to carry gNMI extensions, as per the - description in [Section 2.8](#28-extensions-to-gnmi). + description in [Section 2.8](#28-extensions-to-gnmi). A client generating a `SubscriptionList` message MUST include the `subscription` field - which MUST be a non-empty set of `Subscription` messages, all other @@ -1551,16 +1550,16 @@ A `SubscribeResponse` message is transmitted by a target to a client over an established `Subscribe` RPC. The message contains the following fields: - A set of fields referred to as the `response` fields, only one of which can - be specified per `SubscribeResponse` message: + be specified per `SubscribeResponse` message: - `update` - a `Notification` message providing an update value for a - subscribed data entity as described in [Section - 3.5.2.3](#3523-sending-telemetry-updates). - - `sync_response` - a boolean field indicating that all data values - corresponding to the path(s) specified in the `SubscriptionList` has - been transmitted at least once, used for `ONCE`, `POLL` and `STREAM` - subscriptions. + subscribed data entity as described in [Section + 3.5.2.3](#3523-sending-telemetry-updates). + - `sync_response` - a boolean field indicating that all data values + corresponding to the path(s) specified in the `SubscriptionList` has + been transmitted at least once, used for `ONCE`, `POLL` and `STREAM` + subscriptions. - `extension` - a repeated field used to carry gNMI extensions, as per the - description in [Section 2.8](#28-extensions-to-gnmi). + description in [Section 2.8](#28-extensions-to-gnmi). `SubscribeResponse` messages with the `update` field set to a `Notification` are not required to be sent by the target in timestamp order, and client @@ -1598,46 +1597,45 @@ specified as `STREAM`. Each entry within the `Subscription` message is specified with one of the following `modes`: - **On Change (`ON_CHANGE`)** - when a subscription is defined to be "on - change", data updates are only sent when the value of the data item changes. + change", data updates are only sent when the value of the data item changes. - For all `ON_CHANGE` subscriptions, the target MUST first generate updates - for all paths that match the subscription path(s), and transmit them. - Following this initial set of updates, updated values SHOULD only be - transmitted when their value changes. + for all paths that match the subscription path(s), and transmit them. + Following this initial set of updates, updated values SHOULD only be + transmitted when their value changes. - A heartbeat interval MAY be specified along with an "on change" - subscription - in this case, the value of the data item(s) MUST be re-sent - once per heartbeat interval regardless of whether the value has changed or - not. + subscription - in this case, the value of the data item(s) MUST be re-sent + once per heartbeat interval regardless of whether the value has changed or + not. - **Sampled (`SAMPLE`)** - a subscription that is defined to be sampled MUST - be specified along with a `sample_interval` encoded as an unsigned 64-bit - integer representing nanoseconds between samples. The value of the data - item(s) MUST be sent once per sample interval to the client. If the target - is unable to support the desired `sample_interval` it MUST reject the - subscription by closing the `Subscribe` RPC specifying an `InvalidArgument - (3)` error code. If the `sample_interval` is set to 0, the target MUST - create the subscription and send the data with the lowest interval possible - for the target. + be specified along with a `sample_interval` encoded as an unsigned 64-bit + integer representing nanoseconds between samples. The value of the data + item(s) MUST be sent once per sample interval to the client. If the target + is unable to support the desired `sample_interval` it MUST reject the + subscription by closing the `Subscribe` RPC specifying an `InvalidArgument (3)` error code. If the `sample_interval` is set to 0, the target MUST + create the subscription and send the data with the lowest interval possible + for the target. - Optionally, the `suppress_redundant` field of the `Subscription` message - may be set for a sampled subscription. In the case that it is set to - `true`, the target SHOULD NOT generate a telemetry update message unless - the value of the path being reported on has changed since the last - update was generated. Updates MUST only be generated for those - individual leaf nodes in the subscription that have changed. That is to - say that for a subscription to `/a/b` - where there are leaves `c` and - `d` branching from the `b` node - if the value of `c` has changed, but - `d` remains unchanged, an update for `d` MUST NOT be generated, whereas - an update for `c` MUST be generated. + may be set for a sampled subscription. In the case that it is set to + `true`, the target SHOULD NOT generate a telemetry update message unless + the value of the path being reported on has changed since the last + update was generated. Updates MUST only be generated for those + individual leaf nodes in the subscription that have changed. That is to + say that for a subscription to `/a/b` - where there are leaves `c` and + `d` branching from the `b` node - if the value of `c` has changed, but + `d` remains unchanged, an update for `d` MUST NOT be generated, whereas + an update for `c` MUST be generated. - A `heartbeat_interval` MAY be specified to modify the behavior of - `suppress_redundant` in a sampled subscription. In this case, the - target MUST generate one telemetry update per heartbeat interval, - regardless of whether the `suppress_redundant` flag is set to `true`. - This value is specified as an unsigned 64-bit integer in nanoseconds. + `suppress_redundant` in a sampled subscription. In this case, the + target MUST generate one telemetry update per heartbeat interval, + regardless of whether the `suppress_redundant` flag is set to `true`. + This value is specified as an unsigned 64-bit integer in nanoseconds. - **Target Defined `(TARGET_DEFINED)`** - when a client creates a subscription - specifying the target defined mode, the target MUST determine the best type - of subscription to be created on a per-leaf basis. That is to say, if the - path specified within the message refers to some leaves which are event - driven (e.g., the changing of state of an entity based on an external - trigger) then an `ON_CHANGE` subscription may be created, whereas if other - data represents counter values, a `SAMPLE` subscription may be created. + specifying the target defined mode, the target MUST determine the best type + of subscription to be created on a per-leaf basis. That is to say, if the + path specified within the message refers to some leaves which are event + driven (e.g., the changing of state of an entity based on an external + trigger) then an `ON_CHANGE` subscription may be created, whereas if other + data represents counter values, a `SAMPLE` subscription may be created. ##### 3.5.1.5.3 POLL Subscriptions @@ -1648,7 +1646,7 @@ encapsulated `SubscriptionList`. `Subscription` messages contained within the `SubscriptionList` indicate the set of paths that are of interest to the polling client. -To retrieve data from the target, a client sends a `SubscribeRequest` message +To retrieve data from the target, a client sends a `SubscribeRequest` message to the target, containing a `poll` field, specified to be an empty `Poll` message. On reception of such a message, the target MUST generate updates for all the corresponding paths within the `SubscriptionList`. Updates MUST be @@ -1675,7 +1673,7 @@ gNMI implementation MUST NOT obscure access to these timestamps in an attempt to provide bundling. In cases where a leaf's value is derived from two or more hardware values with distinct timestamps, an implementation SHOULD attempt to provide a consistent and meaningful timestamp that -introduces minimal error. This could include approaches such as attempting to synchronize collection +introduces minimal error. This could include approaches such as attempting to synchronize collection of the values, retaining a consistent sample period and having a robust mechanism to ensure that sampling artifacts are not introduced (e.g. a constant rate byte flow over an interface appearing to have adjacent spikes and dips). @@ -1707,7 +1705,7 @@ branch that applies to a multitude of leaves, e.g. when removing a logical inter in a configuration, deletes could be issued at container level branches that apply to that interface, rather than all the individual leaves. -Explicit deletion also applies to TARGET-DEFINED subscription mode. +Explicit deletion also applies to TARGET-DEFINED subscription mode.\ Whereas, if the TARGET-DEFINED subscription determines the best type of delivery to be ON-CHANGE, explicit deletion is required and if decided to be SAMPLE, deletion will be optional. @@ -1723,9 +1721,9 @@ MUST NOT only send a `delete` for the path or a parent path. When the target has transmitted the initial updates for all paths specified within the subscription, a `SubscribeResponse` message with the `sync_response` field set to `true` MUST be transmitted to the client to indicate that the -initial transmission of updates has concluded. This provides an indication to +initial transmission of updates has concluded. This provides an indication to the client that all of the existing data for the subscription has been sent at -least once. For `STREAM` subscriptions, such messages are not required for +least once. For `STREAM` subscriptions, such messages are not required for subsequent updates. For `POLL` subscriptions, after each set of updates for individual poll request, a `SubscribeResponse` message with the `sync_response` field set to `true` MUST be generated. @@ -1741,12 +1739,12 @@ to configuration. The following table clarifies the target behaviors for `Subscribe` for certain scenarios: -| Subscription Scenario | ONCE/POLL | STREAM | +| Subscription Scenario | ONCE/POLL | STREAM | | ------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------- | --------------------------------------------------------------- | -| Subscribed paths exist or a YANG default value is [in use](https://datatracker.ietf.org/doc/html/rfc7950#section-7.6.1). | Value(s) are returned | Value(s) are returned | +| Subscribed paths exist or a YANG default value is [in use](https://datatracker.ietf.org/doc/html/rfc7950#section-7.6.1). | Value(s) are returned | Value(s) are returned | | Subscribed paths are syntactically correct but one or more paths neither exist (yet) nor has a YANG default value in use. | No value returned for non-existent paths | nothing is sent for non-existent paths (yet), RPC is not closed | -| Subscribed paths are syntactically correct but one or more paths is not implemented by the server. | Return `UNIMPLEMENTED` | Return `UNIMPLEMENTED` | -| One or more subscribed paths is syntactically incorrect. | Return `INVALID_ARGUMENT` | Return `INVALID_ARGUMENT` | +| Subscribed paths are syntactically correct but one or more paths is not implemented by the server. | Return `UNIMPLEMENTED` | Return `UNIMPLEMENTED` | +| One or more subscribed paths is syntactically incorrect. | Return `INVALID_ARGUMENT` | Return `INVALID_ARGUMENT` | # 4 Appendix: Current Protobuf Message and Service Specification @@ -1757,7 +1755,7 @@ The latest Protobuf IDL gNMI specification is found in GitHub at - Ability for the client to exclude paths from a subscription or get. - "Dial out" for the target to register with an NMS and publish pre-configured - subscriptions. + subscriptions. # 6 Copyright @@ -1780,17 +1778,21 @@ limitations under the License # 7 Revision History - v0.10.0: May 25, 2023 - - Add `union_replace` operation. Sync revision to gNMI proto revision. + + - Add `union_replace` operation. Sync revision to gNMI proto revision. - v0.8.3: April 18, 2023 + - Clarify that `SetRequest` `replace` on a list element with `{}` is invalid. - v0.8.2: November 28, 2022 + - Clarify difference between `SetRequest` `update` vs. `replace` when updating a keyed list. - Add gNMI service compatibility version. - v0.8.1: July 7, 2022 + - Clarify that for `Subscribe`, a transition to a YANG default value for a leaf must use `update` rather than just a `delete`. - Clarify that for `Set`, deleting configuration using `replace(nil)` is @@ -1798,14 +1800,17 @@ limitations under the License - Clarify target behavior for certain scenarios for `Get` and `Subscribe`. - v0.8.0: April 28, 2022 + - Add 'double_val' in TypedValue message to replace both 'float_val' and decimal64_val. - Clarify format of responses when PROTO encoding is selected. - v0.7.0: May 22, 2018 + - Add 'atomic' boolean option to Notification message. - v0.6.0: January 25, 2018 + - Add `extension` fields to the top-level RPCs of the gNMI service. - Add recommendation that the gNMI service registers with the gRPC reflection service. @@ -1814,12 +1819,14 @@ limitations under the License - Editorial amendments. - v0.5.0: November 14, 2017 + - Add `target` field within `Path` message with description in [Section 2.2.2.1](#2221-path-target) - Add `updates_only` field within `SubscribeRequest` message. - Add `duplicates` field withing `Update` message. - v0.4.0: June 16, 2017 + - Deprecate the old `value` field within the `Update` message, in favour of the new `TypedValue` field. - Clarify error handling should use `google/rpc/status.proto` rather than @@ -1829,18 +1836,22 @@ limitations under the License repeated `string`. - v0.2.2: March 7, 2017 + - Add clarifications of `ON_CHANGE` subscriptions and the requirement for an initial sync of matching subscription paths. - Correct responses to an unsupported encoding error to be `Unimplemented` (fixes [#36](https://github.com/openconfig/reference/issues/36)). - v0.2.1: November 10, 2016 + - Correct reference to `TEXT` vs. `ASCII` encoding type. + - Ensure that the encodings enumeration is numbered consistently. + - Fix broken links. ## Notes -[^1]: - This matches the types that Go UnixNano and Java TimeUnit toNanos return, - and hence is used rather than an unsigned integer. +\[^1\]: +This matches the types that Go UnixNano and Java TimeUnit toNanos return, +and hence is used rather than an unsigned integer. From 0f7079b02d32bc72f80231ed778e1b88cb38c932 Mon Sep 17 00:00:00 2001 From: ElodinLaarz Date: Thu, 5 Mar 2026 09:16:58 -0800 Subject: [PATCH 2/7] rerun mdformat after fixing spacing. --- rpc/gnmi/gnmi-specification.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/rpc/gnmi/gnmi-specification.md b/rpc/gnmi/gnmi-specification.md index d46d40f..e46bce6 100644 --- a/rpc/gnmi/gnmi-specification.md +++ b/rpc/gnmi/gnmi-specification.md @@ -142,7 +142,7 @@ The fields of the Notification message are as follows: definition in [2.2.1](#221-timestamps). - `prefix` - a prefix which is applied to all path fields (encoded as per [2.2.2](#222-paths)) included in the `Notification` message. The paths - expressed within the message are formed by the concatenation of `prefix + path`. The `prefix` always precedes the `path` elements. Further semantics + expressed within the message are formed by the concatenation of `prefix + path`. The `prefix` always precedes the `path` elements. Further semantics of prefixes are described in [2.4.1](#241-path-prefixes). - `update` - a list of update messages that indicate changes in the underlying data of the target. Both modification and creation of data is expressed @@ -1611,7 +1611,7 @@ with one of the following `modes`: integer representing nanoseconds between samples. The value of the data item(s) MUST be sent once per sample interval to the client. If the target is unable to support the desired `sample_interval` it MUST reject the - subscription by closing the `Subscribe` RPC specifying an `InvalidArgument (3)` error code. If the `sample_interval` is set to 0, the target MUST + subscription by closing the `Subscribe` RPC specifying an `InvalidArgument (3)` error code. If the `sample_interval` is set to 0, the target MUST create the subscription and send the data with the lowest interval possible for the target. - Optionally, the `suppress_redundant` field of the `Subscription` message @@ -1852,6 +1852,6 @@ limitations under the License ## Notes -\[^1\]: +[^1]: This matches the types that Go UnixNano and Java TimeUnit toNanos return, and hence is used rather than an unsigned integer. From c43f147b12f4d41a06897356788317eed02b3cb0 Mon Sep 17 00:00:00 2001 From: ElodinLaarz Date: Thu, 5 Mar 2026 09:18:48 -0800 Subject: [PATCH 3/7] Fix [^1] --- rpc/gnmi/gnmi-specification.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/rpc/gnmi/gnmi-specification.md b/rpc/gnmi/gnmi-specification.md index e46bce6..d8c081c 100644 --- a/rpc/gnmi/gnmi-specification.md +++ b/rpc/gnmi/gnmi-specification.md @@ -1852,6 +1852,5 @@ limitations under the License ## Notes -[^1]: -This matches the types that Go UnixNano and Java TimeUnit toNanos return, +\[^1\]: This matches the types that Go UnixNano and Java TimeUnit toNanos return, and hence is used rather than an unsigned integer. From 942c5c1ff240eef77112fe7abeea2bfb98363228 Mon Sep 17 00:00:00 2001 From: ElodinLaarz Date: Thu, 5 Mar 2026 09:20:50 -0800 Subject: [PATCH 4/7] Fix [^1] for real this time --- rpc/gnmi/gnmi-specification.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/rpc/gnmi/gnmi-specification.md b/rpc/gnmi/gnmi-specification.md index d8c081c..0aa119e 100644 --- a/rpc/gnmi/gnmi-specification.md +++ b/rpc/gnmi/gnmi-specification.md @@ -1852,5 +1852,4 @@ limitations under the License ## Notes -\[^1\]: This matches the types that Go UnixNano and Java TimeUnit toNanos return, -and hence is used rather than an unsigned integer. +\[^1\]: This matches the types that Go UnixNano and Java TimeUnit toNanos return, and hence is used rather than an unsigned integer. From 874c71fa62453aa1cc64360f9b8e2f36c2af44a9 Mon Sep 17 00:00:00 2001 From: ElodinLaarz Date: Thu, 5 Mar 2026 09:27:28 -0800 Subject: [PATCH 5/7] turns out its a github thing --- rpc/gnmi/gnmi-specification.md | 30 +++++++++++++++--------------- 1 file changed, 15 insertions(+), 15 deletions(-) diff --git a/rpc/gnmi/gnmi-specification.md b/rpc/gnmi/gnmi-specification.md index 0aa119e..a449d39 100644 --- a/rpc/gnmi/gnmi-specification.md +++ b/rpc/gnmi/gnmi-specification.md @@ -319,13 +319,13 @@ type. It should be noted that the target never utilises the `Encoding` enumeration to declare to the client the type of encoding utilised, hence the client must infer the encoding from the populated `TypedValue` field. -| Name | Description | `TypedValue` field | `Encoding` Value | +| Name | Description | `TypedValue` field | `Encoding` Value | | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | ---------------- | -| JSON | A JSON encoded string as per [2.3.1](#231-json-and-json_ietf). | `json_val` | 0 | -| Bytes | An arbitrary sequence of bytes as per [2.3.2](#232-bytes). | `bytes_val` | 1 | -| Proto | A [Protobuf](https://developers.google.com/protocol-buffers/) encoded message using scalar values as per [Section 2.3.3](#233-protobuf). | `string_val`, `int_val`, `uint_val`, `bool_val`, `bytes_val`, `float_val`, `leaflist_val` | 2 | -| ASCII | An ASCII encoded string representing text formatted according to a target-defined convention (described in [Section 2.3.4](#234-ascii)). | `ascii_val` | 3 | -| JSON_IETF | A JSON encoded string as per [2.3.1](#231-json-and-json_ietf) using JSON encoding compatible with [RFC 7951](https://tools.ietf.org/html/rfc7951). | `json_ietf_val` | 4 | +| JSON | A JSON encoded string as per [2.3.1](#231-json-and-json_ietf). | `json_val` | 0 | +| Bytes | An arbitrary sequence of bytes as per [2.3.2](#232-bytes). | `bytes_val` | 1 | +| Proto | A [Protobuf](https://developers.google.com/protocol-buffers/) encoded message using scalar values as per [Section 2.3.3](#233-protobuf). | `string_val`, `int_val`, `uint_val`, `bool_val`, `bytes_val`, `float_val`, `leaflist_val` | 2 | +| ASCII | An ASCII encoded string representing text formatted according to a target-defined convention (described in [Section 2.3.4](#234-ascii)). | `ascii_val` | 3 | +| JSON_IETF | A JSON encoded string as per [2.3.1](#231-json-and-json_ietf) using JSON encoding compatible with [RFC 7951](https://tools.ietf.org/html/rfc7951). | `json_ietf_val` | 4 | ### 2.3.1 JSON and JSON_IETF @@ -995,12 +995,12 @@ request a telemetry stream (see [Section The following table clarifies the target behaviors for `Get` for certain scenarios: -| GetRequest Scenario | Target Behavior | +| GetRequest Scenario | Target Behavior | | ------------------------------------------------------------------------------------------------------------------------ | ------------------------- | -| Requested paths exist or a YANG default value is [in use](https://datatracker.ietf.org/doc/html/rfc7950#section-7.6.1). | Value(s) are returned | -| Requested paths are syntactically correct but one or more paths neither exist (yet) nor has a YANG default value in use. | Return `NOT_FOUND` | -| Requested paths are syntactically correct but one or more paths is not implemented by the server. | Return `UNIMPLEMENTED` | -| One or more requested paths is syntactically incorrect. | Return `INVALID_ARGUMENT` | +| Requested paths exist or a YANG default value is [in use](https://datatracker.ietf.org/doc/html/rfc7950#section-7.6.1). | Value(s) are returned | +| Requested paths are syntactically correct but one or more paths neither exist (yet) nor has a YANG default value in use. | Return `NOT_FOUND` | +| Requested paths are syntactically correct but one or more paths is not implemented by the server. | Return `UNIMPLEMENTED` | +| One or more requested paths is syntactically incorrect. | Return `INVALID_ARGUMENT` | ## 3.4 Modifying State @@ -1739,12 +1739,12 @@ to configuration. The following table clarifies the target behaviors for `Subscribe` for certain scenarios: -| Subscription Scenario | ONCE/POLL | STREAM | +| Subscription Scenario | ONCE/POLL | STREAM | | ------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------- | --------------------------------------------------------------- | -| Subscribed paths exist or a YANG default value is [in use](https://datatracker.ietf.org/doc/html/rfc7950#section-7.6.1). | Value(s) are returned | Value(s) are returned | +| Subscribed paths exist or a YANG default value is [in use](https://datatracker.ietf.org/doc/html/rfc7950#section-7.6.1). | Value(s) are returned | Value(s) are returned | | Subscribed paths are syntactically correct but one or more paths neither exist (yet) nor has a YANG default value in use. | No value returned for non-existent paths | nothing is sent for non-existent paths (yet), RPC is not closed | -| Subscribed paths are syntactically correct but one or more paths is not implemented by the server. | Return `UNIMPLEMENTED` | Return `UNIMPLEMENTED` | -| One or more subscribed paths is syntactically incorrect. | Return `INVALID_ARGUMENT` | Return `INVALID_ARGUMENT` | +| Subscribed paths are syntactically correct but one or more paths is not implemented by the server. | Return `UNIMPLEMENTED` | Return `UNIMPLEMENTED` | +| One or more subscribed paths is syntactically incorrect. | Return `INVALID_ARGUMENT` | Return `INVALID_ARGUMENT` | # 4 Appendix: Current Protobuf Message and Service Specification From 214efb4988e680c82e44109660ea07298bfa58a6 Mon Sep 17 00:00:00 2001 From: ElodinLaarz Date: Thu, 5 Mar 2026 10:23:36 -0800 Subject: [PATCH 6/7] mdformat with footnote support. --- rpc/gnmi/gnmi-specification.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/rpc/gnmi/gnmi-specification.md b/rpc/gnmi/gnmi-specification.md index a449d39..c07f6de 100644 --- a/rpc/gnmi/gnmi-specification.md +++ b/rpc/gnmi/gnmi-specification.md @@ -680,7 +680,7 @@ NOT include such values in data instances sent to the client. The `ModelData` message describes a specific model that is supported by the target and used by the client. The fields of the `ModelData` message identify a data model registered in a model catalog, as described in -[[MODEL_CATALOG_DOC]](https://datatracker.ietf.org/doc/draft-openconfig-netmod-model-catalog/) +[\[MODEL_CATALOG_DOC\]](https://datatracker.ietf.org/doc/draft-openconfig-netmod-model-catalog/) (the schema of the catalog itself - expressed in YANG - is described in \[[MODEL_CATALOG_YANG](https://github.com/openconfig/public/tree/master/release/models/catalog)\]). Each model specified by a `ModelData` message may refer to a specific schema @@ -789,7 +789,7 @@ an error status returned upon responding to the `Set` RPC. Each top-level RPC message (e.g., `SubscribeRequest` and `SubscribeResponse` for the `Subscribe` RPC) defines an `extensions` field which can be used to carry additional parameters for a gNMI RPC. -[[GNMI-EXT]](https://github.com/openconfig/reference/blob/master/rpc/gnmi/gnmi-extensions.md) +[\[GNMI-EXT\]](https://github.com/openconfig/reference/blob/master/rpc/gnmi/gnmi-extensions.md) defines the mechanisms to define such extensions. It must be noted that the base operation of the RPCs as described in this specification MUST NOT be modified by an extension. @@ -843,7 +843,7 @@ the username, the target MUST authorize the RPC request. A more detailed discussion of the requirements for authentication and encryption used for gNMI is in -[[GNMI-AUTH]](https://github.com/openconfig/reference/blob/master/rpc/gnmi/gnmi-authentication.md). +[\[GNMI-AUTH\]](https://github.com/openconfig/reference/blob/master/rpc/gnmi/gnmi-authentication.md). ## 3.2 Capability Discovery @@ -1852,4 +1852,4 @@ limitations under the License ## Notes -\[^1\]: This matches the types that Go UnixNano and Java TimeUnit toNanos return, and hence is used rather than an unsigned integer. +[^1]: This matches the types that Go UnixNano and Java TimeUnit toNanos return, and hence is used rather than an unsigned integer. From 8de97329c8c3e08b7c13cea9e04fcfd9a0c4f05a Mon Sep 17 00:00:00 2001 From: ElodinLaarz Date: Thu, 5 Mar 2026 10:28:06 -0800 Subject: [PATCH 7/7] fix link after spacing changes --- rpc/gnmi/gnmi-specification.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/rpc/gnmi/gnmi-specification.md b/rpc/gnmi/gnmi-specification.md index c07f6de..181a61b 100644 --- a/rpc/gnmi/gnmi-specification.md +++ b/rpc/gnmi/gnmi-specification.md @@ -35,7 +35,7 @@ May 25, 2023 - [2.5 Error handling](#25-error-handling) - [2.6 Schema Definition Models](#26-schema-definition-models) - [2.6.1 The ModelData message](#261-the-modeldata-message) - - [2.7 gNMI Origin in `Path`](#27-gnmi-origin--in-path) + - [2.7 gNMI Origin in `Path`](#27-gnmi-origin-in-path) - [2.7.1 Special Values of `origin`](#271-special-values-of-origin) - [2.7.2 Definition of `origin` for YANG-modelled Data](#272-definition-of-origin-for-yang-modelled-data) - [2.7.3 Partial Specifications of Origin in Set](#273-partial-specifications-of-origin-in-set)