| Delay-Tolerant Networking | E. Birrane |
| Internet-Draft | E. DiPietro |
| Intended status: Informational | D. Linko |
| Expires: September 5, 2018 | Johns Hopkins Applied Physics Laboratory |
| March 4, 2018 |
AMA Application Data Model
draft-birrane-dtn-adm-01
This document defines a data model that captures the information necessary to manage applications in asynchronously managed networks. This model includes a set of common type definitions, data structures, and a template for publishing standardized representations of elements of the model.
This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."
This Internet-Draft will expire on September 5, 2018.
Copyright (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.
This document defines a data model suitable for managing applications in asynchronously managed networks.
The Asynchronous Management Architecture [I-D.birrane-dtn-ama] documents a concept for open-loop control of applications (and protocols) for situations where timely, highly-available connections cannot exist amongst managing and and managed nodes in a network. While the AMA describes logical roles and responsibilities, it does not include the detailed information necessary to produce interoperable data models.
This document defines a generic Asynchronous Management Model (AMM) consisting of data types and data structures for managing applications in asynchronous networks. Further, this document provides a template for the standard representation of application-specific instances of this model called the Application Data Model Template (ADM-T). The AMM and ADM-T, together, provide the mechanism for applications to specify how they are to be asynchronously managed in challenged networks. Individual applications capture their unique, static management information in documents compliant with the ASDM-T using the types and structures defined by the AMM. This application-specific document is called the Application Data Model (ADM).
The AMM presented in this document does not assume any specific type of application or underlying network encoding. In order to communicate model elements between AMA Agents and Managers in a network, the model must be encoded for transmission. Any such encoding scheme is outside of the scope of this document. Generally, encoding of the model is a separate concern from the specification of data within the model.
Since different networks may use different encodings for data, mandating an encoding format would require incompatible networks to encapsulate data in ways that could introduce inefficiency and obfuscation. It is envisioned that different networks would be able to encode ASDMs in their native encodings such that translating ASDM data from one encoding to the next could be a mechanical action taken at network borders.
Since the specification does not mandate an encoding format, the ADM-T must provide enough information to make encoding (and translating from one encoding to another) an unambiguous process. Therefore, where necessary, this document provides identification, enumeration and other schemes that ensure ADMs provide enough information to prevent ambiguities caused by different encoding schemes.
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", "Control", "Literal", "Macro", "Manager", "Operator", and "Rule" are used without modification from the definitions provided in [AMA].
Additional terms critical to understanding the ADMT are as follows.
In order to asynchronously manage an application, in accordance with the [I-D.birrane-dtn-ama], an application-specific data model must be created containing all pre-defined management information for that application. This model is termed the Application Data Model (ADM) and forms the core set of information for that application in whichever network it is deployed. The ADM syntactically conforms to the ADM-T and is uses the data structures and types that comprise the AMM.
The information standardized in the ADM represents static configurations and definitions that apply to any deployment of the application, regardless of the network in which it is operating. Within any given network, Managers supplement the information provided by ADMs with dynamic definitions and values. The operational configuration of the network is the union of all supported ADMs and all Manager-defined dynamic configurations. This is termed the Operational Data Model (ODM).
The relationships amongst the AMM, ADM-T, and ADM are illustrated in Figure 1.
Data Model Relationship
+---------+ +---------+
| AMM |-------------->| ADM-T |
+----+----+ +----+----+
| |
| +----------+-------------+
V | | |
+----------+ V V V
| Manager | +-------+ +-------+ +-------+
| Dynamic | | ADM 1 | | ADM 2 | ... | ADM N |
| Config. | +---+---+ +---+---+ +---+---+
+-----+----+ | | |
| | | |
V V V V
+---------------------------------------------+
| ODM |
+---------------------------------------------+
Figure 1
Each ADM must exist within a unique namespace to prevent conflicting definitions across multiple ADMs and ambiguous behavior within network deployments. To ensure the uniqueness of ADM namespaces, they must be assigned by a moderating organization as part of a maintained registry.
ADM namespaces are not expected to be flat, but hierarchical where namespaces that are closer to a root node in the hierarchy are considered to have broader scope than namespaces closer to leaf nodes in the hierarchy. A hierarchical taxonomy of namespaces allows grouping ADMs that share a common classificiation at some level in the namespace hierarchy. Also, a hierarchical namespace can preserve this grouping in cases where a compact or otherwise binary encoding is required. It should be noted that there is no requirement for the namespace hierarchy to be represented as a tree structure; multiple root nodes are acceptable and likely to exist.
In a hierarchical model of namespaces, a particular ADM namespace can be identified as the path to that namespace through the hierarchy. The expression of that path within an ADM is accomplished by defining an ADM Resource Namespace (ARN). An ARN is a URI with the scheme name of "arn" and a scheme-specific part the consists of a colon-separated list of namespaces representing the path from some root in the namespace hierarchy to the allocated space for the ADM.
arn:<Broadest-Scoped Namespace>:<Narrowest-Scoped Namespace>
For example, the DTN community publishes the Bundle Protocol and the Bundle Protocol ADM could be assigned the namespace arn:Dtn:BundleProtocol. The ADM for the Interplanetary Overlay Network (ION) implementation of a Bundle Protocol Agent could have a separate namespace namespace arn:Dtn:Ion:BundleProtocolAdmin.
Every item in an ADM must be uniquely identifiable both within the context of the ADM itself and in the context of any network deploying other ADMs and dynamic content. There are two types of information which, together, uniquely identify a data item within the AMM: identifier meta-data and identifier contents.
Parameterization is used pervasively in the AMM to enable expressive autonomous function and reduce the amount of traffic that would otherwise need to be communicated between Managers and Agents. In this model, several types of data items can be parameterized, to include commands, reports, and even individual data definitions. For example, consider the management of a protocol that supports three data priorities (low, medium, and high). Rather than defining three deparate data items (number_pdus_low, number_pdus_medium, and number_pdus_high) the AMM allows for the specification of a parameter for this data type, such as number_pdus(bitmask) and supports expressions such as number_pdus(low|medium|high).
Parameters in the AMM are associated with the identifier for a data item. By associating parameters with identifiers makes it possible to distinguish between two instances of a parameterized data item. Using the number_pdus data item example, the identifier of the data item number_pdus(low) should be distinguishable from the identifier of the data item number_pdus(low|medium). When represented in a data item identifier, parameters may specify either "formal parameters" or "actual parameters".
Formal parameters define the type, name, and order of the information that customizes a data item. These parameters represent static information (it is not expected that operators add new parameterized information outside of what is represented within an ADM) that is strongly typed.
Formal parameters MUST include type and name information and MAY include an optional default value. If specified, a default value will be used whenever a set of actual parameters fails to provide a value for this formal parameter.
Using the previous example, the formal parameter specification for the number_pdus data item could be represented as number_pdus(UINT priority_mask). Alternatively, a default value could be specified by the ADM as well, which would change the definition to number_pdus(UINT priority_mask = low).
Actual parameters define the type, name, and value of the information that populates a previously-defined formal parameter set. Actual parameters are used to uniquely identify an instance of a parameterized data item.
An actual parameter MUST specify a value and MAY specify a type. If a type is provided it MUST match the type provided by the formal parameter. An actual parameter MUST NOT include NAME information.
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.
This section describes the custom type definitions used by the AMM. Specifying basic type definitions forms the basis for interchangeable encodings of ADMs based on this model.
ADMs support a series of primitive types such as bytes, (un)signed integers, floating point values, and others as outlined in Table 1.
| Type | Description |
|---|---|
| BYTE | unsigned byte value |
| INT | 32-bit signed integer in 2's complement |
| UINT | 32-bit unsigned integer in 2's complement |
| VAST | 64-bit signed integer in 2's complement |
| UVAST | 64-bit unsigned integer in 2's complement |
| REAL32 | Single-precision, 32-bit floating point value in IEEE-754 format. |
| REAL64 | Double-precision, 64-bit floating point value in IEEE-754 format. |
| STRING | NULL-terminated series of characters in UTF-8 format. |
| BOOL | A Boolean value of FALSE (whose integer interpretation is 0) or TRUE (which is any integer interpretation that is not FALSE). |
A derived typed is a primitive type that is interpreted with special semantics. The AMM supports the following derived types.
A Timestamp is a specialization of a UVAST.
There are two "types" of timestamp within the AMM: a relative timestamp and an absolute timestamp. A relative timestamp is defined as the number of seconds between two events (such as the receipt of a control by an agent and the execution of that control). An absolute timestamp is defined as UTC time since the Unix/POSIX Epoch.
Rather than define two separate data types (one for relative timestamps and one for absolute timestamps) or adding an extra field (e.g., a timestamp type identifier) the type of timestamp can be simply and unambiguously inferred from a single timestamp value. The AMM defines a Relative Timestamp Epoch (RTE). Timestamp values less than the RTE will be interpreted as relative timestamps. Timestamp values greater than or equal to the RTE will be interpreted as absolute timestamps. The RTE is defined as September 9th, 2012 (UTC time 1347148800).
For example, a timestamp value of "10" refers to 10 seconds in the future. A timestamp value of "1508554859" refers to Saturday, October 21, 2017 3:00:59 AM.
IF (timestamp < 1347148800) THEN
absolute_time = current_time + timestamp
ELSE
absolute_time = timestamp
It should be noted that absolute and relative times are interchangeable. An absolute time can be converted into a relative time by subtracting the current time from the absolute time. A relative time can be converted into an absolute time by adding to the relative time the current time. A pseudo-code example of this conversion is as follows.
A Type-Name-Value (TNV) is a three-tuple of information that decribes a data value in the AMM. Since the length of a data value is a matter of encoding, there is not an explicit length field present for the data value; it is assumed that any encoding scheme either encodes the lenght in some other way or that, generally, data types and data structures are self-delimiting.
In ADMs, TNVs are used to capture parameterized items and describe the contents of reports.
The meta-data for an identifier provides annotative or otherwise user-friendly descriptive information for the identifier (or the item being identified). This information may be used as documentation (for example, only present in ADMs and on operator consoles) and/or encoded and transmitted over the wire as part of a management protocol.
Meta-data is not required to be unique amongst identifiers. The meta-data supported by the AMM for identifiers is as follows.
Identifier contents are used to either compute or locate a data item. Within the AAM, there are two types of contents: literals and references. A reference is a unique value that can be used to look up (reference) a data item. A literal is a value that can be used to directly compute a data item. An example of a data item that could use a literal identifier would be the unsigned integer value 4.
A reference identifier is used when a data item cannot be trivially computed as a function of an identifier value. Examples of data items requiring a reference identifier would be data structures, externally defined data items, and variables.
A reference identifier consists of four parts: (1) The type of item being identified, (2) a unique handle for the item, (3) optional meta-data related to the issuer of the identifier, and (4) optional meta-data related to the item being named. The description of each of these parts is as follows.
Item Type
The type of the data item being identified, as defined in Section 8.
Unique Handle
The handle is an opaque value that MUST be unique amongst all handles within a given ADM.
Issuer
The issuer field is any string (including a hex string) representing some identification of the organization defining this item. This value may come from a global registry of organizations, an issuing node address, a signed known value, or some other network-unique marking.
Issuer information is only necessary when network operators issue new data items dynamically in a network. As such, the issuer field MUST be present for any dynamic data items added to a network and MUST NOT be present for any static data items defined in the context of an ADM.
Tag
The tag field is any string (including a hex string) used to disambiguate or otherwise validate a reference identifier.
A tag field is only applicable when network operators issue new data items dynamically in a network. As such, the tag field MUST NOT be present unless an Issuer field is also present. A tag field MUST NOT be present for any static data items defined in the context of an ADM.
The contents of the tag field is left to the discretion of the issuer. Examples of potential tag values include an issuer-known version number or a (signed) hashing of the data item associated with the reference identifier.
A literal identifier is used when a data item can be trivially computed as a function of an identifier value. Examples of data items requiring a reference identifier would be numerical values such as the unsigned integer 4.
A literal identifier consists of three parts: (1) The type of item being identified, (2) the data type of the data item, and (3) information necessary to compute the data item. The description of each of these parts is as follows.
Item Type
The type of a literal identifier MUST be a Literal, as defined in Section 8.
Data Type
The type of the literal value. This MUST be one of the primitive types as described in Table 1.
Value
This is information necessary to directly compute the data item value. For example, using string encodings, the literal value 4 could be have the string value "4" whereas a binary encoding might use the value 0x04.
There are several times when an AID must be referenced within the contents of an ADM document and a useful shorthand is defined to allow for this expression. Since an AID name is required to be unique for a given data type, the combination of AID type and AID name may be used as a reference.
Specifically, an AID reference is a string with the form <type>.<name>.
Data item definitions, or parameters associated with those definitions, may operate on a collection of information. However, where possible, the AMM seeks strong data typing which is not always possible when accepting a collection of information. To provide strong type checking, the AMM defines a series of typed collections.
A Type-Name-Value Collection is an ordered array where each element of the array is a TNV.
It is often necessary to discuss collections of data items that are provided as parameters to other items. An AID collection is an ordered set of AIDs. For example, an AMA Agent may support a command to remove a set of report definitions. This command could accept a list of report definitions to remove, identified by the AID for each report definition. In such an instance, the list of repot definitions to be removed could be modeled as an AC.
Expression apply mathematical operations to values to generate new values, typically on computers fulfilling the Agent role within the AMA. Since the variables, operators, and literals that comprise these operations are all formal ADM items, they are all identified by AIDs. Because they are all identified by AIDs, the expression is represented by an AC.
An expression (EXPR) is a AC in which a series of items are ordered so as to produce a valid post-fix mathematical expression. For example, the infix expression A * (B * C) is represented as the sequence A B C * *.
Predicates are Expressions whose values are interpreted as a Boolean. The value of zero MUST be considered "false" and all other values MUST be considered "true".
This section identifies the ADM structures that implement the AMA logical data model.
The AMA defines a series of logical components that should be included as part of an ADM. These components are summarized from the AMA in the following table. The ADM implements these logical components in largely a one-to-one fashion with a few exceptions.
| AMA Component | Summary Description | ADM Structures |
|---|---|---|
| Externally Defined Data | A typed, measured value whose definition and value determination occurs externally from the network management system. | Externally Defined Data |
| Variable | A typed, computed value whose definition and value determination occurs within the network management system. | Variable |
| Report Entry | Collections of Atomic and/or Computed data and/or other Reports. | Table Definition, Table, Report Definition, Report |
| Control | Parameterized opcode for any action that can be taken by an Agent. | Control |
| Rule | A pre-configured response to a predefined time or state on an Agent. | State-Based Rule, Time-Based Rule |
| Macro | An ordered collection of Controls. | Macro |
| Literal | A constant used when evaluating Rules or determining the value of Computed Data. | Literal, Constant |
| Operator | An opcode representing a mathematical function known to an Agent. | Operator |
The remainder of this section describes the format of these structures in the context of the aforementioned ADM data types.
Externally defined data (EDD) are predefined components of an ADM for various applications and protocols. These represent values that are calculated outside of the context of Agents and Managers, such as those values measured by firmware. As such, their value is defined external to the ADM system.
An EDD consists of an AID, type, and a description, as follows.
Managers must:
Agents must:
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 AID, a type, an initializing expression, and a description, as follows.
Managers must:
Agents must:
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 AID, 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.
Managers must:
Agents must:
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.
RPTTs are defined by an AID, the set of information comprising the report, and a description, as follows.
A Report (RPT) is a set of data values populated in conformance to a given RPTT. Each data value in a report is termed a Report Entry (RPTE).
RPTs are defined by their associated report template and the report entries themselves, as follows.
Managers must:
Agents must:
A Control represents a predefined (possibly parameterized) opcode that can be run on an Agent. Controls in the AMM are always defined in the context of an ADM as there is no concept of an operator-defined Control. Since Controls are pre-configured in Agents and Managers as part of ADM support, their representation is simply the AID that identifies them, similar to EDDs.
Controls are identified by their AID and their description, as follows.
Managers must:
Agents must:
A Time-Based Rule (TRL) specifies that a particular action should be taken by an Agent based on some time interval. A TRL specifies that starting at a particular start time, and for every period seconds thereafter, an action should be run by the Agent until the action has been run for count times. When the TRL is no longer valid it MAY BE discarded by the Agent.
Examples of TRLs include:
Managers must:
Agents must:
A State-Based Rule (SRL) specifies that a particular action should be taken by an Agent based on some evaluation of the internal state of the Agent. A SRL specifies that starting at a particular start time an action should be run by the agent if some condition evaluates to true, until the action has been run count times. When the SRL is no longer valid it MAY be discarded by the agent.
Examples of SRLs include:
Managers must:
Agents must:
Macros are ordered collections of AIDs (an AC) that contain Controls or other Macros. When run by an Agent, each AID in the AC is run in order.
A Macro is defined by a AID, a set of Controls, and a description, as follows.
Managers must:
Agents
Constants represent named basic values. Examples include common mathematical values such as PI or well-known Epochs such as the UNIX Epoch. Constants are defined solely within the context of ADMs.
A CONST is defined by its AID, value, and description, as follows.
Managers must:
Agents
Operators represent user-defined mathematical functions implemented in the firmware of an Agent for the purpose of aiding the evaluation of Expressions and Predicates. The AMM separates the concepts of Operators and Controls to prevent side-effects in Expression and Predicate evaluation (e.g. to avoid constructs such as A = B + GenerateReport()) which is why Operators are given their own structure type and Controls do not support a return value.
Because Operators represent custom firmware implemented on the Agent, they are not defined dynamically as part of network operations. Therefore, they may only be defined in the ADM for an application.
An Operator is defined by its AID, its resultant type, the number of operands, the type of operands, and a description, as follows.
Managers must:
Agents must:
This section defines identifiers and enumeration values for objects defined in the AMM. Identifiers are the text abbreviations used in ADMs to identify data types. Enumerations associate data types with a numeric value. These enumerations MUST be used whenever a data type is represented as a numerical representation.
IDs and enumerations are grouped by the kind of data they represent, as follows. AMM structure identifiers occupy enumerations 0 - 9 and represent data structures that are formally identified by an AID. Basic data types occupy enumerations 10-18 and represent primitive data types. Special types occupy the remaining enumeration space.
While the AMM does not specify any encoding of data model elements, a common set of enumerations help to ensure that various encoding standards can interoperate.
| Structure | ID | Enumeration | Numeric |
|---|---|---|---|
| Externally Defined Data | EDD | 0 | No |
| Variable | VAR | 1 | No |
| Table Template | TBLT | 2 | No |
| Report Template | RPTT | 3 | No |
| Control | CTRL | 4 | No |
| Time-Based Rule | TRL | 5 | No |
| State-Based Rule | SRL | 6 | No |
| Macro | MACRO | 7 | No |
| Constant | CONST | 8 | No |
| Operator | OP | 9 | No |
| Basic Data Type | ID | Enumeration | Numeric |
|---|---|---|---|
| BYTE | BYTE | 10 | No |
| Signed 32-bit Integer | INT | 11 | Yes |
| Unsigned 32-bit Integer | UINT | 12 | Yes |
| Signed 64-bit Integer | VAST | 13 | Yes |
| Unsigned 64-bit Integer | UVAST | 14 | Yes |
| Single-Precision Floating Point | REAL32 | 15 | Yes |
| Double-Precision Floating Point | REAL64 | 16 | Yes |
| Character String | STR | 17 | No |
| Boolean | BOOL | 18 | No |
| Compound/Special Data Type | ID | Enumeration | Numeric |
|---|---|---|---|
| Hex String | TS | 19 | No |
| Timestamp | TS | 20 | No |
| Type-Name-Value Collection | TNV | 21 | No |
| Asynchronous Resource Namespace | ARN | 22 | No |
| ADM Identifier | AID | 23 | No |
| AID Collection | AC | 24 | No |
| Expression | EXPR | 25 | No |
| Predicate | EXPR | 26 | No |
When attempting to evaluate operators of different types, wherever possible, an Agent MAY need to promote operands until they are of the correct type. For example, if an Operator is given both an INT and a REAL32, the INT SHOULD be promoted to a REAL32 before the Operator is applied.
INT UINT VAST UVAST REAL32 REAL64
+--------+--------+--------+--------+--------+--------+
INT | INT | INT | VAST | UNK | REAL32 | REAL64 |
UINT | INT | UINT | VAST | UVAST | REAL32 | REAL64 |
VAST | VAST | VAST | VAST | VAST | REAL32 | REAL64 |
UVAST | UNK | UVAST | VAST | UVAST | REAL32 | REAL64 |
REAL32 | REAL32 | REAL32 | REAL32 | REAL32 | REAL32 | REAL64 |
REAL64 | REAL64 | REAL64 | REAL64 | REAL64 | REAL64 | REAL64 |
+--------+--------+--------+--------+--------+--------+
Figure 2: Numeric Promotions
Listing legal promotion rules is mandatory for ensuring that behavior is similar across multiple implementations of Agents and Managers. The listing of legal promotions in the ADM are listed in Figure 2. In this Figure, operands are listed across the top row and down the first column. The resultant type of the promotion is listed in the table at their intersection.
ADMs do not permit promotions between non-numeric types, and numeric promotions not listed in this section are not allowed. Any attempt to perform an illegal promotion SHOULD result in an error.
Variables, Expressions, and Predicates are typed values. When attempting to assign a value of a different type, a numeric conversion must be performed. Any numeric type may be converted to any other numeric type in accordance with the C rules for arithmetic type conversions.
This section is TBD waiting for a final decision on whether we can use YANG separate from NETCONF.
This section provides an ADM template in the form of a JSON document. It is not required that these JSON encodings be used to encode the transmission of AMM information over the wire in the context of a network deployment. It is also not required that only these JSON encodings be used to document ADMs and other AMM information. Since the AMM is designed to allow for multiple encodings, the expression of ADMs in the provided JSON format is intended support translation to other encodings without loss of information.
JSON data types generally support AMM primitive data types. The mapping of AMM primitive types to JSON data types is provided in Table 2.
| AMM Type | JSON Encoding |
|---|---|
| BYTE | number (0 <= # <= 256) |
| INT | number |
| UINT | number |
| VAST | number |
| UVAST | number |
| REAL32 | number |
| REAL64 | number |
| STRING | string |
| BOOL | boolean |
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.
In cases where a hexadecimal value must be encoded, the JSON encoding follows the guidelines for hex-string from RFC6991. In this case, the hexadecimal value can be placed in a formatted string and this string used in place of any numeric type with a hexademical representation.
A Hex String contents a written representation of a hexadecimal value, without prefix. In this scheme, byte values are separated by colons (:). While either upper or lower case characters are acceptable, by convention lower-case characters should be used for increased readability.
For example, given the hexadecimal value 0x12AB the resultant Hex String would be "12:ab".
A TNV is encoded as a JSON object with three element: "type", "name", and "value". For each item in a TNV, there are three acceptable formulations that can be used to represent the item, as illustrated in the following table. For the examples in this table, consider the REAL32 value of PI as 3.14159.
| Desc | Example |
|---|---|
| Full | {"type":"REAL32", "name":"PI", "value":3.14159} |
| Named Type | {"type":"REAL32", "name":"PI", "value":null} |
| Anonymous Type | {"type":"REAL32", "name":null, "value":null} |
| Anonymous Type Value | {"type":"REAL32", "name":null, "value":3.14159} |
| Anonymous Value | {"type":null, "name":null, "value":3.14159} |
A single parameter is encoded as a single JSON object where the key string is the data type of the parameter and the value is the name of the parameter. The general form of the object will be {parm_type:parm_value}.
| Desc | Example |
|---|---|
| Single String Parameter | {"STR":"name"} |
| Single Unsigned Integer Parameter | {"UINT":"name2"} |
| Multiple Parameter | [{"UINT":"name2"}, {"STR":"name"}] |
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('0')","EDD.item2('1')","OP.+UINT"]
The following is an example of a JSON encoding of an EXPR object.
An AID encoding is not needed for the ADM template because all required fields of an AID are already present within ADM objects. Adding an AID field to the ADM needlessly complicates and expands the ADM structure without adding clarity or interoperability. Instead of mandating an AID encoding, the template ensures that relevant information is captured in each ADM data item encoding to support the creation of AIDs when ADM structures are represented in operational network encodings.
NOTE: There is some discussion as to whether the inclusion of an AID JSON encoding in the ADM should be included in the model. This remains an area of active discussion.
Absent a formal AID syntax in the ADM template, a shorthand string is used to reference data items defined in an ADM from elsewhere in the same ADM:
<Adm Structure Type>.<Data Item Name>
In cases where such a reference must include Actual Parameters to completely identify a data item, an optional parameter string MAY be appended to the shorthand reference. Thi optional string encloses a set of comma-separated parameters between a set of parentheses. A parameter may be either a pass-by-value or a pass-by-reference parameter. A pass-by-value parameter is one whose literal value should be used as the parameter value. These parameters are enclosed in single quotes within the parameter string. A pass-by-reference parameter is one whose value is related to some other information provided in the data structure. The manner in which the reference is calculated MUST be documented in the context of the ADM data item using the reference. The optional parameter string format is as follows.
('val_parm_1','val_parm_2',ref_parm_1,... )
| Desc | Example |
|---|---|
| Externally Defined Data Reference | "EDD.item_name" |
| Variable Reference | VAR.var1 |
| Value Parameter EDD Reference | EDD.number_pdu('0x4') |
| Reference Parameter EDD Reference | EDD.number_pdu(ref_parm) |
| Mixed Parameter EDD Reference | EDD.example_item('1', a, '2.0') |
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": [{"STR":"Src"}],
"description": "Successfully Tx BCB blocks from SRC"
The following is an example of a JSON encoding of an EDD 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": ["EDD.item1('0')","EDD.item2('1')","OP.+UINT"]
},
"description": "# total items (# item1 + # item2)."
The following is an example of a JSON encoding of an VAR 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": [{"STR":"ciphersuite_names"}],
"description": "This table lists supported ciphersuites."
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": "full_report",
"parmspec": [{"STR":"Source"}],
"definition" : [
"EDD.data_item1",
"EDD.data_item2('1')",
"EDD.data_item3(Source)",
"EDD.data_item4('1', Source)",
],
"description": "A full report."
The following is an example of a JSON encoding of an RPTT 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": [{"STR":"src"}],
"description": "This control resets counts for the given source."
The following is an example of a JSON encoding of an RPTT 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": ["CTRL.list_vars","CTRL.list_rptts"],
"description": "List user defined data."
The following is an example of a JSON encoding of an RPTT object.
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": "FLOAT",
"value": 3.14159,
"description": "The value of PI."
The following is an example of a JSON encoding of a CONST 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": "+INT",
"result-type": "INT",
"in-type": ["INT", "INT"],
"description": "Int32 addition"
The following is an example of a JSON encoding of a OP object.
The AMM data model additionally defines data objects for both time-based rules and state-based rules. These rules are associated with dynamic behaviors in the context of a network deployment and, as such, are typically not represented as static constructs in the context of an ADM. Therefore, these data structures are not considered in this ADM template.
TBD.
TBD
| [I-D.birrane-dtn-ama] | Birrane, E., "Asynchronous Management Architecture", Internet-Draft draft-birrane-dtn-ama-06, October 2017. |
| [RFC2119] | Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997. |