Delay-Tolerant Networking E. Birrane Internet-Draft E. DiPietro Intended status: Informational D. Linko Expires: September 5, 2018 Johns Hopkins Applied Physics Laboratory March 4, 2018 AMA Application Data Model draft-birrane-dtn-adm-01 Abstract This document defines a data model that captures the information necessary to manage applications in asynchronously managed networks. This model includes a set of common type definitions, data structures, and a template for publishing standardized representations of elements of the model. Status of This Memo This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at https://datatracker.ietf.org/drafts/current/. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." This Internet-Draft will expire on September 5, 2018. Copyright Notice Copyright (c) 2018 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of Birrane, et al. Expires September 5, 2018 [Page 1] Internet-Draft ADM March 2018 the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 1.1. Purpose . . . . . . . . . . . . . . . . . . . . . . . . . 3 1.2. Scope . . . . . . . . . . . . . . . . . . . . . . . . . . 4 2. Requirements Language . . . . . . . . . . . . . . . . . . . . 4 3. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4 4. Data Modeling Concept of Operations . . . . . . . . . . . . . 5 5. Key Concepts . . . . . . . . . . . . . . . . . . . . . . . . 6 5.1. ADM Namespaces . . . . . . . . . . . . . . . . . . . . . 6 5.2. Item Identification . . . . . . . . . . . . . . . . . . . 7 5.3. Parameterization . . . . . . . . . . . . . . . . . . . . 7 5.3.1. Formal Parameters . . . . . . . . . . . . . . . . . . 8 5.3.2. Actual Parameters . . . . . . . . . . . . . . . . . . 8 5.3.3. Optional Parameters . . . . . . . . . . . . . . . . . 8 6. Asynchronous Management Model (AMM) . . . . . . . . . . . . . 9 6.1. Type Definitions . . . . . . . . . . . . . . . . . . . . 9 6.1.1. Primitive Types . . . . . . . . . . . . . . . . . . . 9 6.1.2. Derived Types . . . . . . . . . . . . . . . . . . . . 9 6.2. ADM Identifier (AID) . . . . . . . . . . . . . . . . . . 11 6.2.1. Identifier Meta-Data . . . . . . . . . . . . . . . . 11 6.2.2. Identifier Contents . . . . . . . . . . . . . . . . . 11 6.2.3. AID References . . . . . . . . . . . . . . . . . . . 13 6.3. Collections . . . . . . . . . . . . . . . . . . . . . . . 13 6.3.1. Type-Name-Value Collection (TC) . . . . . . . . . . . 13 6.3.2. AID Collection (AC) . . . . . . . . . . . . . . . . . 13 6.3.3. Expression (EXPR) . . . . . . . . . . . . . . . . . . 14 6.3.4. Predicate (PRED) . . . . . . . . . . . . . . . . . . 14 7. ADM Structures . . . . . . . . . . . . . . . . . . . . . . . 14 7.1. AMA Overview . . . . . . . . . . . . . . . . . . . . . . 14 7.2. Externally Defined Data (EDD) . . . . . . . . . . . . . . 16 7.3. Variables (VAR) . . . . . . . . . . . . . . . . . . . . . 17 7.4. Tables . . . . . . . . . . . . . . . . . . . . . . . . . 18 7.4.1. Table Template (TBLT) . . . . . . . . . . . . . . . . 18 7.4.2. Table (TBL) . . . . . . . . . . . . . . . . . . . . . 19 7.5. Reports . . . . . . . . . . . . . . . . . . . . . . . . . 20 7.5.1. Report Template (RPTT) . . . . . . . . . . . . . . . 20 7.5.2. Report (RPT) . . . . . . . . . . . . . . . . . . . . 21 7.6. Control (CTRL) . . . . . . . . . . . . . . . . . . . . . 22 7.7. Time-Based Rule (TRL) . . . . . . . . . . . . . . . . . . 23 7.8. State-Based Rule (SRL) . . . . . . . . . . . . . . . . . 25 7.9. Macro (MAC) . . . . . . . . . . . . . . . . . . . . . . . 26 7.10. Constant (CONST) . . . . . . . . . . . . . . . . . . . . 27 7.11. Operator (OP) . . . . . . . . . . . . . . . . . . . . . . 28 8. Data Type IDs and Enumerations . . . . . . . . . . . . . . . 30 Birrane, et al. Expires September 5, 2018 [Page 2] Internet-Draft ADM March 2018 8.1. Numeric Promotions . . . . . . . . . . . . . . . . . . . 31 8.2. Numeric Conversions . . . . . . . . . . . . . . . . . . . 32 9. AMM Data Model Specification . . . . . . . . . . . . . . . . 32 10. ADM JSON Template . . . . . . . . . . . . . . . . . . . . . . 32 10.1. Primitive Type Encoding . . . . . . . . . . . . . . . . 33 10.2. Derived Type Encoding . . . . . . . . . . . . . . . . . 33 10.2.1. Hex String . . . . . . . . . . . . . . . . . . . . . 33 10.2.2. Type-Name-Values . . . . . . . . . . . . . . . . . . 34 10.2.3. Formal Parameters . . . . . . . . . . . . . . . . . 34 10.2.4. Expression . . . . . . . . . . . . . . . . . . . . . 35 10.3. ADM Identifier . . . . . . . . . . . . . . . . . . . . . 35 10.4. ADM Structures . . . . . . . . . . . . . . . . . . . . . 36 10.4.1. Externally Defined Data (EDD) Encoding . . . . . . . 36 10.4.2. Variables Encoding . . . . . . . . . . . . . . . . . 37 10.4.3. Table Template (TBLT) Encoding . . . . . . . . . . . 38 10.4.4. Report Template Encoding . . . . . . . . . . . . . . 38 10.4.5. Controls (CTRL) Encoding . . . . . . . . . . . . . . 39 10.4.6. Macro Encoding . . . . . . . . . . . . . . . . . . . 40 10.4.7. Constant (CONST) Encoding . . . . . . . . . . . . . 40 10.4.8. Operator (OP) Encoding . . . . . . . . . . . . . . . 41 10.4.9. Exemptions . . . . . . . . . . . . . . . . . . . . . 41 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 42 12. Security Considerations . . . . . . . . . . . . . . . . . . . 42 13. Informative References . . . . . . . . . . . . . . . . . . . 42 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 42 1. Introduction This document defines a data model suitable for managing applications in asynchronously managed networks. 1.1. Purpose The Asynchronous Management Architecture [I-D.birrane-dtn-ama] documents a concept for open-loop control of applications (and protocols) for situations where timely, highly-available connections cannot exist amongst managing and and managed nodes in a network. While the AMA describes logical roles and responsibilities, it does not include the detailed information necessary to produce interoperable data models. This document defines a generic Asynchronous Management Model (AMM) consisting of data types and data structures for managing applications in asynchronous networks. Further, this document provides a template for the standard representation of application- specific instances of this model called the Application Data Model Template (ADM-T). The AMM and ADM-T, together, provide the mechanism for applications to specify how they are to be asynchronously managed Birrane, et al. Expires September 5, 2018 [Page 3] Internet-Draft ADM March 2018 in challenged networks. Individual applications capture their unique, static management information in documents compliant with the ASDM-T using the types and structures defined by the AMM. This application-specific document is called the Application Data Model (ADM). 1.2. Scope The AMM presented in this document does not assume any specific type of application or underlying network encoding. In order to communicate model elements between AMA Agents and Managers in a network, the model must be encoded for transmission. Any such encoding scheme is outside of the scope of this document. Generally, encoding of the model is a separate concern from the specification of data within the model. Since different networks may use different encodings for data, mandating an encoding format would require incompatible networks to encapsulate data in ways that could introduce inefficiency and obfuscation. It is envisioned that different networks would be able to encode ASDMs in their native encodings such that translating ASDM data from one encoding to the next could be a mechanical action taken at network borders. Since the specification does not mandate an encoding format, the ADM-T must provide enough information to make encoding (and translating from one encoding to another) an unambiguous process. Therefore, where necessary, this document provides identification, enumeration and other schemes that ensure ADMs provide enough information to prevent ambiguities caused by different encoding schemes. 2. Requirements Language The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119]. 3. Terminology Note: The terms "Actor", "Agent", "Externally Defined Data", "Variable", "Control", "Literal", "Macro", "Manager", "Operator", and "Rule" are used without modification from the definitions provided in [AMA]. Additional terms critical to understanding the ADMT are as follows. Birrane, et al. Expires September 5, 2018 [Page 4] Internet-Draft ADM March 2018 o Application - A software implementation running on an Agent and being managed by a manager. This includes software that implements protocol processing on an Agent. o Application Data Model (ADM) - The full set of statically-defined data items necessary to manage an application asynchronously. o Application Data Model Template (ADM-T) - A standard format for expressing predefined data items for an application. o ADM Item Definition (AID) - A parameterized structure used to uniquely identify ADM objects. o Operational Data Model (ODM) - The operational configuration of an Agent. This inludes the union of all ADM information supported by the Agent as well as all operational, dynamic configuration applied to the Agent by Managers in the network. o Report (RPT) - A collection of Report Entries gathered by one or more Agents and provided to one or more Managers. o Report Template (RPT-T) - A named, typed, ordered collection of data types that represents the format of a corresponding Report Entry. This is the schema for a Report Entry, generated by a Manager and communicated to one or more Agents. o Report Entry (RPT-E) - An ordered series of data values generated by an Agent in accordance with a corresponding Report Template. o State-Based Rule (SRL) - A Rule whose action is performed if a defined predicate evaluates to true. SRLs are defined in Section 7.8. o Time-Based Rule (TRL) - A Rule whose action is performed at regular intervals. TRLs are defined in Section 7.7. 4. Data Modeling Concept of Operations In order to asynchronously manage an application, in accordance with the [I-D.birrane-dtn-ama], an application-specific data model must be created containing all pre-defined management information for that application. This model is termed the Application Data Model (ADM) and forms the core set of information for that application in whichever network it is deployed. The ADM syntactically conforms to the ADM-T and is uses the data structures and types that comprise the AMM. Birrane, et al. Expires September 5, 2018 [Page 5] Internet-Draft ADM March 2018 The information standardized in the ADM represents static configurations and definitions that apply to any deployment of the application, regardless of the network in which it is operating. Within any given network, Managers supplement the information provided by ADMs with dynamic definitions and values. The operational configuration of the network is the union of all supported ADMs and all Manager-defined dynamic configurations. This is termed the Operational Data Model (ODM). The relationships amongst the AMM, ADM-T, and ADM are illustrated in Figure 1. Data Model Relationship +---------+ +---------+ | AMM |-------------->| ADM-T | +----+----+ +----+----+ | | | +----------+-------------+ V | | | +----------+ V V V | Manager | +-------+ +-------+ +-------+ | Dynamic | | ADM 1 | | ADM 2 | ... | ADM N | | Config. | +---+---+ +---+---+ +---+---+ +-----+----+ | | | | | | | V V V V +---------------------------------------------+ | ODM | +---------------------------------------------+ Figure 1 5. Key Concepts 5.1. ADM Namespaces Each ADM must exist within a unique namespace to prevent conflicting definitions across multiple ADMs and ambiguous behavior within network deployments. To ensure the uniqueness of ADM namespaces, they must be assigned by a moderating organization as part of a maintained registry. ADM namespaces are not expected to be flat, but hierarchical where namespaces that are closer to a root node in the hierarchy are considered to have broader scope than namespaces closer to leaf nodes in the hierarchy. A hierarchical taxonomy of namespaces allows Birrane, et al. Expires September 5, 2018 [Page 6] Internet-Draft ADM March 2018 grouping ADMs that share a common classificiation at some level in the namespace hierarchy. Also, a hierarchical namespace can preserve this grouping in cases where a compact or otherwise binary encoding is required. It should be noted that there is no requirement for the namespace hierarchy to be represented as a tree structure; multiple root nodes are acceptable and likely to exist. In a hierarchical model of namespaces, a particular ADM namespace can be identified as the path to that namespace through the hierarchy. The expression of that path within an ADM is accomplished by defining an ADM Resource Namespace (ARN). An ARN is a URI with the scheme name of "arn" and a scheme-specific part the consists of a colon- separated list of namespaces representing the path from some root in the namespace hierarchy to the allocated space for the ADM. arn:: For example, the DTN community publishes the Bundle Protocol and the Bundle Protocol ADM could be assigned the namespace arn:Dtn:BundleProtocol. The ADM for the Interplanetary Overlay Network (ION) implementation of a Bundle Protocol Agent could have a separate namespace namespace arn:Dtn:Ion:BundleProtocolAdmin. 5.2. Item Identification Every item in an ADM must be uniquely identifiable both within the context of the ADM itself and in the context of any network deploying other ADMs and dynamic content. There are two types of information which, together, uniquely identify a data item within the AMM: identifier meta-data and identifier contents. 5.3. Parameterization Parameterization is used pervasively in the AMM to enable expressive autonomous function and reduce the amount of traffic that would otherwise need to be communicated between Managers and Agents. In this model, several types of data items can be parameterized, to include commands, reports, and even individual data definitions. For example, consider the management of a protocol that supports three data priorities (low, medium, and high). Rather than defining three deparate data items (number_pdus_low, number_pdus_medium, and number_pdus_high) the AMM allows for the specification of a parameter for this data type, such as number_pdus(bitmask) and supports expressions such as number_pdus(low|medium|high). Parameters in the AMM are associated with the identifier for a data item. By associating parameters with identifiers makes it possible to distinguish between two instances of a parameterized data item. Birrane, et al. Expires September 5, 2018 [Page 7] Internet-Draft ADM March 2018 Using the number_pdus data item example, the identifier of the data item number_pdus(low) should be distinguishable from the identifier of the data item number_pdus(low|medium). When represented in a data item identifier, parameters may specify either "formal parameters" or "actual parameters". 5.3.1. Formal Parameters Formal parameters define the type, name, and order of the information that customizes a data item. These parameters represent static information (it is not expected that operators add new parameterized information outside of what is represented within an ADM) that is strongly typed. Formal parameters MUST include type and name information and MAY include an optional default value. If specified, a default value will be used whenever a set of actual parameters fails to provide a value for this formal parameter. Using the previous example, the formal parameter specification for the number_pdus data item could be represented as number_pdus(UINT priority_mask). Alternatively, a default value could be specified by the ADM as well, which would change the definition to number_pdus(UINT priority_mask = low). 5.3.2. Actual Parameters Actual parameters define the type, name, and value of the information that populates a previously-defined formal parameter set. Actual parameters are used to uniquely identify an instance of a parameterized data item. An actual parameter MUST specify a value and MAY specify a type. If a type is provided it MUST match the type provided by the formal parameter. An actual parameter MUST NOT include NAME information. 5.3.3. Optional Parameters In cases where a formal parameter contains a default value, the associated actual parameter may be omitted. Default values in formal parameters (and, thus, optional actual parameters) are encouraged as they reduce the size of data items communicated amongst Managers and Agents in a network. Birrane, et al. Expires September 5, 2018 [Page 8] Internet-Draft ADM March 2018 6. Asynchronous Management Model (AMM) 6.1. Type Definitions This section describes the custom type definitions used by the AMM. Specifying basic type definitions forms the basis for interchangeable encodings of ADMs based on this model. 6.1.1. Primitive Types ADMs support a series of primitive types such as bytes, (un)signed integers, floating point values, and others as outlined in Table 1. +--------------------+----------------------------------------------+ | Type | Description | +--------------------+----------------------------------------------+ | BYTE | unsigned byte value | | | | | INT | 32-bit signed integer in 2's complement | | | | | UINT | 32-bit unsigned integer in 2's complement | | | | | VAST | 64-bit signed integer in 2's complement | | | | | UVAST | 64-bit unsigned integer in 2's complement | | | | | REAL32 | Single-precision, 32-bit floating point | | | value in IEEE-754 format. | | | | | REAL64 | Double-precision, 64-bit floating point | | | value in IEEE-754 format. | | | | | STRING | NULL-terminated series of characters in | | | UTF-8 format. | | | | | BOOL | A Boolean value of FALSE (whose integer | | | interpretation is 0) or TRUE (which is any | | | integer interpretation that is not FALSE). | +--------------------+----------------------------------------------+ Table 1: Primitive Types 6.1.2. Derived Types A derived typed is a primitive type that is interpreted with special semantics. The AMM supports the following derived types. Birrane, et al. Expires September 5, 2018 [Page 9] Internet-Draft ADM March 2018 6.1.2.1. Timestamp (TS) A Timestamp is a specialization of a UVAST. There are two "types" of timestamp within the AMM: a relative timestamp and an absolute timestamp. A relative timestamp is defined as the number of seconds between two events (such as the receipt of a control by an agent and the execution of that control). An absolute timestamp is defined as UTC time since the Unix/POSIX Epoch. Rather than define two separate data types (one for relative timestamps and one for absolute timestamps) or adding an extra field (e.g., a timestamp type identifier) the type of timestamp can be simply and unambiguously inferred from a single timestamp value. The AMM defines a Relative Timestamp Epoch (RTE). Timestamp values less than the RTE will be interpreted as relative timestamps. Timestamp values greater than or equal to the RTE will be interpreted as absolute timestamps. The RTE is defined as September 9th, 2012 (UTC time 1347148800). For example, a timestamp value of "10" refers to 10 seconds in the future. A timestamp value of "1508554859" refers to Saturday, October 21, 2017 3:00:59 AM. It should be noted that absolute and relative times are interchangeable. An absolute time can be converted into a relative time by subtracting the current time from the absolute time. A relative time can be converted into an absolute time by adding to the relative time the current time. A pseudo-code example of this conversion is as follows. IF (timestamp < 1347148800) THEN absolute_time = current_time + timestamp ELSE absolute_time = timestamp 6.1.2.2. Type-Name-Value (TNV) A Type-Name-Value (TNV) is a three-tuple of information that decribes a data value in the AMM. Since the length of a data value is a matter of encoding, there is not an explicit length field present for the data value; it is assumed that any encoding scheme either encodes the lenght in some other way or that, generally, data types and data structures are self-delimiting. o Type - The strong typing for this value. Types MUST be one of those defined in Section 8. Birrane, et al. Expires September 5, 2018 [Page 10] Internet-Draft ADM March 2018 o Name - A unique identifier for this value. o Value - The value of the data item. In ADMs, TNVs are used to capture parameterized items and describe the contents of reports. 6.2. ADM Identifier (AID) 6.2.1. Identifier Meta-Data The meta-data for an identifier provides annotative or otherwise user-friendly descriptive information for the identifier (or the item being identified). This information may be used as documentation (for example, only present in ADMs and on operator consoles) and/or encoded and transmitted over the wire as part of a management protocol. Meta-data is not required to be unique amongst identifiers. The meta-data supported by the AMM for identifiers is as follows. o Name An identifier name is a string associated with the identifier, but not the identifier itself. Names provide human-readable and/or user-friendly ways to refer to identifiers that are, otherwise, difficult to parse. In cases where the identifier is considered self-evident, an identifier name may be ommitted. o Description An identifier description is a string describing the purpose or usage of the identified item. The intent of the description is to provide human-readable and user-friendly documentation for the item being identified. 6.2.2. Identifier Contents Identifier contents are used to either compute or locate a data item. Within the AAM, there are two types of contents: literals and references. A reference is a unique value that can be used to look up (reference) a data item. A literal is a value that can be used to directly compute a data item. An example of a data item that could use a literal identifier would be the unsigned integer value 4. 6.2.2.1. Reference Identifier A reference identifier is used when a data item cannot be trivially computed as a function of an identifier value. Examples of data Birrane, et al. Expires September 5, 2018 [Page 11] Internet-Draft ADM March 2018 items requiring a reference identifier would be data structures, externally defined data items, and variables. A reference identifier consists of four parts: (1) The type of item being identified, (2) a unique handle for the item, (3) optional meta-data related to the issuer of the identifier, and (4) optional meta-data related to the item being named. The description of each of these parts is as follows. Item Type The type of the data item being identified, as defined in Section 8. Unique Handle The handle is an opaque value that MUST be unique amongst all handles within a given ADM. Issuer The issuer field is any string (including a hex string) representing some identification of the organization defining this item. This value may come from a global registry of organizations, an issuing node address, a signed known value, or some other network-unique marking. Issuer information is only necessary when network operators issue new data items dynamically in a network. As such, the issuer field MUST be present for any dynamic data items added to a network and MUST NOT be present for any static data items defined in the context of an ADM. Tag The tag field is any string (including a hex string) used to disambiguate or otherwise validate a reference identifier. A tag field is only applicable when network operators issue new data items dynamically in a network. As such, the tag field MUST NOT be present unless an Issuer field is also present. A tag field MUST NOT be present for any static data items defined in the context of an ADM. The contents of the tag field is left to the discretion of the issuer. Examples of potential tag values include an issuer-known version number or a (signed) hashing of the data item associated with the reference identifier. 6.2.2.2. Literal Identifier A literal identifier is used when a data item can be trivially computed as a function of an identifier value. Examples of data items requiring a reference identifier would be numerical values such as the unsigned integer 4. Birrane, et al. Expires September 5, 2018 [Page 12] Internet-Draft ADM March 2018 A literal identifier consists of three parts: (1) The type of item being identified, (2) the data type of the data item, and (3) information necessary to compute the data item. The description of each of these parts is as follows. Item Type The type of a literal identifier MUST be a Literal, as defined in Section 8. Data Type The type of the literal value. This MUST be one of the primitive types as described in Table 1. Value This is information necessary to directly compute the data item value. For example, using string encodings, the literal value 4 could be have the string value "4" whereas a binary encoding might use the value 0x04. 6.2.3. AID References There are several times when an AID must be referenced within the contents of an ADM document and a useful shorthand is defined to allow for this expression. Since an AID name is required to be unique for a given data type, the combination of AID type and AID name may be used as a reference. Specifically, an AID reference is a string with the form .. 6.3. Collections Data item definitions, or parameters associated with those definitions, may operate on a collection of information. However, where possible, the AMM seeks strong data typing which is not always possible when accepting a collection of information. To provide strong type checking, the AMM defines a series of typed collections. 6.3.1. Type-Name-Value Collection (TC) A Type-Name-Value Collection is an ordered array where each element of the array is a TNV. 6.3.2. AID Collection (AC) It is often necessary to discuss collections of data items that are provided as parameters to other items. An AID collection is an ordered set of AIDs. For example, an AMA Agent may support a command Birrane, et al. Expires September 5, 2018 [Page 13] Internet-Draft ADM March 2018 to remove a set of report definitions. This command could accept a list of report definitions to remove, identified by the AID for each report definition. In such an instance, the list of repot definitions to be removed could be modeled as an AC. 6.3.3. Expression (EXPR) Expression apply mathematical operations to values to generate new values, typically on computers fulfilling the Agent role within the AMA. Since the variables, operators, and literals that comprise these operations are all formal ADM items, they are all identified by AIDs. Because they are all identified by AIDs, the expression is represented by an AC. An expression (EXPR) is a AC in which a series of items are ordered so as to produce a valid post-fix mathematical expression. For example, the infix expression A * (B * C) is represented as the sequence A B C * *. 6.3.4. Predicate (PRED) Predicates are Expressions whose values are interpreted as a Boolean. The value of zero MUST be considered "false" and all other values MUST be considered "true". 7. ADM Structures This section identifies the ADM structures that implement the AMA logical data model. 7.1. AMA Overview The AMA defines a series of logical components that should be included as part of an ADM. These components are summarized from the AMA in the following table. The ADM implements these logical components in largely a one-to-one fashion with a few exceptions. Birrane, et al. Expires September 5, 2018 [Page 14] Internet-Draft ADM March 2018 +------------+-----------------------------------+------------------+ | AMA | Summary Description | ADM Structures | | Component | | | +------------+-----------------------------------+------------------+ | Externally | A typed, measured value whose | Externally | | Defined | definition and value | Defined Data | | Data | determination occurs externally | | | | from the network management | | | | system. | | | | | | | Variable | A typed, computed value whose | Variable | | | definition and value | | | | determination occurs within the | | | | network management system. | | | | | | | Report | Collections of Atomic and/or | Table | | Entry | Computed data and/or other | Definition, | | | Reports. | Table, Report | | | | Definition, | | | | Report | | | | | | Control | Parameterized opcode for any | Control | | | action that can be taken by an | | | | Agent. | | | | | | | Rule | A pre-configured response to a | State-Based | | | predefined time or state on an | Rule, Time-Based | | | Agent. | Rule | | | | | | Macro | An ordered collection of | Macro | | | Controls. | | | | | | | Literal | A constant used when evaluating | Literal, | | | Rules or determining the value of | Constant | | | Computed Data. | | | | | | | Operator | An opcode representing a | Operator | | | mathematical function known to an | | | | Agent. | | +------------+-----------------------------------+------------------+ AMA Logical Components The remainder of this section describes the format of these structures in the context of the aforementioned ADM data types. Birrane, et al. Expires September 5, 2018 [Page 15] Internet-Draft ADM March 2018 7.2. Externally Defined Data (EDD) Externally defined data (EDD) are predefined components of an ADM for various applications and protocols. These represent values that are calculated outside of the context of Agents and Managers, such as those values measured by firmware. As such, their value is defined external to the ADM system. 7.2.1. Definition An EDD consists of an AID, type, and a description, as follows. AID EDDs are defined solely in the context of an ADM. Since they are sampled external to the management system, changes or additions to EDDs require changes to how the network management system interfaces with other components on an Agent. Because an EDD is defined in the context of an ADM, it MUST NOT contain an Issuer or Tag field and the type of the AID MUST be the EDD type. Type This represents the data type of the value associated with the EDD. Description This represents the human-readable description of the EDD, as a string. 7.2.2. Processing Managers must: o Store the AID for each known EDD definition. o Associate a data type to each known EDD definition. o Encode EDD AIDs in Controls to Agents, as appropriate. Agents must: o Store the AID for each known EDD definition. o Associate a data type to each known EDD definition. o Calculate the value of an EDD definition when required, such as when generating a Report Entry or evaluating an Expression. Birrane, et al. Expires September 5, 2018 [Page 16] Internet-Draft ADM March 2018 7.3. Variables (VAR) Variables (VAR) may be statically defined in an ADM or dynamically by Managers in a network deployment. VARs differ from EDDs in that they are completely described by other known data in the system (either other VARs or other EDDs). For example, letting E# be a EDD item and V# be a VAR item, the following are examples of VAR definitions. V1 = E1 * E2 V2 = V1 + E3 7.3.1. Definition VARs are defined by an AID, a type, an initializing expression, and a description, as follows. AID The type of this AID MUST be type VAR, and the AID MUST NOT contain parameters. Type This is the type of the VAR, and acts as a static cast for the result of the initializing EXPR. This type MUST be one of the data types defined in Table 1. Note, it is possible to specify a type different than the resultant type of the initializing EXPR. For example, if an EXPR adds two single- precision floating point numbers, the VAR MAY have an integer type associated with it. Initializer The initial value of the VAR is given by an initializing EXPR. In the case where the type of the VAR itself is EXPR the initializer is used as the value of the VAR. In the case where the type of the VAR is anything other than EXPR, then the initializer EXPR will be evaluated and the resultant value will be used as the initial value of the VAR. Description This represents the human-readable description of the VAR, as a string. 7.3.2. Processing Managers must: o Store the AID for each ADM-defined VAR definition. Birrane, et al. Expires September 5, 2018 [Page 17] Internet-Draft ADM March 2018 o Send requests to Agents to add, list, describe, and remove VAR definitions. o Remember custom VAR definitions. o Encode VAR AIDs in Controls to Agents, as appropriate. Agents must: o Store the AID for each ADM-defined VAR definition. o Calculate the value of VARs when required, such as during Rule evaluation, calculating other VAR values, and generating Reports. o Add, remove, list, and describe custom VAR definitions. 7.4. Tables A Table is a named, typed, collection of tabular data. Columns within a table are named and typed. Rows within a table capture individual data sets with one value in each row corresponding to one column in the table. Tables are represented in two ways in the AMM: Table Templates and Table Instances. 7.4.1. Table Template (TBLT) A table template identifies the strongly-typed column template that will be followed by any instance of this table available in the network. Table templates appear statically in ADMs and may not be created dynamically within the network by Managers. Changing a table template within an asynchronously managed network would result in confusion if differing template definitions for the same table identifier were to be active in the network at one time. 7.4.1.1. Definition TBLTs are defined by an AID, a set of column descriptions, and table metadata, as follows. AID The type of this AID MUST be type TBLT, and the AID MUST NOT contain parameters. Since Table Template definitions only appear in an ADM document, this AID MUST NOT contain an Issuer or a Tag field. Columns A TBLT is completely defined by its ordered set of columns descriptions. Each column description is a name and a type. Birrane, et al. Expires September 5, 2018 [Page 18] Internet-Draft ADM March 2018 The type of each column MUST be one of the primitive types defined in Table 1. A column description is represented as a TNV that MUST contain type and name information and MUST NOT contain value information. Description This represents the human-readable description of the TBLT, as a string. 7.4.2. Table (TBL) Tables are collections of data that MUST be constructed in accordance with an associated Table Template. Tables MUST NOT appear in the ADM for an application; they are only instantiated dynamically as part of the operation of a network. 7.4.2.1. Definition TBLs are defined by their Table Template, the number of rows in the table, and the associated set of data values for each row. Template AID This is the AID of the Table Template holding the column definitions for this table. This AID MUST match a known Table Template defined in an ADM. Number of Rows This is the number of rows in the table. A Table MAY have zero rows. Rows Information Each row in a TBL is represented as the number of data elements in the row, followed by the data elements themselves. The number of data values for each row MUST be equal to the number of columns defined for the Table Template. The data values for each row are represented by a TNV that optionally contains type information and MUST contain value information. Type information MAY be included when necessary to verify that elements entered into a table match the type expected by a column in the table. 7.4.3. Processing Managers must: o Store the AID for each ADM-defined Table Template definition. Birrane, et al. Expires September 5, 2018 [Page 19] Internet-Draft ADM March 2018 o Request that Agents populate tables according to this template. Agents must: o Store the AID for each ADM-defined Table Template definition. o Produce Tables in accordance with Table Template definitions when required. 7.5. Reports A Report is a set of non-tabular, potentially nested data items that may be predefined in the context of an ADM, or defined dynamically in the context of a deployed network. Reports are represented in two ways in the AMM: Report Templates and Reports. A Report Template defines the type of information to be included in a report, and a Report contains that information. 7.5.1. Report Template (RPTT) A Report Template (RPTT) is the ordered set of data descriptions that describe how values will be represented in a corresponding Report. RPTTs can be viewed as a schema that describes how to interpret a Report; they contain no values and are either defined in an ADM or configured between Managers and Agents during network operations. 7.5.1.1. Definition RPTTs are defined by an AID, the set of information comprising the report, and a description, as follows. AID The type of this AID MUST be type RPTT. If the RPTT is defined in an ADM it MUST NOT contain an Issuer or Tag field. If the RPTT is defined outside of an ADM it MUST contain an Issuer field and MAY contain a Tag field. An RPTT AID MAY be parameterized. If the RPTT AID is parameterized, the parameters MUST be used (in the same number and order) to customize any parameterized data in any Report generated using this template. Entries The list of ordered data items to be included in the report is represented by the list of identifiers for those items. Since every structure in the ADM can be identified by a AID, this value is represented by an AC. Birrane, et al. Expires September 5, 2018 [Page 20] Internet-Draft ADM March 2018 NOTE: Since a RPTT is identified by a AID, it is possible that a RPTT contains the AID of another RPTT. This signifies that a report has, as one of its entries, another report. This is allowed in the system, but MUST NOT lead to circular references. Description This represents the human-readable description of the Report template, as a string. 7.5.2. Report (RPT) A Report (RPT) is a set of data values populated in conformance to a given RPTT. Each data value in a report is termed a Report Entry (RPTE). 7.5.2.1. Definition RPTs are defined by their associated report template and the report entries themselves, as follows. RPTT AID This is the identifier associated with the structure used to help interpret the Report. A Report may be generated in accordance with a predefined Report Template, in which case the AID MUST be the AID of the RPTT. However, a Report MAY be generated without an RPTT (called an anonymous report) in which case this AID MUST be the AID of the Control that caused the report to be generated. Report Entries) This is the collection of data that comprise the report. These entires MUST consist of a series of data values and MAY additionally contain type information for each entry. RPTEs are represented by a TNV collection. This TNV MUST contain VALUEs and MAY contain NAMES. If the RPTT AID associated with this Report is of type CTRL (in which case this is an anonymous Report) then the TNV MUST contain TYPE information as well. Otherwise, the TNV MAY contain TYPE information. 7.5.3. Processing Managers must: o Store the AID for each ADM-defined Report Template. Birrane, et al. Expires September 5, 2018 [Page 21] Internet-Draft ADM March 2018 o Send requests to Agents to add, list, describe, and remove custom Report Templates. o Remember custom Report Templates when processing Report Entries received by Agents. o Encode Report Template AIDs in Controls to Agents, as appropriate. Agents must: o Store the AID for each ADM-defined Report Template. o Populate Report Entries for transmission to Managers when required by a Control. o Add, remove, list, and describe custom Report Templates. 7.6. Control (CTRL) A Control represents a predefined (possibly parameterized) opcode that can be run on an Agent. Controls in the AMM are always defined in the context of an ADM as there is no concept of an operator- defined Control. Since Controls are pre-configured in Agents and Managers as part of ADM support, their representation is simply the AID that identifies them, similar to EDDs. 7.6.1. Definition Controls are identified by their AID and their description, as follows. AID This is the AID identifying the Control. The AID MUST be of type CTRL. Since Controls are only defined in ADMs, this AID MUST NOT have an Issuer field and MUST NOT have a Tag field. The AID MAY have parameters. When defined in the context of an ADM, the Control AID MUST match the definition of a Formal Parameter list (e.g., there are no VALUES). This is because the ADM defines the Controls that can be invoked, but does not define any particular invocation of a Control. When used as part of network operations, a Control AID MUST match the definition of an Actual Parameter list (e.g., there are VALUES). This is because when used operationally, a parameterized Control required parameters to be run. In cases where a Control takes no parameters, the definition in the ADM document MUST be considered the definition of the Control and the presence of the same AID in the context of an Birrane, et al. Expires September 5, 2018 [Page 22] Internet-Draft ADM March 2018 operational system MUST be seen as an invocation of that Control. Description This represents the human-readable description of the Control, as a string. 7.6.2. Processing Managers must: o Store the AID for each ADM-defined Control definition. o Store the number of parameters and each parameter type for parameterized Controls. o Encode Control AIDs in other Controls to Agents, as appropriate. Agents must: o Store the AID for each ADM-defined Control definition. o Implement Controls in firmware and run Controls with appropriate parameters when necessary in the context of Manager direction and Rule execution. o Communicate "return" values from Controls back to Managers as Report Entries where appropriate. 7.7. Time-Based Rule (TRL) A Time-Based Rule (TRL) specifies that a particular action should be taken by an Agent based on some time interval. A TRL specifies that starting at a particular start time, and for every period seconds thereafter, an action should be run by the Agent until the action has been run for count times. When the TRL is no longer valid it MAY BE discarded by the Agent. Examples of TRLs include: Starting 2 hours from receipt, produce a Report Entry for Report Template R1 every 10 hours ending after 20 times. Starting at the given absolute time, run Macro M1 every 24 hours ending after 365 times. Birrane, et al. Expires September 5, 2018 [Page 23] Internet-Draft ADM March 2018 7.7.1. Definition AID This is the AID identifying the TRL. When a TRL is defined in an ADM this AID MUST NOT have an Issuer field and MUST NOT have a Tag field. When the TRL is defined outside of an ADM, the AID MUST have an Issuer field and MAY have a Tag field. This AID MUST NOT be parameterized. START The time at which the TRL should start to be evaluated. This will mark the first running of the action associated with the TRL. PERIOD The number of seconds to wait between running the action associated with the TRL. COUNT The number of times the TRL action may be run. The special value of 0 indicates the TRL should continue running the action indefinitely. ACTION The collection of Controls and/or Macros to run by the TRL. This is captured as a AC with the constraint that every AID within the AC represent a Control or Macro. Description This represents the human-readable description of the TRL, as a string. 7.7.2. Processing Managers must: o Send requests to Agents to add, list, describe, and remove custom TRL definitions. o Remember custom TRL definitions when processing Reports received by Agents. o Send requests to Agents to suspend/resume the evaluation of TRLs. o Encode TRL AIDs in Controls to Agents, as appropriate. Agents must: Birrane, et al. Expires September 5, 2018 [Page 24] Internet-Draft ADM March 2018 o Run the actions associated with TRLs in accordance with their start time and period. o Add, remove, list, and describe custom TRL definitions. o Suspend and resume the evaluation of a TRL when directed by a Manager or another Rule. o Report on the status of TRLs. 7.8. State-Based Rule (SRL) A State-Based Rule (SRL) specifies that a particular action should be taken by an Agent based on some evaluation of the internal state of the Agent. A SRL specifies that starting at a particular start time an action should be run by the agent if some condition evaluates to true, until the action has been run count times. When the SRL is no longer valid it MAY be discarded by the agent. Examples of SRLs include: Starting 2 hours from receipt, whenever V1 > 10, produce a Report Entry for Report Template R1 no more than 20 times. Starting at some future absolute time, whenever V2 != V4, run Macro M1 no more than 36 times. 7.8.1. Definition AID This is the AID identifying the SRL. When a report is defined in an ADM this AID MUST NOT have an Issuer field and MUST NOT have a Tag field. When the SRL is defined outside of an ADM, the AID MUST have an Issuer field and MAY have a Tag field. This AID MUST NOT be parameterized. START The time at which the SRL condition should start to be evaluated. This will mark the first evaluation of the condition associated with the SRL. CONDITION The Predicate which, if true, results in the SRL running the associated action. COUNT Birrane, et al. Expires September 5, 2018 [Page 25] Internet-Draft ADM March 2018 The number of times the SRL action can be run. The special value of 0 indicates there is no limit on how many times the action can be run. ACTION The collection of Controls and/or Macros to run as part of the action. This is captured as an AC data type with the constraint that every AID within the AC represent a Control or Macro. Description This represents the human-readable description of the SRL, as a string. 7.8.2. Processing Managers must: o Send requests to Agents to add, list, describe, suspend, resume, and remove custom SRL definitions. o Remember custom SRL definitions when processing Report Entries received by Agents. o Encode SRL AIDs in Controls to Agents, as appropriate. Agents must: o Run the actions associated with SRLs in accordance with their start time and evaluation of their predicate. o Add, remove, list, and describe custom SRL definitions. o Suspend and resume SRL evaluation when commanded by a Manager or another Rule. 7.9. Macro (MAC) Macros are ordered collections of AIDs (an AC) that contain Controls or other Macros. When run by an Agent, each AID in the AC is run in order. 7.9.1. Definition A Macro is defined by a AID, a set of Controls, and a description, as follows. AID Birrane, et al. Expires September 5, 2018 [Page 26] Internet-Draft ADM March 2018 This is the AID identifying the Macro. When a Macro is defined in an ADM this AID MUST NOT have an Issuer field and MUST NOT have a Tag field. When the Macro is defined outside of an ADM, the AID MUST have an Issuer field and MAY have a Tag field. This AID MUST NOT be parameterized. Definition This is the ordered collection of AIDs that identify the Controls and other Macros that should be run as part of running this Macro. This is represented by a AC. Description This represents the human-readable description of the MACRO, as a string. 7.9.2. Processing Managers must: o Store the AID for each ADM-defined Macro definition. o Send requests to Agents to add, list, describe, and remove custom Macro definitions. o Encode macro AIDs in Controls to Agents, as appropriate. Agents o Store the AID for each ADM-defined Macro definition. o Remember custom Macro definitions and run Macros when appropriate, such as when responding to a run-Macro Control or when executing the action of a TRL or SRL. o Add, remove, list, and describe custom Macro definitions. 7.10. Constant (CONST) Constants represent named basic values. Examples include common mathematical values such as PI or well-known Epochs such as the UNIX Epoch. Constants are defined solely within the context of ADMs. 7.10.1. Definition A CONST is defined by its AID, value, and description, as follows. AID Birrane, et al. Expires September 5, 2018 [Page 27] Internet-Draft ADM March 2018 The AID MUST have type CONST and MUST NOT have an Issuer field and MUST NOT have a Tag field. AIDs for CONST structures MUST NOT be parameterized. Typed Value The value of a constant is the immutable value that should be used in lieu of the Constant AID when evaluating Expressions and Predicates. The typed value of a CONST is represented by a TNV collection that MUST have 1 element and MUST contain a TYPE and a VALUE and MUST NOT contain a NAME. Description This represents the human-readable description of the CONST, as a string. 7.10.2. Processing Managers must: o Store the AID for each ADM-defined Constant definition. o Encode Constant AIDs in controls to Agents, as appropriate. Agents o Store the AID for each ADM-defined Constant definition. o Calculate the value of Constants where appropriate, such as when generating a Report Entry or when evaluating an Expression. 7.11. Operator (OP) Operators represent user-defined mathematical functions implemented in the firmware of an Agent for the purpose of aiding the evaluation of Expressions and Predicates. The AMM separates the concepts of Operators and Controls to prevent side-effects in Expression and Predicate evaluation (e.g. to avoid constructs such as A = B + GenerateReport()) which is why Operators are given their own structure type and Controls do not support a return value. Because Operators represent custom firmware implemented on the Agent, they are not defined dynamically as part of network operations. Therefore, they may only be defined in the ADM for an application. Birrane, et al. Expires September 5, 2018 [Page 28] Internet-Draft ADM March 2018 7.11.1. Definition An Operator is defined by its AID, its resultant type, the number of operands, the type of operands, and a description, as follows. AID The AID MUST have type OP and MUST NOT have an Issuer or Tag field. The AID MUST NOT be parameterized. Out Type This is the return value of the Operator and MAY be different than the operand types accepted by the Operator. Num Operands This is the number of operands accepted by the operator. For example, the unary NOT Operator ("!") would accept one parameter. The binary PLUS Operator ("+") would accept two parameters. A custom function to calculate the average of the last 10 samples of a data item would accept 10 parameters. In Types This is the type information for each operand accepted by the Operator. This is represented as a TNV Collection that MUST contain TYPE information, MAY contain NAME information and MUST NOT contain value information. There MUST be exactly the same number of elements in the TNV collection as the Num Operands specified for the Operator. Description This represents the human-readable description of the Operator, as a string. 7.11.2. Processing Managers must: o Store the AID for each ADM-defined Operator definition. o Encode Operator AIDs in Controls to Agents, as appropriate. Agents must: o Store the AID for each ADM-defined Operator definition. o Store the number of parameters expected for each Operator. Birrane, et al. Expires September 5, 2018 [Page 29] Internet-Draft ADM March 2018 o Calculate the value of applying an Operator to a given set of parameters, such as when evaluating an Expression. 8. Data Type IDs and Enumerations This section defines identifiers and enumeration values for objects defined in the AMM. Identifiers are the text abbreviations used in ADMs to identify data types. Enumerations associate data types with a numeric value. These enumerations MUST be used whenever a data type is represented as a numerical representation. IDs and enumerations are grouped by the kind of data they represent, as follows. AMM structure identifiers occupy enumerations 0 - 9 and represent data structures that are formally identified by an AID. Basic data types occupy enumerations 10-18 and represent primitive data types. Special types occupy the remaining enumeration space. While the AMM does not specify any encoding of data model elements, a common set of enumerations help to ensure that various encoding standards can interoperate. Structure ID Enumeration Numeric ------------------------------- -------------- ----------- ---------- Externally Defined Data EDD 0 No Variable VAR 1 No Table Template TBLT 2 No Report Template RPTT 3 No Control CTRL 4 No Time-Based Rule TRL 5 No State-Based Rule SRL 6 No Macro MACRO 7 No Constant CONST 8 No Operator OP 9 No Birrane, et al. Expires September 5, 2018 [Page 30] Internet-Draft ADM March 2018 Basic Data Type ID Enumeration Numeric ------------------------------- -------------- ----------- ---------- BYTE BYTE 10 No Signed 32-bit Integer INT 11 Yes Unsigned 32-bit Integer UINT 12 Yes Signed 64-bit Integer VAST 13 Yes Unsigned 64-bit Integer UVAST 14 Yes Single-Precision Floating Point REAL32 15 Yes Double-Precision Floating Point REAL64 16 Yes Character String STR 17 No Boolean BOOL 18 No Compound/Special Data Type ID Enumeration Numeric ------------------------------- -------------- ----------- ---------- Hex String TS 19 No Timestamp TS 20 No Type-Name-Value Collection TNV 21 No Asynchronous Resource Namespace ARN 22 No ADM Identifier AID 23 No AID Collection AC 24 No Expression EXPR 25 No Predicate EXPR 26 No 8.1. Numeric Promotions When attempting to evaluate operators of different types, wherever possible, an Agent MAY need to promote operands until they are of the correct type. For example, if an Operator is given both an INT and a REAL32, the INT SHOULD be promoted to a REAL32 before the Operator is applied. Listing legal promotion rules is mandatory for ensuring that behavior is similar across multiple implementations of Agents and Managers. Birrane, et al. Expires September 5, 2018 [Page 31] Internet-Draft ADM March 2018 The listing of legal promotions in the ADM are listed in Figure 2. In this Figure, operands are listed across the top row and down the first column. The resultant type of the promotion is listed in the table at their intersection. INT UINT VAST UVAST REAL32 REAL64 +--------+--------+--------+--------+--------+--------+ INT | INT | INT | VAST | UNK | REAL32 | REAL64 | UINT | INT | UINT | VAST | UVAST | REAL32 | REAL64 | VAST | VAST | VAST | VAST | VAST | REAL32 | REAL64 | UVAST | UNK | UVAST | VAST | UVAST | REAL32 | REAL64 | REAL32 | REAL32 | REAL32 | REAL32 | REAL32 | REAL32 | REAL64 | REAL64 | REAL64 | REAL64 | REAL64 | REAL64 | REAL64 | REAL64 | +--------+--------+--------+--------+--------+--------+ Figure 2: Numeric Promotions ADMs do not permit promotions between non-numeric types, and numeric promotions not listed in this section are not allowed. Any attempt to perform an illegal promotion SHOULD result in an error. 8.2. Numeric Conversions Variables, Expressions, and Predicates are typed values. When attempting to assign a value of a different type, a numeric conversion must be performed. Any numeric type may be converted to any other numeric type in accordance with the C rules for arithmetic type conversions. 9. AMM Data Model Specification This section is TBD waiting for a final decision on whether we can use YANG separate from NETCONF. 10. ADM JSON Template This section provides an ADM template in the form of a JSON document. It is not required that these JSON encodings be used to encode the transmission of AMM information over the wire in the context of a network deployment. It is also not required that only these JSON encodings be used to document ADMs and other AMM information. Since the AMM is designed to allow for multiple encodings, the expression of ADMs in the provided JSON format is intended support translation to other encodings without loss of information. Birrane, et al. Expires September 5, 2018 [Page 32] Internet-Draft ADM March 2018 10.1. Primitive Type Encoding JSON data types generally support AMM primitive data types. The mapping of AMM primitive types to JSON data types is provided in Table 2. +----------+------------------------+ | AMM Type | JSON Encoding | +----------+------------------------+ | BYTE | number (0 <= # <= 256) | | | | | INT | number | | | | | UINT | number | | | | | VAST | number | | | | | UVAST | number | | | | | REAL32 | number | | | | | REAL64 | number | | | | | STRING | string | | | | | BOOL | boolean | +----------+------------------------+ Table 2: Primitive Type Encoding 10.2. Derived Type Encoding In cases where an AMM derived type is simply a special interpretation of a primitive type, the JSON encoding of the derived type will be the same as the JSON encoding of the primitive type from which it derives. 10.2.1. Hex String In cases where a hexadecimal value must be encoded, the JSON encoding follows the guidelines for hex-string from RFC6991. In this case, the hexadecimal value can be placed in a formatted string and this string used in place of any numeric type with a hexademical representation. A Hex String contents a written representation of a hexadecimal value, without prefix. In this scheme, byte values are separated by colons (:). While either upper or lower case characters are Birrane, et al. Expires September 5, 2018 [Page 33] Internet-Draft ADM March 2018 acceptable, by convention lower-case characters should be used for increased readability. For example, given the hexadecimal value 0x12AB the resultant Hex String would be "12:ab". 10.2.2. Type-Name-Values A TNV is encoded as a JSON object with three element: "type", "name", and "value". For each item in a TNV, there are three acceptable formulations that can be used to represent the item, as illustrated in the following table. For the examples in this table, consider the REAL32 value of PI as 3.14159. +---------------------+---------------------------------------------+ | Desc | Example | +---------------------+---------------------------------------------+ | Full | {"type":"REAL32", "name":"PI", | | | "value":3.14159} | | | | | Named Type | {"type":"REAL32", "name":"PI", | | | "value":null} | | | | | Anonymous Type | {"type":"REAL32", "name":null, | | | "value":null} | | | | | Anonymous Type | {"type":"REAL32", "name":null, | | Value | "value":3.14159} | | | | | Anonymous Value | {"type":null, "name":null, "value":3.14159} | +---------------------+---------------------------------------------+ Table 3: TNV Formulations 10.2.3. Formal Parameters A single parameter is encoded as a single JSON object where the key string is the data type of the parameter and the value is the name of the parameter. The general form of the object will be {parm_type:parm_value}. Birrane, et al. Expires September 5, 2018 [Page 34] Internet-Draft ADM March 2018 +--------------------------------+----------------------------------+ | Desc | Example | +--------------------------------+----------------------------------+ | Single String Parameter | {"STR":"name"} | | | | | Single Unsigned Integer | {"UINT":"name2"} | | Parameter | | | | | | Multiple Parameter | [{"UINT":"name2"}, | | | {"STR":"name"}] | +--------------------------------+----------------------------------+ Table 4: Formal Parameter Encoding 10.2.4. Expression An expression is encoded as a JSON object with two elements: a type and a postfix-expr. The description of these elements is as follows. o Type The data type of the evaluation of the initializer expression. o Postfix-Expr A JSON array of elements where each element is an JSON encoding of an ADM Identifier in conformance to Section 10.3. The following is an example of a JSON encoding of an EXPR object. "type": "UINT", "postfix-expr": ["EDD.item1('0')","EDD.item2('1')","OP.+UINT"] 10.3. ADM Identifier An AID encoding is not needed for the ADM template because all required fields of an AID are already present within ADM objects. Adding an AID field to the ADM needlessly complicates and expands the ADM structure without adding clarity or interoperability. Instead of mandating an AID encoding, the template ensures that relevant information is captured in each ADM data item encoding to support the creation of AIDs when ADM structures are represented in operational network encodings. NOTE: There is some discussion as to whether the inclusion of an AID JSON encoding in the ADM should be included in the model. This remains an area of active discussion. Birrane, et al. Expires September 5, 2018 [Page 35] Internet-Draft ADM March 2018 Absent a formal AID syntax in the ADM template, a shorthand string is used to reference data items defined in an ADM from elsewhere in the same ADM: . In cases where such a reference must include Actual Parameters to completely identify a data item, an optional parameter string MAY be appended to the shorthand reference. Thi optional string encloses a set of comma-separated parameters between a set of parentheses. A parameter may be either a pass-by-value or a pass-by-reference parameter. A pass-by-value parameter is one whose literal value should be used as the parameter value. These parameters are enclosed in single quotes within the parameter string. A pass-by-reference parameter is one whose value is related to some other information provided in the data structure. The manner in which the reference is calculated MUST be documented in the context of the ADM data item using the reference. The optional parameter string format is as follows. ('val_parm_1','val_parm_2',ref_parm_1,... ) +---------------------------------+---------------------------------+ | Desc | Example | +---------------------------------+---------------------------------+ | Externally Defined Data | "EDD.item_name" | | Reference | | | | | | Variable Reference | VAR.var1 | | | | | Value Parameter EDD Reference | EDD.number_pdu('0x4') | | | | | Reference Parameter EDD | EDD.number_pdu(ref_parm) | | Reference | | | | | | Mixed Parameter EDD Reference | EDD.example_item('1', a, '2.0') | +---------------------------------+---------------------------------+ Table 5: Data Item ADM Shorthand 10.4. ADM Structures 10.4.1. Externally Defined Data (EDD) Encoding The EDD JSON object is comprised of four elements: "name", "type", "parmspec", and "description". The description of these elements is as follows. Birrane, et al. Expires September 5, 2018 [Page 36] Internet-Draft ADM March 2018 o Name The identifier of the EDD data item. This MUST be unique across all name elements for EDDs in the ADM. o Type The strong typing of this data value. Types MUST be one of those defined in Section 8. o ParmSpec The optional array of formal parameters encoded in accordance with Section 10.2.3. o Description A string description of the kind of data represented by this data item. The following is an example of a JSON encoding of an EDD object. "name": "num_good_tx_bcb_blks_src", "type": "UINT", "parmspec": [{"STR":"Src"}], "description": "Successfully Tx BCB blocks from SRC" 10.4.2. Variables Encoding The VAR JSON object is comprised of four elements: "name", "type", "initializer", and "description". The description of these elements is as follows. o Name The identifier of the variable data item. This MUST be unique across all name elements for VARs in the ADM. o Type The strong typing of this data value. Types MUST be one of those defined in Section 8. o Initializer The expression used to establish the initial value of the variable. This initializer is an expression encoded in conformance with Section 10.2.4. o Description A string description of the kind of data represented by this data item. The following is an example of a JSON encoding of an VAR object. Birrane, et al. Expires September 5, 2018 [Page 37] Internet-Draft ADM March 2018 "name": "total_bad_tx_blks", "type": "UINT", "initializer": { "type": "UINT", "postfix-expr": ["EDD.item1('0')","EDD.item2('1')","OP.+UINT"] }, "description": "# total items (# item1 + # item2)." 10.4.3. Table Template (TBLT) Encoding The TBLT JSON object is comprised of four elements: "name", "columns", and "description". The description of these elements is as follows. o Name The identifier of the table template data item. This MUST be unique across all name elements for TBLTs in the ADM. o Columns This is a JSON array of elements, with each element representing the definition of the type of information represented in each column. Each column is described using the same encoding as a formal parameter described in Section 10.2.3. o Description A string description of the kind of data represented by this data item. The following is an example of a JSON encoding of an TBLT object. "name":"keys", "columns": [{"STR":"ciphersuite_names"}], "description": "This table lists supported ciphersuites." 10.4.4. Report Template Encoding The RPTT JSON object is comprised of four elements: "name", "parmspec", "definition", and "description". The description of these elements is as follows. o Name The identifier of the report template. This MUST be unique across all name elements for RPTTs in the ADM. o ParmSpec This optional item describes parameters for this report. This is encoded as an array where each element in the array is encoded as a formal parameter in accordance with Section 10.2.3. Birrane, et al. Expires September 5, 2018 [Page 38] Internet-Draft ADM March 2018 o Definition This is an array of data elements that represent the ordered set of information associated with the report. Each element in the array is encoded as a data item shorthand in accordance with Section 10.3. Report item elements MAY use reference parameters in their definition. In those cases, the reference parameters in the definition list MUST match report entry parameter names from the ParmSpec element in the report template definition. o Description A string description of the kind of data represented by this data item. The following is an example of a JSON encoding of an RPTT object. "name": "full_report", "parmspec": [{"STR":"Source"}], "definition" : [ "EDD.data_item1", "EDD.data_item2('1')", "EDD.data_item3(Source)", "EDD.data_item4('1', Source)", ], "description": "A full report." 10.4.5. Controls (CTRL) Encoding The CTRL JSON object is comprised of three elements: "name", "parmspec", and "description". The description of these elements is as follows. o Name The identifier of the control. This MUST be unique across all name elements for CTRLs in the ADM. o ParmSpec This optional item describes parameters for this control. This is encoded as an array where each element in the array is encoded as a formal parameter in accordance with Section 10.2.3. o Description A string description of the kind of data represented by this data item. The following is an example of a JSON encoding of an RPTT object. Birrane, et al. Expires September 5, 2018 [Page 39] Internet-Draft ADM March 2018 "name": "reset_src_cnts", "parmspec": [{"STR":"src"}], "description": "This control resets counts for the given source." 10.4.6. Macro Encoding The MACRO JSON object is comprised of three elements: "name", "definition", and "description". The description of these elements is as follows. o Name The identifier of the macro. This MUST be unique across all name elements for MACROs in the ADM. o Definition This is a JSON array whose elements are shorthand references are in accordance with Section 10.3 and are of the type CTRL or MACRO. o Description A string description of the kind of data represented by this data item. The following is an example of a JSON encoding of an RPTT object. "name": "user_list", "definition": ["CTRL.list_vars","CTRL.list_rptts"], "description": "List user defined data." 10.4.7. Constant (CONST) Encoding The CONST JSON object is comprised of four elements: "name", "type", "value, and "description". The description of these elements is as follows. o Name The identifier of the constant. This MUST be unique across all name elements for CONSTs in the ADM. o Type The strong typing of this data value. Types MUST be one of those defined in Section 8. o Value The value of the constant, expressed in the JSON encoding of the data type. o Description Birrane, et al. Expires September 5, 2018 [Page 40] Internet-Draft ADM March 2018 A string description of the kind of data represented by this data item. The following is an example of a JSON encoding of a CONST object. "name": "PI", "type": "FLOAT", "value": 3.14159, "description": "The value of PI." 10.4.8. Operator (OP) Encoding The OP JSON object is comprised of four elements: "name", "result- type", "in-type", and "description". The description of these elements is as follows. o Name The identifier of the operator. This MUST be unique across all name elements for OPs in the ADM. o Result-Type The numeric result of applying the operator to the series of operands. This must be one of the encodings for Table 1. o In-Type This is an ordered JSON array of operands for the operator. Each operand is a data type encoded in accordance with Table 1. o Description A string description of the kind of data represented by this data item. The following is an example of a JSON encoding of a OP object. "name": "+INT", "result-type": "INT", "in-type": ["INT", "INT"], "description": "Int32 addition" 10.4.9. Exemptions The AMM data model additionally defines data objects for both time- based rules and state-based rules. These rules are associated with dynamic behaviors in the context of a network deployment and, as such, are typically not represented as static constructs in the context of an ADM. Therefore, these data structures are not considered in this ADM template. Birrane, et al. Expires September 5, 2018 [Page 41] Internet-Draft ADM March 2018 11. IANA Considerations TBD. 12. Security Considerations TBD 13. Informative References [I-D.birrane-dtn-ama] Birrane, E., "Asynchronous Management Architecture", draft-birrane-dtn-ama-06 (work in progress), October 2017. [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, . Authors' Addresses Edward J. Birrane Johns Hopkins Applied Physics Laboratory Email: Edward.Birrane@jhuapl.edu Evana DiPietro Johns Hopkins Applied Physics Laboratory Email: Evana.DiPietro@jhuapl.edu David Linko Johns Hopkins Applied Physics Laboratory Email: David.Linko@jhuapl.edu Birrane, et al. Expires September 5, 2018 [Page 42]