YumaPro control system message definition.
Version: 2014-11-19
module yumaworks-ycontrol { yang-version 1; namespace "http://yumaworks.com/ns/yumaworks-ycontrol"; prefix yctl; import yuma-ncx { prefix ncx; } import yuma-types { prefix yt; } organization "YumaWorks, Inc."; contact "Support <support at yumaworks.com>"; description "YumaPro control system message definition."; revision "2014-11-19" { description "Support '*' as the service-id to indicate a server event message that is intended for the YControl layer itself, called ALL_SERVICES. Add shutdown-event message for ALL_SERVICES"; } revision "2014-04-08" { description "Initial version."; } container ycontrol { ncx:abstract; ncx:hidden; leaf message-id { type uint32 { range "1 .. max"; } mandatory true; description "Message identifier. For server-response and subsys-response message types, this value is the same as the corresponding request message."; } leaf message-type { type enumeration { enum "server-event" { value 0; description "Message from server to sub-system. No response expected."; } enum "server-request" { value 1; description "Request message from server to sub-system. A response is expected."; } enum "server-response" { value 2; description "Response message from server to sub-system. Sent when subsys-req received. No response is expected"; } enum "subsys-event" { value 3; description "Message from sub-system to server. No response expected."; } enum "subsys-request" { value 4; description "Request message from sub-system to server. A response is expected."; } enum "subsys-response" { value 5; description "Response message from sub-system to server. Sent when server-req received. No response is expected"; } enum "ycontrol-error" { value 6; description "Response message from either sub-system or server. Sent when a recoverable YControl or service layer error occurs. If non-recoverable error, then session is dropped and no response is sent. Example error: message is for a service-id that does not exist. No response is expected"; } } mandatory true; description "Message type"; } leaf server-id { type union { type yt:NcxName; type string { length "0"; } } mandatory true; description "Server identifier or empty if not known by subsys"; } leaf subsys-id { type yt:NcxName; mandatory true; description "Subsystem identifier"; } leaf service-id { type union { type yt:NcxName; type string { pattern '\*'; } } mandatory true; description "Service identifier. The value '*' indicates a server-event message to all services. These messages are handled by the ycontrol library, not the individual service libraries."; } choice message-payload { mandatory true; container payload { description "This <payload> container is augmented with a service-specific container from other modules."; leaf shutdown-event { type empty; description "Message type: server-event; Purpose: The server is shutting down. Sent to all services (service-id = '*') Expected Response Message: none"; } container yp-grpc { choice message-type { mandatory true; leaf register-request { type empty; description "Message type: subsys-request; Purpose: register the YP-gRPC subsystem Expected Response Message: ok or error"; } container capability-ad-event { description "Subsystem event to advertise all the gRPC available and active capabilities during the registration time. Type: subsys-event Expected Response Message: none"; leaf name { type yang:yang-identifier; mandatory true; description "Name of the gRCP server."; } leaf address { type inet:host; mandatory true; description "IP Address or host name for the gRPC server. The value returned is implementation specific (e.g., hostname, IPv4 address, IPv6 address)"; } leaf port { type inet:port-number; description "TCP port number for the gRPC server. If not present then the default port for the protocol will be used."; } leaf-list proto { type string; description "The list of proto files that gRPC server supports."; } list service { key "name"; description "List of gRPC Services supported by the gRPC server and related information."; leaf name { type string; description "Name of the gRCP Service associated with this list entry."; } list method { key "name"; description "The list of methods supported by the gRPC server and related information."; leaf name { type string; description "Name of the Service Method associated with this list entry."; } leaf client-streaming { type boolean; description "True if the client supports streaming for this method FALSE otherwise."; } leaf server-streaming { type boolean; description "True if the server supports streaming for this method. FALSE otherwise."; } } // list method } // list service } // container capability-ad-event container open-stream-event { description "Subsystem event to advertise a new gRPC server or client stream(s). Type: subsys-event Expected Response Message: none"; list server-stream { key "name"; description "Contains a list of open server gRPC streams."; leaf name { type string; description "Name of a gRCP server stream."; } leaf location { type inet:uri; mandatory true; description "Contains a URL that represents the RPC that uses this client stream."; } } // list server-stream list client-stream { key "name"; description "Contains a list of open client gRPC streams."; leaf name { type string; description "Name of a gRCP client stream."; } leaf location { type inet:uri; mandatory true; description "Contains a URL that represents the RPC that uses this server stream."; } } // list client-stream } // container open-stream-event container close-stream-event { description "Subsystem event to advertise that the gRPC server or client stream was closed. Type: subsys-event Expected Response Message: none"; leaf-list server-stream { type string; description "The list of closed server gRPC streams."; } leaf-list client-stream { type string; description "The list of closed client gRPC streams."; } } // container close-stream-event } // choice message-type } // container yp-grpc 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"; 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"; } } // 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"; 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; } } } // 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 { 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 } // 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."; } 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; } } } // 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."; 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 } // container use-models 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; } } } // 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."; 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."; } 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 leaf-list delete { type string; description "A list of paths that indicate the deletion of data nodes on the target."; } } // list notification } // container notifications 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; } } } // 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."; 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 } // container replace container update { description "A set of Update messages indicating elements of the data tree whose content is to be updated."; 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 } // container update 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; } } } // 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 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; } } } // container set-response } // choice message-type } // container yp-gnmi } // container payload leaf ok { type empty; description "Sent when a request message is processed successfully and no data is needed in the response."; } container error { leaf error-number { type uint32; mandatory true; description "Internal error number"; } leaf transaction-id { type string; description "Server specific transaction identifier. Sent from subsystem to server in subsys-response. It identifies the transaction in case multiple transactions are in progress at once."; } leaf error-message { type string; description "Internal error message, if different from get_error_string(error-number)."; } leaf error-index { type uint32 { range "1 .. max"; } description "Internal edit index number from <start-transaction> message. Set only if an edit-specific error occurred."; } } // container error } // choice message-payload } // container ycontrol } // module yumaworks-ycontrol
© 2023 YumaWorks, Inc. All rights reserved.