module yumaworks-yp-gnmi {

    yang-version 1.1;

    namespace
      "http://yumaworks.com/ns/yumaworks-yp-gnmi";

    prefix ypgnmi;

    import yumaworks-ycontrol {
      prefix yctl;
    }
    import yuma-types {
      prefix yt;
    }

    organization "YumaWorks, Inc.";

    contact
      "Support <support at yumaworks.com>";

    description
      "Package gNMI defines a service specification for the gRPC
       Network Management Interface. This interface is defined to
       be a standard interface via which a network management system
       ('client') can subscribe to state values, retrieve snapshots of
       state information, and manipulate the state of a data tree
       supported by a device ('target').

       This document references the gNMI Specification which can be
       found at:
       http://github.com/openconfig/reference/blob/master/rpc/gnmi

       Licensed under the Apache License, Version 2.0 (the 'License');
       you may not use this file except in compliance with the License.
       You may obtain a copy of the License at:
       http://www.apache.org/licenses/LICENSE-2.0


       YumaPro gNMI message definitions.
       Copyright (c) 2014 - 2018, YumaWorks, Inc. All rights reserved.

       Redistribution and use in source and binary forms, with or
       without modification, is permitted pursuant to, and subject
       to the license terms contained in, the BSD 3-Clause License
       http://opensource.org/licenses/BSD-3-Clause
       ";

    revision "2018-02-05" {
      description
        "Initial version for datastore access.";
    }


    typedef supported-encoding {
      type enumeration {
        enum "json_val" {
          value 0;
          description
            "A JSON encoded string";
        }
        enum "bytes_val" {
          value 1;
          description
            "An arbitrary sequence of bytes";
        }
        enum "any_val" {
          value 2;
          description
            "A Protobuf encoded message using protobuf.any";
        }
        enum "ascii_val" {
          value 3;
          description
            "An ASCII encoded string representing text
             formatted according to a target-defined convention";
        }
        enum "json_ietf_val" {
          value 4;
          description
            "A JSON encoded string using JSON encoding compatible
             with [RFC 7951]";
        }
      }
    }

    grouping extension-field {
      description
        "The Extension message is defined within the gnmi_ext.proto
        specification. It is carried as a repeated field within each
        of the top-level request and response gNMI messages.

        The Extension message consists of a single oneof which may contain:
         - A well-known extension. Each well known extension defined
           in the gnmi_ext.proto file will be added to the oneof and
           assigned a unique field tag.
         - A registered extension, expressed as a RegisteredExtension message.

        The subfields of this message are:
         - An enumerated id field used to store the unique ID assigned
           to the registered extension.
         - A bytes field which stores the binary-marshalled protobuf
           for the extension.";
      leaf-list extension {
        type union {
          type enumeration {
            enum "EID_UNSET" {
              value 0;
            }
            enum "EID_EXPERIMENTAL" {
              value 1;
              description
                "An experimental extension that may be used during
                 prototyping of a new extension.";
            }
          }
          type binary;
        }
      }
    }  // grouping extension-field

    grouping model-data {
      description
        "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 [draft-openconfig-netmod-model-catalog]
        (the schema of the catalog itself - expressed in YANG - is described
        in [openconfig-module-catalog.yang]).
        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.

        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.
        - version - the supported (or requested) version of the model,
          expressed as 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.";
      list supported-modules {
        key "name";
        description
          "A set of ModelData messages describing each of the
           models supported by the target";
        leaf name {
          type string;
          description
            "Name of the model expressed as a string.";
        }

        leaf organization {
          type string;
          mandatory true;
          description
            "The organization publishing the model, expressed
             as a string.";
        }

        leaf version {
          type string;
          mandatory true;
          description
            "The supported (or requested) version of the model,
             expressed as a string which represents the semantic version
             of the catalog entry.";
        }
      }  // list supported-modules
    }  // grouping model-data

