[Docs] [txt|pdf|xml|html] [Tracker] [Email] [Diff1] [Diff2] [Nits]

Versions: 00 01

Delay-Tolerant Networking                                     E. Birrane
Internet-Draft                                               E. DiPietro
Intended status: Informational                                  D. Linko
Expires: September 5, 2018      Johns Hopkins Applied Physics Laboratory
                                                           March 4, 2018


                       AMA Application Data Model
                        draft-birrane-dtn-adm-01

Abstract

   This document defines a data model that captures the information
   necessary to manage applications in asynchronously managed networks.
   This model includes a set of common type definitions, data
   structures, and a template for publishing standardized
   representations of elements of the model.

Status of This Memo

   This Internet-Draft is submitted in full conformance with the
   provisions of BCP 78 and BCP 79.

   Internet-Drafts are working documents of the Internet Engineering
   Task Force (IETF).  Note that other groups may also distribute
   working documents as Internet-Drafts.  The list of current Internet-
   Drafts is at https://datatracker.ietf.org/drafts/current/.

   Internet-Drafts are draft documents valid for a maximum of six months
   and may be updated, replaced, or obsoleted by other documents at any
   time.  It is inappropriate to use Internet-Drafts as reference
   material or to cite them other than as "work in progress."

   This Internet-Draft will expire on September 5, 2018.

