| 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
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.
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 (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 the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License.
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.
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 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.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119].
Note: The terms "Actor", "Agent", "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.
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.
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.
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.
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.
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.
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.
+-------+ +-------+
| TOP-A | | TOP-B |
+---+---+ +---+---+
| _____|_____
| | |
+-------+ +-------+ +-------+
| MID-A | | MID-B | | MID-C |
+-------+ +-------+ +-------+
_________|_________ | |
| | | | |
+-------+ +-------+ +-------+ +-------+ +-------+
| LOW-A | | LOW-B | | LOW-C | | LOW-A | | LOW-A |
+-------+ +-------+ +-------+ +-------+ +-------+
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.
Moderated namespaces require resources to review and publish and are best suited for static AMM object definitions, such as those found in ADMs.
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.
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- 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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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"
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.
| 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 if_name)" | Formal parameter definition of num_bytes object that accepts a string interface name. |
| "num_bytes_if(String if_name=eth0)" | Formal parameter definition of num_bytes 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, Int n2 = 3)" | Formal parameter of object obj1 in 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. |
This section describes the type definitions used by the AMM.
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). |
A derived typed is a primitive type that is interpreted with special semantics. The AMM supports the following derived types.
A Byte String is a specialization of the String primitive data type used to store binary data using base64 encoding as defined in [RFC4648].
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.
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.
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.
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.
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.
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.
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.
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.
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.
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:
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:
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.
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.
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.
Operators represent user-defined mathematical functions implemented in the firmware of an Agent for the purpose of aiding the evaluation of Expressions.
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.
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.
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.
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.
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:
SBRs are defined by their ARI, start time, condition, maximum run count, action, and description, as follows.
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.
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.
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.
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:
TBRs are defined by their ARI, start time, period, maximum run count, action, and description, as follows.
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.
This section describes the handling and exchange of AMM objects between Agents and Managers in a network.
Managers must:
Agents must:
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 |
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.
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.
| 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 |
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.
| 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 |
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 |
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.
INT UINT VAST UVAST REAL32 REAL64
+--------+--------+--------+--------+--------+--------+
INT | INT | INT | VAST | UNK | REAL32 | REAL64 |
UINT | INT | UINT | VAST | UVAST | REAL32 | REAL64 |
VAST | VAST | VAST | VAST | VAST | REAL32 | REAL64 |
UVAST | UNK | UVAST | VAST | UVAST | REAL32 | REAL64 |
REAL32 | REAL32 | REAL32 | REAL32 | REAL32 | REAL32 | REAL64 |
REAL64 | REAL64 | REAL64 | REAL64 | REAL64 | REAL64 | REAL64 |
+--------+--------+--------+--------+--------+--------+
Figure 2: Numeric Promotions
Listing legal promotion rules is mandatory for ensuring that behavior is similar across multiple implementations of Agents and Managers. The listing of legal promotions in the 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.
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.
Variables, Expressions, and Predicates are typed values. When attempting to assign a value of a different type, a numeric conversion must be performed. Any numeric type may be converted to any other numeric type in accordance with the C rules for arithmetic type conversions.
This section 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 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.
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.
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: Section 5.4.1, with the exception of the metadata (MDAT) array which is unique to the ADM template itself.
Where each array is named after the mnemonic for the particular AMM object, as defined in
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.
{
"Mdat" : [],
"Edd" : [],
"Var" : [],
"Rptt" : [],
"Tblt" : [],
"Ctrl" : [],
"Const : [],
"Mac" : [],
"Oper" : []
}
The general format of the JSON ADM Template is as follows.
The metadata array contains CONST objects that provide information about the ADM itself.
Metadata objects are encoded in the same way as CONST objects, in accordance with Section 6.6.2.
This section describes the JSON encoding of AMM data types defined in Section 5.2.
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 |
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.
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 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 Value | {"type":"REAL32", "name":null, "value":3.14159} |
| Anonymous Value | {"type":null, "name":null, "value":3.14159} |
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.
"type": "UINT",
"postfix-expr": ["Edd.item1","Edd.item2","Oper.+UINT"]
The following is an example of a JSON encoding of an EXPR object.
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.
The following are examples of JSON encoded ARI objects.
| String Encoding | JSON Encoding |
|---|---|
| "N1/N2/Edd.edd1" | {"ns":"N1/N2", "nm":"Edd.edd1"} |
| "N1/N2/Edd.edd2(UINT num=3)" | {"ns":"N1/N2", "nm":"Edd.edd2", "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"}]} |
The following guidelines apply to the JSON encoding of AMM objects.
The CONST JSON object is comprised of four elements: "name", "type", "value, and "description". The description of these elements is as follows:
"name": "PI",
"type": "REAL64",
"value": 3.14159,
"description": "The value of PI."
The following is an example of a JSON encoding of a CONST object.
The CTRL JSON object is comprised of three elements: "name", "parmspec", and "description". The description of these elements is as follows:
"name": "reset_src_cnts",
"parmspec": [{"type":"STR","name":"src"}],
"description": "This control resets counts for the given source."
The following is an example of a JSON encoding of an CTRL object.
The EDD JSON object is comprised of four elements: "name", "type", "parmspec", and "description". The description of these elements is as follows:
"name": "num_good_tx_bcb_blks_src",
"type": "UINT",
"parmspec": [{"type":"STR","name":"Src"}],
"description": "Successfully Tx BCB blocks from SRC"
The following is an example of a JSON encoding of an EDD object.
The Macro JSON object is comprised of three elements: "name", "definition", and "description". The description of these elements is as follows:
"name": "user_list",
"definition": [{
"nm":"Ctrl.list_vars",
"ap": []
},
{
"nm":Ctrl.list_rptts"
"ap": []
}],
"description": "List user defined data."
The following is an example of a JSON encoding of an MAC object.
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": "plusINT",
"result-type": "INT",
"in-type": ["INT", "INT"],
"description": "Int32 addition"
The following is an example of a JSON encoding of an OP object.
The TBLT JSON object is comprised of four elements: "name", "columns", and "description". The description of these elements is as follows:
"name":"keys",
"columns": [{"type":"STR","name":"ciphersuite_names"}],
"description": "This table lists supported cipher suites."
The following is an example of a JSON encoding of an TBLT object.
The RPTT JSON object is comprised of four elements: "name", "parmspec", "definition", and "description". The description of these elements is as follows:
{
"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."
}
The following is an example of a JSON encoding of an RPTT object.
The VAR JSON object is comprised of four elements: "name", "type", "initializer", and "description". The description of these elements is as follows:
{
"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)."
}
The following is an example of a JSON encoding of an VAR object.
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.
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.
+------------------------+------------------------+
| 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 |
+------------------------+------------------------+
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.
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.
| [RFC2119] | Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997. |
| [RFC3339] | Klyne, G. and C. Newman, "Date and Time on the Internet: Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002. |
| [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. |
| [RFC4648] | Josefsson, S., "The Base16, Base32, and Base64 Data Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006. |
| [I-D.birrane-dtn-ama] | Birrane, E., "Asynchronous Management Architecture", Internet-Draft draft-birrane-dtn-ama-06, October 2017. |