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

Abstract

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.

Status of This Memo

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 Notice

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.


Table of Contents

1. Introduction

This document defines a data model suitable for managing applications in asynchronously managed networks.

1.1. Purpose

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.

1.2. Scope

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.

2. Requirements Language

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

3. Terminology

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.

4. Data Modeling Concept of Operations

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

5. Type Definitions

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.

5.1. Primitive Types

ADMs support a series of primitive types such as bytes, (un)signed integers, floating point values, and others as outlined in Table 1.

Primitive Types
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).

5.2. Derived Types

A derived typed is a primitive type that is interpreted with special semantics. The ADM supports the following derived types.

5.2.1. Hex String

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.

5.2.2. Timestamp (TS)

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.

5.2.3. Type-Name-Value Collection

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.

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

6. Identification

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

6.1. Asynchronous Resource Namespace (ARNs)

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.

6.2. Managed Identifiers

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.

6.2.1. MID Semantic Information

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.

6.2.2. MID Value

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.

6.2.2.1. Named Item

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.

6.2.2.2. Literal Item

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.

Sample Literal MIDs
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

6.2.3. MID Parameters

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.

6.2.3.1. Formal 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".

6.2.3.2. Actual Parameters

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

6.2.3.3. Optional Parameters

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.

TNV Formulations
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

6.2.3.4. Parameter Evaluation

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

6.2.3.4.1. Parameter By Value

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.

6.2.3.4.2. Parameter By Evaluation

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.

6.2.3.4.3. Identifying Parameter Approach

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.

6.2.4. MID References

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

7. Collections

7.1. MID Collection (MC)

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

7.2. Expression (EXPR)

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

7.3. Predicate (PRED)

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

8. ADM Structures

This section identifies the ADM structures that implement the AMA logical data model.

8.1. AMA Overview

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

8.2. Externally Defined Data (EDD)

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.

8.2.1. Definition

An EDD consists of a MID, type, and a description, as follows.

MID

EDDs are defined solely in the context of an ADD. Since they are sampled external to the management system, changes or additions to EDDs require changes to how the network management system interfaces with other components on an Agent.
Because an EDD is defined in the context of an ADD, it MUST NOT contain an Issuer or Tag field and the type of the MID MUST be the EDD type.
Type

This represents the data type of the value associated with the EDD.
Description

This represents the human-readable description of the EDD, as a string.

8.2.2. Processing

Managers

Agents

8.3. Variables (VAR)

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

8.3.1. Definition

VARs are defined by a MID, a type, an initializing expression, and a description, as follows.

MID

The type of this MID MUST be type VAR, and the MID MUST NOT contain parameters.
Type

This is the type of the VAR, and acts as a static cast for the result of the initializing EXPR. This type MUST be one of the data types defined in Table 1. Note, it is possible to specify a type different than the resultant type of the initializing EXPR. For example, if an EXPR adds two single-precision floating point numbers, the VAR MAY have an integer type associated with it.
Initializer

The initial value of the VAR is given by an initializing EXPR. In the case where the type of the VAR itself is EXPR the initializer is used as the value of the VAR. In the case where the type of the VAR is anything other than EXPR, then the initializer EXPR will be evaluated and the resultant value will be used as the initial value of the VAR.
Description

This represents the human-readable description of the VAR, as a string.

8.3.2. Processing

Managers

Agents

8.4. Tables

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.

8.4.1. Table Template (TBLT)

Table definitions are predefined items of an ADM and, as such, MUST appear in the ADD for an application.

8.4.1.1. Definition

TBLTs are defined by a MID, a set of column descriptions, and a description, as follows.

MID

The type of this MID MUST be type TBLT, and the MID MUST NOT contain parameters. Since Table Template definitions only appear in an ADD document, this MID MUST NOT contain an Issuer or a Tag field.
Columns

A Table is completely defined by its ordered set of columns descriptions. Each column description is a name and a type. The type of each column MUST be one of the primitive types defined in Table 1.
A column description is represented as a TNV string that MUST contain TYPE and NAME information and MUST NOT contain VALUE information. For example, a table with three columns could be represented by the TNV string "REAL32:col1&INT:col2&UINT:col3".
Description

This represents the human-readable description of the TABLE template, as a string.

8.4.2. Table (TBL)

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.

8.4.2.1. Definition

