| Delay-Tolerant Networking | E. Birrane |
| Internet-Draft | E. DiPietro |
| Intended status: Informational | D. Linko |
| Expires: May 3, 2018 | Johns Hopkins Applied Physics Laboratory |
| October 30, 2017 |
AMA Application Data Modeling
draft-birrane-dtn-adm-00
This document defines a data model suitable for managing applications in asynchronously managed networks. This includes a description of the data structures and type definitions that comprise the data model as well as a template for publishing standardized representations of static elements of the model. A YANG representation of the data model and the template are also provided.
This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."
This Internet-Draft will expire on May 3, 2018.
Copyright (c) 2017 IETF Trust and the persons identified as the document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License.
This document defines a data model suitable for managing applications in asynchronously managed networks.
The Asynchronous Management Architecture [I-D.birrane-dtn-ama] documents a concept for open-loop control of applications and protocols for situations where timely, highly-available connections cannot exist amongst managing and and managed nodes in a network. While the AMA describes a logical data model, it does not include the detailed information necessary to produce interoperable physical models.
This document provides a normative physical model, called an Application Data Model (ADM), that is compliant with the AMA logical data model and can be used to manage individual applications (or protocols). An ADM is comprised of both predefined and dynamic information. Predefined information is represented in an Application Data Definition (ADD) document populated in conformance with an an Application Data Template (ADT). Dynamic information is created on-the-fly by operators in the context of individual network deployments and management scenarios.
The ADM presented in this document is a data model. In order to communicate this model between agents and managers in a network, the model must be encoded for transmission. Any such encoding scheme is outside of the scope of this document. Generally, encoding of the model is a separate concern from the specification of data within the model.
Since different networks may use different encodings for data, mandating an encoding format would require incompatible networks to encapsulate data in ways that could introduce inefficiency and obfuscation. It is envisioned that different networks would be able to encode ADMs in their native encodings such that translating ADM data from one encoding to the next could be a mechanical action taken at network borders. For this reason, the ADM model must provide information necessary to allow for the coherent translation of of different encodings.
Since the specification does not mandate an encoding format, the data model itself must provide enough information to make encoding (and translating from one encoding to another) an unambiguous process. Therefore, where necessary, this document provides identification, enumeration and other schemes that ensure ADMs provide enough information to prevent ambiguities caused by different encoding schemes.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119].
Note: The terms "Actor", "Agent", "Application Data Model", "Atomic Data", "Computed Data", "Control", "Literal", "Macro", "Manager", "Report Template", "Report Entry", and "Rule" are used without modification from the definitions provided in [AMA].
Additional terms critical to understanding the ADMT are as follows.
When a new application is to be asynchronously managed in accordance with the [I-D.birrane-dtn-ama], the series of control and data information specific to that application must be captured in a data model. Portions of that data model will be predefined and common to all instances of the application and portions of the data model will be ad-hoc in the context of specific network deployments and operational conditions.
The conceptual set of all information necessary to manage an application is defined as the data model for that application and termed the Application Data Model (ADM). The portions of the ADM that are predefined can be published as a common set of management information that is otherwise agnostic of any specific network deployment. That set of predefined information is termed the Application Data Definitions (ADD).
To aid in the exchange of data model information, a common identification scheme and data format should be used to capture information. This is defined in this document as a template that can be filled out for each application and is terms the Application Data Template (ADT).
The relationship of the ADM, ADD, and ADT are illustrated in Figure 1.
Data Model Relationship
+---------+
| ADT |
+----+----+
|
V
+---------+ +-----------+
| Ad-Hoc | | Published |
| Info | | ADD |
+----+----+ +-----+-----+
| |
V V
+-----------------------------+
| ADM |
+-----------------------------+
Figure 1
This section describes custom type definitions used by the ADM. Specifying basic type definitions is important as it forms the basis for interchangeable encodings of the model.
ADMs support a series of primitive types such as bytes, (un)signed integers, floating point values, and others as outlined in Table 1.
| Type | Description |
|---|---|
| BYTE | unsigned byte value |
| INT | 32-bit signed integer in 2's complement |
| UINT | 32-bit unsigned integer in 2's complement |
| VAST | 64-bit signed integer in 2's complement |
| UVAST | 64-bit unsigned integer in 2's complement |
| REAL32 | Single-precision, 32-bit floating point value in IEEE-754 format. |
| REAL64 | Double-precision, 64-bit floating point value in IEEE-754 format. |
| STRING | NULL-terminated series of characters in UTF-8 format. |
| BOOL | A Boolean value of FALSE (whose integer interpretation is 0) or TRUE (which is any integer interpretation that is not FALSE). |
A derived typed is a primitive type that is interpreted with special semantics. The ADM supports the following derived types.
A Hex String is a special type of STRING.
A Hex String contents a written representation of a hexadecimal value, without prefix. In this scheme, byte values are separated by colons (:). While either upper or lower case characters are acceptable, by convention lower-case characters should be used for increased readability.
For example, given the hexadecimal value 0x12AB the resultant Hex String would be "12:ab".
Hex Strings follow the format of the hex-string derived type as defined in RFC6991.
A Timestamp is a special type of UVAST.
There are two "types" of timestamp within an ADM: a relative timestamp and an absolute timestamp. A relative timestamp is defined as the number of seconds between two events (such as the receipt of a control by an agent and the execution of that control). An absolute timestamp is defined as UTC time since the Unix/POSIX Epoch.
Rather than define two separate data types (one for relative timestamps and one for absolute timestamps) or adding an extra field (e.g., a timestamp type identifier) the type of timestamp can be simply and unambiguously inferred from a single timestamp value. The ADMT defines a Relative Timestamp Epoch. Timestamp values less than the RTE will be interpreted as relative timestamps. Timestamp values greater than or equal to the RTE will be interpreted as absolute timestamps. The RTE is defined as September 9th, 2012 (UTC time 1347148800).
For example, a timestamp value of "10" refers to 10 seconds in the future. A timestamp value of "1508554859" refers to Saturday, October 21, 2017 3:00:59 AM.
IF (timestamp < 1347148800) THEN
absolute_time = current_time + timestamp
ELSE
absolute_time = timestamp
It should be noted that absolute and relative times are interchangeable. An absolute time can be converted into a relative time by subtracting the current time from the absolute time. A relative time can be converted into an absolute time by adding to the relative time the current time. A pseudo-code example of this conversion is as follows.
A Type-Name-Value Collection (TNV) is a special type of STRING.
A TNV describes a list of ADM items with each item described as the three-tuple of {type, name, value} or certain permitted subsets of that three-tuple. The general form of the string is <type>:<name>=<value> with each item in the collection separated by "&".
Type refers to the string representation of the ADM item type as defined in Section 9. Name refers to the name of the ADM item. Value refers to the string (or hex string) value of the ADM item.
For each item in a TNV, there are three acceptable formulations that can be used to represent the item, as illustrated in the following table. For the examples in this table, consider the REAL32 value of PI as 3.14159.
| Desc | Format | Example |
|---|---|---|
| Full | <type>:<name>=<value> | REAL32:PI=3.14159&INT:PI_INT=3 |
| Named Type | <type>:<name> | REAL32:PI&INT:PI_INT |
| Anonymous Type | <type> | REAL32&INT |
| Anonymous Type Value | <type>:=<value> | REAL32:=3.14159&INT:=3 |
| Anonymous Value | =<value> | =3.14159&=3 |
| Mixed | Varies | REAL32:PI=3.14159&INT:PI_INT&INT&=3 |
In ADMs, TNVs are used to capture parameterized items and describe the contents of reports.
The primary responsibility of an ADM is to uniquely identify the components necessary to asynchronously manage the application. This section describes the two mechanisms used to identify every item within every ADM: Asynchronous Resource Names (ARNs) and Managed Identifiers (MIDs).
Every ADM must identify itself by an asynchronous resource namespace (ARN). This is separate from the YANG namespace and provides a moderated, formatted way of identifying the ADM in the context of other ADMs. Such a naming provides important semantic information necessary for encodings of ADM contents. The format of an ARN is a colon-separated set of moderated scoping keywords, as follows.
arn:<Broadest-Scoped Keyword>:<Narrowest-Scoped Keyword>
For example, the DTN community publishes the Bundle Protocol and the ADM for the Bundle Protocol could be assigned the namespace arn:Dtn:BundleProtocol. Another ADM published specifically for management of a particular implementation of a Bundle Protocol Agent (for example, the Interplanetary Overlay network (ION)) could have the separate namespace arn:DTN:ION:BundleProtocolAdmin.
ARN keywords will be moderated to create a known keyword list and associated ontology that provides some semantic structure to ADM names beyond the associations that may or may not be present to allow groupings in the YANG format.
Every item codified in a published ADM (or generated in operational use) must be uniquely identifiable. The Managed Identifier (MID) accomplishes this by providing a variable-length, flexible structure with optional fields to capture special identifier-related circumstances.
A MID in an ADM consists of three types of information: (1) human-readable semantic information, (2) the identifier value, and (3) parameters, if necessary.
A MID can have an optional name and description associated with it. These help provide documentation of the ADM item identified by the MID.
The MID Name is a string that should uniquely identify the ADM item within the context of the ADM. It is recommended that this name be a human-readable and user-friendly alternative to the numeric ID portion of the MID.
The MID Description is a string that captures important information describing the purpose of usage of the ADM item. The description should also be human-readable and user-friendly. The MID description is not considered part of the uniquely identifying part of the MID and may be duplicated across multiple MIDs in an ADM. No part of the MID description should be used to interpret the uniqueness of any ADM item.
There are two categories of information that can be identified by a MID in an ADM: named and literal items. A named item is an item in an ADM whose value should not be used as its identifier. This can be because the value is not unique to the item, or the value is of such length or complexity as to make its use as an identifier impractical. A literal item is one that can be uniquely and succinctly identified by its value.
The identification of a named item consists of four parts: (1) The type of item being identified, (2) a unique identifying value for the item, (3) an optional issuer field, and (4) an optional tag field. These four items are represented as a string with the format <Type>_<enumeration>:<issuer>:<tag>. The description of each of these types is as follows.
Item Type
The type of the ADM item being identified is the string representation of the type, as defined in Section 9.
Unique Identifier
The identifier may be any uniquely identifying information, such as the name of the MID, or a numeric enumeration of the order of the MID in the ADM.
Issuer
The issuer field is any string (or hex string) representing some identification of the organization defining this item. This value may come from a global registry of organizations, an issuing node address, a signed known value, or some other network-unique marking. When an item is defined in the context of an ADM, the issuer tag MUST NOT be present. ADD-defined items are defined relative to their ARN and need no additional information to determine their issuer. Therefore, the issuer tag is only present in ADM items created on-the-fly as part of an operational network.
Tag
The tag field is any string (including a hex string) used to disambiguate or otherwise validate a MID created by an issuer. Similar to the issuer field, the tag field MUST NOT be present in a MID identified in an ADM. Since a tag field has meaning only in the context of its issuer it MUST NOT be present in a MID that is lacking an issuer field. The contents of the tag field is left to the discretion of the issuer. Examples of envisioned tag values include an issuer-known version number or a signed or unsigned hashing of the data associated with the MID.
The identification of a literal item consists of three parts: (1) The type of item being identified, (2) the data type of the value, and (3) the value of the item. These two items are represented as a string in the ADM with the format <Type>_<value type>.<value>. The description of each of these types is as follows.
Item Type
The type of a literal item MUST be LIT.
Value Type
The type of the literal value. This MUST be one of the primitive types as described in Table 1.
Value
The value is simply the value of the item.
For example, here are some ways of identifying the literal value "9" in an ADM.
| Description | Example |
|---|---|
| As a signed integer | LIT_INT.9 |
| As an unsigned integer | LIT_UINT.9 |
| As a floating point value | LIT_REAL32.9.0 |
| As a string | LIT_STR.Nine |
Certain ADM items can be parameterized to support a cleaner and less-chatty interface between agents and managers. When a MID is parameterized, a parameter specification is appended to the end of the string representation of the MID. This specification may capture "formal parameters" or "actual parameters". The ADM also supports the specification of optional parameters.
A "formal parameter" defines the type, name, and order of the variables that should be provided to the MID. Formal parameters are defined in the context of an ADM using static, strong typing. This approach is similar to how parameters are defined in a function definition, such as "foo(int a, float b)". In this example, the function foo is defined as accepting two variables: an integer named "a" and a floating point value named "b".
Formal parameters MUST include TYPE and NAME information and MAY include an optional default VALUE. If specified, a default value will be used whenever a set of Actual Parameters fails to provide a value for this Formal Parameter.
Formal parameters are represented in a MID using a TNV Collection. The TNV for the example above could be represented as "INT:a&REAL32:b". Also, if parameter a had a default value of 7, the Formal Parameter list could have been represented as "INT:a=7&REAL32:b".
An "actual parameter" defines the type, name, and value of a set of variables that serve as arguments for a previously-defined formal parameter set. Actual parameters are used when a particular instance of a parameterized ADM item is generated by an Agent or a Manager and the MID of that instance must contain values that match, in type and number, the formal parameters of the ADM item. Using the "foo" example above, an actual parameter list would be represented in the call "foo(3, 3.14)".
An Actual Parameter MAY have any combination of TYPE or VALUE information. If the Formal Parameter list defined a default value, then the associated Actual Parameter MAY also be empty. If a TYPE is provided in an Actual Parameter then the type MUST match the type provided by the Formal Parameter. An Actual Parameter MUST NOT include NAME information.
Actual parameters are represented in a MID using a TNV string. The TNV for the example above could be represented as "INT:a=3&REAL32:b=3.14". If parameter a had a default value defined, then another possible Actual Parameter list for the above example could be represented as "INT:=&b=3.14" or simply "&b=3.14".
When parameterizing an ADM item, some parameters may be optional with default values defined if parameters are omitted. The use of optional parameters helps keep MID values small when using default values for parameters is a common case, rather than forcing all parameters to be provided all the time.
Consider the following TNV string capturing a set of formal parameters: "INT:a&REAL32:b&UINT:c=0&INT:d=-1". The following table shows the values of formal parameters c and d given a variety of TNV strings representing actual parameters.
| Actual Parameter | C Value | D Value |
|---|---|---|
| INT:=3&REAL32:=3.14 | 0 | -1 |
| INT:=3&REAL32:=3.14&UINT:=1 | 1 | -1 |
| INT:=3&REAL32:=3.14&UINT:=1&INT:=-2 | 1 | -2 |
| INT:=3&REAL32:=3.14&&INT:=-2 | 0 | -2 |
Actual Parameters in a MID may be represented in one of two ways: the parameter itself (parameter by value), or an expression used to determine the parameter (parameter by evaluation).
When specifying a parameter using a value, the type of the Actual Parameter MUST be present and MUST match the expected Formal Parameter type. The Actual Parameter value will be used as the value of the parameter.
For example, consider a Formal Parameter list that takes 1 parameter, an unsigned integer (UINT). When populating this parameter by value, the type of the Actual Parameter MUST be UINT and the parameter value MUST be the desired unsigned integer.
When the value of a Actual Parameter is likely to change, an Expression (EXPR) may be substituted for the Actual Parameter value. The Expression can then be evaluated to calculate the value.
An Actual Parameter defined by evaluation MUST be of type EXPR, and the type of the EXPR must be equal to the expected type. Expressions and Expression types are discussed in Section 3.6.2.
NOTE: If the type of the Formal Parameter is already EXPR, and an Actual Parameter of type EXPR is provided, then the Actual Parameter MUST be processed in the same way as Parameter By Value. The ADM does not support an EXPR which references another EXPR as doing so leads to significant confusion in implementations and the possibility of circular reference.
The determination of whether an Actual Parameter should be interpreted by value or by evaluation is made by comparing the given type of the Actual Parameter to the expected type of the Formal Parameter.
If the types match, then the Actual Parameter MUST be considered by value. If the Actual Parameter type is an EXPR and the EXPR type matches the Formal Parameter type, then the Actual Parameter MUST be considered by evaluation of the EXPR. In any other case, the Actual Parameter MUST be considered invalid as being from a type mismatch.
There are several times when a MID must be referenced within the contents of an ADM document and a useful shorthand is defined to allow for this expression. Since a MID name is required to be unique for a given data type, the combination of MID type and MID name may be used as a reference.
Specifically, a MID reference is a string with the form <type>.<name>.
Often, in either an ADM or an ADD, it is necessary to discuss collections of items that are provided as parameters to other items. For example, a Control that is used to generate a series of Report Entries may accept, as a parameter, a list of the MIDs defining the Report Templates to be generated.
A MC may be represented as a string that contains zero or more MID representations separated by whitespace. A MID within a MC MAY be either a MID Reference or a MID Identifier.
A MC may alternatively be represented as an array with zero or more elements, with each element being a MID representation (either a MID reference or a MID identifier).
Expression apply mathematical operations to values to generate new values, typically on computers fulfilling the Agent role within the AMA. Since the variables, operators, and literals that comprise these operations are all formal ADM items, they are all identified by MIDs. Because they are all identified by MIDs, the expression may be represented by a MC.
An expression (EXPR) is a MC in which a series of items are ordered so as to produce a valid post-fix mathematical expression. For example, the infix expression A * (B * C) is represented as the sequence A B C * *.
Predicates are Expressions whose values are interpreted as a Boolean. The value of zero MUST be considered "false" and all other values MUST be considered "true".
This section identifies the ADM structures that implement the AMA logical data model.
The AMA defines a series of logical components that should be included as part of an ADM. These components are summarized from the AMA in the following table. The ADM implements these logical components in largely a one-to-one fashion with a few exceptions.
| AMA Component | Summary Description | ADM Structure |
|---|---|---|
| Atomic Data | A typed, measured value whose definition and value determination occurs externally from the network management system. | Externally Defined Data |
| Computed Data | A typed, computed value whose definition and value determination occurs within the network management system. | Variable |
| Report Entry | Collections of Atomic and/or Computed data and/or other Reports. | Table Definition, Table, Report Definition, Report |
| Control | Parameterized opcode for any action that can be taken by an Agent. | Control |
| Rule | A pre-configured response to a predefined time or state on an Agent. | State-Based Rule, Time-Based Rule |
| Macro | An ordered collection of Controls. | Macro |
| Literal | A constant used when evaluating Rules or determining the value of Computed Data. | Literal, Constant |
| Operator | An opcode representing a mathematical function known to an Agent. | Operator |
The remainder of this section describes the format of these structures in the context of the aforementioned ADM data types.
Externally defined data (EDD) are predefined components of an ADM for various applications and protocols. These represent values that are calculated outside of the context of Agents and Managers, such as those values measured by firmware. As such, their value is defined external to the ADM system.
An EDD consists of a MID, type, and a description, as follows.
Managers
Agents
Variables (VAR) may be predefined in an ADD or dynamically in a network deployment. VARs differ from EDDs in that they are completely described by other known data in the system (either other VARs or other EDDs). For example, letting E# be a EDD item and V# be a VAR item, the following are examples of VAR definitions.
V1 = E1 * E2
V2 = V1 + E3
VARs are defined by a MID, a type, an initializing expression, and a description, as follows.
Managers
Agents
A Table is a named, typed, collection of tabular data. Columns within a table are named and typed. Rows within a table capture individual data sets with one value in each row corresponding to one column in the table.
Tables are represented in two ways in the ADM: Table Definitions and Table Instances. A Table Definition appears in an ADD and describes the general format of a table. A Table Instance is a set of data populated according to the structure of a Table Definition.
Table definitions are predefined items of an ADM and, as such, MUST appear in the ADD for an application.
TBLTs are defined by a MID, a set of column descriptions, and a description, as follows.
Tables are collections of data that MUST be constructed in accordance with an associated Table Template. Tables MUST NOT appear in the ADD for an application; they are only instantiated dynamically as part of the operation of a network.
TBLs are defined by their Table Template, the number of rows in the table, and the associated set of data values for each row.
Managers
Agents
A Report is a set of non-tabular, potentially nested data items that may be predefined in the context of an ADD, or defined dynamically in the context of a deployed network.
Reports are represented in two ways in the ADM: Report Templates and Reports. A Report Template defines the type of information to be included in a report, and a Report contains that information.
A Report Template (RPTT) is the ordered set of data descriptions that describe how values will be represented in a corresponding Report. RPTTs can be viewed as a schema that describes how to interpret a Report; they contain no values and are either defined in an ADM or configured between Managers and Agents during network operations.
RPTTs are defined by a MID, the set of information comprising the report, and a description, as follows.
A Report (RPT) is a set of data values populated in conformance to a given RPTT. Each data value in a report is termed a Report Entry (RPTE).
RPTs are defined by their associated report template and the report entries themselves, as follows.
Managers
Agents
A Control represents a predefined (possibly parameterized) opcode that can be run on an Agent. Controls in the ADM are always defined in the context of an ADD as there is no concept of an operator-defined Control. Since Controls are pre-configured in Agents and Managers as part of ADM support, their representation is simply the MID that identifies them, similar to EDDs.
Controls are identified by their MID and their description, as follows.
Managers
Agents
A Time-Based Rule (TRL) specifies that a particular action should be taken by an Agent based on some time interval. A TRL specifies that starting at a particular START time, and for every PERIOD seconds thereafter, an ACTION should be run by the Agent until the ACTION has been run for COUNT times. When the TRL is no longer valid it MAY BE discarded by the Agent.
Examples of TRLs include:
Managers
Agents
A State-Based Rule (SRL) specifies that a particular action should be taken by an Agent based on some evaluation of the internal state of the Agent. A SRL specifies that starting at a particular START time an ACTION should be run by the agent if some CONDITION evaluates to true, until the ACTION has been run COUNT times. When the SRL is no longer valid it MAY be discarded by the agent.
Examples of SRLs include:
Managers
Agents
Macros are ordered collections of MIDs (an MC) that contain Controls or other Macros. When run by an Agent, each MID in the MC is run in order.
A Macro is defined by a MID, a set of Controls, and a description, as follows.
Managers
Agents
Constants represent named basic values. Examples include common mathematical values such as PI or well-known Epochs such as the UNIX Epoch. Constants are defined solely within the context of ADDs.
A CONST is defined by its MID, value, and description, as follows.
Managers
Agents
Operators represent user-defined mathematical functions implemented in the firmware of an Agent for the purpose of aiding the evaluation of Expressions and Predicates. The ADM separates the concepts of Operators and Controls to prevent side-effects in Expression and Predicate evaluation (e.g. to avoid constructs such as A = B + GenerateReport()) which is why Operators are given their own structure type and Controls do not support a return value.
Because Operators represent custom firmware implemented on the Agent, they are not defined dynamically as part of network operations. Therefore, they may only be defined in the ADD for an application.
An Operator is defined by its MID, its resultant type, the number of operands, the type of operands, and a description, as follows.
Managers
Agents
This section defines identifiers and enumeration values for objects defined in the ADM. Identifiers are the text abbreviations used in ADMs to identify data types. Enumerations associate data types with a numeric value. These enumerations MUST be used whenever a data type is represented as a numerical representation.
IDs and enumerations are grouped by the kind of data they represent, as follows. ADM structure identifiers occupy enumerations 0 - 9 and represent data structures that are formally identified by a MID. Basic data types occupy enumerations 10-18 and represent primitive data types. Special types occupy the remaining enumeration space.
While the ADM does not specify any encoding of data model elements, a common set of enumerations help to ensure that various encoding standards can interoperate.
| Structure | ID | Enumeration | Numeric |
|---|---|---|---|
| Externally Defined Data | EDD | 0 | No |
| Variable | VAR | 1 | No |
| Table Template | TBLT | 2 | No |
| Report Template | RPTT | 3 | No |
| Control | CTRL | 4 | No |
| Time-Based Rule | TRL | 5 | No |
| State-Based Rule | SRL | 6 | No |
| Macro | MACRO | 7 | No |
| Constant | CONST | 8 | No |
| Operator | OP | 9 | No |
| Basic Data Type | ID | Enumeration | Numeric |
|---|---|---|---|
| BYTE | BYTE | 10 | No |
| Signed 32-bit Integer | INT | 11 | Yes |
| Unsigned 32-bit Integer | UINT | 12 | Yes |
| Signed 64-bit Integer | VAST | 13 | Yes |
| Unsigned 64-bit Integer | UVAST | 14 | Yes |
| Single-Precision Floating Point | REAL32 | 15 | Yes |
| Double-Precision Floating Point | REAL64 | 16 | Yes |
| Character String | STR | 17 | No |
| Boolean | BOOL | 18 | No |
| Compound/Special Data Type | ID | Enumeration | Numeric |
|---|---|---|---|
| Hex String | TS | 19 | No |
| Timestamp | TS | 20 | No |
| Type-Name-Value Collection | TNV | 21 | No |
| Asynchronous Resource Namespace | ARN | 22 | No |
| Managed Identifier | MID | 23 | No |
| MID Collection | MC | 24 | No |
| Expression | EXPR | 25 | No |
| Predicate | EXPR | 26 | No |
When attempting to evaluate operators of different types, wherever possible, an Agent MAY need to promote operands until they are of the correct type. For example, if an Operator is given both an INT and a REAL32, the INT SHOULD be promoted to a REAL32 before the Operator is applied.
INT UINT VAST UVAST REAL32 REAL64
+--------+--------+--------+--------+--------+--------+
INT | INT | INT | VAST | UNK | REAL32 | REAL64 |
UINT | INT | UINT | VAST | UVAST | REAL32 | REAL64 |
VAST | VAST | VAST | VAST | VAST | REAL32 | REAL64 |
UVAST | UNK | UVAST | VAST | UVAST | REAL32 | REAL64 |
REAL32 | REAL32 | REAL32 | REAL32 | REAL32 | REAL32 | REAL64 |
REAL64 | REAL64 | REAL64 | REAL64 | REAL64 | REAL64 | REAL64 |
+--------+--------+--------+--------+--------+--------+
Figure 2: Numeric Promotions
Listing legal promotion rules is mandatory for ensuring that behavior is similar across multiple implementations of Agents and Managers. The listing of legal promotions in the ADM are listed in Figure 2. In this Figure, operands are listed across the top row and down the first column. The resultant type of the promotion is listed in the table at their intersection.
ADMs do not permit promotions between non-numeric types, and numeric promotions not listed in this section are not allowed. Any attempt to perform an illegal promotion SHOULD result in an error.
Variables, Expressions, and Predicates are typed values. When attempting to assign a value of a different type, a numeric conversion must be performed. Any numeric type may be converted to any other numeric type in accordance with the C rules for arithmetic type conversions.
This section contains three sets of YANG modules which capture the ADM and ADT concepts.
There are two YANG modules that capture all elements of the ADM: basic structures and complex structures, as follows.
module basic-structures{
yang-version 1.1;
namespace "urn:ietf:params:xml:ns:yang:basic-structures";
prefix basic;
organization "JHUAPL";
contact
"Edward.Birrane@jhuapl.edu";
revision "2017-10-30" {
description "Initial Revision";
}
description
"This YANG module models the basic structures and collections that make up the complex structures in asynchronous systems.";
typedef type-enum{
type enumeration{
enum EDD{description "external defined data";}
enum VAR{description "variable";}
enum RPT{description "report";}
enum CTRL{description "control";}
enum SRL{description "state-based rule";}
enum TRL{description "time-based rule";}
enum MACRO{description "macro";}
enum CONST{description "constant";}
enum OP{description "operator";}
enum TBL{description "table";}//moved to capture in a nibble
enum LIT{description "literal";}
enum BYTE{description "unsigned byte value";}
enum INT{description "32bit signed integer";}
enum UINT{description "32bit unsigned integer";}
enum VAST{description "64bit signed integer";}
enum UVAST{description "64bit unsigned integer";}
enum REAL32{description "32bit floating point";}
enum REAL64{description "64bit floating point";}
enum BOOL{description "boolean";}
enum SDNV{description "self-delimiting numeric value";}
enum TS{description "timestamp";}
enum STR{description "string";}
enum BLOB{description "binary large object";}
enum MID{description "managed identifier";}
enum MC{description "MID collection";}
enum EXPR{description "expression";}
enum DC{description "data-collection";}
enum TC{description "type-collection";}
enum TDC{description "type-data-collection";}
}
description "This is the enumeration for the various basic data types.";
}
typedef hex-string{
type string{
pattern
'[0-9a-fA-F]{2}(:[0-9a-fA-F]{2})*';
}
description
"This defines a hexadecimal string with octets represented as hex digits
separated by colons. The canonical representation uses
lowercase characters.";
reference
"RFC 6991:Common YANG Data Types";
}
typedef mid-ref{
type string{
pattern
'^(EDD|VAR|RPT|CTRL|SRL|TRL|MACRO|CONST|OP|TBL).\w+$';
}
description
"A mid reference uses the MID's type and it's unique name to quickly identify it.
They are used in MID collections to avoid restating already defined MIDs, helping to reduce space.";
}
typedef ts{
type uint64;
description
"A timestamp value can represent either a relative or absolute time.
A relative time is defined as the number of seconds between two events.
An absolute time is defined as UTC time using the UNIX/POSIX Epoch.";
}
typedef type-name-value-collection{
type string{
pattern
'^((EDD|VAR|RPT|CTRL|SRL|TRL|MACRO|CONST|OP|BYTE|INT|UINT|VAST|UVAST|REAL32|REAL64|BOOL|SDNV|TS|STR|BLOB|MID|MC|EXR|DC|TDC|TBL):\S+(&(EDD|VAR|RPT|CTRL|SRL|TRL|MACRO|CONST|OP|BYTE|INT|UINT|VAST|UVAST|REAL32|REAL64|BOOL|SDNV|TS|STR|BLOB|MID|MC|EXR|DC|TDC|TBL):\S+)*)|(^\S+=\S+(&\S+=\S+)*)|((EDD|VAR|RPT|CTRL|SRL|TRL|MACRO|CONST|OP|BYTE|INT|UINT|VAST|UVAST|REAL32|REAL64|BOOL|SDNV|TS|STR|BLOB|MID|MC|EXR|DC|TDC|TBL):\S+=\S+(&(EDD|VAR|RPT|CTRL|SRL|TRL|MACRO|CONST|OP|BYTE|INT|UINT|VAST|UVAST|REAL32|REAL64|BOOL|SDNV|TS|STR|BLOB|MID|MC|EXR|DC|TDC|TBL):\S+=\S+)*)(&((EDD|VAR|RPT|CTRL|SRL|TRL|MACRO|CONST|OP|BYTE|INT|UINT|VAST|UVAST|REAL32|REAL64|BOOL|SDNV|TS|STR|BLOB|MID|MC|EXR|DC|TDC|TBL):\S+(&(EDD|VAR|RPT|CTRL|SRL|TRL|MACRO|CONST|OP|BYTE|INT|UINT|VAST|UVAST|REAL32|REAL64|BOOL|SDNV|TS|STR|BLOB|MID|MC|EXR|DC|TDC|TBL):\S+)*)|(^\S+=\S+(&\S+=\S+)*)|((EDD|VAR|RPT|CTRL|SRL|TRL|MACRO|CONST|OP|BYTE|INT|UINT|VAST|UVAST|REAL32|REAL64|BOOL|SDNV|TS|STR|BLOB|MID|MC|EXR|DC|TDC|TBL):\S+=\S+(&(EDD|VAR|RPT|CTRL|SRL|TRL|MACRO|CONST|OP|BYTE|INT|UINT|VAST|UVAST|REAL32|REAL64|BOOL|SDNV|TS|STR|BLOB|MID|MC|EXR|DC|TDC|TBL):\S+=\S+)*))*$';
}
description
"A TNV collection describes a list of ADM items where each item is described as a three tuple of {type, name, value}
or certain permitted subsets of that three-tuple.
GENERAL FORMAT- <type>:<name>=<value>";
}
grouping mid{
description
"A managed identifier(MID) is used to provide unique naming for structures.
There is a general MID format for everything except for Literals.
Literal MIDs are interpreted in a different way to express numeric values without the need to store numbers as full MIDs.
Regular expressions are used to show a general human readable organization of a MID.";
leaf name{
type string;
description
"The human readable name identifying the MID. Should act as the key in the structure containing the MIDs.";
}
choice mid{
case reg-mid{
leaf id{
type string{
pattern
'^(EDD|VAR|RPT|CTRL|SRL|TRL|MACRO|CONST|OP|TBL)_(\w+)(\.\w+)?(:\w+(:\w+)?)?$';
}
mandatory true;
description
"This pattern organizes the needed information for a MID.
<TYPE>_<ID>.<opt nicknamed>:<opt issuer>:<opt tag>
The type and ID field is mandatory. Everything else is optional and can be left as an empty section.
The type gives the type of the identifed object. The ID is the unique ID of the object.
The optional but encouraged nickname helps to reduce the total space of the MID.
The optional issuer represents a predetermined issuer name.
The optional tag is used to disambiguate multiple MIDs with the same OID/Issuer combination. MIDs can't have a tag without an issuer.
ex.) VAR_01.14 => MID for a for a non-parameterized compressed variable with nickname 14 and id 01";
}
choice params{
case proto{
leaf paramspec-proto{
type type-name-value-collection;
description
"In a proto-mid, parameters represents a prototype with parameters being a type collection.";
}
}
case full{
leaf paramspec{
type type-name-value-collection;
description
"This parameter specification can represent a function call with the parameters being a typed data collection.";
}
}
description
"Depending on if the MID's parameters have values or not, a type-collection or a type-data-collection could be used.";
}
}
case LIT-mid{
leaf num-id{
type string{
pattern
'^LIT_(INT|UINT|VAST|UVAST|REAL32|REAL64)\.(\d+(\.\d+))?$';
}
mandatory true;
description
"Literals are specialized MIDs.
Since Literals are not stored and evaluated when needed, there is no 'name field' associated with them.
Literals only contain type value information.
ex.) LIT_INT.9 is how the integer value 9 would be expressed";
}
}
mandatory true;
description
"You can use either a standard MID or a specialized literal MID to represent numbers.";
}
}
grouping mid-collection{
description
"A mid collection(MC) is a collection of MIDs. The ideal way to show a MC is to list the MIDs using a mid-ref or nickname id pair,
and use the full-MIDs only when that MID is being defined for the first time.";
choice mc-type{
case string{
leaf string-mc{
type string;
description
"The MID collection is represented using a string to list all the mids.
If it contains MIDs that have already been defined, then it should use the mid-ref format previously stated.
MIDs are separated by spaces.";
}
}
case array{
leaf-list array-mc{
type string;
description
"The MID collection is represented using an array to list all the MIDs.
If it contains MIDs that have already been defined then it should use the mid-ref format previously stated.";
}
}
mandatory true;
description
"A MID collection can be modeled as a string, where MIDs are separated by spaces, or by an array of MIDs.";
}
}
grouping expr{
description
"Expressions apply operations to values to generate new values.";
leaf type{
type type-enum;
mandatory true;
description
"This is the enumeration representing the type of the result of the evaluated expression";
}
uses mid-collection{
description
'An expression is represented as a MID collection,
where each MID in the ordered collection represents the data, constants
and/or operations that comprise the expression. The expression must use the following pattern:
EDD/VAR/CONST/NUM.name OP.name EDD/VAR/CONST/NUM.name.....
(((EDD)|(VAR)|(CONST)|(NUM)).(\w+)_?)+op.\S)+
Uses post fix format.';
}
}
}
module complex-structures{
yang-version 1.1;
namespace "urn:ietf:params:xml:ns:yang:complex-structures";
prefix complex;
import basic-structures{
prefix basic;
}
organization "JHUAPL";
contact
"Edward.Birrane@jhuapl.edu";
revision "2017-10-30" {
description "Initial Revision";
}
description
"This module models complex structures for asynchronous systems.";
grouping externally-defined-data {
description
"Externally defined data (EDD) represents values that are calculated outside of the context of Agents and Managers
such as values that are measured by firmware.";
uses basic:mid;
leaf type {
type basic:type-enum;
mandatory true;
description
"This is the type of the stored data.";
}
leaf description{
type string;
description
"This gives a human readable description of the EDD.";
}
}
grouping variable{
description
"Variables are values that are completely described by other known data in the system such as other variables or other EDDs.";
uses basic:mid{
description
"This is the MID for the variable.";
}
leaf type{
type basic:type-enum;
mandatory true;
description
"This is the type of the variable. It acts as a static cast for the result of the initializing expression.";
}
container initializer{
uses basic:expr;
presence
"This is the initializer represented by an expression";
description
"An expression is used as the initializer for the variable.";
}
leaf description{
type string;
description
"This is the human readable description of the variable.";
}
}
grouping table-template {
description
"This is the template for prototyping tables.";
uses basic:mid{
description
"This is the MID for the table-template.";
}
leaf columns{
type basic:type-name-value-collection;
mandatory true;
description
"A TNV collection is used to store the type and names of the columns in the table-template.";
}
leaf description{
type string;
description
"This is the human readable description of the table.";
}
}
grouping table {
description
"A table is a names, typed, collection of tabular data with each row represented as a data collection
and each column defined by both a column name and a column type.";
uses basic:mid{
description
"This is the MID for the table.";
}
leaf columns{
type basic:type-name-value-collection;
mandatory true;
description
"A TNV collection is used to store the type and names of the columns in the table.";
}
leaf num-rows{
type uint64;
mandatory true;
description
"This is the number of rows in the TBL.";
}
list rows{
key "num";
leaf num{
type uint64;
description "This is the number of data values in the row.";
}
leaf data{
type basic:type-name-value-collection;
description
"A TNV collection is used since col-types gives the types.";
}
description
"These are the rows of the table.";
}
leaf description{
type string;
description "This is the human readable description of the table.";
}
}
grouping report{
description
"A report is a typed data collection that is identified by a mid and generated to capture the return value of a control.";
uses basic:mid{
description
"This contains the MID for the report entry.";
}
leaf values{
type basic:type-name-value-collection;
description
"This TNV collection contains the values for the report entry.";
}
leaf description{
type string;
description
"This is the human readable description of the report-entry.";
}
}
grouping report-template{
description
"A report template is the ordered set of data descriptions which describe
how values will be represented in a corresponding report entry.";
uses basic:mid{
description
"This contains the MID for the report entry.";
}
uses basic:mid-collection;
leaf description{
type string;
description
"This is the human readable description of the report-template.";
}
}
grouping control{
description
"A control represents a pre-defined opcode that can be run on an agent.";
uses basic:mid{
description
"This is the MID identifying the control. It must NOT have an issuer field nor a tag field.";
}
leaf description{
type string;
description
"This is the human readable description of the control.";
}
}
grouping time-based-rule{
description
"A time based rule specifies that a particular action should be taken by an agent
based on some time interval.";
uses basic:mid{
description
"This is the MID identifying the time-based rule.";
}
leaf start{
type basic:ts;
mandatory true;
description
"This is the time at which the TRL should start.";
}
leaf period{
type uint64;
default 1;
description
"This is the length of time to wait in between running the action associated with the TRL.";
}
leaf count{
type uint64;
mandatory true;
description
"This is the number of times that action is performed. 0 = inf";
}
container action{
uses basic:mid-collection;
presence
"The action is a mid-collection;";
description
"This is the collection of controls and/or macros to be run by the TRL.";
}
leaf description{
type string;
description
"This is the human readable description of the time-based-rule.";
}
}
grouping state-based-rule{
description
"A state based rule(SRL) specifies that a particular action should be taken by an agent
based on some evaluation of the internal state of the agent.";
uses basic:mid{
description
"This is the MID identifying the SRL.";
}
leaf start{
type basic:ts;
mandatory true;
description
"This is the time at which the SRL should start to be evaluated.";
}
container condition{
uses basic:expr;
presence
"The condition is represented by an expression.";
description
"This contains the boolean expression, which, if true, results in the SRL running the associated action.";
}
leaf count{
type uint64;
mandatory true;
description
"This is the number of times the action is run. 0 = inf";
}
container action{
uses basic:mid-collection;
presence
"The action is a mid-collection.";
description
"This is the collection of controls and/or macros to be run as part of the action.";
}
leaf description{
type string;
description
"This is the human readable description of the state-based-rule.";
}
}
grouping macro{
description
"This is the ordered collections of MIDs that contain controls or other macros. When run by an agent, each MID in the mid-collection
is run in order.";
uses basic:mid{
description
"This is the MID identifying the Macro.";
}
container definition{
uses basic:mid-collection;
presence
"The definition is represented by a mid collection.";
description
"This is the ordered collections of MIDs which identify the controls and
other macros that should be run as part of the running macro.";
}
leaf description{
type string;
description
"This is the human readable description of the macro.";
}
}
grouping constant{
description
"Constants represent named values defined in an ADM.";
uses basic:mid{
description
"This is the MID that corresponds to the constant.";
}
leaf typed-value{
type basic:type-name-value-collection{
pattern
}
mandatory true;
description
"This is the type and value of the constant.";
}
leaf description{
type string;
description
"This is the human readable description of the constant.";
}
}
grouping operator{
description
"Operators are always defined in the context of an ADM. They represent functions
implemented by the firmware of the agent.";
uses basic:mid{
description
"Since Operators are always defined soley in the context of an ADM,
the issuer and tag field should not be used.";
}
leaf out-type{
type basic:type-enum;
description
"This is the type of the return value of the operator.";
}
leaf in-type{
type basic:type-name-value-collection{
pattern
}
description
"This is the type(s) of the inputs of the operator.";
}
leaf num-operands{
type uint32;
mandatory true;
description
"This is the number of operands needed to utilize the operator.";
}
leaf description{
type string;
description
"This is the human readable description of the operator.";
}
}
}
The ADT lists the set of predefined information necessary to capture the non-dynamic parts of an application data model, as follows.
module adm{
yang-version 1.1;
namespace "urn:ietf:params:xml:ns:yang:adm";
prefix adm;
import complex-structures{
prefix complex;
}
organization "JHUAPL";
contact
"Edward.Birrane@jhuapl.edu";
revision "2017-10-30" {
description "Initial Revision";
}
description
"This YANG module is used for modeling Application Data Models (ADMs). All keys in the list of the information uses the associated with the data's MIDs.";
list metadata{
key "name";
uses complex:constant;
description
"This is the metadata for the ADM. Should contain Name, Version, Namespace, and Issuing organization of the adm";
}
list externally-defined-data{
key "name";
uses complex:externally-defined-data{
description
"These are the EDD definitions that are defined by the ADM and its firmware";
}
description
"This is the listing of all the EDDs that are defined in the ADM.";
}
list tables{
key "name";
uses complex:table-template;
description
"This is the list of all the table/table-templates in the ADM.";
}
list variables{
key "name";
uses complex:variable{
description "These are the variables created and defined by the ADM.";
}
description
"Variable definitions are expressions used to calculate data values, on the fly,
from a set of other variable definitions, EDDs, constants, or numerics using any
of the operators defined.";
}
list report-templates{
key "name";
uses complex:report-template;
description
"This is the collection of report templates, which is the ordered set of data descriptions that
describe how values will be represented in a corresponding Report Entry.";
}
list controls{
key "name";
uses complex:control;
description
"This is the collection of controls which represent well-known command opcodes
that can be run by the Agent in response to direct request by an AMP manager or
in response to time- or state-based rules on the agent itself.";
}
list constants{
key "name";
uses complex:constant;
description
"These are the constants made available in the ADM.";
}
list macros{
key "name";
uses complex:macro;
description
"Macro definitions are ordered collections of controls that can be sequentially run.";
}
list operators{
key "name";
uses complex:operator;
description
"This is the set of operators that are made available in the ADM";
}
}
TBD.
TBD
| [I-D.birrane-dtn-ama] | Birrane, E., "Asynchronous Management Architecture", Internet-Draft draft-birrane-dtn-ama-05, March 2017. |
| [RFC2119] | Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997. |