Delay-Tolerant Networking E. Birrane
Internet-Draft E. DiPietro
Intended status: Informational D. Linko
Expires: January 1, 2019 Johns Hopkins Applied Physics Laboratory
June 30, 2018
AMA Application Data Model
draft-birrane-dtn-adm-03
Abstract
This document defines a physical data model that captures the
information necessary to asynchronously manage applications. This
model provides a set of common type definitions, data structures, and
a template for publishing standardized representations of model
elements.
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 January 1, 2019.
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 January 1, 2019 [Page 1]
Internet-Draft ADM June 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. Scope . . . . . . . . . . . . . . . . . . . . . . . . . . 3
2. Requirements Language . . . . . . . . . . . . . . . . . . . . 4
3. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4
4. Data Modeling Concept of Operations . . . . . . . . . . . . . 5
5. Asynchronous Management Model (AMM) . . . . . . . . . . . . . 6
5.1. The AMM Resource Identifier (ARI) . . . . . . . . . . . . 6
5.1.1. Namespaces . . . . . . . . . . . . . . . . . . . . . 7
5.1.2. Object Names . . . . . . . . . . . . . . . . . . . . 9
5.1.3. Parameters . . . . . . . . . . . . . . . . . . . . . 9
5.1.4. Special Case: Literal Values . . . . . . . . . . . . 10
5.1.5. String Canonical Forms . . . . . . . . . . . . . . . 11
5.1.6. Examples . . . . . . . . . . . . . . . . . . . . . . 12
5.2. AMM Type Definitions . . . . . . . . . . . . . . . . . . 15
5.2.1. Primitive Types . . . . . . . . . . . . . . . . . . . 15
5.2.2. Derived Types . . . . . . . . . . . . . . . . . . . . 15
5.2.3. Collections . . . . . . . . . . . . . . . . . . . . . 17
5.3. Object Definitions . . . . . . . . . . . . . . . . . . . 18
5.3.1. Common Object Metadata . . . . . . . . . . . . . . . 18
5.3.2. Externally Defined Data (EDD) . . . . . . . . . . . . 19
5.3.3. Constant (CONST) . . . . . . . . . . . . . . . . . . 19
5.3.4. Control (CTRL) . . . . . . . . . . . . . . . . . . . 20
5.3.5. Macro (MAC) . . . . . . . . . . . . . . . . . . . . . 21
5.3.6. Operator (OP) . . . . . . . . . . . . . . . . . . . . 21
5.3.7. Reports . . . . . . . . . . . . . . . . . . . . . . . 23
5.3.8. State-Based Rule (SBR) . . . . . . . . . . . . . . . 24
5.3.9. Tables . . . . . . . . . . . . . . . . . . . . . . . 25
5.3.10. Time-Based Rule (TBR) . . . . . . . . . . . . . . . . 27
5.3.11. Variable (VAR) . . . . . . . . . . . . . . . . . . . 28
5.3.12. Common Object Processing . . . . . . . . . . . . . . 29
5.4. Data Type Mnemonics and Enumerations . . . . . . . . . . 30
5.4.1. AMM Objects . . . . . . . . . . . . . . . . . . . . . 30
5.4.2. Primitive Data Types . . . . . . . . . . . . . . . . 31
5.4.3. Compound Data Types . . . . . . . . . . . . . . . . . 32
5.4.4. Numeric Promotions . . . . . . . . . . . . . . . . . 33
5.4.5. Numeric Conversions . . . . . . . . . . . . . . . . . 33
6. JSON ADM Template . . . . . . . . . . . . . . . . . . . . . . 33
6.1. ADM Inclusion . . . . . . . . . . . . . . . . . . . . . . 34
6.2. ADMT Object Collections . . . . . . . . . . . . . . . . . 34
6.3. ADM Metadata . . . . . . . . . . . . . . . . . . . . . . 35
6.4. Type Encodings . . . . . . . . . . . . . . . . . . . . . 36
6.4.1. Primitive Type Encoding . . . . . . . . . . . . . . . 36
6.4.2. Derived Type Encoding . . . . . . . . . . . . . . . . 36
Birrane, et al. Expires January 1, 2019 [Page 2]
Internet-Draft ADM June 2018
6.4.3. Collection Encoding . . . . . . . . . . . . . . . . . 37
6.5. ARI Encoding . . . . . . . . . . . . . . . . . . . . . . 38
6.6. ADM Structures . . . . . . . . . . . . . . . . . . . . . 40
6.6.1. General Notes . . . . . . . . . . . . . . . . . . . . 40
6.6.2. Constant (CONST) Encoding . . . . . . . . . . . . . . 41
6.6.3. Control (CTRL) Encoding . . . . . . . . . . . . . . . 41
6.6.4. Externally Defined Data (EDD) Encoding . . . . . . . 42
6.6.5. Macro Encoding . . . . . . . . . . . . . . . . . . . 43
6.6.6. Operator (OP) Encoding . . . . . . . . . . . . . . . 43
6.6.7. Table Template (TBLT) Encoding . . . . . . . . . . . 44
6.6.8. Report Template Encoding . . . . . . . . . . . . . . 44
6.6.9. Variables Encoding . . . . . . . . . . . . . . . . . 46
6.6.10. Exemptions . . . . . . . . . . . . . . . . . . . . . 47
7. ADM Author Considerations . . . . . . . . . . . . . . . . . . 47
8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 49
9. Security Considerations . . . . . . . . . . . . . . . . . . . 49
10. References . . . . . . . . . . . . . . . . . . . . . . . . . 49
10.1. Normative References . . . . . . . . . . . . . . . . . . 49
10.2. Informative References . . . . . . . . . . . . . . . . . 49
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 50
1. Introduction
The Asynchronous Management Architecture (AMA) [I-D.birrane-dtn-ama]
defines a concept for the open-loop control of applications (and
protocols) in situations where timely, highly-available connections
cannot exist amongst managing and managed nodes in a network. While
the AMA provides a logical data model, it does not include the
detailed information necessary to produce interoperable data models.
1.1. Scope
This document defines a physical data model suitable for managing
applications in accordance with the AMA. This physical model is
termed the Asynchronous Management Model (AMM) and consists of the
data types and data structures needed to manage applications in
asynchronous networks.
This document also provides a template, called the Application Data
Model Template (ADMT), for the standardized representation of
application-specific instances of this model. Using the types and
structures defined by the AMM, individual applications can capture
their unique, static management information in documents compliant
with the ADMT. These application-specific documents are called
Application Data Models (ADMs).
The AMM presented in this document does not assume any specific type
of application or underlying network encoding. In order to
Birrane, et al. Expires January 1, 2019 [Page 3]
Internet-Draft ADM June 2018
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,
the encoding of the model is a separate concern from the
specification of data within the model.
Because 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 the translation of
ADM data from one encoding to another can be completed using
mechanical action taken at network borders.
Since the specification does not mandate an encoding format, the AMM
and ADMT 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 contain 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", "Constant", Control", "Literal", "Macro", "Manager",
"Operator", "Report", "Report Template", "Rule", "State-Based Rule",
"Table", "Table Template", and "Time-Based Rule" are used without
modification from the definitions provided in the
[I-D.birrane-dtn-ama].
Additional terms defined in this document are as follows.
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 set of statically-defined data
items necessary to manage an application asynchronously.
o Application Data Model Template (ADMT) - A standard format for
expressing predefined data items for an application.
Birrane, et al. Expires January 1, 2019 [Page 4]
Internet-Draft ADM June 2018
o AMM Resource Identifier (ARI) - A unique identifier for any AMM
object, syntactically conformant to the Uniform Resource
Identifier (URI) syntax documented in [RFC3986] and using the
scheme name "ari".
o ADM Namespace - A moderated, hierarchical taxonomy of namespaces
that describe a set of ADM scopes. Specifically, an individual
ADM namespace is a specific sequence of ADM namespaces, from most
general to most specific, that uniquely and unambiguously identify
the namespace of a particular ADM.
o Operational Data Model (ODM) - The operational configuration of an
Agent. This includes 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.
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 any predefined 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 ADMT and uses the data structures and types that comprise the
AMM.
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, ADMT, and ADM are illustrated in
Figure 1.
Birrane, et al. Expires January 1, 2019 [Page 5]
Internet-Draft ADM June 2018
Data Model Relationship
+---------+ +---------+
| AMM |-------------->| ADMT |
+----+----+ +----+----+
| |
| +----------+-------------+
V | | |
+----------+ V V V
| Network | +-------+ +-------+ +-------+
| Specific | | ADM 1 | | ADM 2 | ... | ADM N |
| Config. | +---+---+ +---+---+ +---+---+
+----+-----+ | | |
| | | |
V V V V
+---------------------------------------------+
| ODM |
+---------------------------------------------+
Figure 1
In this figure, AMM data types and structures form the common
elements of the management model used by both ADMs and network
specific configurations. Together, the set of static information
provided by the union of all supported ADMs with the set of operator-
specified dynamic AMM objects, forms the operational data model used
to manage the network.
5. Asynchronous Management Model (AMM)
This section describes the Asynchronous Management Model, which is
the set of objects used to implement the logical data model provided
by the AMA. This section also provides additional information
necessary to work with this model, such as data type specifications,
identifier constructs, and naming conventions.
5.1. The AMM Resource Identifier (ARI)
Every object in the AMM must be uniquely identifiable, regardless of
whether the item is defined formally in an ADM document or informally
by operators in the context of a specific network deployment. The
AMM Resource Identifier (ARI) uniquely identifies AMM objects.
There are three components to the ARI: namespaces, object names, and
parameters. This section defines each of these components, discusses
special cases, and presents a string canonicalization of these
identifiers, with examples.
Birrane, et al. Expires January 1, 2019 [Page 6]
Internet-Draft ADM June 2018
5.1.1. Namespaces
AMM objects exist within unique namespaces to prevent conflicting
names within network deployments, particularly in cases where network
operators are allowed to define their own object names. In this
capacity, namespaces exists to eliminate the chance of a conflicting
object name. They MUST NOT be used as a security mechanism. An
Agent or Manager MUST NOT infer security information or access
control based solely on namespace information.
The AMM defines three ways to identify namespaces for AMM object
names: Moderated Namespaces, Anonymous Namespaces, and Issuer
Namespaces.
5.1.1.1. Moderated Namespaces
The most effective way to ensure the uniqueness of an AMM Object is
to name it in the context of a moderated namespace. These namespaces
are assigned by an overseeing organization as part of a maintained
namespace registry.
Moderated namespaces are hierarchical, which allows the grouping of
objects that share common attributes - for example, objects
associated with related protocols may have protocol-specific
namespaces that are grouped under a single encompassing namespace.
Namespaces that are closer to a root node in the moderated hierarchy
have broader scope than namespaces closer to leaf nodes in that
hierarchy. There is no requirement that the namespace hierarchy be
represented as a single tree structure; multiple root nodes are
acceptable and likely to exist.
In a hierarchical model of namespaces, a particular namespace can be
identified as the path to that namespace through the hierarchy. The
expression of that path within an ADM is accomplished by listing each
namespace along the path, separated by the tokenizing character "/".
For example, consider the namespaces in the following figure.
Birrane, et al. Expires January 1, 2019 [Page 7]
Internet-Draft ADM June 2018
+-------+ +-------+
| TOP-A | | TOP-B |
+---+---+ +---+---+
| _____|_____
| | |
+-------+ +-------+ +-------+
| MID-A | | MID-B | | MID-C |
+-------+ +-------+ +-------+
_________|_________ | |
| | | | |
+-------+ +-------+ +-------+ +-------+ +-------+
| LOW-A | | LOW-B | | LOW-C | | LOW-A | | LOW-A |
+-------+ +-------+ +-------+ +-------+ +-------+
Given this hierarchy, the following are all valid namespace
representations.
TOP-A/
TOP-A/MID-A
TOP-A/MID-A/LOW-A
TOP-B/MID-B/LOW-A
TOP-B/MID-C/LOW-A
Moderated namespaces require resources to review and publish and are
best suited for static AMM object definitions, such as those found in
ADMs.
5.1.1.2. Anonymous Namespaces
It is possible for network operators to define AMM objects that are
not associated with a namespace. In this case, a nil namespace can
be defined. This special case is considered the use of an
"anonymous" namespace.
Policy decisions as to whether anonymous namespaces are allowed in
the system should be determined before network deployment. The use
of an anonymous namespace greatly increases the chances of naming
collisions.
5.1.1.3. Informal Namespaces
Network-specific configurations, as illustrated in Figure 1, are
dynamic, ephemeral, not captured in published ADMs, and do not use
moderated namespaces. Instead, AMM objects that comprise network-
Birrane, et al. Expires January 1, 2019 [Page 8]
Internet-Draft ADM June 2018
specific configuration can be uniquely differentiated as a function
of their "Issuer" and an issuer-specific "Tag".
An Issuer is any string that identifies the organization that is
defining an AMM object. This value may come from a global registry
of organizations, an issuing node address, a signed known value, or
some other network-unique marking. Issuers MUST NOT conflict with
known moderated namespaces, and Agents and Managers should not
process Issuers that conflict with existing moderated namespaces.
A Tag is any string used to disambiguate AMM Objects for an Issuer.
The contents of the tag are 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.
5.1.2. Object Names
Object names are strings whose value is determined by the creator of
the object. For those objects defined in accordance with the ADMT
Template, the structure of the object name is given in Section 5.3.1.
5.1.3. Parameters
Parameterization is used in the AMM to enable expressive autonomous
function and reduce the amount of traffic communicated between
Managers and Agents. In the AMM, most objects can be parameterized
and the meaning of parameterization for each object is described in
detail in Section 5.3.
If there are two instances of an AMM object that have the same
namespace and same object name but have different parameters, then
those instances are both unique and the ARIs for those instances MUST
also be unique. Therefore, parameters are considered part of an AMM
object's identifier.
There are two types of parameters defined in the AMM: Formal and
Actual parameters. The terms formal parameter and actual parameter
follow common computer programming vernacular for discussing function
declarations and function calls, respectively.
5.1.3.1. Formal Parameters
Formal parameters define the type, name, and order of the information
that customizes an AMM Object. They represent the unchanging
"definition" of the parameterized object.
Birrane, et al. Expires January 1, 2019 [Page 9]
Internet-Draft ADM June 2018
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.
5.1.3.2. Actual Parameters
Actual parameters represent the data values passed to a parameterized
AMM Object. They "fulfill" the parameter requirements defined by the
formal parameters for that object.
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.
There are two ways in which the value of an actual parameter can be
specified: parameter-by-value and parameter-by-name.
Parameter-By-Value
This method involves directly supplying the value as part of
the actual parameter. It is the default method for supplying
values.
Parameter-By-Name
This method involves specifying the name of some other
parameter and using that other parameter's value for the
value of this parameter. This method is useful when a
parameterized AMM Object contains another parameterized AMM
Object. The contained object's actual parameter can be given
as the name of the containing object's parameter. In that
way, a containing object's parameters can be "pass down" to
all of the objects it contains.
5.1.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.
5.1.4. Special Case: Literal Values
As defined in the AMA, Literal values are those whose value and
identifier are equivalent. For example, the literal "4" serves as
both an identifier and a value. When literal values are used in
objects in the AMM, they are able to have a simplified identification
scheme.
Birrane, et al. Expires January 1, 2019 [Page 10]
Internet-Draft ADM June 2018
Because the value of a Literal object serves as its identifier, there
is no need for namespaces, object names, or parameters. A literal
can be completely identified by its data type and data value. Since
Literals in the AMA are used to identify primitive data types, the
type of a Literal identifier MUST be as described in Table 2.
5.1.5. String Canonical Forms
While there may exist multiple encodings of an ARI, to include the
JSON encodings presented in Section 6 and other binary encodings in
other specifications, this section defines a universal string
representation of the ARI, as such a representation is helpful to
express examples in this and other documents.
This representation is not prescriptive; other string encodings may
exist that differ from the one used in this document.
5.1.5.1. General ARI String Representation
The String Canonical Form of the ARI is expressed as a Uniform
Resource Identifier (URI), as documented in [RFC3986]. A URI is
syntactically decomposed into a scheme name and a scheme-specific
part. The set of known scheme names is moderated by IANA. The
scheme-specific part of the URI is dependent on the scheme name.
The scheme name of the ARI is "ari". The scheme-specific part of the
"ari" scheme follows the format:
ari:/<Namespace>/<ObjectName><(Parameters)>
With the string representation of each scheme given as follows.
Namespaces
Namespaces are represented as "/" separated lists, with
individual namespace types represented as follows:
* Moderated namespaces are listed in order from the most
general namespace to the most specific namespace. For
example: "GENERAL/MIDDLE/SPECIFIC/".
* Anonymous namespaces are empty and are represented as "/".
* Informal namespaces follow the general pattern of
moderated namespaces - starting with the general Issuer
followed by the more specific issuer tag. For example:
"Issuer/Tag". In cases where the Tag is omitted, then the
representation is simply "Issuer/".
Birrane, et al. Expires January 1, 2019 [Page 11]
Internet-Draft ADM June 2018
Object Names
The object name is a string as specified in Section 5.3.1.
Parameters
If present, parameters are represented as a comma-separated
string enclosed in parenthesis. Different types of
parameters are represented as follows.
* Formal parameters follow the pattern <type> <name> and if
there is a default value, it is represented by the
substring "= <value>".
* Actual Parameters-By-Value are represented as the string
encoding of their value.
* Actual Parameters-By-Name are represented as the name of
the parameter enclosed in angle brackets.
Note: If an actual parameter is missing for a formal
parameter that has a default value, then the ARI string MUST
have a blank space where the actual parameter would have
been. This missing parameter will also have a comma,
separating it from other actual parameters in the ARI string.
5.1.5.1.1. Shortform Encoding
In cases where a default namespace can be assumed (for example, in
the context of an ADM with a defined namespace) the prefix
ari:/Namespace/ can be omitted.
5.1.5.2. Literal String Encoding
The string representation of a Literal ARI is much simpler and
consists of simply the data type of the Literal followed by the
value, as follows:
"(type) value"
5.1.6. Examples
The ARIs for the following sample AMM objects are encoded in Table 1.
Note that these examples are for the identifiers of AMM objects, not
their entire definition.
o The number of bytes received by an Agent, defined in the N1/N2
namespace and called num_bytes.
Birrane, et al. Expires January 1, 2019 [Page 12]
Internet-Draft ADM June 2018
o The number of bytes received through an interface, called
num_bytes_if, which takes a single string parameter named
"if_name" with a default value oth "eth0".
o An anonymous, operator-defined object named "obj1" which takes two
unsigned integer parameters, n1 and n2, with default values of 3
and 4, respectively.
o The typed, Literal value of 4.
Birrane, et al. Expires January 1, 2019 [Page 13]
Internet-Draft ADM June 2018
+------------------------+------------------------------------------+
| ARI String | Description |
+------------------------+------------------------------------------+
| "ari:N1/N2/num_bytes" | Unparameterized num_bytes object in the |
| | N1/N2 namespace. |
| | |
| "num_bytes" | Shortform encoding where the N1/N2 |
| | namespace can be assumed. |
| | |
| "num_bytes_if(String | Formal parameter definition of num_bytes |
| if_name)" | object that accepts a string interface |
| | name. |
| | |
| "num_bytes_if(String | Formal parameter definition of num_bytes |
| if_name=eth0)" | object that accepts a string interface |
| | name with a default value. |
| | |
| "num_bytes_if()" | Actual parameter using the default value |
| | of eth0. |
| | |
| "num_bytes_if(eth0)" | Actual parameter of eth0. |
| | |
| "ari:/obj1(Int n1 = 0, | Formal parameter of object obj1 in |
| Int n2 = 3)" | anonymous namespace taking 2 default |
| | parameters. |
| | |
| "ari:/obj1(, )" | Actual parameter using the default |
| | values of 0 for n1 and 3 for n2. |
| | |
| "ari:/obj1(, 4)" | Actual parameter using the default value |
| | of 0 for n1. |
| | |
| "ari:/obj1(4, )" | Actual parameter using the default value |
| | of 3 for n2. |
| | |
| "ari:/obj1(4,4)" | Actual parameters provided for all obj1 |
| | parameters. |
| | |
| "ari:/obj1(<input>,4)" | Actual parameters provided for all obj1 |
| | parameters, with the value of the first |
| | parameter taken from some other |
| | parameter named "input". |
| | |
| "(UINT) 4" | The Literal value 4 interpreted as a |
| | 32-bit unsigned integer. |
+------------------------+------------------------------------------+
Table 1
Birrane, et al. Expires January 1, 2019 [Page 14]
Internet-Draft ADM June 2018
5.2. AMM Type Definitions
This section describes the type definitions used by the AMM.
5.2.1. Primitive Types
The AMM supports a series of primitive types as outlined in Table 2.
+--------------------+----------------------------------------------+
| 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 (whose integer |
| | interpretation is not 0). |
+--------------------+----------------------------------------------+
Table 2: Primitive Types
5.2.2. Derived Types
A derived typed is a primitive type that is interpreted with special
semantics. The AMM supports the following derived types.
5.2.2.1. Byte String
A Byte String is a specialization of the String primitive data type
used to store binary data using base64 encoding as defined in
[RFC4648].
Birrane, et al. Expires January 1, 2019 [Page 15]
Internet-Draft ADM June 2018
5.2.2.2. Time Values (TV) and Timestamps (TS)
A Time Value (TV) is a specialization of the String primitive data
type whose time interpretation is as given in this section. There
are two "types" of time representations within the AMM: relative
times and absolute times.
An absolute time represents an instant in time. It MUST be formatted
as a date-time in accordance with [RFC3339].
A relative time is defined as the amount of time after an instant in
time. A relative time MUST be formatted as a full-time in accordance
with [RFC3339]. Relative times have advantages over absolute times:
they do not require time to be synchronized across Agents and
Managers, and they are more compact in their representation. For
example, expressing the semantics "run control_one 10 seconds after
receiving it" or "run control_two 20 seconds after running
control_one" is more appropriate using relative times than absolute
times. The initiating event of a relative time MUST be unambiguously
defined in the context using the time value.
As a practical matter, encodings of relative times MAY impose a limit
of no more than 17 years of relative time, which corresponds to
roughly 29 bits of information and is considered well past an upper
bound of efficiency for using a relative time versus an absolute
time.
An absolute time may be differentiated from a relative time based on
whether the time specification is a date-time or a full-time.
For example, "00:00:10Z" is a relative time representing 10 seconds
after an initiating event. "2019-01-01T08:00:00Z" is an absolute
time that refers to 8am, Tuesday January 1st, 2019.
A Timestamp (TS) represents a specific point in time when an event
occurred. As such, it MUST be represented as an absolute time.
5.2.2.3. Type-Name-Value (TNV)
A Type-Name-Value (TNV) is a three-tuple of information that
describes a typed, named 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 explicitly encodes length or that the length is self-
delineating in the encoding.
o Type - The strong typing for this value. Types MUST be one of
those defined in Section 5.4.
Birrane, et al. Expires January 1, 2019 [Page 16]
Internet-Draft ADM June 2018
o Name - A unique identifier for this value.
o Value - The value of the data item.
5.2.2.4. User-Specified Derived Types
Individual ADMs and network operators may derive other types that
specialize the types provided by the AMM. When doing so, AMM data
types MUST be used to capture the specialization and any user-
specific verification or validation MUST occur in user-specific
implementations on Agents and Managers.
5.2.3. Collections
AMM objects, or parameters associated with those objects, often need
to represent groups of related information. Since the AMM is
strongly typed, these groups of related information are represented
by special data types called collections. AMM collections are
ordered and may contain duplicate entries.
The AMM defines three typed collections that capture TNVs, ARIs, and
mathematical expressions.
5.2.3.1. Type-Name-Value Collection (TNVC)
A Type-Name-Value Collection (TNVC) is an ordered array where each
element of the array is a TNV.
TNVCs are often used to capture formal and actual parameters for AMM
objects.
5.2.3.2. ARI Collection (AC)
An ARI Collection (AC) is an ordered set of ARIs.
ACs are often used when there exists a need to refer to multiple AMM
objects as a single unit. For example, when defining a Report
Template, the definition may have an AC that defines the ordered ARIs
whose values constitute that report.
5.2.3.3. Expression (EXPR)
An Expression (EXPR) is a specialization of an AC where each ARI in
the collection is either an operand or an operator. These operands
and operators form a mathematical expression that is used to compute
a numerical value.
Birrane, et al. Expires January 1, 2019 [Page 17]
Internet-Draft ADM June 2018
Within an Expression, an operand MUST be an ARI with one of the
following types: Literal, Constant, Externally Defined Data, or
Variable. An operator MUST be an ARI of type Operator.
Since the Expression is an AC, there are no annotative constructs
such as parenthesis to enforce certain orders of operation. To
preserve an unambiguous calculation of values, the ARIs that form an
Expression MUST be represented in postfix order. Postfix notation
requires no additional symbols to enforce precedence, always results
in a more efficient encoding, and post-fix engines can be implemented
efficiently in embedded systems.
For example, the infix expression A * (B * C) is represented as the
postfix A B C * *.
Expressions are often used when assigning values to a Variable or
when calculating the state of the Agent in the context of a State-
Based Rule.
5.3. Object Definitions
This section identifies the AMM Objects that instantiate the AMA
logical data model and the processing required to support these
objects at Agents and Managers in the network.
5.3.1. Common Object Metadata
Every object in the AMM includes a set of metadata providing
annotative or otherwise user-friendly descriptive information for the
object. 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.
Metadata is not required to be unique amongst objects and individual
encodings MAY choose to not encode metadata in cases where the
information is not needed to uniquely identify objects. The metadata
supported by the AMM for objects is as follows:
(STR) Name
An object name is a string associated with the object, but
does not constitute the sole identifier for the object.
Names provide human-readable and/or user-friendly ways to
refer to objects within a given context.
(STR) Description
An object description is a string describing the purpose or
usage of the object in a human-readable format. The
description serves as documentation for the object and SHOULD
Birrane, et al. Expires January 1, 2019 [Page 18]
Internet-Draft ADM June 2018
be the same regardless of how the object might be
parameterized. For example, the description of a CTRL object
should document the purpose of the CTRL in a way that is
independent of the value of any particular parameter value
passed to that CTRL.
5.3.2. Externally Defined Data (EDD)
Externally defined data (EDD), as defined in the AMA, represent data
values that are computed external to the network management system.
The definition of these values are solely defined in the context of
an ADM; since their calculation exists outside of the network
management system, they are not added or removed as part of the
dynamic configuration of the network management system.
An EDD consists of an ARI, type, and a description, with the
following caveats:
(ARI) Identifier
This Identifier MUST be of type EDD and MAY be parameterized,
particularly in cases where the specific computed value can
be identified by an associative look-up, as discussed in
Section 7.
(UINT) Type
The data type of the EDD value MUST be specified as part of
the EDD definition and this type MUST be one of the primitive
data types defined in Table 2.
(STR) Description
This represents the human-readable description of the EDD.
5.3.3. 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.
Constants MUST NOT be defined as part of dynamic network
configuration.
Allowing network operators to define constants dynamically means that
a Constant could be defined, removed, and then re-defined at a later
time with a different value, which defeats the purpose of having
Constants. Variables MUST be used instead of Constants for the
purpose of adding new values to the dynamic network configuration.
A CONST is defined by its ARI, value, and description, with the
following caveats.
Birrane, et al. Expires January 1, 2019 [Page 19]
Internet-Draft ADM June 2018
(ARI) Identifier
This Identifier MUST be of type CONST and MUST NOT be
parameterized. Parameterizing a Constant implies that its
value is dependent upon the set of parameters sent to it,
which defeats the purpose of defining a constant value.
(TNV) Typed Value
The value of a constant is the immutable value that should be
used in lieu of the Constant ARI.
This value is expressed as a TNV with the following
requirements.
* Type MUST be one of the primitive data types defined in
Table 2.
* Name MUSt be omitted as the CONST ARI defines the name for
this value.
* Value must be present and consistent with the data type
for this CONST.
(STR) Description
This represents the human-readable description of the CONST,
as a string.
5.3.4. Control (CTRL)
A Control represents a predefined function that can be run on an
Agent. Controls are not able to be defined as part of dynamic
network configuration since their execution is typically part of the
firmware or other implementation of the Agent outside of the context
of the network management system.
Network operators that wish to dynamically execute functions on an
Agent may use Macros, State-Based Rule, and Time-Based Rule instead.
Controls are identified by their ARI and their description, with the
following caveats.
(ARI) Identifier
This Identifier MUST be of type CTRL and MAY be parameterized
in cases where the function executed by that Control takes
parameters.
When defined in the context of an ADM, the Control ARI MUST
match the definition of a Formal Parameter list. This is
because the ADM defines the Controls that can be invoked, but
does not define any particular invocation of a Control.
Birrane, et al. Expires January 1, 2019 [Page 20]
Internet-Draft ADM June 2018
When used as part of network operations, a Control ARI MUST
match the definition of an Actual Parameter list. 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 ARI in the context of an
operational system MUST be seen as an invocation of that
Control.
(STR) Description
This represents the human-readable description of the
Control, as a string.
5.3.5. Macro (MAC)
Macros are ordered collections of Controls or other Macros. When run
by an Agent, each ARI in the AC is run in order. A Macro may be
defined as part of an ADM or as part of dynamic network
configuration.
In cases where a Macro contains another Macro, implementations MUST
implement some mechanism for preventing infinite recursions, such as
defining maximum nesting levels, performing Macro inspection, and/or
enforcing maximum execution times.
A Macro is defined by an ARI, a content definition, and a
description, as follows.
(ARI) Identifier
This Identifier MUST be of type MAC and MAY be parameterized
and, if so, the parameter may be passed-by-name to any
parameterized elements within the Macro.
(AC) Definition
The Macro definition is modeled as an AC, where each ARI
within the AC MUST be either a Control or a Macro.
(STR) Description
This represents the human-readable description of the Macro,
as a string.
5.3.6. Operator (OP)
Operators represent user-defined mathematical functions implemented
in the firmware of an Agent for the purpose of aiding the evaluation
of Expressions.
Birrane, et al. Expires January 1, 2019 [Page 21]
Internet-Draft ADM June 2018
The AMM separates the concepts of Operators and Controls to prevent
side-effects in Expression evaluation (e.g. to avoid constructs such
as A = B + GenerateReport()). For this reason, 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 an ADM.
An Operator is defined by its ARI, its resultant type, the number of
operands, the type of operands, and a description, as follows.
(ARI) Identifier
This Identifier MUST be of type OP and MUST NOT be
parameterized. Much like Constants, Operators represent
immutable mathematical functions. The operands of an
Operator are not considered as "parameters" to the Operator.
(UINT) Out Type
This is the return value of the Operator and MAY be different
than the operand types accepted by the Operator. This type
MUST be one of the primitive data types defined in Table 2.
(UINT) Num Operands
This is the number of operands evaluated by the operator.
For example, the unary NOT Operator ("!") would operate on a
single operand. The binary PLUS Operator ("+") would operate
on two operands. A custom operator to calculate the average
of the last 10 samples of data would operate on 10 operands.
(TNVC) In Types
This is the type information for each operand operated on by
the Operator, modeled as a TNV Collection (TNVC). There MUST
be one TNV in the TNVC for each operand, and each TNV MUST
adhere to the following requirements:
* The Type field MUST be present and MUST be one of the
primitive data types defined in Table 2.
* The Name field MAY be present to capture a semantic name
for the operand.
* The Value field MUST NOT be present.
(STR) Description
This represents the human-readable description of the
Operator, as a string.
Birrane, et al. Expires January 1, 2019 [Page 22]
Internet-Draft ADM June 2018
5.3.7. 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.
5.3.7.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.
Since a RPTT may contain other RPTTs, implementations MUST implement
some mechanism to prevent the definition of circular references.
RPTTs are defined by an ARI, the report template definition, and a
description, as follows.
(ARI) Identifier
This Identifier MUST be of type RPTT and MAY be parameterized
and, if so, the parameter may be passed-by-name to any
parameterized elements within the RPTT.
(AC) Definition
The Report Definition is modeled as an AC, where each ARI
within the AC MUST identify either a CONST, LIT, EDD, VAR, or
other RPTT.
(STR) Description
This represents the human-readable description of the Report
template, as a string.
5.3.7.2. Report (RPT)
A Report (RPT) is a set of data values populated in conformance to a
given data definition. Reports do not have an individual identifier
- rather they are uniquely identified by their definition and the
timestamp at which their data values were collected.
RPTs are defined by their associated template, the time at which the
report was generated, and the individual entries in the report, as
follows.
Birrane, et al. Expires January 1, 2019 [Page 23]
Internet-Draft ADM June 2018
(ARI) Template Id
This is the ARI of the object that defines the format of the
report data values. This ARI MUST define an AMM object of
type RPTT, EDD, or VAR, or CTRL.
If this ARI is parameterized, this ARI MUST include the
actual parameters used in the generation of the report.
(TV) Generation Time
This is the absolute time at which the report was generated
by the Agent.
(TNVC) Report Entries
This is the collection of data values that comprise the
report. If the template for this report is an EDD, VAR, or
CTRL then there MUST be one entry for this report. If the
template is a RPTT, then there MUST be one entry for every
item defined in the template.
Entries are modeled as a TNVC, with each TNV representing a
report entry with the following requiremnts.
* Type MAY be ommitted in cases where checking type safety
is not required.
* Name MAY be omitted in cases where a semantic name for the
entry can be derived from the template.
* Value MUST be present and consistent with the type for
this entry from the associated template item.
5.3.8. State-Based Rule (SBR)
A State-Based Rule (SBR) specifies that starting at a particular time
an action should be run by the Agent if some condition evaluates to
true, until the action has been run a maximum number of times. When
the SBR is no longer valid it MAY be discarded by the Agent.
Examples of SBRs include:
Starting 2 hours from receipt, whenever Variable V1 > 10, produce
a Report Entry for Report Template R1 no more than 20 times.
Starting at some future absolute time, whenever Variable V2 !=
Variable V4, run Macro M1 no more than 36 times.
SBRs are defined by their ARI, start time, condition, maximum run
count, action, and description, as follows.
(ARI) Identifier
Birrane, et al. Expires January 1, 2019 [Page 24]
Internet-Draft ADM June 2018
This Identifier MUST be of type SBR and MUST NOT be
parameterized.
(TV) START
The time at which the SBR condition should start to be
evaluated. This will mark the first evaluation of the
condition associated with the SBR.
(EXPR) CONDITION
The Expression which, if true, results in the SBR running the
associated action. An Expression is considered true if it
evaluates to a non-zero number.
(UVAST) COUNT
The number of times the SBR action can be run. The special
value of 0 indicates there is no limit on how many times the
action can be run.
(AC) 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 ARI within the AC represent a Control
or Macro.
(STR) Description
This represents the human-readable description of the SBR, as
a string.
5.3.9. 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.
5.3.9.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.
TBLTs are defined by an ARI, a set of column descriptions, and table
metadata, as follows.
Birrane, et al. Expires January 1, 2019 [Page 25]
Internet-Draft ADM June 2018
(ARI) Identifier
This Identifier MUST be of type TBLT and MUST be of type
TBLT, and MUST NOT contain parameters.
(TNVC) Columns
A TBLT is defined by its ordered set of columns descriptions
captured as a TNVC with each TNV in the collection describing
a table column with the following requirements.
* Type MUST be present and MUST be one of the primitive
types defined in Table 2.
* Name MAY be omitted in cases where a semantic name for the
column can be derived from the template.
* Value MUST NOT be present as a column does not contain
data values.
(STR) Description
This represents the human-readable description of the TBLT,
as a string.
5.3.9.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.
TBLs are defined by their Table Template, the number of rows in the
table, and the associated set of data values for each row.
(ARI) Template Id
This is the ARI of the Table Template holding the column
definitions for this table. This ARI MUST be of type TBLT
and match a known Table Template.
(UINT) Number of Rows
This is the number of rows in the table. A Table MAY have
zero rows.
(TNVC) Rows Information
Each row in a TBL is represented by a TNVC, with each TNV in
the collection representing the value for a specific column
with the following requirements.
* Type MAY be present, when necessary to verify that
elements in the row match the types of table columns.
Birrane, et al. Expires January 1, 2019 [Page 26]
Internet-Draft ADM June 2018
* Name MUST NOT be present.
* Value MUST be present and compatible with the type of the
associated column.
The number of TNVs in the collection MUST be equal to the
number of columns defined for the Table Template.
5.3.10. Time-Based Rule (TBR)
A Time-Based Rule (TBR) 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 TBR is no longer valid it MAY be discarded by the Agent.
Examples of TBRs include:
Starting 2 hours from receipt, produce a Report 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.
TBRs are defined by their ARI, start time, period, maximum run count,
action, and description, as follows.
(ARI) Identifier
This Identifier MUST be of type TBR and MUST NOT be
parameterized.
(TV) Start
The time at which the TBR should start to be evaluated. This
will mark the first running of the action associated with the
TBR.
(TV) Period
The time to wait between running the action associated with
the TBR. This value MUST be a relative time value.
(UVAST) Count
The number of times the TBR action may be run. The special
value of 0 indicates the TBR should continue running the
action indefinitely.
(AC) Action
The collection of Controls and/or Macros to run by the TBR.
This is captured as a AC with the constraint that every ARI
within the AC represent a Control or Macro.
Birrane, et al. Expires January 1, 2019 [Page 27]
Internet-Draft ADM June 2018
(STR) Description
This represents the human-readable description of the TBR, as
a string.
5.3.11. Variable (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
VARs are defined by an ARI, a type, an initializing expression, and a
description, as follows.
(ARI) Identifier
The type of this ARI MUST be type VAR, and the ARI MUST NOT
contain parameters.
(UINT) 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 2.
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.
(EXPR) 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 result of that
evaluation will be the initial value of the VAR.
(STR) Description
This represents the human-readable description of the VAR, as
a string.
Birrane, et al. Expires January 1, 2019 [Page 28]
Internet-Draft ADM June 2018
5.3.12. Common Object Processing
This section describes the handling and exchange of AMM objects
between Agents and Managers in a network.
Managers must:
o Store the ARI and definitions for both network-specific and ADM-
defined AMM Objects.
o Send requests to Agents to add, list, describe, and remove custom
AMM object definitions.
o Verify and interpret reports against report templates and tables
against table templates when receiving these objects from an
Agent.
o Encode ARIs in Objects to Agents, and decode ARIs from Agents.
o Provide actual parameters when sending parameterized objects to an
Agent.
Agents must:
o Store the ARI for all ADM-defined AMM objects.
o Calculate the value of an AMM object when required, such as when
generating a Report or evaluating an Expression.
o Implement Controls in firmware and run Controls and Macros with
appropriate parameters when necessary in the context of Manager
direction and Rule execution.
o Communicate "return" values from Controls back to Managers as
Reports where appropriate.
o Persist custom AMM object definitions.
o Add, remove, list, and describe custom AMM objects as requested by
Managers.
o Calculate the value of applying an Operator to a given set of
operands, such as when evaluating an Expression.
o Populate Reports and Tables for transmission to Managers when
required.
Birrane, et al. Expires January 1, 2019 [Page 29]
Internet-Draft ADM June 2018
o Run the actions associated with SBRs and TBRs in accordance with
their definitions.
o Calculate the value of VARs when required, such as during Rule
evaluation, calculating other VAR values, and generating Reports.
5.4. Data Type Mnemonics and Enumerations
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.
This section defines string (mnemonic) and integer (enumeration)
mechanisms for referring to AMM data and object types. Data types
are separated into 4 major categories:
Category Range
------------------ ------------
AMM Objects Types 0x00 - 0x0F
Primitive Types 0x10 - 0x1F
Compound Types 0x20 - 0x2F
Reserved 0x30 - 0xFF
Type Categories and Ranges
Within each category, the type of information, it's mnemonic, unique
enumeration value, and whether it is considered a numeric value for
expression evaluation are listed.
5.4.1. AMM Objects
AMM Objects include the set of objects identifiable using the ARI
construct. The type field of the ARI MUST be one of these values.
AMM Objects MUST be identified as follows.
Birrane, et al. Expires January 1, 2019 [Page 30]
Internet-Draft ADM June 2018
Structure Mnemonic Enumeration Numeric
------------------------------- -------------- ----------- ----------
Constant CONST 0 No
Control CTRL 1 No
Externally Defined Data EDD 2 No
Literal LIT 3 No
Macro MAC 4 No
Operator OPER 5 No
Report RPT 6 No
Report Template RPTT 7 No
State-Based Rule SBR 8 No
Table TBL 9 No
Table Template TBLT 10 No
Time-Based Rule TBR 11 No
Variable VAR 12 No
Reserved 13-15 No
5.4.2. Primitive Data Types
Primitive data include the basic set of objects that must be encoded
to transfer AMM objects. All AMM objects are built from combinations
of these primitive types. Primitive types MUST be identified as
follows.
Birrane, et al. Expires January 1, 2019 [Page 31]
Internet-Draft ADM June 2018
Basic Data Type Mnemonic Enumeration Numeric
------------------------------- -------------- ----------- ----------
Boolean BOOL 16 No
BYTE BYTE 17 No
Character String STR 18 No
Signed 32-bit Integer INT 19 Yes
Unsigned 32-bit Integer UINT 20 Yes
Signed 64-bit Integer VAST 21 Yes
Unsigned 64-bit Integer UVAST 22 Yes
Single-Precision Floating Point REAL32 23 Yes
Double-Precision Floating Point REAL64 24 Yes
Reserved 25-31 No
5.4.3. Compound Data Types
Compound data include combinations of primitive data types, to
include collections. Compound types MUST be identified as follows.
Compound/Special Data Type Mnemonic Enumeration Numeric
------------------------------- -------------- ----------- ----------
Time Value TV 32 No
Timestamp TS 33 No
Type-Name-Value TNV 34 No
Type-Name-Value Collection TNVC 35 No
AMM Resource Identifier ARI 36 No
ARI Collection AC 37 No
Expression EXPR 38 No
Byte String BYTESTR 39 No
Reserved - Protocol 40-47 No
Birrane, et al. Expires January 1, 2019 [Page 32]
Internet-Draft ADM June 2018
5.4.4. Numeric Promotions
When attempting to evaluate operators of different types, 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.
The listing of legal promotions in the AMM 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
The AMM does 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.
5.4.5. 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.
6. JSON ADM Template
This section provides an ADM template in the form of a JSON document
and describes the JSON representation of AMM objects that MUST be
used to populate this JSON ADM template.
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
Birrane, et al. Expires January 1, 2019 [Page 33]
Internet-Draft ADM June 2018
the AMM is designed to allow for multiple encodings, the expression
of ADMs in the provided JSON format is intended to support
translation to other encodings without loss of information.
6.1. ADM Inclusion
ADMs expressed in conformance with this template are captured as
individual JSON files. AMM Objects defined in one ADM template MAY
refer to objects defined in another ADM template file. To enable
type checking of these cross-ADM references, the ADM template
supports the "uses" keyword to identify other ADM files that contain
objects referenced in the current ADM file.
The syntax of the uses statement is as follows.
"uses":["file1","file2",...,"fileN"]
Where file_# represents a JSON-formatted ADM file defining a
namespace used in this ADM file.
6.2. ADMT Object Collections
The JSON ADM Template is defined as a JSON object containing a series
of arrays - one for each type of information specified in the
template. There are arrays for:
o metadata constants
o EDD definitions
o VAR definitions
o RPTT definitions
o TBLT definitions
o CTRL definitions
o CONST definitions
o MAC definitions
o OP definitions
Where each array is named after the mnemonic for the particular AMM
object, as defined in Section 5.4.1, with the exception of the
metadata (MDAT) array which is unique to the ADM template itself.
Birrane, et al. Expires January 1, 2019 [Page 34]
Internet-Draft ADM June 2018
In particular, the template does not provide definitions for RPT,
TBL, SBR, or TBR objects as these are defined dynamically in the
context of a network deployment.
The general format of the JSON ADM Template is as follows.
{
"Mdat" : [],
"Edd" : [],
"Var" : [],
"Rptt" : [],
"Tblt" : [],
"Ctrl" : [],
"Const : [],
"Mac" : [],
"Oper" : []
}
6.3. ADM Metadata
The metadata array contains CONST objects that provide information
about the ADM itself.
(STR) name
This is the human-readable name of the ADM that should appear
in message logs, user-interfaces, and other human-facing
applications.
(STR) namespace
This is the Moderated Namespace of the ADM, as defined in
Section 5.1.1 and string-encoded in accordance with
Section 5.1.5.1.
(STR) version
This is a string representation of the version of the ADM.
ADM version representations are formated at the discretion of
the publishing organization.
(STR) organization
This is the name of the issuing organization for this ADM.
Metadata objects are encoded in the same way as CONST objects, in
accordance with Section 6.6.2.
Birrane, et al. Expires January 1, 2019 [Page 35]
Internet-Draft ADM June 2018
6.4. Type Encodings
This section describes the JSON encoding of AMM data types defined in
Section 5.2.
6.4.1. Primitive Type Encoding
JSON data types generally have direct support for the AMM primitive
data types. The mapping of AMM primitive types to JSON data types is
provided in Table 3.
+----------+------------------------+
| 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 3: Primitive Type Encoding
6.4.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.
6.4.2.1. Type-Name-Value
A TNV is encoded as a JSON object with three elements: "type",
"name", and "value". For each item in a TNV, there are three
acceptable formulations that can be used to represent the item, as
Birrane, et al. Expires January 1, 2019 [Page 36]
Internet-Draft ADM June 2018
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 4: TNV Formulations
6.4.3. Collection Encoding
The TNVC and AC collections are encoded as JSON arrays, with each
object in the array represented in accordance with the JSON encoding
for that object type (TNV or ARI, respectively).
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.
(UINT) type
The data type of the evaluation of the initializer
expression.
(AC) postfix-expr
A JSON array of elements where each element is an JSON
encoding of an ARI in conformance to Section 6.5.
The following is an example of a JSON encoding of an EXPR object.
"type": "UINT",
"postfix-expr": ["Edd.item1","Edd.item2","Oper.+UINT"]
Birrane, et al. Expires January 1, 2019 [Page 37]
Internet-Draft ADM June 2018
6.5. ARI Encoding
An ARI may be encoded as either a string or as a JSON object, with
the two representations being unambiguously interchangeable.
Additionally, there exists a long-form and short-form encoding of the
ARI.
String encodings provide a more compact and human-readable
representation of the ARI. When an ARI is represented as a string in
a JSON object, it MUST be encoded in accordance with Section 5.1.5.1.
If the ARI references an object that is defined in the current ADM,
then the shortform string encoding may be used, as described in
Section 5.1.5.1.1. The object name to be used in the string encoding
is the same as the "nm" value for the JSON object encoding, as
described below.
JSON object encoding of the ARI provides additional structure that
makes ARI information verification easier. An ARI is encoded as a
JSON object with three keys: namespace, object name, and parameters,
encoded as follows.
ns
This element identifies the namespace within which the ARI
has been defined, and encoded as a string in accordance with
Section 5.1.5.1. In cases where the ARI identifies an object
defined in the ADM in which it is used, the ADM's namespace
may be assumed as the namespace of the ADM and this element
can be omitted from the ARI JSON object.
nm
The name of an object defined in an ADM is a string defined
as the concatenation of the ADMT collection defining the
object, the "." separator, and the string name of the object
itself. For example, an EDD defined in the Edd array and
named edd1 would have the string name "Edd.edd1".
fp
ARI formal parameters, if present, are defined as an array
with each element in the array representing the JSON TNV
encoding of the parameter. If a default value is not defined
for the parameter, then the value of the TNV MUST be omitted.
The fp element is not used when AMM objects are defined in
the context of an ADM, as the ADM template for defining
objects already includes parameter information. This element
is used when AMM objects are defined in accordance with the
JSON ADM syntax, but by network operators as part of network-
specific configuration.
Birrane, et al. Expires January 1, 2019 [Page 38]
Internet-Draft ADM June 2018
If the ARI JSON object has the fp element, then it MUST NOT
have the ap element. An ARI MUST NOT define both formal and
actual parameters in the same object instance.
ap
ARI actual parameters, if present, are defined as an array
with each element of the array representing the JSON TNV
encoding of the parameter. In cases where an optional
parameter is not present, an empty TNV object will be used in
its place for that parameter. The name element of the TNV
MUST NOT be present for actual parameters.
In cases where the actual parameter is by value, then the TNV
value key will hold the JSON encoding of the value of the
parameter.
In cases where the actual parameter is by name, then the TNV
MUST have the type "ParmName" and the value MUST be the
string name of the parameter whose value should be used to
populate the value of this actual parameter, as described in
Section 5.1.3.2.
If the ARI JSON object has the fp element, then it MUST NOT
have the ap element. An ARI MUST NOT define both formal and
actual parameters in the same object instance.
The following are examples of JSON encoded ARI objects.
Birrane, et al. Expires January 1, 2019 [Page 39]
Internet-Draft ADM June 2018
+---------------------------+---------------------------------------+
| String Encoding | JSON Encoding |
+---------------------------+---------------------------------------+
| "N1/N2/Edd.edd1" | {"ns":"N1/N2", "nm":"Edd.edd1"} |
| | |
| "N1/N2/Edd.edd2(UINT | {"ns":"N1/N2", "nm":"Edd.edd2", |
| num=3)" | "fp":[{"type":"UINT", "name"="num", |
| | value":3}]} |
| | |
| "N1/N2/Edd.edd2()" | {"ns":"N1/N2", "nm":"Edd.edd2", |
| | "ap":[{}]} |
| | |
| "N1/N2/Edd.edd2(4)" | {"ns":"N1/N2", "nm":"Edd.edd2", |
| | "ap":[{"type":"UINT", "value":4}]} |
| | |
| "N1/N2/Edd.edd3(<input>)" | {"ns":"N1/N2", "nm":"Edd.edd3", |
| | "ap":[{"type":"ParmName", |
| | "value":"input"}]} |
+---------------------------+---------------------------------------+
Table 5: Formal Parameter Encoding
6.6. ADM Structures
6.6.1. General Notes
The following guidelines apply to the JSON encoding of AMM objects.
Identification
Objects do not include an ARI object as part of their
definition. All of the contents of an ARI are derivable in
the context of the ADM and adding an ARI encoding as part of
the AMM object definition would be redundant and require
maintaining naming information in two places in the ADM
document.
Common Elements
Every JSON encoding of an AMM object MUST have the following
elements:
* Name
The identifier of the AMM Object. This MUST be unique
across all name elements defined in the ADM collection of
these types of objects.
* Description
A string description of the kind of data represented by
this data item.
Birrane, et al. Expires January 1, 2019 [Page 40]
Internet-Draft ADM June 2018
Formal Parameters
If an AMM object may be parameterized, then an element MUST
be present in the JSON object named "parmspec" which is
defined as a JSON-encoded TNVC. Each element in the TNVC
representing the JSON TNV encoding of the formal parameter.
If a default value is not defined for the parameter, then the
value of the TNV MUST be omitted.
6.6.2. 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:
Name
The identifier of the constant. This MUST be unique across
all name elements for CONSTs in the ADM.
Type
The strong typing of this data value. Types MUST be one of
those defined in Section 5.4.
Value
The value of the constant, expressed in the JSON encoding of
the data type.
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 CONST object.
"name": "PI",
"type": "REAL64",
"value": 3.14159,
"description": "The value of PI."
6.6.3. Control (CTRL) Encoding
The CTRL JSON object is comprised of three elements: "name",
"parmspec", and "description". The description of these elements is
as follows:
Name
The identifier of the control. This MUST be unique across
all name elements for CTRLs in the ADM.
ParmSpec
Birrane, et al. Expires January 1, 2019 [Page 41]
Internet-Draft ADM June 2018
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
Paragraph 3.
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 CTRL object.
"name": "reset_src_cnts",
"parmspec": [{"type":"STR","name":"src"}],
"description": "This control resets counts for the given source."
6.6.4. 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:
Name
The identifier of the EDD data item. This MUST be unique
across all name elements for EDDs in the ADM.
Type
The strong typing of this data value. Types MUST be one of
those defined in Section 5.4.
ParmSpec
The optional array of formal parameters encoded in accordance
with Paragraph 3.
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": [{"type":"STR","name":"Src"}],
"description": "Successfully Tx BCB blocks from SRC"
Birrane, et al. Expires January 1, 2019 [Page 42]
Internet-Draft ADM June 2018
6.6.5. Macro Encoding
The Macro JSON object is comprised of three elements: "name",
"definition", and "description". The description of these elements
is as follows:
Name
The identifier of the macro. This MUST be unique across all
name elements for MACs in the ADM.
Definition
This is a JSON array whose elements are shorthand references
are in accordance with Section 6.5 and are of the type CTRL
or MAC.
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 MAC object.
"name": "user_list",
"definition": [{
"nm":"Ctrl.list_vars",
"ap": []
},
{
"nm":Ctrl.list_rptts"
"ap": []
}],
"description": "List user defined data."
6.6.6. 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.
Name
The identifier of the operator. This MUST be unique across
all name elements for OPs in the ADM.
Result-Type
The numeric result of applying the operator to the series of
operands. This must be one of the encodings for Table 2.
In-Type
Birrane, et al. Expires January 1, 2019 [Page 43]
Internet-Draft ADM June 2018
This is an ordered JSON array of operands for the operator.
Each operand is a data type encoded in accordance with
Table 2.
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 OP object.
"name": "plusINT",
"result-type": "INT",
"in-type": ["INT", "INT"],
"description": "Int32 addition"
6.6.7. 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:
Name
The identifier of the table template data item. This MUST be
unique across all name elements for TBLTs in the ADM.
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 TNV described in Table 4.
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": [{"type":"STR","name":"ciphersuite_names"}],
"description": "This table lists supported cipher suites."
6.6.8. 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:
Name
Birrane, et al. Expires January 1, 2019 [Page 44]
Internet-Draft ADM June 2018
The identifier of the report template. This MUST be unique
across all name elements for RPTTs in the ADM.
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
Paragraph 3.
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 6.5.
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.
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 January 1, 2019 [Page 45]
Internet-Draft ADM June 2018
{
"name": "default_report",
"parmspec": [{
"type": "STR",
"name": "endpoint_id"
}],
"definition": [
{
"ns": "DTN:bp",
"nm": "Edd.edd_using_a_parm",
"ap": [{
"type": "PARMNAME",
"value": "endpoint_id"
}]
},
{
"ns": "DTN:bp",
"nm": "Edd.edd_with_default ",
"ap": [{
"type": "INT",
"value": ""}
]},
{ "ns": "DTN:bp",
"nm": "Edd.edd_with_no_parms ",
"ap": []
}
]
"description": "A default report."
}
6.6.9. Variables Encoding
The VAR JSON object is comprised of four elements: "name", "type",
"initializer", and "description". The description of these elements
is as follows:
Name
The identifier of the variable data item. This MUST be
unique across all name elements for VARs in the ADM.
Type
The strong typing of this data value. Types MUST be one of
those defined in Section 5.4.
Initializer
The expression used to establish the initial value of the
variable. This initializer is an expression encoded in
conformance with Section 6.4.3.
Birrane, et al. Expires January 1, 2019 [Page 46]
Internet-Draft ADM June 2018
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.
{
"name": "total_bad_tx_blks",
"type": "UINT",
"initializer": {
"type": "UINT",
"postfix-expr": [{
"nm": "Edd.item1",
"ap": [{
"type": "UINT",
"value": 0
}]
}, {
"nm":"Edd.item2",
"ap":[{
"type":"UINT",
"value": 1
]}
}, {
"nm": "Oper.plusUINT",
"ap":[]
}]
},
"description": "# total items (# item1 + # item2)."
}
6.6.10. Exemptions
Certain AMM objects are not intended to be statically defined in the
context of an ADM document. Literals, Reports, Tables, State-Based
Rules, and Time-Based Rules all only have meaning in the context of
an operational network. These objects are defined by network
operators as part of network-specific configuration and therefore not
present in the ADM Template.
7. ADM Author Considerations
The AMM model provides multiple ways to represent certain types of
data. This section provides informative guidance on how to express
application management constructs efficiently when authoring an ADM
document.
Birrane, et al. Expires January 1, 2019 [Page 47]
Internet-Draft ADM June 2018
Use Parameters for Dynamic Information.
Parameters provide a powerful mechanism for expressing
associative look-ups of EDD data. EDDs SHOULD be parameterized
when the definition of the EDD is dependent upon run-time
information. For example, if requesting the number of bytes
through a specific endpoint, the construct
num_bytes("endpoint_name") is simpler to understand and more
robust to new endpoint additions than attempting to enumerate the
number and name of potential endpoints when defining the ADM.
Do Not Use Parameters for Static Information.
Parameters incur bandwidth and processing costs (such as type
checking) and should only be used where necessary. If an EDD
object can be parameterized, but the set of parameters is known
and unchanging it may be more efficient to define multiple
unparameterized EDD objects instead. For example, consider a
single parameterized EDD object reporting the number of bytes of
data received for a specific, known set of priorities and a
request to report on those bytes for the "low", "med", and "high"
priorities. Below are two ways to represent these data: using
parameters and not using parameters.
+------------------------+------------------------+
| Parameterized EDDs | Non-Parameterized EDDs |
+------------------------+------------------------+
| num_bytes_by_pri(low) | num_bytes_by_low_pri |
| num_bytes_by_pri(med) | num_bytes_by_med_pri |
| num_bytes_by_pri(high) | num_bytes_by_high_pri |
+------------------------+------------------------+
The use of parameters in this case only incurs the overhead of
type checking, parameter encoding/decoding, and associative
lookups. This situation should be avoided when deciding when to
parameterize AMM objects.
Use Tables for Related Data.
In cases where multiple EDD or VAR values are likely to be
evaluated together, then that information SHOULD be placed in a
Table Template rather than defining multiple EDD and VAR objects.
By making a Table Template, the relationships amongst various
data values are preserved. Otherwise, Managers would need to
remember to query multiple EDD and/or VAR objects together which
is burdensome, but also results in high bandwidth and processor
utilization.
Birrane, et al. Expires January 1, 2019 [Page 48]
Internet-Draft ADM June 2018
8. IANA Considerations
This document defines a moderated namespace registry in
Section 5.1.1.1. This registry is envisioned to be moderated by
IANA. Entries in this registry are to be made through Expert Review.
This document defines a new URI scheme, "ari", as defined in
Section 5.1.5.
9. Security Considerations
This document does not describe any on-the-wire encoding or other
messaging syntax. It is assumed that the exchange of AMM objects
between Agents and Managers occurs within the context of an
appropriate network environment.
This AMM model may be extended to include the concept of Access
Control Lists (ACLs) to enforce roles and responsibilities amongst
Managers in the network. This access control would be implemented
separately from network security mechanisms.
10. References
10.1. Normative References
[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>.
[RFC3339] Klyne, G. and C. Newman, "Date and Time on the Internet:
Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002,
<https://www.rfc-editor.org/info/rfc3339>.
[RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
Resource Identifier (URI): Generic Syntax", STD 66,
RFC 3986, DOI 10.17487/RFC3986, January 2005,
<https://www.rfc-editor.org/info/rfc3986>.
[RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data
Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006,
<https://www.rfc-editor.org/info/rfc4648>.
10.2. Informative References
[I-D.birrane-dtn-ama]
Birrane, E., "Asynchronous Management Architecture",
draft-birrane-dtn-ama-06 (work in progress), October 2017.
Birrane, et al. Expires January 1, 2019 [Page 49]
Internet-Draft ADM June 2018
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 January 1, 2019 [Page 50]