    grouping update-list {
      description
        "A re-usable Update message is utilised to indicate changes to
        paths where a new value is required. The Update message contains
        two fields";
      list update {
        key "path";
        description
          "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.";
        leaf path {
          type string;
          description
            "Paths are represented according to gNMI Path Conventions,
             which defines a structured format for path elements, and any
             associated key values.";
        }

        leaf typed-value {
          type string;
          description
            "The value of a data node (or subtree) is encoded in a
             TypedValue message as a oneof field to allow selection of
             the data type by setting exactly one of the member fields.

             TypedValue is used to encode a value being sent between the
             client and target (originated by either entity).

             message TypedValue {
              One of the fields within the val oneof is populated with the
              value of the update. The type of the value being included in
              the Update determines which field should be populated. In
              the case that the encoding is a particular form of the base
              protobuf type, a specific field is used to store the
              value (e.g., json_val).

              oneof value {
                string string_val = 1;            // String value.
                int64 int_val = 2;                // Integer value.
                uint64 uint_val = 3;              // Unsigned integer value.
                bool bool_val = 4;                // Bool value.
                // Arbitrary byte sequence value.
                bytes bytes_val = 5;
                float float_val = 6;              // Floating point value.
                Decimal64 decimal_val = 7;        // Decimal64 encoded value.
                // Mixed type scalar array value.
                ScalarArray leaflist_val = 8;
                // protobuf.Any encoded bytes.
                google.protobuf.Any any_val = 9;
                bytes json_val = 10;              // JSON-encoded text.
                // JSON-encoded text per RFC7951.
                bytes json_ietf_val = 11;
                string ascii_val = 12;            // Arbitrary ASCII text.
              }
             }
            ";
        }

        leaf duplicates {
          type uint32;
          description
            "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.";
        }
      }  // list update
    }  // grouping update-list

    grouping notifications {
      description
        "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 higher-layer messages for various purposes.

        The creator of a Notification message MUST include the timestamp
        field. All other fields are optional.";
      list notification {
        key "timestamp";
        leaf timestamp {
          type string;
          description
            "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).";
        }

        leaf prefix {
          type string;
          description
            "A prefix which is applied to all path fields 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.";
        }

        leaf alias {
          type string;
          description
            "A string providing an alias for the prefix specified within
             the notification message.";
        }

        uses update-list;

        leaf-list delete {
          type string;
          description
            "A list of paths that indicate the deletion of data nodes
             on the target.";
        }
      }  // list notification
    }  // grouping notifications

    grouping config-parms {
      leaf-list module {
        type yt:NcModuleSpec;
        description
          "Module libraries to use to generate gNMI datastore.
            Generated datastore package contains definitions of structs
            which represent a YANG schema.

            The datastore representation written in go, this
            datastore let us convert/validate/parse YANG to XML/JSON
            to ProtoBuff";
      }
    }  // grouping config-parms

