AMA Application Data Model
draft-birrane-dtn-adm-01
The information below is for an old version of the document.
| Document | Type |
This is an older version of an Internet-Draft whose latest revision state is "Replaced".
|
|
|---|---|---|---|
| Authors | Edward J. Birrane , Evana DiPietro , David Linko | ||
| Last updated | 2018-03-04 | ||
| RFC stream | (None) | ||
| Formats | |||
| Stream | Stream state | (No stream defined) | |
| Consensus boilerplate | Unknown | ||
| RFC Editor Note | (None) | ||
| IESG | IESG state | I-D Exists | |
| Telechat date | (None) | ||
| Responsible AD | (None) | ||
| Send notices to | (None) |
draft-birrane-dtn-adm-01
Delay-Tolerant Networking E. Birrane
Internet-Draft E. DiPietro
Intended status: Informational D. Linko
Expires: September 5, 2018 Johns Hopkins Applied Physics Laboratory
March 4, 2018
AMA Application Data Model
draft-birrane-dtn-adm-01
Abstract
This document defines a data model that captures the information
necessary to manage applications in asynchronously managed networks.
This model includes a set of common type definitions, data
structures, and a template for publishing standardized
representations of elements of the model.
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 September 5, 2018.
Copyright Notice
Copyright (c) 2018 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
Birrane, et al. Expires September 5, 2018 [Page 1]
Internet-Draft ADM March 2018
the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License.
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1. Purpose . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.2. Scope . . . . . . . . . . . . . . . . . . . . . . . . . . 4
2. Requirements Language . . . . . . . . . . . . . . . . . . . . 4
3. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4
4. Data Modeling Concept of Operations . . . . . . . . . . . . . 5
5. Key Concepts . . . . . . . . . . . . . . . . . . . . . . . . 6
5.1. ADM Namespaces . . . . . . . . . . . . . . . . . . . . . 6
5.2. Item Identification . . . . . . . . . . . . . . . . . . . 7
5.3. Parameterization . . . . . . . . . . . . . . . . . . . . 7
5.3.1. Formal Parameters . . . . . . . . . . . . . . . . . . 8
5.3.2. Actual Parameters . . . . . . . . . . . . . . . . . . 8
5.3.3. Optional Parameters . . . . . . . . . . . . . . . . . 8
6. Asynchronous Management Model (AMM) . . . . . . . . . . . . . 9
6.1. Type Definitions . . . . . . . . . . . . . . . . . . . . 9
6.1.1. Primitive Types . . . . . . . . . . . . . . . . . . . 9
6.1.2. Derived Types . . . . . . . . . . . . . . . . . . . . 9
6.2. ADM Identifier (AID) . . . . . . . . . . . . . . . . . . 11
6.2.1. Identifier Meta-Data . . . . . . . . . . . . . . . . 11
6.2.2. Identifier Contents . . . . . . . . . . . . . . . . . 11
6.2.3. AID References . . . . . . . . . . . . . . . . . . . 13
6.3. Collections . . . . . . . . . . . . . . . . . . . . . . . 13
6.3.1. Type-Name-Value Collection (TC) . . . . . . . . . . . 13
6.3.2. AID Collection (AC) . . . . . . . . . . . . . . . . . 13
6.3.3. Expression (EXPR) . . . . . . . . . . . . . . . . . . 14
6.3.4. Predicate (PRED) . . . . . . . . . . . . . . . . . . 14
7. ADM Structures . . . . . . . . . . . . . . . . . . . . . . . 14
7.1. AMA Overview . . . . . . . . . . . . . . . . . . . . . . 14
7.2. Externally Defined Data (EDD) . . . . . . . . . . . . . . 16
7.3. Variables (VAR) . . . . . . . . . . . . . . . . . . . . . 17
7.4. Tables . . . . . . . . . . . . . . . . . . . . . . . . . 18
7.4.1. Table Template (TBLT) . . . . . . . . . . . . . . . . 18
7.4.2. Table (TBL) . . . . . . . . . . . . . . . . . . . . . 19
7.5. Reports . . . . . . . . . . . . . . . . . . . . . . . . . 20
7.5.1. Report Template (RPTT) . . . . . . . . . . . . . . . 20
7.5.2. Report (RPT) . . . . . . . . . . . . . . . . . . . . 21
7.6. Control (CTRL) . . . . . . . . . . . . . . . . . . . . . 22
7.7. Time-Based Rule (TRL) . . . . . . . . . . . . . . . . . . 23
7.8. State-Based Rule (SRL) . . . . . . . . . . . . . . . . . 25
7.9. Macro (MAC) . . . . . . . . . . . . . . . . . . . . . . . 26
7.10. Constant (CONST) . . . . . . . . . . . . . . . . . . . . 27
7.11. Operator (OP) . . . . . . . . . . . . . . . . . . . . . . 28
8. Data Type IDs and Enumerations . . . . . . . . . . . . . . . 30
Birrane, et al. Expires September 5, 2018 [Page 2]
Internet-Draft ADM March 2018
8.1. Numeric Promotions . . . . . . . . . . . . . . . . . . . 31
8.2. Numeric Conversions . . . . . . . . . . . . . . . . . . . 32
9. AMM Data Model Specification . . . . . . . . . . . . . . . . 32
10. ADM JSON Template . . . . . . . . . . . . . . . . . . . . . . 32
10.1. Primitive Type Encoding . . . . . . . . . . . . . . . . 33
10.2. Derived Type Encoding . . . . . . . . . . . . . . . . . 33
10.2.1. Hex String . . . . . . . . . . . . . . . . . . . . . 33
10.2.2. Type-Name-Values . . . . . . . . . . . . . . . . . . 34
10.2.3. Formal Parameters . . . . . . . . . . . . . . . . . 34
10.2.4. Expression . . . . . . . . . . . . . . . . . . . . . 35
10.3. ADM Identifier . . . . . . . . . . . . . . . . . . . . . 35
10.4. ADM Structures . . . . . . . . . . . . . . . . . . . . . 36
10.4.1. Externally Defined Data (EDD) Encoding . . . . . . . 36
10.4.2. Variables Encoding . . . . . . . . . . . . . . . . . 37
10.4.3. Table Template (TBLT) Encoding . . . . . . . . . . . 38
10.4.4. Report Template Encoding . . . . . . . . . . . . . . 38
10.4.5. Controls (CTRL) Encoding . . . . . . . . . . . . . . 39
10.4.6. Macro Encoding . . . . . . . . . . . . . . . . . . . 40
10.4.7. Constant (CONST) Encoding . . . . . . . . . . . . . 40
10.4.8. Operator (OP) Encoding . . . . . . . . . . . . . . . 41
10.4.9. Exemptions . . . . . . . . . . . . . . . . . . . . . 41
11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 42
12. Security Considerations . . . . . . . . . . . . . . . . . . . 42
13. Informative References . . . . . . . . . . . . . . . . . . . 42
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 42
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 logical roles and responsibilities, it does
not include the detailed information necessary to produce
interoperable data models.
This document defines a generic Asynchronous Management Model (AMM)
consisting of data types and data structures for managing
applications in asynchronous networks. Further, this document
provides a template for the standard representation of application-
specific instances of this model called the Application Data Model
Template (ADM-T). The AMM and ADM-T, together, provide the mechanism
for applications to specify how they are to be asynchronously managed
Birrane, et al. Expires September 5, 2018 [Page 3]
Internet-Draft ADM March 2018
in challenged networks. Individual applications capture their
unique, static management information in documents compliant with the
ASDM-T using the types and structures defined by the AMM. This
application-specific document is called the Application Data Model
(ADM).
1.2. Scope
The AMM presented in this document does not assume any specific type
of application or underlying network encoding. In order to
communicate model elements between AMA 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 ASDMs in their native encodings such that translating ASDM
data from one encoding to the next could be a mechanical action taken
at network borders.
Since the specification does not mandate an encoding format, the
ADM-T 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", "Externally Defined Data",
"Variable", "Control", "Literal", "Macro", "Manager", "Operator", and
"Rule" are used without modification from the definitions provided in
[AMA].
Additional terms critical to understanding the ADMT are as follows.
Birrane, et al. Expires September 5, 2018 [Page 4]
Internet-Draft ADM March 2018
o Application - A software implementation running on an Agent and
being managed by a manager. This includes software that
implements protocol processing on an Agent.
o Application Data Model (ADM) - The full set of statically-defined
data items necessary to manage an application asynchronously.
o Application Data Model Template (ADM-T) - A standard format for
expressing predefined data items for an application.
o ADM Item Definition (AID) - A parameterized structure used to
uniquely identify ADM objects.
o Operational Data Model (ODM) - The operational configuration of an
Agent. This inludes the union of all ADM information supported by
the Agent as well as all operational, dynamic configuration
applied to the Agent by Managers in the network.
o Report (RPT) - A collection of Report Entries gathered by one or
more Agents and provided to one or more Managers.
o Report Template (RPT-T) - A named, typed, ordered collection of
data types that represents the format of a corresponding Report
Entry. This is the schema for a Report Entry, generated by a
Manager and communicated to one or more Agents.
o Report Entry (RPT-E) - An ordered series of data values generated
by an Agent in accordance with a corresponding Report Template.
o State-Based Rule (SRL) - A Rule whose action is performed if a
defined predicate evaluates to true. SRLs are defined in
Section 7.8.
o Time-Based Rule (TRL) - A Rule whose action is performed at
regular intervals. TRLs are defined in Section 7.7.
4. Data Modeling Concept of Operations
In order to asynchronously manage an application, in accordance with
the [I-D.birrane-dtn-ama], an application-specific data model must be
created containing all pre-defined management information for that
application. This model is termed the Application Data Model (ADM)
and forms the core set of information for that application in
whichever network it is deployed. The ADM syntactically conforms to
the ADM-T and is uses the data structures and types that comprise the
AMM.
Birrane, et al. Expires September 5, 2018 [Page 5]
Internet-Draft ADM March 2018
The information standardized in the ADM represents static
configurations and definitions that apply to any deployment of the
application, regardless of the network in which it is operating.
Within any given network, Managers supplement the information
provided by ADMs with dynamic definitions and values. The
operational configuration of the network is the union of all
supported ADMs and all Manager-defined dynamic configurations. This
is termed the Operational Data Model (ODM).
The relationships amongst the AMM, ADM-T, and ADM are illustrated in
Figure 1.
Data Model Relationship
+---------+ +---------+
| AMM |-------------->| ADM-T |
+----+----+ +----+----+
| |
| +----------+-------------+
V | | |
+----------+ V V V
| Manager | +-------+ +-------+ +-------+
| Dynamic | | ADM 1 | | ADM 2 | ... | ADM N |
| Config. | +---+---+ +---+---+ +---+---+
+-----+----+ | | |
| | | |
V V V V
+---------------------------------------------+
| ODM |
+---------------------------------------------+
Figure 1
5. Key Concepts
5.1. ADM Namespaces
Each ADM must exist within a unique namespace to prevent conflicting
definitions across multiple ADMs and ambiguous behavior within
network deployments. To ensure the uniqueness of ADM namespaces,
they must be assigned by a moderating organization as part of a
maintained registry.
ADM namespaces are not expected to be flat, but hierarchical where
namespaces that are closer to a root node in the hierarchy are
considered to have broader scope than namespaces closer to leaf nodes
in the hierarchy. A hierarchical taxonomy of namespaces allows
Birrane, et al. Expires September 5, 2018 [Page 6]
Internet-Draft ADM March 2018
grouping ADMs that share a common classificiation at some level in
the namespace hierarchy. Also, a hierarchical namespace can preserve
this grouping in cases where a compact or otherwise binary encoding
is required. It should be noted that there is no requirement for the
namespace hierarchy to be represented as a tree structure; multiple
root nodes are acceptable and likely to exist.
In a hierarchical model of namespaces, a particular ADM namespace can
be identified as the path to that namespace through the hierarchy.
The expression of that path within an ADM is accomplished by defining
an ADM Resource Namespace (ARN). An ARN is a URI with the scheme
name of "arn" and a scheme-specific part the consists of a colon-
separated list of namespaces representing the path from some root in
the namespace hierarchy to the allocated space for the ADM.
arn:<Broadest-Scoped Namespace>:<Narrowest-Scoped Namespace>
For example, the DTN community publishes the Bundle Protocol and the
Bundle Protocol ADM could be assigned the namespace
arn:Dtn:BundleProtocol. The ADM for the Interplanetary Overlay
Network (ION) implementation of a Bundle Protocol Agent could have a
separate namespace namespace arn:Dtn:Ion:BundleProtocolAdmin.
5.2. Item Identification
Every item in an ADM must be uniquely identifiable both within the
context of the ADM itself and in the context of any network deploying
other ADMs and dynamic content. There are two types of information
which, together, uniquely identify a data item within the AMM:
identifier meta-data and identifier contents.
5.3. Parameterization
Parameterization is used pervasively in the AMM to enable expressive
autonomous function and reduce the amount of traffic that would
otherwise need to be communicated between Managers and Agents. In
this model, several types of data items can be parameterized, to
include commands, reports, and even individual data definitions. For
example, consider the management of a protocol that supports three
data priorities (low, medium, and high). Rather than defining three
deparate data items (number_pdus_low, number_pdus_medium, and
number_pdus_high) the AMM allows for the specification of a parameter
for this data type, such as number_pdus(bitmask) and supports
expressions such as number_pdus(low|medium|high).
Parameters in the AMM are associated with the identifier for a data
item. By associating parameters with identifiers makes it possible
to distinguish between two instances of a parameterized data item.
Birrane, et al. Expires September 5, 2018 [Page 7]
Internet-Draft ADM March 2018
Using the number_pdus data item example, the identifier of the data
item number_pdus(low) should be distinguishable from the identifier
of the data item number_pdus(low|medium). When represented in a data
item identifier, parameters may specify either "formal parameters" or
"actual parameters".
5.3.1. Formal Parameters
Formal parameters define the type, name, and order of the information
that customizes a data item. These parameters represent static
information (it is not expected that operators add new parameterized
information outside of what is represented within an ADM) that is
strongly typed.
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.
Using the previous example, the formal parameter specification for
the number_pdus data item could be represented as number_pdus(UINT
priority_mask). Alternatively, a default value could be specified by
the ADM as well, which would change the definition to
number_pdus(UINT priority_mask = low).
5.3.2. Actual Parameters
Actual parameters define the type, name, and value of the information
that populates a previously-defined formal parameter set. Actual
parameters are used to uniquely identify an instance of a
parameterized data item.
An actual parameter MUST specify a value and MAY specify a type. If
a type is provided it MUST match the type provided by the formal
parameter. An actual parameter MUST NOT include NAME information.
5.3.3. Optional Parameters
In cases where a formal parameter contains a default value, the
associated actual parameter may be omitted. Default values in formal
parameters (and, thus, optional actual parameters) are encouraged as
they reduce the size of data items communicated amongst Managers and
Agents in a network.
Birrane, et al. Expires September 5, 2018 [Page 8]
Internet-Draft ADM March 2018
6. Asynchronous Management Model (AMM)
6.1. Type Definitions
This section describes the custom type definitions used by the AMM.
Specifying basic type definitions forms the basis for interchangeable
encodings of ADMs based on this model.
6.1.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.
+--------------------+----------------------------------------------+
| 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). |
+--------------------+----------------------------------------------+
Table 1: Primitive Types
6.1.2. Derived Types
A derived typed is a primitive type that is interpreted with special
semantics. The AMM supports the following derived types.
Birrane, et al. Expires September 5, 2018 [Page 9]
Internet-Draft ADM March 2018
6.1.2.1. Timestamp (TS)
A Timestamp is a specialization of a UVAST.
There are two "types" of timestamp within the AMM: 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
AMM defines a Relative Timestamp Epoch (RTE). 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.
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.
IF (timestamp < 1347148800) THEN
absolute_time = current_time + timestamp
ELSE
absolute_time = timestamp
6.1.2.2. Type-Name-Value (TNV)
A Type-Name-Value (TNV) is a three-tuple of information that decribes
a data value in the AMM. Since the length of a data value is a
matter of encoding, there is not an explicit length field present for
the data value; it is assumed that any encoding scheme either encodes
the lenght in some other way or that, generally, data types and data
structures are self-delimiting.
o Type - The strong typing for this value. Types MUST be one of
those defined in Section 8.
Birrane, et al. Expires September 5, 2018 [Page 10]
Internet-Draft ADM March 2018
o Name - A unique identifier for this value.
o Value - The value of the data item.
In ADMs, TNVs are used to capture parameterized items and describe
the contents of reports.
6.2. ADM Identifier (AID)
6.2.1. Identifier Meta-Data
The meta-data for an identifier provides annotative or otherwise
user-friendly descriptive information for the identifier (or the item
being identified). This information may be used as documentation
(for example, only present in ADMs and on operator consoles) and/or
encoded and transmitted over the wire as part of a management
protocol.
Meta-data is not required to be unique amongst identifiers. The
meta-data supported by the AMM for identifiers is as follows.
o Name
An identifier name is a string associated with the identifier, but
not the identifier itself. Names provide human-readable and/or
user-friendly ways to refer to identifiers that are, otherwise,
difficult to parse. In cases where the identifier is considered
self-evident, an identifier name may be ommitted.
o Description
An identifier description is a string describing the purpose or
usage of the identified item. The intent of the description is to
provide human-readable and user-friendly documentation for the
item being identified.
6.2.2. Identifier Contents
Identifier contents are used to either compute or locate a data item.
Within the AAM, there are two types of contents: literals and
references. A reference is a unique value that can be used to look
up (reference) a data item. A literal is a value that can be used to
directly compute a data item. An example of a data item that could
use a literal identifier would be the unsigned integer value 4.
6.2.2.1. Reference Identifier
A reference identifier is used when a data item cannot be trivially
computed as a function of an identifier value. Examples of data
Birrane, et al. Expires September 5, 2018 [Page 11]
Internet-Draft ADM March 2018
items requiring a reference identifier would be data structures,
externally defined data items, and variables.
A reference identifier consists of four parts: (1) The type of item
being identified, (2) a unique handle for the item, (3) optional
meta-data related to the issuer of the identifier, and (4) optional
meta-data related to the item being named. The description of each
of these parts is as follows.
Item Type
The type of the data item being identified, as defined in Section 8.
Unique Handle
The handle is an opaque value that MUST be unique amongst all handles
within a given ADM.
Issuer
The issuer field is any string (including a 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.
Issuer information is only necessary when network operators issue new
data items dynamically in a network. As such, the issuer field MUST
be present for any dynamic data items added to a network and MUST NOT
be present for any static data items defined in the context of an
ADM.
Tag
The tag field is any string (including a hex string) used to
disambiguate or otherwise validate a reference identifier.
A tag field is only applicable when network operators issue new data
items dynamically in a network. As such, the tag field MUST NOT be
present unless an Issuer field is also present. A tag field MUST NOT
be present for any static data items defined in the context of an
ADM.
The contents of the tag field is left to the discretion of the
issuer. Examples of potential tag values include an issuer-known
version number or a (signed) hashing of the data item associated with
the reference identifier.
6.2.2.2. Literal Identifier
A literal identifier is used when a data item can be trivially
computed as a function of an identifier value. Examples of data
items requiring a reference identifier would be numerical values such
as the unsigned integer 4.
Birrane, et al. Expires September 5, 2018 [Page 12]
Internet-Draft ADM March 2018
A literal identifier consists of three parts: (1) The type of item
being identified, (2) the data type of the data item, and (3)
information necessary to compute the data item. The description of
each of these parts is as follows.
Item Type
The type of a literal identifier MUST be a Literal, as defined in
Section 8.
Data Type
The type of the literal value. This MUST be one of the primitive
types as described in Table 1.
Value
This is information necessary to directly compute the data item
value. For example, using string encodings, the literal value 4
could be have the string value "4" whereas a binary encoding might
use the value 0x04.
6.2.3. AID References
There are several times when an AID must be referenced within the
contents of an ADM document and a useful shorthand is defined to
allow for this expression. Since an AID name is required to be
unique for a given data type, the combination of AID type and AID
name may be used as a reference.
Specifically, an AID reference is a string with the form
<type>.<name>.
6.3. Collections
Data item definitions, or parameters associated with those
definitions, may operate on a collection of information. However,
where possible, the AMM seeks strong data typing which is not always
possible when accepting a collection of information. To provide
strong type checking, the AMM defines a series of typed collections.
6.3.1. Type-Name-Value Collection (TC)
A Type-Name-Value Collection is an ordered array where each element
of the array is a TNV.
6.3.2. AID Collection (AC)
It is often necessary to discuss collections of data items that are
provided as parameters to other items. An AID collection is an
ordered set of AIDs. For example, an AMA Agent may support a command
Birrane, et al. Expires September 5, 2018 [Page 13]
Internet-Draft ADM March 2018
to remove a set of report definitions. This command could accept a
list of report definitions to remove, identified by the AID for each
report definition. In such an instance, the list of repot
definitions to be removed could be modeled as an AC.
6.3.3. 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
AIDs. Because they are all identified by AIDs, the expression is
represented by an AC.
An expression (EXPR) is a AC 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 * *.
6.3.4. 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".
7. ADM Structures
This section identifies the ADM structures that implement the AMA
logical data model.
7.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.
Birrane, et al. Expires September 5, 2018 [Page 14]
Internet-Draft ADM March 2018
+------------+-----------------------------------+------------------+
| AMA | Summary Description | ADM Structures |
| Component | | |
+------------+-----------------------------------+------------------+
| Externally | A typed, measured value whose | Externally |
| Defined | definition and value | Defined Data |
| Data | determination occurs externally | |
| | from the network management | |
| | system. | |
| | | |
| Variable | A typed, computed value whose | Variable |
| | definition and value | |
| | determination occurs within the | |
| | network management system. | |
| | | |
| Report | Collections of Atomic and/or | Table |
| Entry | Computed data and/or other | Definition, |
| | Reports. | Table, Report |
| | | Definition, |
| | | Report |
| | | |
| Control | Parameterized opcode for any | Control |
| | action that can be taken by an | |
| | Agent. | |
| | | |
| Rule | A pre-configured response to a | State-Based |
| | predefined time or state on an | Rule, Time-Based |
| | Agent. | Rule |
| | | |
| Macro | An ordered collection of | Macro |
| | Controls. | |
| | | |
| Literal | A constant used when evaluating | Literal, |
| | Rules or determining the value of | Constant |
| | Computed Data. | |
| | | |
| Operator | An opcode representing a | Operator |
| | mathematical function known to an | |
| | Agent. | |
+------------+-----------------------------------+------------------+
AMA Logical Components
The remainder of this section describes the format of these
structures in the context of the aforementioned ADM data types.
Birrane, et al. Expires September 5, 2018 [Page 15]
Internet-Draft ADM March 2018
7.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.
7.2.1. Definition
An EDD consists of an AID, type, and a description, as follows.
AID
EDDs are defined solely in the context of an ADM. 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 ADM, it MUST
NOT contain an Issuer or Tag field and the type of the AID
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.
7.2.2. Processing
Managers must:
o Store the AID for each known EDD definition.
o Associate a data type to each known EDD definition.
o Encode EDD AIDs in Controls to Agents, as appropriate.
Agents must:
o Store the AID for each known EDD definition.
o Associate a data type to each known EDD definition.
o Calculate the value of an EDD definition when required, such as
when generating a Report Entry or evaluating an Expression.
Birrane, et al. Expires September 5, 2018 [Page 16]
Internet-Draft ADM March 2018
7.3. Variables (VAR)
Variables (VAR) may be statically defined in an ADM or dynamically by
Managers 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
7.3.1. Definition
VARs are defined by an AID, a type, an initializing expression, and a
description, as follows.
AID
The type of this AID MUST be type VAR, and the AID 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.
7.3.2. Processing
Managers must:
o Store the AID for each ADM-defined VAR definition.
Birrane, et al. Expires September 5, 2018 [Page 17]
Internet-Draft ADM March 2018
o Send requests to Agents to add, list, describe, and remove VAR
definitions.
o Remember custom VAR definitions.
o Encode VAR AIDs in Controls to Agents, as appropriate.
Agents must:
o Store the AID for each ADM-defined VAR definition.
o Calculate the value of VARs when required, such as during Rule
evaluation, calculating other VAR values, and generating Reports.
o Add, remove, list, and describe custom VAR definitions.
7.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 AMM:
Table Templates and Table Instances.
7.4.1. Table Template (TBLT)
A table template identifies the strongly-typed column template that
will be followed by any instance of this table available in the
network. Table templates appear statically in ADMs and may not be
created dynamically within the network by Managers. Changing a table
template within an asynchronously managed network would result in
confusion if differing template definitions for the same table
identifier were to be active in the network at one time.
7.4.1.1. Definition
TBLTs are defined by an AID, a set of column descriptions, and table
metadata, as follows.
AID
The type of this AID MUST be type TBLT, and the AID MUST NOT
contain parameters. Since Table Template definitions only
appear in an ADM document, this AID MUST NOT contain an
Issuer or a Tag field.
Columns
A TBLT is completely defined by its ordered set of columns
descriptions. Each column description is a name and a type.
Birrane, et al. Expires September 5, 2018 [Page 18]
Internet-Draft ADM March 2018
The type of each column MUST be one of the primitive types
defined in Table 1.
A column description is represented as a TNV that MUST
contain type and name information and MUST NOT contain value
information.
Description
This represents the human-readable description of the TBLT,
as a string.
7.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 ADM
for an application; they are only instantiated dynamically as part of
the operation of a network.
7.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 AID
This is the AID of the Table Template holding the column
definitions for this table. This AID MUST match a known
Table Template defined in an ADM.
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.
7.4.3. Processing
Managers must:
o Store the AID for each ADM-defined Table Template definition.
Birrane, et al. Expires September 5, 2018 [Page 19]
Internet-Draft ADM March 2018
o Request that Agents populate tables according to this template.
Agents must:
o Store the AID for each ADM-defined Table Template definition.
o Produce Tables in accordance with Table Template definitions when
required.
7.5. Reports
A Report is a set of non-tabular, potentially nested data items that
may be predefined in the context of an ADM, or defined dynamically in
the context of a deployed network.
Reports are represented in two ways in the AMM: Report Templates and
Reports. A Report Template defines the type of information to be
included in a report, and a Report contains that information.
7.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.
7.5.1.1. Definition
RPTTs are defined by an AID, the set of information comprising the
report, and a description, as follows.
AID
The type of this AID MUST be type RPTT. If the RPTT is
defined in an ADM it MUST NOT contain an Issuer or Tag field.
If the RPTT is defined outside of an ADM it MUST contain an
Issuer field and MAY contain a Tag field.
An RPTT AID MAY be parameterized. If the RPTT AID 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 AID,
this value is represented by an AC.
Birrane, et al. Expires September 5, 2018 [Page 20]
Internet-Draft ADM March 2018
NOTE: Since a RPTT is identified by a AID, it is possible
that a RPTT contains the AID 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.
7.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).
7.5.2.1. Definition
RPTs are defined by their associated report template and the report
entries themselves, as follows.
RPTT AID
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 AID MUST be the AID of the RPTT. However, a Report MAY
be generated without an RPTT (called an anonymous report) in
which case this AID MUST be the AID of the Control that
caused the report to be generated.
Report Entries)
This is the collection 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 AID
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.
7.5.3. Processing
Managers must:
o Store the AID for each ADM-defined Report Template.
Birrane, et al. Expires September 5, 2018 [Page 21]
Internet-Draft ADM March 2018
o Send requests to Agents to add, list, describe, and remove custom
Report Templates.
o Remember custom Report Templates when processing Report Entries
received by Agents.
o Encode Report Template AIDs in Controls to Agents, as appropriate.
Agents must:
o Store the AID for each ADM-defined Report Template.
o Populate Report Entries for transmission to Managers when required
by a Control.
o Add, remove, list, and describe custom Report Templates.
7.6. Control (CTRL)
A Control represents a predefined (possibly parameterized) opcode
that can be run on an Agent. Controls in the AMM are always defined
in the context of an ADM 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
AID that identifies them, similar to EDDs.
7.6.1. Definition
Controls are identified by their AID and their description, as
follows.
AID
This is the AID identifying the Control. The AID MUST be of
type CTRL. Since Controls are only defined in ADMs, this AID
MUST NOT have an Issuer field and MUST NOT have a Tag field.
The AID MAY have parameters.
When defined in the context of an ADM, the Control AID MUST
match the definition of a Formal Parameter list (e.g., there
are no VALUES). This is because the ADM 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 AID 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 ADM document MUST be considered the definition of the
Control and the presence of the same AID in the context of an
Birrane, et al. Expires September 5, 2018 [Page 22]
Internet-Draft ADM March 2018
operational system MUST be seen as an invocation of that
Control.
Description
This represents the human-readable description of the
Control, as a string.
7.6.2. Processing
Managers must:
o Store the AID for each ADM-defined Control definition.
o Store the number of parameters and each parameter type for
parameterized Controls.
o Encode Control AIDs in other Controls to Agents, as appropriate.
Agents must:
o Store the AID for each ADM-defined Control definition.
o Implement Controls in firmware and run Controls with appropriate
parameters when necessary in the context of Manager direction and
Rule execution.
o Communicate "return" values from Controls back to Managers as
Report Entries where appropriate.
7.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:
Starting 2 hours from receipt, produce a Report Entry for Report
Template R1 every 10 hours ending after 20 times.
Starting at the given absolute time, run Macro M1 every 24 hours
ending after 365 times.
Birrane, et al. Expires September 5, 2018 [Page 23]
Internet-Draft ADM March 2018
7.7.1. Definition
AID
This is the AID identifying the TRL. When a TRL is defined
in an ADM this AID MUST NOT have an Issuer field and MUST NOT
have a Tag field. When the TRL is defined outside of an ADM,
the AID MUST have an Issuer field and MAY have a Tag field.
This AID 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 AC with the constraint that every AID
within the AC represent a Control or Macro.
Description
This represents the human-readable description of the TRL, as
a string.
7.7.2. Processing
Managers must:
o Send requests to Agents to add, list, describe, and remove custom
TRL definitions.
o Remember custom TRL definitions when processing Reports received
by Agents.
o Send requests to Agents to suspend/resume the evaluation of TRLs.
o Encode TRL AIDs in Controls to Agents, as appropriate.
Agents must:
Birrane, et al. Expires September 5, 2018 [Page 24]
Internet-Draft ADM March 2018
o Run the actions associated with TRLs in accordance with their
start time and period.
o Add, remove, list, and describe custom TRL definitions.
o Suspend and resume the evaluation of a TRL when directed by a
Manager or another Rule.
o Report on the status of TRLs.
7.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:
Starting 2 hours from receipt, whenever V1 > 10, produce a Report
Entry for Report Template R1 no more than 20 times.
Starting at some future absolute time, whenever V2 != V4, run
Macro M1 no more than 36 times.
7.8.1. Definition
AID
This is the AID identifying the SRL. When a report is
defined in an ADM this AID MUST NOT have an Issuer field and
MUST NOT have a Tag field. When the SRL is defined outside
of an ADM, the AID MUST have an Issuer field and MAY have a
Tag field. This AID 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
Birrane, et al. Expires September 5, 2018 [Page 25]
Internet-Draft ADM March 2018
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 an AC data type with the
constraint that every AID within the AC represent a Control
or Macro.
Description
This represents the human-readable description of the SRL, as
a string.
7.8.2. Processing
Managers must:
o Send requests to Agents to add, list, describe, suspend, resume,
and remove custom SRL definitions.
o Remember custom SRL definitions when processing Report Entries
received by Agents.
o Encode SRL AIDs in Controls to Agents, as appropriate.
Agents must:
o Run the actions associated with SRLs in accordance with their
start time and evaluation of their predicate.
o Add, remove, list, and describe custom SRL definitions.
o Suspend and resume SRL evaluation when commanded by a Manager or
another Rule.
7.9. Macro (MAC)
Macros are ordered collections of AIDs (an AC) that contain Controls
or other Macros. When run by an Agent, each AID in the AC is run in
order.
7.9.1. Definition
A Macro is defined by a AID, a set of Controls, and a description, as
follows.
AID
Birrane, et al. Expires September 5, 2018 [Page 26]
Internet-Draft ADM March 2018
This is the AID identifying the Macro. When a Macro is
defined in an ADM this AID MUST NOT have an Issuer field and
MUST NOT have a Tag field. When the Macro is defined outside
of an ADM, the AID MUST have an Issuer field and MAY have a
Tag field. This AID MUST NOT be parameterized.
Definition
This is the ordered collection of AIDs that identify the
Controls and other Macros that should be run as part of
running this Macro. This is represented by a AC.
Description
This represents the human-readable description of the MACRO,
as a string.
7.9.2. Processing
Managers must:
o Store the AID for each ADM-defined Macro definition.
o Send requests to Agents to add, list, describe, and remove custom
Macro definitions.
o Encode macro AIDs in Controls to Agents, as appropriate.
Agents
o Store the AID for each ADM-defined Macro definition.
o Remember custom Macro definitions and run Macros when appropriate,
such as when responding to a run-Macro Control or when executing
the action of a TRL or SRL.
o Add, remove, list, and describe custom Macro definitions.
7.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 ADMs.
7.10.1. Definition
A CONST is defined by its AID, value, and description, as follows.
AID
Birrane, et al. Expires September 5, 2018 [Page 27]
Internet-Draft ADM March 2018
The AID MUST have type CONST and MUST NOT have an Issuer
field and MUST NOT have a Tag field. AIDs 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 AID 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.
Description
This represents the human-readable description of the CONST,
as a string.
7.10.2. Processing
Managers must:
o Store the AID for each ADM-defined Constant definition.
o Encode Constant AIDs in controls to Agents, as appropriate.
Agents
o Store the AID for each ADM-defined Constant definition.
o Calculate the value of Constants where appropriate, such as when
generating a Report Entry or when evaluating an Expression.
7.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 AMM 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 ADM for an application.
Birrane, et al. Expires September 5, 2018 [Page 28]
Internet-Draft ADM March 2018
7.11.1. Definition
An Operator is defined by its AID, its resultant type, the number of
operands, the type of operands, and a description, as follows.
AID
The AID MUST have type OP and MUST NOT have an Issuer or Tag
field. The AID 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.
7.11.2. Processing
Managers must:
o Store the AID for each ADM-defined Operator definition.
o Encode Operator AIDs in Controls to Agents, as appropriate.
Agents must:
o Store the AID for each ADM-defined Operator definition.
o Store the number of parameters expected for each Operator.
Birrane, et al. Expires September 5, 2018 [Page 29]
Internet-Draft ADM March 2018
o Calculate the value of applying an Operator to a given set of
parameters, such as when evaluating an Expression.
8. Data Type IDs and Enumerations
This section defines identifiers and enumeration values for objects
defined in the AMM. 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. AMM structure identifiers occupy enumerations 0 - 9 and
represent data structures that are formally identified by an AID.
Basic data types occupy enumerations 10-18 and represent primitive
data types. Special types occupy the remaining enumeration space.
While the AMM 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
Birrane, et al. Expires September 5, 2018 [Page 30]
Internet-Draft ADM March 2018
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
ADM Identifier AID 23 No
AID Collection AC 24 No
Expression EXPR 25 No
Predicate EXPR 26 No
8.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.
Listing legal promotion rules is mandatory for ensuring that behavior
is similar across multiple implementations of Agents and Managers.
Birrane, et al. Expires September 5, 2018 [Page 31]
Internet-Draft ADM March 2018
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.
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
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.
8.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.
9. AMM Data Model Specification
This section is TBD waiting for a final decision on whether we can
use YANG separate from NETCONF.
10. ADM JSON Template
This section provides an ADM template in the form of a JSON document.
It is not required that these JSON encodings be used to encode the
transmission of AMM information over the wire in the context of a
network deployment. It is also not required that only these JSON
encodings be used to document ADMs and other AMM information. Since
the AMM is designed to allow for multiple encodings, the expression
of ADMs in the provided JSON format is intended support translation
to other encodings without loss of information.
Birrane, et al. Expires September 5, 2018 [Page 32]
Internet-Draft ADM March 2018
10.1. Primitive Type Encoding
JSON data types generally support AMM primitive data types. The
mapping of AMM primitive types to JSON data types is provided in
Table 2.
+----------+------------------------+
| AMM Type | JSON Encoding |
+----------+------------------------+
| BYTE | number (0 <= # <= 256) |
| | |
| INT | number |
| | |
| UINT | number |
| | |
| VAST | number |
| | |
| UVAST | number |
| | |
| REAL32 | number |
| | |
| REAL64 | number |
| | |
| STRING | string |
| | |
| BOOL | boolean |
+----------+------------------------+
Table 2: Primitive Type Encoding
10.2. Derived Type Encoding
In cases where an AMM derived type is simply a special interpretation
of a primitive type, the JSON encoding of the derived type will be
the same as the JSON encoding of the primitive type from which it
derives.
10.2.1. Hex String
In cases where a hexadecimal value must be encoded, the JSON encoding
follows the guidelines for hex-string from RFC6991. In this case,
the hexadecimal value can be placed in a formatted string and this
string used in place of any numeric type with a hexademical
representation.
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
Birrane, et al. Expires September 5, 2018 [Page 33]
Internet-Draft ADM March 2018
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".
10.2.2. Type-Name-Values
A TNV is encoded as a JSON object with three element: "type", "name",
and "value". 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 | Example |
+---------------------+---------------------------------------------+
| Full | {"type":"REAL32", "name":"PI", |
| | "value":3.14159} |
| | |
| Named Type | {"type":"REAL32", "name":"PI", |
| | "value":null} |
| | |
| Anonymous Type | {"type":"REAL32", "name":null, |
| | "value":null} |
| | |
| Anonymous Type | {"type":"REAL32", "name":null, |
| Value | "value":3.14159} |
| | |
| Anonymous Value | {"type":null, "name":null, "value":3.14159} |
+---------------------+---------------------------------------------+
Table 3: TNV Formulations
10.2.3. Formal Parameters
A single parameter is encoded as a single JSON object where the key
string is the data type of the parameter and the value is the name of
the parameter. The general form of the object will be
{parm_type:parm_value}.
Birrane, et al. Expires September 5, 2018 [Page 34]
Internet-Draft ADM March 2018
+--------------------------------+----------------------------------+
| Desc | Example |
+--------------------------------+----------------------------------+
| Single String Parameter | {"STR":"name"} |
| | |
| Single Unsigned Integer | {"UINT":"name2"} |
| Parameter | |
| | |
| Multiple Parameter | [{"UINT":"name2"}, |
| | {"STR":"name"}] |
+--------------------------------+----------------------------------+
Table 4: Formal Parameter Encoding
10.2.4. Expression
An expression is encoded as a JSON object with two elements: a type
and a postfix-expr. The description of these elements is as follows.
o Type
The data type of the evaluation of the initializer expression.
o Postfix-Expr
A JSON array of elements where each element is an JSON encoding of
an ADM Identifier in conformance to Section 10.3.
The following is an example of a JSON encoding of an EXPR object.
"type": "UINT",
"postfix-expr": ["EDD.item1('0')","EDD.item2('1')","OP.+UINT"]
10.3. ADM Identifier
An AID encoding is not needed for the ADM template because all
required fields of an AID are already present within ADM objects.
Adding an AID field to the ADM needlessly complicates and expands the
ADM structure without adding clarity or interoperability. Instead of
mandating an AID encoding, the template ensures that relevant
information is captured in each ADM data item encoding to support the
creation of AIDs when ADM structures are represented in operational
network encodings.
NOTE: There is some discussion as to whether the inclusion of an AID
JSON encoding in the ADM should be included in the model. This
remains an area of active discussion.
Birrane, et al. Expires September 5, 2018 [Page 35]
Internet-Draft ADM March 2018
Absent a formal AID syntax in the ADM template, a shorthand string is
used to reference data items defined in an ADM from elsewhere in the
same ADM:
<Adm Structure Type>.<Data Item Name>
In cases where such a reference must include Actual Parameters to
completely identify a data item, an optional parameter string MAY be
appended to the shorthand reference. Thi optional string encloses a
set of comma-separated parameters between a set of parentheses. A
parameter may be either a pass-by-value or a pass-by-reference
parameter. A pass-by-value parameter is one whose literal value
should be used as the parameter value. These parameters are enclosed
in single quotes within the parameter string. A pass-by-reference
parameter is one whose value is related to some other information
provided in the data structure. The manner in which the reference is
calculated MUST be documented in the context of the ADM data item
using the reference. The optional parameter string format is as
follows.
('val_parm_1','val_parm_2',ref_parm_1,... )
+---------------------------------+---------------------------------+
| Desc | Example |
+---------------------------------+---------------------------------+
| Externally Defined Data | "EDD.item_name" |
| Reference | |
| | |
| Variable Reference | VAR.var1 |
| | |
| Value Parameter EDD Reference | EDD.number_pdu('0x4') |
| | |
| Reference Parameter EDD | EDD.number_pdu(ref_parm) |
| Reference | |
| | |
| Mixed Parameter EDD Reference | EDD.example_item('1', a, '2.0') |
+---------------------------------+---------------------------------+
Table 5: Data Item ADM Shorthand
10.4. ADM Structures
10.4.1. Externally Defined Data (EDD) Encoding
The EDD JSON object is comprised of four elements: "name", "type",
"parmspec", and "description". The description of these elements is
as follows.
Birrane, et al. Expires September 5, 2018 [Page 36]
Internet-Draft ADM March 2018
o Name
The identifier of the EDD data item. This MUST be unique across
all name elements for EDDs in the ADM.
o Type
The strong typing of this data value. Types MUST be one of those
defined in Section 8.
o ParmSpec
The optional array of formal parameters encoded in accordance with
Section 10.2.3.
o Description
A string description of the kind of data represented by this data
item.
The following is an example of a JSON encoding of an EDD object.
"name": "num_good_tx_bcb_blks_src",
"type": "UINT",
"parmspec": [{"STR":"Src"}],
"description": "Successfully Tx BCB blocks from SRC"
10.4.2. Variables Encoding
The VAR JSON object is comprised of four elements: "name", "type",
"initializer", and "description". The description of these elements
is as follows.
o Name
The identifier of the variable data item. This MUST be unique
across all name elements for VARs in the ADM.
o Type
The strong typing of this data value. Types MUST be one of those
defined in Section 8.
o Initializer
The expression used to establish the initial value of the
variable. This initializer is an expression encoded in
conformance with Section 10.2.4.
o Description
A string description of the kind of data represented by this data
item.
The following is an example of a JSON encoding of an VAR object.
Birrane, et al. Expires September 5, 2018 [Page 37]
Internet-Draft ADM March 2018
"name": "total_bad_tx_blks",
"type": "UINT",
"initializer": {
"type": "UINT",
"postfix-expr": ["EDD.item1('0')","EDD.item2('1')","OP.+UINT"]
},
"description": "# total items (# item1 + # item2)."
10.4.3. Table Template (TBLT) Encoding
The TBLT JSON object is comprised of four elements: "name",
"columns", and "description". The description of these elements is
as follows.
o Name
The identifier of the table template data item. This MUST be
unique across all name elements for TBLTs in the ADM.
o Columns
This is a JSON array of elements, with each element representing
the definition of the type of information represented in each
column. Each column is described using the same encoding as a
formal parameter described in Section 10.2.3.
o Description
A string description of the kind of data represented by this data
item.
The following is an example of a JSON encoding of an TBLT object.
"name":"keys",
"columns": [{"STR":"ciphersuite_names"}],
"description": "This table lists supported ciphersuites."
10.4.4. Report Template Encoding
The RPTT JSON object is comprised of four elements: "name",
"parmspec", "definition", and "description". The description of
these elements is as follows.
o Name
The identifier of the report template. This MUST be unique across
all name elements for RPTTs in the ADM.
o ParmSpec
This optional item describes parameters for this report. This is
encoded as an array where each element in the array is encoded as
a formal parameter in accordance with Section 10.2.3.
Birrane, et al. Expires September 5, 2018 [Page 38]
Internet-Draft ADM March 2018
o Definition
This is an array of data elements that represent the ordered set
of information associated with the report. Each element in the
array is encoded as a data item shorthand in accordance with
Section 10.3.
Report item elements MAY use reference parameters in their
definition. In those cases, the reference parameters in the
definition list MUST match report entry parameter names from the
ParmSpec element in the report template definition.
o Description
A string description of the kind of data represented by this data
item.
The following is an example of a JSON encoding of an RPTT object.
"name": "full_report",
"parmspec": [{"STR":"Source"}],
"definition" : [
"EDD.data_item1",
"EDD.data_item2('1')",
"EDD.data_item3(Source)",
"EDD.data_item4('1', Source)",
],
"description": "A full report."
10.4.5. Controls (CTRL) Encoding
The CTRL JSON object is comprised of three elements: "name",
"parmspec", and "description". The description of these elements is
as follows.
o Name
The identifier of the control. This MUST be unique across all
name elements for CTRLs in the ADM.
o ParmSpec
This optional item describes parameters for this control. This is
encoded as an array where each element in the array is encoded as
a formal parameter in accordance with Section 10.2.3.
o Description
A string description of the kind of data represented by this data
item.
The following is an example of a JSON encoding of an RPTT object.
Birrane, et al. Expires September 5, 2018 [Page 39]
Internet-Draft ADM March 2018
"name": "reset_src_cnts",
"parmspec": [{"STR":"src"}],
"description": "This control resets counts for the given source."
10.4.6. Macro Encoding
The MACRO JSON object is comprised of three elements: "name",
"definition", and "description". The description of these elements
is as follows.
o Name
The identifier of the macro. This MUST be unique across all name
elements for MACROs in the ADM.
o Definition
This is a JSON array whose elements are shorthand references are
in accordance with Section 10.3 and are of the type CTRL or MACRO.
o Description
A string description of the kind of data represented by this data
item.
The following is an example of a JSON encoding of an RPTT object.
"name": "user_list",
"definition": ["CTRL.list_vars","CTRL.list_rptts"],
"description": "List user defined data."
10.4.7. Constant (CONST) Encoding
The CONST JSON object is comprised of four elements: "name", "type",
"value, and "description". The description of these elements is as
follows.
o Name
The identifier of the constant. This MUST be unique across all
name elements for CONSTs in the ADM.
o Type
The strong typing of this data value. Types MUST be one of those
defined in Section 8.
o Value
The value of the constant, expressed in the JSON encoding of the
data type.
o Description
Birrane, et al. Expires September 5, 2018 [Page 40]
Internet-Draft ADM March 2018
A string description of the kind of data represented by this data
item.
The following is an example of a JSON encoding of a CONST object.
"name": "PI",
"type": "FLOAT",
"value": 3.14159,
"description": "The value of PI."
10.4.8. Operator (OP) Encoding
The OP JSON object is comprised of four elements: "name", "result-
type", "in-type", and "description". The description of these
elements is as follows.
o Name
The identifier of the operator. This MUST be unique across all
name elements for OPs in the ADM.
o Result-Type
The numeric result of applying the operator to the series of
operands. This must be one of the encodings for Table 1.
o In-Type
This is an ordered JSON array of operands for the operator. Each
operand is a data type encoded in accordance with Table 1.
o Description
A string description of the kind of data represented by this data
item.
The following is an example of a JSON encoding of a OP object.
"name": "+INT",
"result-type": "INT",
"in-type": ["INT", "INT"],
"description": "Int32 addition"
10.4.9. Exemptions
The AMM data model additionally defines data objects for both time-
based rules and state-based rules. These rules are associated with
dynamic behaviors in the context of a network deployment and, as
such, are typically not represented as static constructs in the
context of an ADM. Therefore, these data structures are not
considered in this ADM template.
Birrane, et al. Expires September 5, 2018 [Page 41]
Internet-Draft ADM March 2018
11. IANA Considerations
TBD.
12. Security Considerations
TBD
13. Informative References
[I-D.birrane-dtn-ama]
Birrane, E., "Asynchronous Management Architecture",
draft-birrane-dtn-ama-06 (work in progress), October 2017.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997,
<https://www.rfc-editor.org/info/rfc2119>.
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
Birrane, et al. Expires September 5, 2018 [Page 42]