TBLs are defined by their Table Template, the number of rows in the table, and the associated set of data values for each row.

Template MID

This is the MID of the Table Template holding the column definitions for this table. This MID MUST match a known Table Template defined in an ADD.
Number of Rows

This is the number of rows in the table. A Table MAY have zero rows.
Rows Information

Each row in a TBL is represented as the number of data elements in the row, followed by the data elements themselves.
The number of data values for each row MUST be equal to the number of columns defined for the Table Template.
The data values for each row are represented by a TNV that optionally contains TYPE information and MUST contain value information. Type information MAY be included when necessary to verify that elements entered into a table match the type expected by a column in the table.
For example, given the above Table Template example, a valid row could be represented as "=3.14&=3&=3" or as "REAL32:=3.14&INT:=3&UINT:=3".

8.4.3. Processing

Managers

Agents

8.5. Reports

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.

8.5.1. Report Template (RPTT)

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.

8.5.1.1. Definition

RPTTs are defined by a MID, the set of information comprising the report, and a description, as follows.

MID

The type of this MID MUST be type RPTT. If the RPTT is defined in an ADD it MUST NOT contain an Issuer or Tag field. If the RPTT is defined outside of an ADD it MUST contain an Issuer field and MAY contain a Tag field.
An RPTT MID MAY be parameterized. If the RPTT MID is parameterized, the parameters MUST be used (in the same number and order) to customize any parameterized data in any Report generated using this template.
Entries

The list of ordered data items to be included in the report is represented by the list of identifiers for those items. Since every structure in the ADM can be identified by a MID, this value is represented by a MC.
NOTE: Since a RPTT is identified by a MID, it is possible that a RPTT contains the MID of another RPTT. This signifies that a report has, as one of its entries, another report. This is allowed in the system, but MUST NOT lead to circular references.
Description

This represents the human-readable description of the Report template, as a string.

8.5.2. Report (RPT)

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

8.5.2.1. Definition

RPTs are defined by their associated report template and the report entries themselves, as follows.

RPTT MID

This is the identifier associated with the structure used to help interpret the Report. A Report may be generated in accordance with a predefined Report Template, in which case the MID MUST be the MID of the RPTT. However, a Report MAY be generated without an RPTT (called an anonymous report) in which case this MID MUST be the MID of the Control that caused the report to be generated.
Report Entries)

This is the collect of data that comprise the report. These entires MUST consist of a series of data values and MAY additionally contain type information for each entry.
RPTEs are represented by a TNV collection. This TNV MUST contain VALUEs and MAY contain NAMES. If the RPTT MID associated with this Report is of type CTRL (in which case this is an anonymous Report) then the TNV MUST contain TYPE information as well. Otherwise, the TNV MAY contain TYPE information.

8.5.3. Processing

Managers

Agents

8.6. Control (CTRL)

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.

8.6.1. Definition

Controls are identified by their MID and their description, as follows.

MID

This is the MID identifying the Control. The MID MUST be of type CTRL. Since Controls are only defined in ADDs, this MID MUST NOT have an Issuer field and MUST NOT have a Tag field. The MID MAY have parameters.
When defined in the context of an ADD, the Control MID MUST match the definition of a Formal Parameter list (e.g., there are no VALUES). This is because the ADD defines the Controls that can be invoked, but does not define any particular invocation of a Control.
When used as part of network operations, a Control MID MUST match the definition of an Actual Parameter list (e.g., there are VALUES). This is because when used operationally, a parameterized Control required parameters to be run.
In cases where a Control takes no parameters, the definition in the ADD document MUST be considered the definition of the Control and the presence of the same MID in the context of an operational system MUST be seen as an invocation of that Control.
Description

This represents the human-readable description of the Control, as a string.

8.6.2. Processing

Managers

Agents

8.7. Time-Based Rule (TRL)

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:

8.7.1. Definition

MID

This is the MID identifying the TRL. When a TRL is defined in an ADD this MID MUST NOT have an Issuer field and MUST NOT have a Tag field. When the TRL is defined outside of an ADD, the MID MUST have an Issuer field and MAY have a Tag field. This MID MUST NOT be parameterized.
START

The time at which the TRL should start to be evaluated. This will mark the first running of the action associated with the TRL.
PERIOD

The number of seconds to wait between running the action associated with the TRL.
COUNT

The number of times the TRL action may be run. The special value of 0 indicates the TRL should continue running the action indefinitely.
ACTION