Copyright Notice

   Copyright (c) 2018 IETF Trust and the persons identified as the
   document authors.  All rights reserved.

   This document is subject to BCP 78 and the IETF Trust's Legal
   Provisions Relating to IETF Documents
   (https://trustee.ietf.org/license-info) in effect on the date of
   publication of this document.  Please review these documents
   carefully, as they describe your rights and restrictions with respect
   to this document.  Code Components extracted from this document must
   include Simplified BSD License text as described in Section 4.e of




Birrane, et al.         Expires September 5, 2018               [Page 1]


Internet-Draft                     ADM                        March 2018


   the Trust Legal Provisions and are provided without warranty as
   described in the Simplified BSD License.

Table of Contents

   1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   3
     1.1.  Purpose . . . . . . . . . . . . . . . . . . . . . . . . .   3
     1.2.  Scope . . . . . . . . . . . . . . . . . . . . . . . . . .   4
   2.  Requirements Language . . . . . . . . . . . . . . . . . . . .   4
   3.  Terminology . . . . . . . . . . . . . . . . . . . . . . . . .   4
   4.  Data Modeling Concept of Operations . . . . . . . . . . . . .   5
   5.  Key Concepts  . . . . . . . . . . . . . . . . . . . . . . . .   6
     5.1.  ADM Namespaces  . . . . . . . . . . . . . . . . . . . . .   6
     5.2.  Item Identification . . . . . . . . . . . . . . . . . . .   7
     5.3.  Parameterization  . . . . . . . . . . . . . . . . . . . .   7
       5.3.1.  Formal Parameters . . . . . . . . . . . . . . . . . .   8
       5.3.2.  Actual Parameters . . . . . . . . . . . . . . . . . .   8
       5.3.3.  Optional Parameters . . . . . . . . . . . . . . . . .   8
   6.  Asynchronous Management Model (AMM) . . . . . . . . . . . . .   9
     6.1.  Type Definitions  . . . . . . . . . . . . . . . . . . . .   9
       6.1.1.  Primitive Types . . . . . . . . . . . . . . . . . . .   9
       6.1.2.  Derived Types . . . . . . . . . . . . . . . . . . . .   9
     6.2.  ADM Identifier (AID)  . . . . . . . . . . . . . . . . . .  11
       6.2.1.  Identifier Meta-Data  . . . . . . . . . . . . . . . .  11
       6.2.2.  Identifier Contents . . . . . . . . . . . . . . . . .  11
       6.2.3.  AID References  . . . . . . . . . . . . . . . . . . .  13
     6.3.  Collections . . . . . . . . . . . . . . . . . . . . . . .  13
       6.3.1.  Type-Name-Value Collection (TC) . . . . . . . . . . .  13
       6.3.2.  AID Collection (AC) . . . . . . . . . . . . . . . . .  13
       6.3.3.  Expression (EXPR) . . . . . . . . . . . . . . . . . .  14
       6.3.4.  Predicate (PRED)  . . . . . . . . . . . . . . . . . .  14
   7.  ADM Structures  . . . . . . . . . . . . . . . . . . . . . . .  14
     7.1.  AMA Overview  . . . . . . . . . . . . . . . . . . . . . .  14
     7.2.  Externally Defined Data (EDD) . . . . . . . . . . . . . .  16
     7.3.  Variables (VAR) . . . . . . . . . . . . . . . . . . . . .  17
     7.4.  Tables  . . . . . . . . . . . . . . . . . . . . . . . . .  18
       7.4.1.  Table Template (TBLT) . . . . . . . . . . . . . . . .  18
       7.4.2.  Table (TBL) . . . . . . . . . . . . . . . . . . . . .  19
     7.5.  Reports . . . . . . . . . . . . . . . . . . . . . . . . .  20
       7.5.1.  Report Template (RPTT)  . . . . . . . . . . . . . . .  20
       7.5.2.  Report (RPT)  . . . . . . . . . . . . . . . . . . . .  21
     7.6.  Control (CTRL)  . . . . . . . . . . . . . . . . . . . . .  22
     7.7.  Time-Based Rule (TRL) . . . . . . . . . . . . . . . . . .  23
     7.8.  State-Based Rule (SRL)  . . . . . . . . . . . . . . . . .  25
     7.9.  Macro (MAC) . . . . . . . . . . . . . . . . . . . . . . .  26
     7.10. Constant (CONST)  . . . . . . . . . . . . . . . . . . . .  27
     7.11. Operator (OP) . . . . . . . . . . . . . . . . . . . . . .  28
   8.  Data Type IDs and Enumerations  . . . . . . . . . . . . . . .  30



Birrane, et al.         Expires September 5, 2018               [Page 2]


Internet-Draft                     ADM                        March 2018


     8.1.  Numeric Promotions  . . . . . . . . . . . . . . . . . . .  31
     8.2.  Numeric Conversions . . . . . . . . . . . . . . . . . . .  32
   9.  AMM Data Model Specification  . . . . . . . . . . . . . . . .  32
   10. ADM JSON Template . . . . . . . . . . . . . . . . . . . . . .  32
     10.1.  Primitive Type Encoding  . . . . . . . . . . . . . . . .  33
     10.2.  Derived Type Encoding  . . . . . . . . . . . . . . . . .  33
       10.2.1.  Hex String . . . . . . . . . . . . . . . . . . . . .  33
       10.2.2.  Type-Name-Values . . . . . . . . . . . . . . . . . .  34
       10.2.3.  Formal Parameters  . . . . . . . . . . . . . . . . .  34
       10.2.4.  Expression . . . . . . . . . . . . . . . . . . . . .  35
     10.3.  ADM Identifier . . . . . . . . . . . . . . . . . . . . .  35
     10.4.  ADM Structures . . . . . . . . . . . . . . . . . . . . .  36
       10.4.1.  Externally Defined Data (EDD) Encoding . . . . . . .  36
       10.4.2.  Variables Encoding . . . . . . . . . . . . . . . . .  37
       10.4.3.  Table Template (TBLT) Encoding . . . . . . . . . . .  38
       10.4.4.  Report Template Encoding . . . . . . . . . . . . . .  38
       10.4.5.  Controls (CTRL) Encoding . . . . . . . . . . . . . .  39
       10.4.6.  Macro Encoding . . . . . . . . . . . . . . . . . . .  40
       10.4.7.  Constant (CONST) Encoding  . . . . . . . . . . . . .  40
       10.4.8.  Operator (OP) Encoding . . . . . . . . . . . . . . .  41
       10.4.9.  Exemptions . . . . . . . . . . . . . . . . . . . . .  41
   11. IANA Considerations . . . . . . . . . . . . . . . . . . . . .  42
   12. Security Considerations . . . . . . . . . . . . . . . . . . .  42
   13. Informative References  . . . . . . . . . . . . . . . . . . .  42
   Authors' Addresses  . . . . . . . . . . . . . . . . . . . . . . .  42

1.  Introduction

   This document defines a data model suitable for managing applications
   in asynchronously managed networks.

1.1.  Purpose

   The Asynchronous Management Architecture [I-D.birrane-dtn-ama]
   documents a concept for open-loop control of applications (and
   protocols) for situations where timely, highly-available connections
   cannot exist amongst managing and and managed nodes in a network.
   While the AMA describes logical roles and responsibilities, it does
   not include the detailed information necessary to produce
   interoperable data models.

   This document defines a generic Asynchronous Management Model (AMM)
   consisting of data types and data structures for managing
   applications in asynchronous networks.  Further, this document
   provides a template for the standard representation of application-
   specific instances of this model called the Application Data Model
   Template (ADM-T).  The AMM and ADM-T, together, provide the mechanism
   for applications to specify how they are to be asynchronously managed



Birrane, et al.         Expires September 5, 2018               [Page 3]


Internet-Draft                     ADM                        March 2018


   in challenged networks.  Individual applications capture their
   unique, static management information in documents compliant with the
   ASDM-T using the types and structures defined by the AMM.  This
   application-specific document is called the Application Data Model
   (ADM).

1.2.  Scope

   The AMM presented in this document does not assume any specific type
   of application or underlying network encoding.  In order to
   communicate model elements between AMA Agents and Managers in a
   network, the model must be encoded for transmission.  Any such
   encoding scheme is outside of the scope of this document.  Generally,
   encoding of the model is a separate concern from the specification of
   data within the model.

   Since different networks may use different encodings for data,
   mandating an encoding format would require incompatible networks to
   encapsulate data in ways that could introduce inefficiency and
   obfuscation.  It is envisioned that different networks would be able
   to encode ASDMs in their native encodings such that translating ASDM
   data from one encoding to the next could be a mechanical action taken
   at network borders.

   Since the specification does not mandate an encoding format, the
   ADM-T must provide enough information to make encoding (and
   translating from one encoding to another) an unambiguous process.
   Therefore, where necessary, this document provides identification,
   enumeration and other schemes that ensure ADMs provide enough
   information to prevent ambiguities caused by different encoding
   schemes.

2.  Requirements Language

   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
   "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
   document are to be interpreted as described in [RFC2119].

3.  Terminology

   Note: The terms "Actor", "Agent", "Externally Defined Data",
   "Variable", "Control", "Literal", "Macro", "Manager", "Operator", and
   "Rule" are used without modification from the definitions provided in
   [AMA].

   Additional terms critical to understanding the ADMT are as follows.





Birrane, et al.         Expires September 5, 2018               [Page 4]


Internet-Draft                     ADM                        March 2018


   o  Application - A software implementation running on an Agent and
      being managed by a manager.  This includes software that
      implements protocol processing on an Agent.

   o  Application Data Model (ADM) - The full set of statically-defined
      data items necessary to manage an application asynchronously.

   o  Application Data Model Template (ADM-T) - A standard format for
      expressing predefined data items for an application.

   o  ADM Item Definition (AID) - A parameterized structure used to
      uniquely identify ADM objects.

   o  Operational Data Model (ODM) - The operational configuration of an
      Agent.  This inludes the union of all ADM information supported by
      the Agent as well as all operational, dynamic configuration
      applied to the Agent by Managers in the network.

   o  Report (RPT) - A collection of Report Entries gathered by one or
      more Agents and provided to one or more Managers.

   o  Report Template (RPT-T) - A named, typed, ordered collection of
      data types that represents the format of a corresponding Report
      Entry.  This is the schema for a Report Entry, generated by a
      Manager and communicated to one or more Agents.

   o  Report Entry (RPT-E) - An ordered series of data values generated
      by an Agent in accordance with a corresponding Report Template.

   o  State-Based Rule (SRL) - A Rule whose action is performed if a
      defined predicate evaluates to true.  SRLs are defined in
      Section 7.8.

   o  Time-Based Rule (TRL) - A Rule whose action is performed at
      regular intervals.  TRLs are defined in Section 7.7.

4.  Data Modeling Concept of Operations

   In order to asynchronously manage an application, in accordance with
   the [I-D.birrane-dtn-ama], an application-specific data model must be
   created containing all pre-defined management information for that
   application.  This model is termed the Application Data Model (ADM)
   and forms the core set of information for that application in
   whichever network it is deployed.  The ADM syntactically conforms to
   the ADM-T and is uses the data structures and types that comprise the
   AMM.





Birrane, et al.         Expires September 5, 2018               [Page 5]


Internet-Draft                     ADM                        March 2018


   The information standardized in the ADM represents static
   configurations and definitions that apply to any deployment of the
   application, regardless of the network in which it is operating.
   Within any given network, Managers supplement the information
   provided by ADMs with dynamic definitions and values.  The
   operational configuration of the network is the union of all
   supported ADMs and all Manager-defined dynamic configurations.  This
   is termed the Operational Data Model (ODM).

   The relationships amongst the AMM, ADM-T, and ADM are illustrated in
   Figure 1.

                          Data Model Relationship


               +---------+               +---------+
               |   AMM   |-------------->|  ADM-T  |
               +----+----+               +----+----+
                    |                         |
                    |              +----------+-------------+
                    V              |          |             |
               +----------+        V          V             V
               | Manager  |    +-------+  +-------+     +-------+
               | Dynamic  |    | ADM 1 |  | ADM 2 | ... | ADM N |
               | Config.  |    +---+---+  +---+---+     +---+---+
               +-----+----+        |          |             |
                    |              |          |             |
                    V              V          V             V
                  +---------------------------------------------+
                  |                     ODM                     |
                  +---------------------------------------------+

                                 Figure 1

5.  Key Concepts

5.1.  ADM Namespaces

   Each ADM must exist within a unique namespace to prevent conflicting
   definitions across multiple ADMs and ambiguous behavior within
   network deployments.  To ensure the uniqueness of ADM namespaces,
   they must be assigned by a moderating organization as part of a
   maintained registry.

   ADM namespaces are not expected to be flat, but hierarchical where
   namespaces that are closer to a root node in the hierarchy are
   considered to have broader scope than namespaces closer to leaf nodes
   in the hierarchy.  A hierarchical taxonomy of namespaces allows



Birrane, et al.         Expires September 5, 2018               [Page 6]


Internet-Draft                     ADM                        March 2018


   grouping ADMs that share a common classificiation at some level in
   the namespace hierarchy.  Also, a hierarchical namespace can preserve
   this grouping in cases where a compact or otherwise binary encoding
   is required.  It should be noted that there is no requirement for the
   namespace hierarchy to be represented as a tree structure; multiple
   root nodes are acceptable and likely to exist.

   In a hierarchical model of namespaces, a particular ADM namespace can
   be identified as the path to that namespace through the hierarchy.
   The expression of that path within an ADM is accomplished by defining
   an ADM Resource Namespace (ARN).  An ARN is a URI with the scheme
   name of "arn" and a scheme-specific part the consists of a colon-
   separated list of namespaces representing the path from some root in
   the namespace hierarchy to the allocated space for the ADM.

   arn:<Broadest-Scoped Namespace>:<Narrowest-Scoped Namespace>

   For example, the DTN community publishes the Bundle Protocol and the
   Bundle Protocol ADM could be assigned the namespace
   arn:Dtn:BundleProtocol.  The ADM for the Interplanetary Overlay
   Network (ION) implementation of a Bundle Protocol Agent could have a
   separate namespace namespace arn:Dtn:Ion:BundleProtocolAdmin.

5.2.  Item Identification

   Every item in an ADM must be uniquely identifiable both within the
   context of the ADM itself and in the context of any network deploying
   other ADMs and dynamic content.  There are two types of information
   which, together, uniquely identify a data item within the AMM:
   identifier meta-data and identifier contents.

5.3.  Parameterization

   Parameterization is used pervasively in the AMM to enable expressive
   autonomous function and reduce the amount of traffic that would
   otherwise need to be communicated between Managers and Agents.  In
   this model, several types of data items can be parameterized, to
   include commands, reports, and even individual data definitions.  For
   example, consider the management of a protocol that supports three
   data priorities (low, medium, and high).  Rather than defining three
   deparate data items (number_pdus_low, number_pdus_medium, and
   number_pdus_high) the AMM allows for the specification of a parameter
   for this data type, such as number_pdus(bitmask) and supports
   expressions such as number_pdus(low|medium|high).

   Parameters in the AMM are associated with the identifier for a data
   item.  By associating parameters with identifiers makes it possible
   to distinguish between two instances of a parameterized data item.



Birrane, et al.         Expires September 5, 2018               [Page 7]


Internet-Draft                     ADM                        March 2018


   Using the number_pdus data item example, the identifier of the data
   item number_pdus(low) should be distinguishable from the identifier
   of the data item number_pdus(low|medium).  When represented in a data
   item identifier, parameters may specify either "formal parameters" or
   "actual parameters".

5.3.1.  Formal Parameters

   Formal parameters define the type, name, and order of the information
   that customizes a data item.  These parameters represent static
   information (it is not expected that operators add new parameterized
   information outside of what is represented within an ADM) that is
   strongly typed.

   Formal parameters MUST include type and name information and MAY
   include an optional default value.  If specified, a default value
   will be used whenever a set of actual parameters fails to provide a
   value for this formal parameter.

   Using the previous example, the formal parameter specification for
   the number_pdus data item could be represented as number_pdus(UINT
   priority_mask).  Alternatively, a default value could be specified by
   the ADM as well, which would change the definition to
   number_pdus(UINT priority_mask = low).

5.3.2.  Actual Parameters

   Actual parameters define the type, name, and value of the information
   that populates a previously-defined formal parameter set.  Actual
   parameters are used to uniquely identify an instance of a
   parameterized data item.

   An actual parameter MUST specify a value and MAY specify a type.  If
   a type is provided it MUST match the type provided by the formal
   parameter.  An actual parameter MUST NOT include NAME information.

5.3.3.  Optional Parameters

   In cases where a formal parameter contains a default value, the
   associated actual parameter may be omitted.  Default values in formal
   parameters (and, thus, optional actual parameters) are encouraged as
   they reduce the size of data items communicated amongst Managers and
   Agents in a network.








Birrane, et al.         Expires September 5, 2018               [Page 8]


Internet-Draft                     ADM                        March 2018


6.  Asynchronous Management Model (AMM)

6.1.  Type Definitions

   This section describes the custom type definitions used by the AMM.
   Specifying basic type definitions forms the basis for interchangeable
   encodings of ADMs based on this model.

6.1.1.  Primitive Types

   ADMs support a series of primitive types such as bytes, (un)signed
   integers, floating point values, and others as outlined in Table 1.

   +--------------------+----------------------------------------------+
   |        Type        |                 Description                  |
   +--------------------+----------------------------------------------+
   |        BYTE        |             unsigned byte value              |
   |                    |                                              |
   |        INT         |   32-bit signed integer in 2's complement    |
   |                    |                                              |
   |        UINT        |  32-bit unsigned integer in 2's complement   |
   |                    |                                              |
   |        VAST        |   64-bit signed integer in 2's complement    |
   |                    |                                              |
   |       UVAST        |  64-bit unsigned integer in 2's complement   |
   |                    |                                              |
   |       REAL32       |   Single-precision, 32-bit floating point    |
   |                    |          value in IEEE-754 format.           |
   |                    |                                              |
   |       REAL64       |   Double-precision, 64-bit floating point    |
   |                    |          value in IEEE-754 format.           |
   |                    |                                              |
   |       STRING       |   NULL-terminated series of characters in    |
   |                    |                UTF-8 format.                 |
   |                    |                                              |
   |        BOOL        |   A Boolean value of FALSE (whose integer    |
   |                    |  interpretation is 0) or TRUE (which is any  |
   |                    |  integer interpretation that is not FALSE).  |
   +--------------------+----------------------------------------------+

                         Table 1: Primitive Types

6.1.2.  Derived Types

   A derived typed is a primitive type that is interpreted with special
   semantics.  The AMM supports the following derived types.





Birrane, et al.         Expires September 5, 2018               [Page 9]


Internet-Draft                     ADM                        March 2018


6.1.2.1.  Timestamp (TS)

   A Timestamp is a specialization of a UVAST.

   There are two "types" of timestamp within the AMM: a relative
   timestamp and an absolute timestamp.  A relative timestamp is defined
   as the number of seconds between two events (such as the receipt of a
   control by an agent and the execution of that control).  An absolute
   timestamp is defined as UTC time since the Unix/POSIX Epoch.

   Rather than define two separate data types (one for relative
   timestamps and one for absolute timestamps) or adding an extra field
   (e.g., a timestamp type identifier) the type of timestamp can be
   simply and unambiguously inferred from a single timestamp value.  The
   AMM defines a Relative Timestamp Epoch (RTE).  Timestamp values less
   than the RTE will be interpreted as relative timestamps.  Timestamp
   values greater than or equal to the RTE will be interpreted as
   absolute timestamps.  The RTE is defined as September 9th, 2012 (UTC
   time 1347148800).

   For example, a timestamp value of "10" refers to 10 seconds in the
   future.  A timestamp value of "1508554859" refers to Saturday,
   October 21, 2017 3:00:59 AM.

   It should be noted that absolute and relative times are
   interchangeable.  An absolute time can be converted into a relative
   time by subtracting the current time from the absolute time.  A
   relative time can be converted into an absolute time by adding to the
   relative time the current time.  A pseudo-code example of this
   conversion is as follows.

      IF (timestamp < 1347148800) THEN
        absolute_time = current_time + timestamp
      ELSE
        absolute_time = timestamp

6.1.2.2.  Type-Name-Value (TNV)

   A Type-Name-Value (TNV) is a three-tuple of information that decribes
   a data value in the AMM.  Since the length of a data value is a
   matter of encoding, there is not an explicit length field present for
   the data value; it is assumed that any encoding scheme either encodes
   the lenght in some other way or that, generally, data types and data
   structures are self-delimiting.

   o  Type - The strong typing for this value.  Types MUST be one of
      those defined in Section 8.




Birrane, et al.         Expires September 5, 2018              [Page 10]


Internet-Draft                     ADM                        March 2018


   o  Name - A unique identifier for this value.

   o  Value - The value of the data item.

   In ADMs, TNVs are used to capture parameterized items and describe
   the contents of reports.

6.2.  ADM Identifier (AID)

6.2.1.  Identifier Meta-Data

   The meta-data for an identifier provides annotative or otherwise
   user-friendly descriptive information for the identifier (or the item
   being identified).  This information may be used as documentation
   (for example, only present in ADMs and on operator consoles) and/or
   encoded and transmitted over the wire as part of a management
   protocol.

   Meta-data is not required to be unique amongst identifiers.  The
   meta-data supported by the AMM for identifiers is as follows.

   o  Name
      An identifier name is a string associated with the identifier, but
      not the identifier itself.  Names provide human-readable and/or
      user-friendly ways to refer to identifiers that are, otherwise,
      difficult to parse.  In cases where the identifier is considered
      self-evident, an identifier name may be ommitted.

   o  Description
      An identifier description is a string describing the purpose or
      usage of the identified item.  The intent of the description is to
      provide human-readable and user-friendly documentation for the
      item being identified.

6.2.2.  Identifier Contents

   Identifier contents are used to either compute or locate a data item.
   Within the AAM, there are two types of contents: literals and
   references.  A reference is a unique value that can be used to look
   up (reference) a data item.  A literal is a value that can be used to
   directly compute a data item.  An example of a data item that could
   use a literal identifier would be the unsigned integer value 4.

6.2.2.1.  Reference Identifier

   A reference identifier is used when a data item cannot be trivially
   computed as a function of an identifier value.  Examples of data




Birrane, et al.         Expires September 5, 2018              [Page 11]


Internet-Draft                     ADM                        March 2018


   items requiring a reference identifier would be data structures,
   externally defined data items, and variables.

   A reference identifier consists of four parts: (1) The type of item
   being identified, (2) a unique handle for the item, (3) optional
   meta-data related to the issuer of the identifier, and (4) optional
   meta-data related to the item being named.  The description of each
   of these parts is as follows.

   Item Type
   The type of the data item being identified, as defined in Section 8.

   Unique Handle
   The handle is an opaque value that MUST be unique amongst all handles
   within a given ADM.

   Issuer
   The issuer field is any string (including a hex string) representing
   some identification of the organization defining this item.  This
   value may come from a global registry of organizations, an issuing
   node address, a signed known value, or some other network-unique
   marking.
   Issuer information is only necessary when network operators issue new
   data items dynamically in a network.  As such, the issuer field MUST
   be present for any dynamic data items added to a network and MUST NOT
   be present for any static data items defined in the context of an
   ADM.

   Tag
   The tag field is any string (including a hex string) used to
   disambiguate or otherwise validate a reference identifier.
   A tag field is only applicable when network operators issue new data
   items dynamically in a network.  As such, the tag field MUST NOT be
   present unless an Issuer field is also present.  A tag field MUST NOT
   be present for any static data items defined in the context of an
   ADM.
   The contents of the tag field is left to the discretion of the
   issuer.  Examples of potential tag values include an issuer-known
   version number or a (signed) hashing of the data item associated with
   the reference identifier.

6.2.2.2.  Literal Identifier

   A literal identifier is used when a data item can be trivially
   computed as a function of an identifier value.  Examples of data
   items requiring a reference identifier would be numerical values such
   as the unsigned integer 4.




Birrane, et al.         Expires September 5, 2018              [Page 12]


Internet-Draft                     ADM                        March 2018


   A literal identifier consists of three parts: (1) The type of item
   being identified, (2) the data type of the data item, and (3)
   information necessary to compute the data item.  The description of
   each of these parts is as follows.

   Item Type
   The type of a literal identifier MUST be a Literal, as defined in
   Section 8.

   Data Type
   The type of the literal value.  This MUST be one of the primitive
   types as described in Table 1.

   Value
   This is information necessary to directly compute the data item
   value.  For example, using string encodings, the literal value 4
   could be have the string value "4" whereas a binary encoding might
   use the value 0x04.

6.2.3.  AID References

   There are several times when an AID must be referenced within the
   contents of an ADM document and a useful shorthand is defined to
   allow for this expression.  Since an AID name is required to be
   unique for a given data type, the combination of AID type and AID
   name may be used as a reference.

   Specifically, an AID reference is a string with the form
   <type>.<name>.

6.3.  Collections

   Data item definitions, or parameters associated with those
   definitions, may operate on a collection of information.  However,
   where possible, the AMM seeks strong data typing which is not always
   possible when accepting a collection of information.  To provide
   strong type checking, the AMM defines a series of typed collections.

6.3.1.  Type-Name-Value Collection (TC)

   A Type-Name-Value Collection is an ordered array where each element
   of the array is a TNV.

6.3.2.  AID Collection (AC)

   It is often necessary to discuss collections of data items that are
   provided as parameters to other items.  An AID collection is an
   ordered set of AIDs.  For example, an AMA Agent may support a command



Birrane, et al.         Expires September 5, 2018              [Page 13]


Internet-Draft                     ADM                        March 2018


   to remove a set of report definitions.  This command could accept a
   list of report definitions to remove, identified by the AID for each
   report definition.  In such an instance, the list of repot
   definitions to be removed could be modeled as an AC.

6.3.3.  Expression (EXPR)

   Expression apply mathematical operations to values to generate new
   values, typically on computers fulfilling the Agent role within the
   AMA.  Since the variables, operators, and literals that comprise
   these operations are all formal ADM items, they are all identified by
   AIDs.  Because they are all identified by AIDs, the expression is
   represented by an AC.

   An expression (EXPR) is a AC in which a series of items are ordered
   so as to produce a valid post-fix mathematical expression.  For
   example, the infix expression A * (B * C) is represented as the
   sequence A B C * *.

6.3.4.  Predicate (PRED)

   Predicates are Expressions whose values are interpreted as a Boolean.
   The value of zero MUST be considered "false" and all other values
   MUST be considered "true".

7.  ADM Structures

   This section identifies the ADM structures that implement the AMA
   logical data model.

7.1.  AMA Overview

   The AMA defines a series of logical components that should be
   included as part of an ADM.  These components are summarized from the
   AMA in the following table.  The ADM implements these logical
   components in largely a one-to-one fashion with a few exceptions.















Birrane, et al.         Expires September 5, 2018              [Page 14]


Internet-Draft                     ADM                        March 2018


   +------------+-----------------------------------+------------------+
   | AMA        | Summary Description               | ADM Structures   |
   | Component  |                                   |                  |
   +------------+-----------------------------------+------------------+
   | Externally | A typed, measured value whose     | Externally       |
   | Defined    | definition and value              | Defined Data     |
   | Data       | determination occurs externally   |                  |
   |            | from the network management       |                  |
   |            | system.                           |                  |
   |            |                                   |                  |
   | Variable   | A typed, computed value whose     | Variable         |
   |            | definition and value              |                  |
   |            | determination occurs within the   |                  |
   |            | network management system.        |                  |
   |            |                                   |                  |
   | Report     | Collections of Atomic and/or      | Table            |
   | Entry      | Computed data and/or other        | Definition,      |
   |            | Reports.                          | Table, Report    |
   |            |                                   | Definition,      |
   |            |                                   | Report           |
   |            |                                   |                  |
   | Control    | Parameterized opcode for any      | Control          |
   |            | action that can be taken by an    |                  |
   |            | Agent.                            |                  |
   |            |                                   |                  |
   | Rule       | A pre-configured response to a    | State-Based      |
   |            | predefined time or state on an    | Rule, Time-Based |
   |            | Agent.                            | Rule             |
   |            |                                   |                  |
   | Macro      | An ordered collection of          | Macro            |
   |            | Controls.                         |                  |
   |            |                                   |                  |
   | Literal    | A constant used when evaluating   | Literal,         |
   |            | Rules or determining the value of | Constant         |
   |            | Computed Data.                    |                  |
   |            |                                   |                  |
   | Operator   | An opcode representing a          | Operator         |
   |            | mathematical function known to an |                  |
   |            | Agent.                            |                  |
   +------------+-----------------------------------+------------------+

                          AMA Logical Components

   The remainder of this section describes the format of these
   structures in the context of the aforementioned ADM data types.






Birrane, et al.         Expires September 5, 2018              [Page 15]


Internet-Draft                     ADM                        March 2018


7.2.  Externally Defined Data (EDD)

   Externally defined data (EDD) are predefined components of an ADM for
   various applications and protocols.  These represent values that are
   calculated outside of the context of Agents and Managers, such as
   those values measured by firmware.  As such, their value is defined
   external to the ADM system.

7.2.1.  Definition

   An EDD consists of an AID, type, and a description, as follows.

   AID
           EDDs are defined solely in the context of an ADM.  Since they
           are sampled external to the management system, changes or
           additions to EDDs require changes to how the network
           management system interfaces with other components on an
           Agent.
           Because an EDD is defined in the context of an ADM, it MUST
           NOT contain an Issuer or Tag field and the type of the AID
           MUST be the EDD type.

   Type
           This represents the data type of the value associated with
           the EDD.

   Description
           This represents the human-readable description of the EDD, as
           a string.

7.2.2.  Processing

   Managers must:

   o  Store the AID for each known EDD definition.

   o  Associate a data type to each known EDD definition.

   o  Encode EDD AIDs in Controls to Agents, as appropriate.

   Agents must:

   o  Store the AID for each known EDD definition.

   o  Associate a data type to each known EDD definition.

   o  Calculate the value of an EDD definition when required, such as
      when generating a Report Entry or evaluating an Expression.



Birrane, et al.         Expires September 5, 2018              [Page 16]


Internet-Draft                     ADM                        March 2018


7.3.  Variables (VAR)

   Variables (VAR) may be statically defined in an ADM or dynamically by
   Managers in a network deployment.  VARs differ from EDDs in that they
   are completely described by other known data in the system (either
   other VARs or other EDDs).  For example, letting E# be a EDD item and
   V# be a VAR item, the following are examples of VAR definitions.

   V1 = E1 * E2

   V2 = V1 + E3

7.3.1.  Definition

   VARs are defined by an AID, a type, an initializing expression, and a
   description, as follows.

   AID
           The type of this AID MUST be type VAR, and the AID MUST NOT
           contain parameters.

   Type
           This is the type of the VAR, and acts as a static cast for
           the result of the initializing EXPR.  This type MUST be one
           of the data types defined in Table 1.  Note, it is possible
           to specify a type different than the resultant type of the
           initializing EXPR.  For example, if an EXPR adds two single-
           precision floating point numbers, the VAR MAY have an integer
           type associated with it.

   Initializer
           The initial value of the VAR is given by an initializing
           EXPR.  In the case where the type of the VAR itself is EXPR
           the initializer is used as the value of the VAR.  In the case
           where the type of the VAR is anything other than EXPR, then
           the initializer EXPR will be evaluated and the resultant
           value will be used as the initial value of the VAR.

   Description
           This represents the human-readable description of the VAR, as
           a string.

7.3.2.  Processing

   Managers must:

   o  Store the AID for each ADM-defined VAR definition.




Birrane, et al.         Expires September 5, 2018              [Page 17]


Internet-Draft                     ADM                        March 2018


   o  Send requests to Agents to add, list, describe, and remove VAR
      definitions.

   o  Remember custom VAR definitions.

   o  Encode VAR AIDs in Controls to Agents, as appropriate.

   Agents must:

   o  Store the AID for each ADM-defined VAR definition.

   o  Calculate the value of VARs when required, such as during Rule
      evaluation, calculating other VAR values, and generating Reports.

   o  Add, remove, list, and describe custom VAR definitions.

7.4.  Tables

   A Table is a named, typed, collection of tabular data.  Columns
   within a table are named and typed.  Rows within a table capture
   individual data sets with one value in each row corresponding to one
   column in the table.  Tables are represented in two ways in the AMM:
   Table Templates and Table Instances.

7.4.1.  Table Template (TBLT)

   A table template identifies the strongly-typed column template that
   will be followed by any instance of this table available in the
   network.  Table templates appear statically in ADMs and may not be
   created dynamically within the network by Managers.  Changing a table
   template within an asynchronously managed network would result in
   confusion if differing template definitions for the same table
   identifier were to be active in the network at one time.

7.4.1.1.  Definition

   TBLTs are defined by an AID, a set of column descriptions, and table
   metadata, as follows.

   AID
           The type of this AID MUST be type TBLT, and the AID MUST NOT
           contain parameters.  Since Table Template definitions only
           appear in an ADM document, this AID MUST NOT contain an
           Issuer or a Tag field.

   Columns
           A TBLT is completely defined by its ordered set of columns
           descriptions.  Each column description is a name and a type.



Birrane, et al.         Expires September 5, 2018              [Page 18]


Internet-Draft                     ADM                        March 2018


           The type of each column MUST be one of the primitive types
           defined in Table 1.
           A column description is represented as a TNV that MUST
           contain type and name information and MUST NOT contain value
           information.

   Description
           This represents the human-readable description of the TBLT,
           as a string.

7.4.2.  Table (TBL)

   Tables are collections of data that MUST be constructed in accordance
   with an associated Table Template.  Tables MUST NOT appear in the ADM
   for an application; they are only instantiated dynamically as part of
   the operation of a network.

7.4.2.1.  Definition

   TBLs are defined by their Table Template, the number of rows in the
   table, and the associated set of data values for each row.

   Template AID
           This is the AID of the Table Template holding the column
           definitions for this table.  This AID MUST match a known
           Table Template defined in an ADM.

   Number of Rows
           This is the number of rows in the table.  A Table MAY have
           zero rows.

   Rows Information
           Each row in a TBL is represented as the number of data
           elements in the row, followed by the data elements
           themselves.
           The number of data values for each row MUST be equal to the
           number of columns defined for the Table Template.
           The data values for each row are represented by a TNV that
           optionally contains type information and MUST contain value
           information.  Type information MAY be included when necessary
           to verify that elements entered into a table match the type
           expected by a column in the table.

7.4.3.  Processing

   Managers must:

   o  Store the AID for each ADM-defined Table Template definition.



Birrane, et al.         Expires September 5, 2018              [Page 19]


Internet-Draft                     ADM                        March 2018


   o  Request that Agents populate tables according to this template.

   Agents must:

   o  Store the AID for each ADM-defined Table Template definition.

   o  Produce Tables in accordance with Table Template definitions when
      required.

7.5.  Reports

   A Report is a set of non-tabular, potentially nested data items that
   may be predefined in the context of an ADM, or defined dynamically in
   the context of a deployed network.

   Reports are represented in two ways in the AMM: Report Templates and
   Reports.  A Report Template defines the type of information to be
   included in a report, and a Report contains that information.

7.5.1.  Report Template (RPTT)

   A Report Template (RPTT) is the ordered set of data descriptions that
   describe how values will be represented in a corresponding Report.
   RPTTs can be viewed as a schema that describes how to interpret a
   Report; they contain no values and are either defined in an ADM or
   configured between Managers and Agents during network operations.

7.5.1.1.  Definition

   RPTTs are defined by an AID, the set of information comprising the
   report, and a description, as follows.

   AID
           The type of this AID MUST be type RPTT.  If the RPTT is
           defined in an ADM it MUST NOT contain an Issuer or Tag field.
           If the RPTT is defined outside of an ADM it MUST contain an
           Issuer field and MAY contain a Tag field.
           An RPTT AID MAY be parameterized.  If the RPTT AID is
           parameterized, the parameters MUST be used (in the same
           number and order) to customize any parameterized data in any
           Report generated using this template.

   Entries
           The list of ordered data items to be included in the report
           is represented by the list of identifiers for those items.
           Since every structure in the ADM can be identified by a AID,
           this value is represented by an AC.




Birrane, et al.         Expires September 5, 2018              [Page 20]


Internet-Draft                     ADM                        March 2018


           NOTE: Since a RPTT is identified by a AID, it is possible
           that a RPTT contains the AID of another RPTT.  This signifies
           that a report has, as one of its entries, another report.
           This is allowed in the system, but MUST NOT lead to circular
           references.

   Description
           This represents the human-readable description of the Report
           template, as a string.

7.5.2.  Report (RPT)

   A Report (RPT) is a set of data values populated in conformance to a
   given RPTT.  Each data value in a report is termed a Report Entry
   (RPTE).

7.5.2.1.  Definition

   RPTs are defined by their associated report template and the report
   entries themselves, as follows.

   RPTT AID
           This is the identifier associated with the structure used to
           help interpret the Report.  A Report may be generated in
           accordance with a predefined Report Template, in which case
           the AID MUST be the AID of the RPTT.  However, a Report MAY
           be generated without an RPTT (called an anonymous report) in
           which case this AID MUST be the AID of the Control that
           caused the report to be generated.

   Report Entries)
           This is the collection of data that comprise the report.
           These entires MUST consist of a series of data values and MAY
           additionally contain type information for each entry.
           RPTEs are represented by a TNV collection.  This TNV MUST
           contain VALUEs and MAY contain NAMES.  If the RPTT AID
           associated with this Report is of type CTRL (in which case
           this is an anonymous Report) then the TNV MUST contain TYPE
           information as well.  Otherwise, the TNV MAY contain TYPE
           information.