    augment /yctl:ycontrol/yctl:message-payload/yctl:payload/yctl:payload {
      container yp-gnmi {
        choice message-type {
          mandatory true;
          leaf config-request {
            type empty;
            description
              "Message type: subsys-request;
                Purpose: register the service with the server
                and request the service configuration from server.
                Expected Response Message: config-response";
          }
          leaf register-request {
            type empty;
            description
              "Message type: subsys-request;
                Purpose: register the YP-gNMI subsystem
                Expected Response Message: ok or error";
          }
          container config-response {
            description
              "Message type: server-reply;
              Purpose: server will send this element containing the
              requested sub-system configuration.
              Expected Response Message: none";
            uses config-parms;
          }  // container config-response
          container capability-request {
            description
              "Message type: subsys-request;
              Purpose: The CapabilityRequest message is sent to the server
              to request capability information from the server.
              The CapabilityRequest message carries a single repeated
              extension field.

              Expected Response Message: capability-response";
            uses extension-field;
          }  // container capability-request
          container capability-response {
            description
              "Message type: server-response;
              Purpose: message that includes its YP-gNMI service version,
              the versioned data models it supports, and 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, etc), and the encoding to be used
              for the data.

              Expected Response Message: none";
            container supported-modules {
              uses model-data;
            }  // container supported-modules

            leaf supported-encodings {
              type supported-encoding;
              default 'json_val';
              description
                "An enumeration field describing the data encodings supported
                by the target";
            }

            leaf gNMI-version {
              type string;
              description
                "The semantic version of the gNMI service supported by the
                target, specified as a string.";
            }

            uses extension-field;
          }  // container capability-response
          container get-request {
            description
              "Message type: subsys-request;
              Purpose: Ask the main server to send the running
              configuration contents

              Expected Response Message: get-response";
            leaf prefix {
              type string;
              description
                "Paths are represented according to gNMI Path Conventions,
                 which defines a structured format for path elements,
                 and any associated key values.

                 In a number of messages, a prefix can be specified to
                 reduce the lengths of path fields within the message.
                 In this case, a prefix field is specified within a
                 message - comprising of a valid path.
                 In the case that a prefix is specified, the absolute
                 path is comprised of the concatenation of the list of
                 path elements representing the prefix and the list of
                 path elements in the path field.";
            }

            leaf-list path {
              type string;
              description
                "A set of 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.";
            }

            leaf type {
              type enumeration {
                enum "config" {
                  value 0;
                }
                enum "state" {
                  value 1;
                }
                enum "oper" {
                  value 2;
                }
                enum "all" {
                  value 3;
                }
              }
              default 'all';
              description
                "The type of data that is requested from the target.
                 The valid values for type are described below.

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

                  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.";
            }

            leaf encoding {
              type supported-encoding;
              default 'json_val';
              description
                "The encoding that the target should utilise to serialise
                 the subtree of the data tree requested.

                 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.";
            }

            container use-models {
              description
                "A set of ModelData messages indicating the schema definition
                 modules that define the data elements that should be returned
                 in response to the Get RPC call.";
              uses model-data;
            }  // container use-models

            uses extension-field;
          }  // container get-request
          container get-response {
            description
              "Message type: server-response;
              Purpose: Provide the contents of the
              configuration contents.

              Expected Response Message: none";
            container notifications {
              description
                "A set of Notification messages. 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.";
              uses notifications;
            }  // container notifications

            uses extension-field;
          }  // container get-response
          container set-request {
            description
              "Message type: subsys-request;
              Purpose: Ask the main server to send the running
              configuration contents

              In response to a SetRequest, the target MUST respond with a
              SetResponse message. For each operation specified in the
              SetRequest message, an UpdateResult message MUST be included
              in the response field of the SetResponse. The order in which
              the operations are applied MUST be maintained such that
              UpdateResult messages can be correlated to the SetRequest
              operations. In the case of a failure of an operation,
              the status of the UpdateResult message MUST be populated with
              error information. In addition, the status of the SetResponse
              message MUST be populated with an error message indicating
              the success or failure of the set of operations within the
              SetRequest message.";
            leaf prefix {
              type string;
              description
                "The prefix specified is applied to all paths defined
                 within other fields of the message.";
            }

            leaf-list delete {
              type string;
              description
                "A set of paths which are to be removed from the data tree.
                 Where a path is contained within the delete field of the
                 SetRequest message, it should be removed from the target's
                 data tree. In the case that the path specified is to an
                 element that has children, these children MUST be recursively
                 deleted. If a wildcard path is utilised, the wildcards
                 MUST be expanded by the target, and the corresponding
                 elements of the data tree deleted. Such wildcards MUST
                 support paths specifying a subset of attributes required
                 to identify entries within a collection (list, array, or map)
                 of the data schema.

                 In the case that a path specifies an element within the data
                 tree that does not exist, these deletes MUST be silently
                 accepted.";
            }

            container replace {
              description
                "A set of Update messages indicating elements of the
                 data tree whose content is to be replaced.";
              uses update-list;
            }  // container replace

            container update {
              description
                "A set of Update messages indicating elements of the data
                 tree whose content is to be updated.";
              uses update-list;
            }  // container update

            uses extension-field;
          }  // container set-request
          container set-response {
            description
              "A set of Update messages indicating elements of the
               data tree whose content is to be replaced.

               Expected Response Message: none";
            leaf prefix {
              type string;
              description
                "The prefix specified is applied to all paths defined
                 within other fields of the message.";
            }

            leaf timestamp {
              type string;
              description
                "A timestamp at which the set request message was accepted by
                 the system.";
            }

            list update-result {
              key "path op";
              description
                "Containing a list of responses, one per operation specified
                 within the SetRequest message. Each response consists of
                 an UpdateResult message with the following fields";
              leaf path {
                type string;
                description
                  "The path 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.";
              }

              leaf op {
                type enumeration {
                  enum "invalid" {
                    value 0;
                  }
                  enum "delete" {
                    value 1;
                  }
                  enum "replace" {
                    value 2;
                  }
                  enum "update" {
                    value 3;
                  }
                }
                description
                  "The operation corresponding to the path. This value
                   MUST be one of DELETE, REPLACE, or UPDATE.";
              }

              container status {
                leaf code {
                  type int32;
                  description
                    "code - a 32-bit integer value corresponding to the
                     canonical gRPC error code. The Netconfd Internal
                     error in this message.";
                }

                leaf message {
                  type string;
                  description
                    "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.
                     In our case error-string.";
                }

                leaf details {
                  type string;
                  description
                    "details - a repeated field of protobuf. Any messages
                     that carry error details. In our case just error-info";
                }
              }  // container status
            }  // list update-result

            uses extension-field;
          }  // container set-response
        }  // choice message-type
      }  // container yp-gnmi
    }
  }  // module yumaworks-yp-gnmi