The collection of Controls and/or Macros to run by the TRL. This is captured as a MC with the constraint that every MID within the MC represent a Control or Macro.
Description

This represents the human-readable description of the TRL, as a string.

8.7.2. Processing

Managers

Agents

8.8. State-Based Rule (SRL)

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:

8.8.1. Definition

MID

This is the MID identifying the SRL. When a report is defined in an ADM this MID MUST NOT have an Issuer field and MUST NOT have a Tag field. When the SRL is defined outside of an ADM, the MID MUST have an Issuer field and MAY have a Tag field. This MID MUST NOT be parameterized.
START

The time at which the SRL condition should start to be evaluated. This will mark the first evaluation of the condition associated with the SRL.
CONDITION

The Predicate which, if true, results in the SRL running the associated action.
COUNT

The number of times the SRL action can be run. The special value of 0 indicates there is no limit on how many times the action can be run.
ACTION

The collection of Controls and/or Macros to run as part of the action. This is captured as a MC data type with the constraint that every MID within the MC represent a Control or Macro.
Description

This represents the human-readable description of the SRL, as a string.

8.8.2. Processing

Managers

Agents

8.9. Macro (MAC)

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.

8.9.1. Definition

A Macro is defined by a MID, a set of Controls, and a description, as follows.

MID

This is the MID identifying the Macro. When a Macro is defined in an ADD this MID MUST NOT have an Issuer field and MUST NOT have a Tag field. When the Macro is defined outside of an ADD, the MID MUST have an Issuer field and MAY have a Tag field. This MID MUST NOT be parameterized.
Definition

This is the ordered collection of MIDs that identify the Controls and other Macros that should be run as part of running this Macro. This is represented by a MC.
Description

This represents the human-readable description of the MACRO, as a string.

8.9.2. Processing

Managers

Agents

8.10. Constant (CONST)

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.

8.10.1. Definition

A CONST is defined by its MID, value, and description, as follows.

MID

The MID MUST have type CONST and MUST NOT have an Issuer field and MUST NOT have a Tag field. MIDs for CONST structures MUST NOT be parameterized.
Typed Value

The value of a constant is the immutable value that should be used in lieu of the Constant MID when evaluating Expressions and Predicates.
The typed value of a CONST is represented by a TNV collection that MUST have 1 element and MUST contain a TYPE and a VALUE and MUST NOT contain a NAME. An example of a typed value for a CONST would be ""REAL32:=3.14".
Description

This represents the human-readable description of the CONST, as a string.

8.10.2. Processing

Managers

Agents

8.11. Operator (OP)

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.

8.11.1. Definition

An Operator is defined by its MID, its resultant type, the number of operands, the type of operands, and a description, as follows.

MID

The MID MUST have type OP and MUST NOT have an Issuer or Tag field. The MID MUST NOT be parameterized.
Out Type

This is the return value of the Operator and MAY be different than the operand types accepted by the Operator.
Num Operands

This is the number of operands accepted by the operator. For example, the unary NOT Operator ("!") would accept one parameter. The binary PLUS Operator ("+") would accept two parameters. A custom function to calculate the average of the last 10 samples of a data item would accept 10 parameters.
In Types

This is the TYPE information for each operand accepted by the Operator. This is represented as a TNV Collection that MUST contain TYPE information, MAY contain NAME information and MUST NOT contain VALUE information. There MUST be exactly the same number of elements in the TNV collection as the Num Operands specified for the Operator.
Description

This represents the human-readable description of the Operator, as a string.

8.11.2. Processing

Managers

Agents

9. Data Type IDs and Enumerations

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

9.1. Numeric Promotions

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.

9.2. Numeric Conversions

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.

10. YANG Modules

This section contains three sets of YANG modules which capture the ADM and ADT concepts.

10.1. ADM Types and Structures

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

10.2. Application Data Template

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

11. IANA Considerations

TBD.

12. Security Considerations

TBD

13. Informative References

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

Authors' Addresses

Edward J. Birrane Johns Hopkins Applied Physics Laboratory EMail: Edward.Birrane@jhuapl.edu
Evana DiPietro Johns Hopkins Applied Physics Laboratory EMail: Evana.DiPietro@jhuapl.edu
David Linko Johns Hopkins Applied Physics Laboratory EMail: David.Linko@jhuapl.edu