7.5.3.  Processing

   Managers must:

   o  Store the AID for each ADM-defined Report Template.





Birrane, et al.         Expires September 5, 2018              [Page 21]


Internet-Draft                     ADM                        March 2018


   o  Send requests to Agents to add, list, describe, and remove custom
      Report Templates.

   o  Remember custom Report Templates when processing Report Entries
      received by Agents.

   o  Encode Report Template AIDs in Controls to Agents, as appropriate.

   Agents must:

   o  Store the AID for each ADM-defined Report Template.

   o  Populate Report Entries for transmission to Managers when required
      by a Control.

   o  Add, remove, list, and describe custom Report Templates.

7.6.  Control (CTRL)

   A Control represents a predefined (possibly parameterized) opcode
   that can be run on an Agent.  Controls in the AMM are always defined
   in the context of an ADM as there is no concept of an operator-
   defined Control.  Since Controls are pre-configured in Agents and
   Managers as part of ADM support, their representation is simply the
   AID that identifies them, similar to EDDs.

7.6.1.  Definition

   Controls are identified by their AID and their description, as
   follows.

   AID
           This is the AID identifying the Control.  The AID MUST be of
           type CTRL.  Since Controls are only defined in ADMs, this AID
           MUST NOT have an Issuer field and MUST NOT have a Tag field.
           The AID MAY have parameters.
           When defined in the context of an ADM, the Control AID MUST
           match the definition of a Formal Parameter list (e.g., there
           are no VALUES).  This is because the ADM defines the Controls
           that can be invoked, but does not define any particular
           invocation of a Control.
           When used as part of network operations, a Control AID MUST
           match the definition of an Actual Parameter list (e.g., there
           are VALUES).  This is because when used operationally, a
           parameterized Control required parameters to be run.
           In cases where a Control takes no parameters, the definition
           in the ADM document MUST be considered the definition of the
           Control and the presence of the same AID in the context of an



Birrane, et al.         Expires September 5, 2018              [Page 22]


Internet-Draft                     ADM                        March 2018


           operational system MUST be seen as an invocation of that
           Control.

   Description
           This represents the human-readable description of the
           Control, as a string.

7.6.2.  Processing

   Managers must:

   o  Store the AID for each ADM-defined Control definition.

   o  Store the number of parameters and each parameter type for
      parameterized Controls.

   o  Encode Control AIDs in other Controls to Agents, as appropriate.

   Agents must:

   o  Store the AID for each ADM-defined Control definition.

   o  Implement Controls in firmware and run Controls with appropriate
      parameters when necessary in the context of Manager direction and
      Rule execution.

   o  Communicate "return" values from Controls back to Managers as
      Report Entries where appropriate.

7.7.  Time-Based Rule (TRL)

   A Time-Based Rule (TRL) specifies that a particular action should be
   taken by an Agent based on some time interval.  A TRL specifies that
   starting at a particular start time, and for every period seconds
   thereafter, an action should be run by the Agent until the action has
   been run for count times.  When the TRL is no longer valid it MAY BE
   discarded by the Agent.

   Examples of TRLs include:

      Starting 2 hours from receipt, produce a Report Entry for Report
      Template R1 every 10 hours ending after 20 times.

      Starting at the given absolute time, run Macro M1 every 24 hours
      ending after 365 times.






Birrane, et al.         Expires September 5, 2018              [Page 23]


Internet-Draft                     ADM                        March 2018


7.7.1.  Definition

   AID
           This is the AID identifying the TRL.  When a TRL is defined
           in an ADM this AID MUST NOT have an Issuer field and MUST NOT
           have a Tag field.  When the TRL is defined outside of an ADM,
           the AID MUST have an Issuer field and MAY have a Tag field.
           This AID MUST NOT be parameterized.

   START
           The time at which the TRL should start to be evaluated.  This
           will mark the first running of the action associated with the
           TRL.

   PERIOD
           The number of seconds to wait between running the action
           associated with the TRL.

   COUNT
           The number of times the TRL action may be run.  The special
           value of 0 indicates the TRL should continue running the
           action indefinitely.

   ACTION
           The collection of Controls and/or Macros to run by the TRL.
           This is captured as a AC with the constraint that every AID
           within the AC represent a Control or Macro.

   Description
           This represents the human-readable description of the TRL, as
           a string.

7.7.2.  Processing

   Managers must:

   o  Send requests to Agents to add, list, describe, and remove custom
      TRL definitions.

   o  Remember custom TRL definitions when processing Reports received
      by Agents.

   o  Send requests to Agents to suspend/resume the evaluation of TRLs.

   o  Encode TRL AIDs in Controls to Agents, as appropriate.

   Agents must:




Birrane, et al.         Expires September 5, 2018              [Page 24]


Internet-Draft                     ADM                        March 2018


   o  Run the actions associated with TRLs in accordance with their
      start time and period.

   o  Add, remove, list, and describe custom TRL definitions.

   o  Suspend and resume the evaluation of a TRL when directed by a
      Manager or another Rule.

   o  Report on the status of TRLs.

7.8.  State-Based Rule (SRL)

   A State-Based Rule (SRL) specifies that a particular action should be
   taken by an Agent based on some evaluation of the internal state of
   the Agent.  A SRL specifies that starting at a particular start time
   an action should be run by the agent if some condition evaluates to
   true, until the action has been run count times.  When the SRL is no
   longer valid it MAY be discarded by the agent.

   Examples of SRLs include:

      Starting 2 hours from receipt, whenever V1 > 10, produce a Report
      Entry for Report Template R1 no more than 20 times.

      Starting at some future absolute time, whenever V2 != V4, run
      Macro M1 no more than 36 times.

7.8.1.  Definition

   AID
           This is the AID identifying the SRL.  When a report is
           defined in an ADM this AID MUST NOT have an Issuer field and
           MUST NOT have a Tag field.  When the SRL is defined outside
           of an ADM, the AID MUST have an Issuer field and MAY have a
           Tag field.  This AID MUST NOT be parameterized.

   START
           The time at which the SRL condition should start to be
           evaluated.  This will mark the first evaluation of the
           condition associated with the SRL.

   CONDITION
           The Predicate which, if true, results in the SRL running the
           associated action.

   COUNT





Birrane, et al.         Expires September 5, 2018              [Page 25]


Internet-Draft                     ADM                        March 2018


           The number of times the SRL action can be run.  The special
           value of 0 indicates there is no limit on how many times the
           action can be run.

   ACTION
           The collection of Controls and/or Macros to run as part of
           the action.  This is captured as an AC data type with the
           constraint that every AID within the AC represent a Control
           or Macro.

   Description
           This represents the human-readable description of the SRL, as
           a string.

7.8.2.  Processing

   Managers must:

   o  Send requests to Agents to add, list, describe, suspend, resume,
      and remove custom SRL definitions.

   o  Remember custom SRL definitions when processing Report Entries
      received by Agents.

   o  Encode SRL AIDs in Controls to Agents, as appropriate.

   Agents must:

   o  Run the actions associated with SRLs in accordance with their
      start time and evaluation of their predicate.

   o  Add, remove, list, and describe custom SRL definitions.

   o  Suspend and resume SRL evaluation when commanded by a Manager or
      another Rule.

7.9.  Macro (MAC)

   Macros are ordered collections of AIDs (an AC) that contain Controls
   or other Macros.  When run by an Agent, each AID in the AC is run in
   order.

7.9.1.  Definition

   A Macro is defined by a AID, a set of Controls, and a description, as
   follows.

   AID



Birrane, et al.         Expires September 5, 2018              [Page 26]


Internet-Draft                     ADM                        March 2018


           This is the AID identifying the Macro.  When a Macro is
           defined in an ADM this AID MUST NOT have an Issuer field and
           MUST NOT have a Tag field.  When the Macro is defined outside
           of an ADM, the AID MUST have an Issuer field and MAY have a
           Tag field.  This AID MUST NOT be parameterized.

   Definition
           This is the ordered collection of AIDs that identify the
           Controls and other Macros that should be run as part of
           running this Macro.  This is represented by a AC.

   Description
           This represents the human-readable description of the MACRO,
           as a string.

7.9.2.  Processing

   Managers must:

   o  Store the AID for each ADM-defined Macro definition.

   o  Send requests to Agents to add, list, describe, and remove custom
      Macro definitions.

   o  Encode macro AIDs in Controls to Agents, as appropriate.

   Agents

   o  Store the AID for each ADM-defined Macro definition.

   o  Remember custom Macro definitions and run Macros when appropriate,
      such as when responding to a run-Macro Control or when executing
      the action of a TRL or SRL.

   o  Add, remove, list, and describe custom Macro definitions.

7.10.  Constant (CONST)

   Constants represent named basic values.  Examples include common
   mathematical values such as PI or well-known Epochs such as the UNIX
   Epoch.  Constants are defined solely within the context of ADMs.

7.10.1.  Definition

   A CONST is defined by its AID, value, and description, as follows.

   AID




Birrane, et al.         Expires September 5, 2018              [Page 27]


Internet-Draft                     ADM                        March 2018


           The AID MUST have type CONST and MUST NOT have an Issuer
           field and MUST NOT have a Tag field.  AIDs for CONST
           structures MUST NOT be parameterized.

   Typed Value
           The value of a constant is the immutable value that should be
           used in lieu of the Constant AID when evaluating Expressions
           and Predicates.
           The typed value of a CONST is represented by a TNV collection
           that MUST have 1 element and MUST contain a TYPE and a VALUE
           and MUST NOT contain a NAME.

   Description
           This represents the human-readable description of the CONST,
           as a string.

7.10.2.  Processing

   Managers must:

   o  Store the AID for each ADM-defined Constant definition.

   o  Encode Constant AIDs in controls to Agents, as appropriate.

   Agents

   o  Store the AID for each ADM-defined Constant definition.

   o  Calculate the value of Constants where appropriate, such as when
      generating a Report Entry or when evaluating an Expression.

7.11.  Operator (OP)

   Operators represent user-defined mathematical functions implemented
   in the firmware of an Agent for the purpose of aiding the evaluation
   of Expressions and Predicates.  The AMM separates the concepts of
   Operators and Controls to prevent side-effects in Expression and
   Predicate evaluation (e.g. to avoid constructs such as A = B +
   GenerateReport()) which is why Operators are given their own
   structure type and Controls do not support a return value.

   Because Operators represent custom firmware implemented on the Agent,
   they are not defined dynamically as part of network operations.
   Therefore, they may only be defined in the ADM for an application.







Birrane, et al.         Expires September 5, 2018              [Page 28]


Internet-Draft                     ADM                        March 2018


7.11.1.  Definition

   An Operator is defined by its AID, its resultant type, the number of
   operands, the type of operands, and a description, as follows.

   AID
           The AID MUST have type OP and MUST NOT have an Issuer or Tag
           field.  The AID MUST NOT be parameterized.

   Out Type
           This is the return value of the Operator and MAY be different
           than the operand types accepted by the Operator.

   Num Operands
           This is the number of operands accepted by the operator.  For
           example, the unary NOT Operator ("!") would accept one
           parameter.  The binary PLUS Operator ("+") would accept two
           parameters.  A custom function to calculate the average of
           the last 10 samples of a data item would accept 10
           parameters.

   In Types
           This is the type information for each operand accepted by the
           Operator.  This is represented as a TNV Collection that MUST
           contain TYPE information, MAY contain NAME information and
           MUST NOT contain value information.  There MUST be exactly
           the same number of elements in the TNV collection as the Num
           Operands specified for the Operator.

   Description
           This represents the human-readable description of the
           Operator, as a string.

7.11.2.  Processing

   Managers must:

   o  Store the AID for each ADM-defined Operator definition.

   o  Encode Operator AIDs in Controls to Agents, as appropriate.

   Agents must:

   o  Store the AID for each ADM-defined Operator definition.

   o  Store the number of parameters expected for each Operator.





Birrane, et al.         Expires September 5, 2018              [Page 29]


Internet-Draft                     ADM                        March 2018


   o  Calculate the value of applying an Operator to a given set of
      parameters, such as when evaluating an Expression.

8.  Data Type IDs and Enumerations

   This section defines identifiers and enumeration values for objects
   defined in the AMM.  Identifiers are the text abbreviations used in
   ADMs to identify data types.  Enumerations associate data types with
   a numeric value.  These enumerations MUST be used whenever a data
   type is represented as a numerical representation.

   IDs and enumerations are grouped by the kind of data they represent,
   as follows.  AMM structure identifiers occupy enumerations 0 - 9 and
   represent data structures that are formally identified by an AID.
   Basic data types occupy enumerations 10-18 and represent primitive
   data types.  Special types occupy the remaining enumeration space.

   While the AMM does not specify any encoding of data model elements, a
   common set of enumerations help to ensure that various encoding
   standards can interoperate.

   Structure                       ID             Enumeration Numeric
   ------------------------------- -------------- ----------- ----------
   Externally Defined Data         EDD            0           No

   Variable                        VAR            1           No

   Table Template                  TBLT           2           No

   Report Template                 RPTT           3           No

   Control                         CTRL           4           No

   Time-Based Rule                 TRL            5           No

   State-Based Rule                SRL            6           No

   Macro                           MACRO          7           No

   Constant                        CONST          8           No

   Operator                        OP             9           No









Birrane, et al.         Expires September 5, 2018              [Page 30]


Internet-Draft                     ADM                        March 2018


   Basic Data Type                 ID             Enumeration Numeric
   ------------------------------- -------------- ----------- ----------
   BYTE                            BYTE           10          No

   Signed 32-bit Integer           INT            11          Yes

   Unsigned 32-bit Integer         UINT           12          Yes

   Signed 64-bit Integer           VAST           13          Yes

   Unsigned 64-bit Integer         UVAST          14          Yes

   Single-Precision Floating Point REAL32         15          Yes

   Double-Precision Floating Point REAL64         16          Yes

   Character String                STR            17          No

   Boolean                         BOOL           18          No

   Compound/Special Data Type      ID             Enumeration Numeric
   ------------------------------- -------------- ----------- ----------
   Hex String                      TS             19          No

   Timestamp                       TS             20          No

   Type-Name-Value Collection      TNV            21          No

   Asynchronous Resource Namespace ARN            22          No

   ADM Identifier                  AID            23          No

   AID Collection                  AC             24          No

   Expression                      EXPR           25          No

   Predicate                       EXPR           26          No

8.1.  Numeric Promotions

   When attempting to evaluate operators of different types, wherever
   possible, an Agent MAY need to promote operands until they are of the
   correct type.  For example, if an Operator is given both an INT and a
   REAL32, the INT SHOULD be promoted to a REAL32 before the Operator is
   applied.

   Listing legal promotion rules is mandatory for ensuring that behavior
   is similar across multiple implementations of Agents and Managers.



Birrane, et al.         Expires September 5, 2018              [Page 31]


Internet-Draft                     ADM                        March 2018


   The listing of legal promotions in the ADM are listed in Figure 2.
   In this Figure, operands are listed across the top row and down the
   first column.  The resultant type of the promotion is listed in the
   table at their intersection.


                 INT     UINT     VAST     UVAST     REAL32   REAL64
               +--------+--------+--------+--------+--------+--------+
        INT    | INT    | INT    | VAST   | UNK    | REAL32 | REAL64 |
        UINT   | INT    | UINT   | VAST   | UVAST  | REAL32 | REAL64 |
        VAST   | VAST   | VAST   | VAST   | VAST   | REAL32 | REAL64 |
        UVAST  | UNK    | UVAST  | VAST   | UVAST  | REAL32 | REAL64 |
        REAL32 | REAL32 | REAL32 | REAL32 | REAL32 | REAL32 | REAL64 |
        REAL64 | REAL64 | REAL64 | REAL64 | REAL64 | REAL64 | REAL64 |
               +--------+--------+--------+--------+--------+--------+


                       Figure 2: Numeric Promotions

   ADMs do not permit promotions between non-numeric types, and numeric
   promotions not listed in this section are not allowed.  Any attempt
   to perform an illegal promotion SHOULD result in an error.

8.2.  Numeric Conversions

   Variables, Expressions, and Predicates are typed values.  When
   attempting to assign a value of a different type, a numeric
   conversion must be performed.  Any numeric type may be converted to
   any other numeric type in accordance with the C rules for arithmetic
   type conversions.

9.  AMM Data Model Specification

   This section is TBD waiting for a final decision on whether we can
   use YANG separate from NETCONF.

10.  ADM JSON Template

   This section provides an ADM template in the form of a JSON document.
   It is not required that these JSON encodings be used to encode the
   transmission of AMM information over the wire in the context of a
   network deployment.  It is also not required that only these JSON
   encodings be used to document ADMs and other AMM information.  Since
   the AMM is designed to allow for multiple encodings, the expression
   of ADMs in the provided JSON format is intended support translation
   to other encodings without loss of information.





Birrane, et al.         Expires September 5, 2018              [Page 32]


Internet-Draft                     ADM                        March 2018


10.1.  Primitive Type Encoding

   JSON data types generally support AMM primitive data types.  The
   mapping of AMM primitive types to JSON data types is provided in
   Table 2.

                   +----------+------------------------+
                   | AMM Type |     JSON Encoding      |
                   +----------+------------------------+
                   |   BYTE   | number (0 <= # <= 256) |
                   |          |                        |
                   |   INT    |         number         |
                   |          |                        |
                   |   UINT   |         number         |
                   |          |                        |
                   |   VAST   |         number         |
                   |          |                        |
                   |  UVAST   |         number         |
                   |          |                        |
                   |  REAL32  |         number         |
                   |          |                        |
                   |  REAL64  |         number         |
                   |          |                        |
                   |  STRING  |         string         |
                   |          |                        |
                   |   BOOL   |        boolean         |
                   +----------+------------------------+

                     Table 2: Primitive Type Encoding

10.2.  Derived Type Encoding

   In cases where an AMM derived type is simply a special interpretation
   of a primitive type, the JSON encoding of the derived type will be
   the same as the JSON encoding of the primitive type from which it
   derives.

10.2.1.  Hex String

   In cases where a hexadecimal value must be encoded, the JSON encoding
   follows the guidelines for hex-string from RFC6991.  In this case,
   the hexadecimal value can be placed in a formatted string and this
   string used in place of any numeric type with a hexademical
   representation.

   A Hex String contents a written representation of a hexadecimal
   value, without prefix.  In this scheme, byte values are separated by
   colons (:).  While either upper or lower case characters are



Birrane, et al.         Expires September 5, 2018              [Page 33]


Internet-Draft                     ADM                        March 2018


   acceptable, by convention lower-case characters should be used for
   increased readability.

   For example, given the hexadecimal value 0x12AB the resultant Hex
   String would be "12:ab".

10.2.2.  Type-Name-Values

   A TNV is encoded as a JSON object with three element: "type", "name",
   and "value".  For each item in a TNV, there are three acceptable
   formulations that can be used to represent the item, as illustrated
   in the following table.  For the examples in this table, consider the
   REAL32 value of PI as 3.14159.

   +---------------------+---------------------------------------------+
   |         Desc        |                   Example                   |
   +---------------------+---------------------------------------------+
   |         Full        |        {"type":"REAL32", "name":"PI",       |
   |                     |               "value":3.14159}              |
   |                     |                                             |
   |      Named Type     |        {"type":"REAL32", "name":"PI",       |
   |                     |                "value":null}                |
   |                     |                                             |
   |    Anonymous Type   |        {"type":"REAL32", "name":null,       |
   |                     |                "value":null}                |
   |                     |                                             |
   |    Anonymous Type   |        {"type":"REAL32", "name":null,       |
   |        Value        |               "value":3.14159}              |
   |                     |                                             |
   |   Anonymous Value   | {"type":null, "name":null, "value":3.14159} |
   +---------------------+---------------------------------------------+

                         Table 3: TNV Formulations

10.2.3.  Formal Parameters

   A single parameter is encoded as a single JSON object where the key
   string is the data type of the parameter and the value is the name of
   the parameter.  The general form of the object will be
   {parm_type:parm_value}.











Birrane, et al.         Expires September 5, 2018              [Page 34]


Internet-Draft                     ADM                        March 2018


   +--------------------------------+----------------------------------+
   |              Desc              |             Example              |
   +--------------------------------+----------------------------------+
   |    Single String Parameter     |          {"STR":"name"}          |
   |                                |                                  |
   |    Single Unsigned Integer     |         {"UINT":"name2"}         |
   |           Parameter            |                                  |
   |                                |                                  |
   |       Multiple Parameter       |        [{"UINT":"name2"},        |
   |                                |         {"STR":"name"}]          |
   +--------------------------------+----------------------------------+

                    Table 4: Formal Parameter Encoding

10.2.4.  Expression

   An expression is encoded as a JSON object with two elements: a type
   and a postfix-expr.  The description of these elements is as follows.

   o  Type
      The data type of the evaluation of the initializer expression.

   o  Postfix-Expr
      A JSON array of elements where each element is an JSON encoding of
      an ADM Identifier in conformance to Section 10.3.

   The following is an example of a JSON encoding of an EXPR object.

   "type": "UINT",
   "postfix-expr": ["EDD.item1('0')","EDD.item2('1')","OP.+UINT"]

10.3.  ADM Identifier

   An AID encoding is not needed for the ADM template because all
   required fields of an AID are already present within ADM objects.
   Adding an AID field to the ADM needlessly complicates and expands the
   ADM structure without adding clarity or interoperability.  Instead of
   mandating an AID encoding, the template ensures that relevant
   information is captured in each ADM data item encoding to support the
   creation of AIDs when ADM structures are represented in operational
   network encodings.

   NOTE: There is some discussion as to whether the inclusion of an AID
   JSON encoding in the ADM should be included in the model.  This
   remains an area of active discussion.






Birrane, et al.         Expires September 5, 2018              [Page 35]


Internet-Draft                     ADM                        March 2018


   Absent a formal AID syntax in the ADM template, a shorthand string is
   used to reference data items defined in an ADM from elsewhere in the
   same ADM:

   <Adm Structure Type>.<Data Item Name>

   In cases where such a reference must include Actual Parameters to
   completely identify a data item, an optional parameter string MAY be
   appended to the shorthand reference.  Thi optional string encloses a
   set of comma-separated parameters between a set of parentheses.  A
   parameter may be either a pass-by-value or a pass-by-reference
   parameter.  A pass-by-value parameter is one whose literal value
   should be used as the parameter value.  These parameters are enclosed
   in single quotes within the parameter string.  A pass-by-reference
   parameter is one whose value is related to some other information
   provided in the data structure.  The manner in which the reference is
   calculated MUST be documented in the context of the ADM data item
   using the reference.  The optional parameter string format is as
   follows.

   ('val_parm_1','val_parm_2',ref_parm_1,... )

   +---------------------------------+---------------------------------+
   |               Desc              |             Example             |
   +---------------------------------+---------------------------------+
   |     Externally Defined Data     |         "EDD.item_name"         |
   |            Reference            |                                 |
   |                                 |                                 |
   |        Variable Reference       |             VAR.var1            |
   |                                 |                                 |
   |  Value Parameter EDD Reference  |      EDD.number_pdu('0x4')      |
   |                                 |                                 |
   |     Reference Parameter EDD     |     EDD.number_pdu(ref_parm)    |
   |            Reference            |                                 |
   |                                 |                                 |
   |  Mixed Parameter EDD Reference  | EDD.example_item('1', a, '2.0') |
   +---------------------------------+---------------------------------+

                     Table 5: Data Item ADM Shorthand

10.4.  ADM Structures

10.4.1.  Externally Defined Data (EDD) Encoding

   The EDD JSON object is comprised of four elements: "name", "type",
   "parmspec", and "description".  The description of these elements is
   as follows.




Birrane, et al.         Expires September 5, 2018              [Page 36]


Internet-Draft                     ADM                        March 2018


   o  Name
      The identifier of the EDD data item.  This MUST be unique across
      all name elements for EDDs in the ADM.

   o  Type
      The strong typing of this data value.  Types MUST be one of those
      defined in Section 8.

   o  ParmSpec
      The optional array of formal parameters encoded in accordance with
      Section 10.2.3.

   o  Description
      A string description of the kind of data represented by this data
      item.

   The following is an example of a JSON encoding of an EDD object.

      "name": "num_good_tx_bcb_blks_src",
      "type": "UINT",
      "parmspec": [{"STR":"Src"}],
      "description": "Successfully Tx BCB blocks from SRC"

10.4.2.  Variables Encoding

   The VAR JSON object is comprised of four elements: "name", "type",
   "initializer", and "description".  The description of these elements
   is as follows.

   o  Name
      The identifier of the variable data item.  This MUST be unique
      across all name elements for VARs in the ADM.

   o  Type
      The strong typing of this data value.  Types MUST be one of those
      defined in Section 8.

   o  Initializer
      The expression used to establish the initial value of the
      variable.  This initializer is an expression encoded in
      conformance with Section 10.2.4.

   o  Description
      A string description of the kind of data represented by this data
      item.

   The following is an example of a JSON encoding of an VAR object.




Birrane, et al.         Expires September 5, 2018              [Page 37]


Internet-Draft                     ADM                        March 2018


      "name": "total_bad_tx_blks",
      "type": "UINT",
      "initializer": {
        "type": "UINT",
        "postfix-expr": ["EDD.item1('0')","EDD.item2('1')","OP.+UINT"]
      },
      "description": "# total items (# item1 + # item2)."

10.4.3.  Table Template (TBLT) Encoding

   The TBLT JSON object is comprised of four elements: "name",
   "columns", and "description".  The description of these elements is
   as follows.

   o  Name
      The identifier of the table template data item.  This MUST be
      unique across all name elements for TBLTs in the ADM.

   o  Columns
      This is a JSON array of elements, with each element representing
      the definition of the type of information represented in each
      column.  Each column is described using the same encoding as a
      formal parameter described in Section 10.2.3.

   o  Description
      A string description of the kind of data represented by this data
      item.

   The following is an example of a JSON encoding of an TBLT object.

      "name":"keys",
      "columns": [{"STR":"ciphersuite_names"}],
      "description": "This table lists supported ciphersuites."

10.4.4.  Report Template Encoding

   The RPTT JSON object is comprised of four elements: "name",
   "parmspec", "definition", and "description".  The description of
   these elements is as follows.

   o  Name
      The identifier of the report template.  This MUST be unique across
      all name elements for RPTTs in the ADM.

   o  ParmSpec
      This optional item describes parameters for this report.  This is
      encoded as an array where each element in the array is encoded as
      a formal parameter in accordance with Section 10.2.3.



Birrane, et al.         Expires September 5, 2018              [Page 38]


Internet-Draft                     ADM                        March 2018


   o  Definition
      This is an array of data elements that represent the ordered set
      of information associated with the report.  Each element in the
      array is encoded as a data item shorthand in accordance with
      Section 10.3.
      Report item elements MAY use reference parameters in their
      definition.  In those cases, the reference parameters in the
      definition list MUST match report entry parameter names from the
      ParmSpec element in the report template definition.

   o  Description
      A string description of the kind of data represented by this data
      item.

   The following is an example of a JSON encoding of an RPTT object.

      "name": "full_report",
      "parmspec": [{"STR":"Source"}],
      "definition" : [
        "EDD.data_item1",
        "EDD.data_item2('1')",
        "EDD.data_item3(Source)",
        "EDD.data_item4('1', Source)",
      ],
      "description": "A full report."

10.4.5.  Controls (CTRL) Encoding

   The CTRL JSON object is comprised of three elements: "name",
   "parmspec", and "description".  The description of these elements is
   as follows.

   o  Name
      The identifier of the control.  This MUST be unique across all
      name elements for CTRLs in the ADM.

   o  ParmSpec
      This optional item describes parameters for this control.  This is
      encoded as an array where each element in the array is encoded as
      a formal parameter in accordance with Section 10.2.3.

   o  Description
      A string description of the kind of data represented by this data
      item.

   The following is an example of a JSON encoding of an RPTT object.





Birrane, et al.         Expires September 5, 2018              [Page 39]


Internet-Draft                     ADM                        March 2018


      "name": "reset_src_cnts",
      "parmspec": [{"STR":"src"}],
      "description": "This control resets counts for the given source."

10.4.6.  Macro Encoding

   The MACRO JSON object is comprised of three elements: "name",
   "definition", and "description".  The description of these elements
   is as follows.

   o  Name
      The identifier of the macro.  This MUST be unique across all name
      elements for MACROs in the ADM.

   o  Definition
      This is a JSON array whose elements are shorthand references are
      in accordance with Section 10.3 and are of the type CTRL or MACRO.

   o  Description
      A string description of the kind of data represented by this data
      item.

   The following is an example of a JSON encoding of an RPTT object.

      "name": "user_list",
      "definition": ["CTRL.list_vars","CTRL.list_rptts"],
      "description": "List user defined data."

10.4.7.  Constant (CONST) Encoding

   The CONST JSON object is comprised of four elements: "name", "type",
   "value, and "description".  The description of these elements is as
   follows.

   o  Name
      The identifier of the constant.  This MUST be unique across all
      name elements for CONSTs in the ADM.

   o  Type
      The strong typing of this data value.  Types MUST be one of those
      defined in Section 8.

   o  Value
      The value of the constant, expressed in the JSON encoding of the
      data type.

   o  Description




Birrane, et al.         Expires September 5, 2018              [Page 40]


Internet-Draft                     ADM                        March 2018


      A string description of the kind of data represented by this data
      item.

   The following is an example of a JSON encoding of a CONST object.

      "name": "PI",
      "type": "FLOAT",
      "value": 3.14159,
      "description": "The value of PI."

10.4.8.  Operator (OP) Encoding

   The OP JSON object is comprised of four elements: "name", "result-
   type", "in-type", and "description".  The description of these
   elements is as follows.

   o  Name
      The identifier of the operator.  This MUST be unique across all
      name elements for OPs in the ADM.

   o  Result-Type
      The numeric result of applying the operator to the series of
      operands.  This must be one of the encodings for Table 1.

   o  In-Type
      This is an ordered JSON array of operands for the operator.  Each
      operand is a data type encoded in accordance with Table 1.

   o  Description
      A string description of the kind of data represented by this data
      item.

   The following is an example of a JSON encoding of a OP object.

      "name": "+INT",
      "result-type": "INT",
      "in-type": ["INT", "INT"],
      "description": "Int32 addition"

10.4.9.  Exemptions

   The AMM data model additionally defines data objects for both time-
   based rules and state-based rules.  These rules are associated with
   dynamic behaviors in the context of a network deployment and, as
   such, are typically not represented as static constructs in the
   context of an ADM.  Therefore, these data structures are not
   considered in this ADM template.




Birrane, et al.         Expires September 5, 2018              [Page 41]


Internet-Draft                     ADM                        March 2018


11.  IANA Considerations

   TBD.

12.  Security Considerations

   TBD

13.  Informative References

   [I-D.birrane-dtn-ama]
              Birrane, E., "Asynchronous Management Architecture",
              draft-birrane-dtn-ama-06 (work in progress), October 2017.

   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
              Requirement Levels", BCP 14, RFC 2119,
              DOI 10.17487/RFC2119, March 1997,
              <https://www.rfc-editor.org/info/rfc2119>.

Authors' Addresses

   Edward J. Birrane
   Johns Hopkins Applied Physics Laboratory

   Email: Edward.Birrane@jhuapl.edu


   Evana DiPietro
   Johns Hopkins Applied Physics Laboratory

   Email: Evana.DiPietro@jhuapl.edu


   David Linko
   Johns Hopkins Applied Physics Laboratory

   Email: David.Linko@jhuapl.edu














Birrane, et al.         Expires September 5, 2018              [Page 42]


Html markup produced by rfcmarkup 1.126, available from https://tools.ietf.org/tools/rfcmarkup/