Skip to main content

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

The information below is for an old version of the document.
Document Type
This is an older version of an Internet-Draft whose latest revision state is "Replaced".
Authors Edward J. Birrane , Evana DiPietro , David Linko
Last updated 2018-06-30
RFC stream (None)
Formats
Stream Stream state (No stream defined)
Consensus boilerplate Unknown
RFC Editor Note (None)
IESG IESG state I-D Exists
Telechat date (None)
Responsible AD (None)
Send notices to (None)
draft-birrane-dtn-adm-02
Delay-Tolerant Networking                                     E. Birrane
Internet-Draft                                               E. DiPietro
Intended status: Informational                                  D. Linko
Expires: December 31, 2018      Johns Hopkins Applied Physics Laboratory
                                                           June 29, 2018

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

Abstract

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

Status of This Memo

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

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

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

   This Internet-Draft will expire on December 31, 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 December 31, 2018               [Page 1]
Internet-Draft                     ADM                         June 2018

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

Table of Contents

   1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   3
     1.1.  Scope . . . . . . . . . . . . . . . . . . . . . . . . . .   3
   2.  Requirements Language . . . . . . . . . . . . . . . . . . . .   4
   3.  Terminology . . . . . . . . . . . . . . . . . . . . . . . . .   4
   4.  Data Modeling Concept of Operations . . . . . . . . . . . . .   5
   5.  Asynchronous Management Model (AMM) . . . . . . . . . . . . .   6
     5.1.  The AMM Resource Identifier (ARI) . . . . . . . . . . . .   6
       5.1.1.  Namespaces  . . . . . . . . . . . . . . . . . . . . .   7
       5.1.2.  Object Names  . . . . . . . . . . . . . . . . . . . .   9
       5.1.3.  Parameters  . . . . . . . . . . . . . . . . . . . . .   9
       5.1.4.  Special Case: Literal Values  . . . . . . . . . . . .  10
       5.1.5.  String Canonical Forms  . . . . . . . . . . . . . . .  11
       5.1.6.  Examples  . . . . . . . . . . . . . . . . . . . . . .  12
     5.2.  AMM Type Definitions  . . . . . . . . . . . . . . . . . .  15
       5.2.1.  Primitive Types . . . . . . . . . . . . . . . . . . .  15
       5.2.2.  Derived Types . . . . . . . . . . . . . . . . . . . .  15
       5.2.3.  Collections . . . . . . . . . . . . . . . . . . . . .  17
     5.3.  Object Definitions  . . . . . . . . . . . . . . . . . . .  18
       5.3.1.  Common Object Metadata  . . . . . . . . . . . . . . .  18
       5.3.2.  Externally Defined Data (EDD) . . . . . . . . . . . .  19
       5.3.3.  Constant (CONST)  . . . . . . . . . . . . . . . . . .  19
       5.3.4.  Control (CTRL)  . . . . . . . . . . . . . . . . . . .  20
       5.3.5.  Macro (MAC) . . . . . . . . . . . . . . . . . . . . .  21
       5.3.6.  Operator (OP) . . . . . . . . . . . . . . . . . . . .  21
       5.3.7.  Reports . . . . . . . . . . . . . . . . . . . . . . .  23
       5.3.8.  State-Based Rule (SBR)  . . . . . . . . . . . . . . .  24
       5.3.9.  Tables  . . . . . . . . . . . . . . . . . . . . . . .  25
       5.3.10. Time-Based Rule (TBR) . . . . . . . . . . . . . . . .  27
       5.3.11. Variable (VAR)  . . . . . . . . . . . . . . . . . . .  28
       5.3.12. Common Object Processing  . . . . . . . . . . . . . .  29
     5.4.  Data Type Mnemonics and Enumerations  . . . . . . . . . .  30
       5.4.1.  AMM Objects . . . . . . . . . . . . . . . . . . . . .  30
       5.4.2.  Primitive Data Types  . . . . . . . . . . . . . . . .  31
       5.4.3.  Compound Data Types . . . . . . . . . . . . . . . . .  32
       5.4.4.  Numeric Promotions  . . . . . . . . . . . . . . . . .  33
       5.4.5.  Numeric Conversions . . . . . . . . . . . . . . . . .  33
   6.  JSON ADM Template . . . . . . . . . . . . . . . . . . . . . .  33
     6.1.  ADM Inclusion . . . . . . . . . . . . . . . . . . . . . .  34
     6.2.  ADMT Object Collections . . . . . . . . . . . . . . . . .  34
     6.3.  ADM Metadata  . . . . . . . . . . . . . . . . . . . . . .  35
     6.4.  Type Encodings  . . . . . . . . . . . . . . . . . . . . .  36
       6.4.1.  Primitive Type Encoding . . . . . . . . . . . . . . .  36
       6.4.2.  Derived Type Encoding . . . . . . . . . . . . . . . .  36

Birrane, et al.         Expires December 31, 2018               [Page 2]
Internet-Draft                     ADM                         June 2018

       6.4.3.  Collection Encoding . . . . . . . . . . . . . . . . .  37
     6.5.  ARI Encoding  . . . . . . . . . . . . . . . . . . . . . .  38
     6.6.  ADM Structures  . . . . . . . . . . . . . . . . . . . . .  40
       6.6.1.  General Notes . . . . . . . . . . . . . . . . . . . .  40
       6.6.2.  Constant (CONST) Encoding . . . . . . . . . . . . . .  41
       6.6.3.  Control (CTRL) Encoding . . . . . . . . . . . . . . .  41
       6.6.4.  Externally Defined Data (EDD) Encoding  . . . . . . .  42
       6.6.5.  Macro Encoding  . . . . . . . . . . . . . . . . . . .  43
       6.6.6.  Operator (OP) Encoding  . . . . . . . . . . . . . . .  43
       6.6.7.  Table Template (TBLT) Encoding  . . . . . . . . . . .  44
       6.6.8.  Report Template Encoding  . . . . . . . . . . . . . .  44
       6.6.9.  Variables Encoding  . . . . . . . . . . . . . . . . .  46
       6.6.10. Exemptions  . . . . . . . . . . . . . . . . . . . . .  47
   7.  ADM Author Considerations . . . . . . . . . . . . . . . . . .  47
   8.  IANA Considerations . . . . . . . . . . . . . . . . . . . . .  49
   9.  Security Considerations . . . . . . . . . . . . . . . . . . .  49
   10. References  . . . . . . . . . . . . . . . . . . . . . . . . .  49
     10.1.  Normative References . . . . . . . . . . . . . . . . . .  49
     10.2.  Informative References . . . . . . . . . . . . . . . . .  49
   Authors' Addresses  . . . . . . . . . . . . . . . . . . . . . . .  50

1.  Introduction

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

1.1.  Scope

   This document defines a physical data model suitable for managing
   applications in accordance with the AMA.  This physical model is
   termed the Asynchronous Management Model (AMM) and consists of the
   data types and data structures needed to manage applications in
   asynchronous networks.

   This document also provides a template, called the Application Data
   Model Template (ADMT), for the standardized representation of
   application-specific instances of this model.  Using the types and
   structures defined by the AMM, individual applications can capture
   their unique, static management information in documents compliant
   with the ADMT.  These application-specific documents are called
   Application Data Models (ADMs).

   The AMM presented in this document does not assume any specific type
   of application or underlying network encoding.  In order to

Birrane, et al.         Expires December 31, 2018               [Page 3]
Internet-Draft                     ADM                         June 2018

   communicate model elements between AMA Agents and Managers in a
   network, the model must be encoded for transmission.  Any such
   encoding scheme is outside of the scope of this document.  Generally,
   the encoding of the model is a separate concern from the
   specification of data within the model.

   Because different networks may use different encodings for data,
   mandating an encoding format would require incompatible networks to
   encapsulate data in ways that could introduce inefficiency and
   obfuscation.  It is envisioned that different networks would be able
   to encode ADMs in their native encodings such that the translation of
   ADM data from one encoding to another can be completed using
   mechanical action taken at network borders.

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

2.  Requirements Language

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

3.  Terminology

   Note: The terms "Actor", "Agent", "Externally Defined Data",
   "Variable", "Constant", Control", "Literal", "Macro", "Manager",
   "Operator", "Report", "Report Template", "Rule", "State-Based Rule",
   "Table", "Table Template", and "Time-Based Rule" are used without
   modification from the definitions provided in the
   [I-D.birrane-dtn-ama].

   Additional terms defined in this document are as follows.

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

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

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

Birrane, et al.         Expires December 31, 2018               [Page 4]
Internet-Draft                     ADM                         June 2018

   o  AMM Resource Identifier (ARI) - A unique identifier for any AMM
      object, syntactically conformant to the Uniform Resource
      Identifier (URI) syntax documented in [RFC3986] and using the
      scheme name "ari".

   o  ADM Namespace - A moderated, hierarchical taxonomy of namespaces
      that describe a set of ADM scopes.  Specifically, an individual
      ADM namespace is a specific sequence of ADM namespaces, from most
      general to most specific, that uniquely and unambiguously identify
      the namespace of a particular ADM.

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

4.  Data Modeling Concept of Operations

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

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

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

Birrane, et al.         Expires December 31, 2018               [Page 5]
Internet-Draft                     ADM                         June 2018

                          Data Model Relationship

             +---------+               +---------+
             |   AMM   |-------------->|  ADMT   |
             +----+----+               +----+----+
                  |                         |
                  |              +----------+-------------+
                  V              |          |             |
             +----------+        V          V             V
             | Network  |    +-------+  +-------+     +-------+
             | Specific |    | ADM 1 |  | ADM 2 | ... | ADM N |
             | Config.  |    +---+---+  +---+---+     +---+---+
             +----+-----+        |          |             |
                  |              |          |             |
                  V              V          V             V
                +---------------------------------------------+
                |                     ODM                     |
                +---------------------------------------------+

                                 Figure 1

   In this figure, AMM data types and structures form the common
   elements of the management model used by both ADMs and network
   specific configurations.  Together, the set of static information
   provided by the union of all supported ADMs with the set of operator-
   specified dynamic AMM objects, forms the operational data model used
   to manage the network.

5.  Asynchronous Management Model (AMM)

   This section describes the Asynchronous Management Model, which is
   the set of objects used to implement the logical data model provided
   by the AMA.  This section also provides additional information
   necessary to work with this model, such as data type specifications,
   identifier constructs, and naming conventions.

5.1.  The AMM Resource Identifier (ARI)

   Every object in the AMM must be uniquely identifiable, regardless of
   whether the item is defined formally in an ADM document or informally
   by operators in the context of a specific network deployment.  The
   AMM Resource Identifier (ARI) uniquely identifies AMM objects.

   There are three components to the ARI: namespaces, object names, and
   parameters.  This section defines each of these components, discusses
   special cases, and presents a string canonicalization of these
   identifiers, with examples.

Birrane, et al.         Expires December 31, 2018               [Page 6]
Internet-Draft                     ADM                         June 2018

5.1.1.  Namespaces

   AMM objects exist within unique namespaces to prevent conflicting
   names within network deployments, particularly in cases where network
   operators are allowed to define their own object names.  In this
   capacity, namespaces exists to eliminate the chance of a conflicting
   object name.  They MUST NOT be used as a security mechanism.  An
   Agent or Manager MUST NOT infer security information or access
   control based solely on namespace information.

   The AMM defines three ways to identify namespaces for AMM object
   names: Moderated Namespaces, Anonymous Namespaces, and Issuer
   Namespaces.

5.1.1.1.  Moderated Namespaces

   The most effective way to ensure the uniqueness of an AMM Object is
   to name it in the context of a moderated namespace.  These namespaces
   are assigned by an overseeing organization as part of a maintained
   namespace registry.

   Moderated namespaces are hierarchical, which allows the grouping of
   objects that share common attributes - for example, objects
   associated with related protocols may have protocol-specific
   namespaces that are grouped under a single encompassing namespace.
   Namespaces that are closer to a root node in the moderated hierarchy
   have broader scope than namespaces closer to leaf nodes in that
   hierarchy.  There is no requirement that the namespace hierarchy be
   represented as a single tree structure; multiple root nodes are
   acceptable and likely to exist.

   In a hierarchical model of namespaces, a particular namespace can be
   identified as the path to that namespace through the hierarchy.  The
   expression of that path within an ADM is accomplished by listing each
   namespace along the path, separated by the tokenizing character "/".
   For example, consider the namespaces in the following figure.

Birrane, et al.         Expires December 31, 2018               [Page 7]
Internet-Draft                     ADM                         June 2018

             +-------+                   +-------+
             | TOP-A |                   | TOP-B |
             +---+---+                   +---+---+
                 |                      _____|_____
                 |                     |           |
             +-------+             +-------+   +-------+
             | MID-A |             | MID-B |   | MID-C |
             +-------+             +-------+   +-------+
        _________|_________            |           |
       |         |         |           |           |
   +-------+ +-------+ +-------+   +-------+   +-------+
   | LOW-A | | LOW-B | | LOW-C |   | LOW-A |   | LOW-A |
   +-------+ +-------+ +-------+   +-------+   +-------+

   Given this hierarchy, the following are all valid namespace
   representations.

      TOP-A/

      TOP-A/MID-A

      TOP-A/MID-A/LOW-A

      TOP-B/MID-B/LOW-A

      TOP-B/MID-C/LOW-A

   Moderated namespaces require resources to review and publish and are
   best suited for static AMM object definitions, such as those found in
   ADMs.

5.1.1.2.  Anonymous Namespaces

   It is possible for network operators to define AMM objects that are
   not associated with a namespace.  In this case, a nil namespace can
   be defined.  This special case is considered the use of an
   "anonymous" namespace.

   Policy decisions as to whether anonymous namespaces are allowed in
   the system should be determined before network deployment.  The use
   of an anonymous namespace greatly increases the chances of naming
   collisions.

5.1.1.3.  Informal Namespaces

   Network-specific configurations, as illustrated in Figure 1, are
   dynamic, ephemeral, not captured in published ADMs, and do not use
   moderated namespaces.  Instead, AMM objects that comprise network-

Birrane, et al.         Expires December 31, 2018               [Page 8]
Internet-Draft                     ADM                         June 2018

   specific configuration can be uniquely differentiated as a function
   of their "Issuer" and an issuer-specific "Tag".

   An Issuer is any string that identifies the organization that is
   defining an AMM object.  This value may come from a global registry
   of organizations, an issuing node address, a signed known value, or
   some other network-unique marking.  Issuers MUST NOT conflict with
   known moderated namespaces, and Agents and Managers should not
   process Issuers that conflict with existing moderated namespaces.

   A Tag is any string used to disambiguate AMM Objects for an Issuer.
   The contents of the tag are left to the discretion of the Issuer.
   Examples of potential tag values include an issuer-known version
   number or a (signed) hashing of the data item associated with the
   reference identifier.

5.1.2.  Object Names

   Object names are strings whose value is determined by the creator of
   the object.  For those objects defined in accordance with the ADMT
   Template, the structure of the object name is given in Section 5.3.1.

5.1.3.  Parameters

   Parameterization is used in the AMM to enable expressive autonomous
   function and reduce the amount of traffic communicated between
   Managers and Agents.  In the AMM, most objects can be parameterized
   and the meaning of parameterization for each object is described in
   detail in Section 5.3.

   If there are two instances of an AMM object that have the same
   namespace and same object name but have different parameters, then
   those instances are both unique and the ARIs for those instances MUST
   also be unique.  Therefore, parameters are considered part of an AMM
   object's identifier.

   There are two types of parameters defined in the AMM: Formal and
   Actual parameters.  The terms formal parameter and actual parameter
   follow common computer programming vernacular for discussing function
   declarations and function calls, respectively.

5.1.3.1.  Formal Parameters

   Formal parameters define the type, name, and order of the information
   that customizes an AMM Object.  They represent the unchanging
   "definition" of the parameterized object.

Birrane, et al.         Expires December 31, 2018               [Page 9]
Internet-Draft                     ADM                         June 2018

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

5.1.3.2.  Actual Parameters

   Actual parameters represent the data values passed to a parameterized
   AMM Object.  They "fulfill" the parameter requirements defined by the
   formal parameters for that object.

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

   There are two ways in which the value of an actual parameter can be
   specified: parameter-by-value and parameter-by-name.

   Parameter-By-Value
           This method involves directly supplying the value as part of
           the actual parameter.  It is the default method for supplying
           values.

   Parameter-By-Name
           This method involves specifying the name of some other
           parameter and using that other parameter's value for the
           value of this parameter.  This method is useful when a
           parameterized AMM Object contains another parameterized AMM
           Object.  The contained object's actual parameter can be given
           as the name of the containing object's parameter.  In that
           way, a containing object's parameters can be "pass down" to
           all of the objects it contains.

5.1.3.3.  Optional Parameters

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

5.1.4.  Special Case: Literal Values

   As defined in the AMA, Literal values are those whose value and
   identifier are equivalent.  For example, the literal "4" serves as
   both an identifier and a value.  When literal values are used in
   objects in the AMM, they are able to have a simplified identification
   scheme.

Birrane, et al.         Expires December 31, 2018              [Page 10]
Internet-Draft                     ADM                         June 2018

   Because the value of a Literal object serves as its identifier, there
   is no need for namespaces, object names, or parameters.  A literal
   can be completely identified by its data type and data value.  Since
   Literals in the AMA are used to identify primitive data types, the
   type of a Literal identifier MUST be as described in Table 2.

5.1.5.  String Canonical Forms

   While there may exist multiple encodings of an ARI, to include the
   JSON encodings presented in Section 6 and other binary encodings in
   other specifications, this section defines a universal string
   representation of the ARI, as such a representation is helpful to
   express examples in this and other documents.

   This representation is not prescriptive; other string encodings may
   exist that differ from the one used in this document.

5.1.5.1.  General ARI String Representation

   The String Canonical Form of the ARI is expressed as a Uniform
   Resource Identifier (URI), as documented in [RFC3986].  A URI is
   syntactically decomposed into a scheme name and a scheme-specific
   part.  The set of known scheme names is moderated by IANA.  The
   scheme-specific part of the URI is dependent on the scheme name.

   The scheme name of the ARI is "ari".  The scheme-specific part of the
   "ari" scheme follows the format:

   ari:/<Namespace>/<ObjectName><(Parameters)>

   With the string representation of each scheme given as follows.

   Namespaces
           Namespaces are represented as "/" separated lists, with
           individual namespace types represented as follows:

           *  Moderated namespaces are listed in order from the most
              general namespace to the most specific namespace.  For
              example: "GENERAL/MIDDLE/SPECIFIC/".

           *  Anonymous namespaces are empty and are represented as "/".

           *  Informal namespaces follow the general pattern of
              moderated namespaces - starting with the general Issuer
              followed by the more specific issuer tag.  For example:
              "Issuer/Tag".  In cases where the Tag is omitted, then the
              representation is simply "Issuer/".

Birrane, et al.         Expires December 31, 2018              [Page 11]
Internet-Draft                     ADM                         June 2018

   Object Names
           The object name is a string as specified in Section 5.3.1.

   Parameters
           If present, parameters are represented as a comma-separated
           string enclosed in parenthesis.  Different types of
           parameters are represented as follows.

           *  Formal parameters follow the pattern <type> <name> and if
              there is a default value, it is represented by the
              substring "= <value>".

           *  Actual Parameters-By-Value are represented as the string
              encoding of their value.

           *  Actual Parameters-By-Name are represented as the name of
              the parameter enclosed in angle brackets.

           Note: If an actual parameter is missing for a formal
           parameter that has a default value, then the ARI string MUST
           have a blank space where the actual parameter would have
           been.  This missing parameter will also have a comma,
           separating it from other actual parameters in the ARI string.

5.1.5.1.1.  Shortform Encoding

   In cases where a default namespace can be assumed (for example, in
   the context of an ADM with a defined namespace) the prefix
   ari:/Namespace/ can be omitted.

5.1.5.2.  Literal String Encoding

   The string representation of a Literal ARI is much simpler and
   consists of simply the data type of the Literal followed by the
   value, as follows:

   "(type) value"

5.1.6.  Examples

   The ARIs for the following sample AMM objects are encoded in Table 1.
   Note that these examples are for the identifiers of AMM objects, not
   their entire definition.

   o  The number of bytes received by an Agent, defined in the N1/N2
      namespace and called num_bytes.

Birrane, et al.         Expires December 31, 2018              [Page 12]
Internet-Draft                     ADM                         June 2018

   o  The number of bytes received through an interface, called
      num_bytes_if, which takes a single string parameter named
      "if_name" with a default value oth "eth0".

   o  An anonymous, operator-defined object named "obj1" which takes two
      unsigned integer parameters, n1 and n2, with default values of 3
      and 4, respectively.

   o  The typed, Literal value of 4.

Birrane, et al.         Expires December 31, 2018              [Page 13]
Internet-Draft                     ADM                         June 2018

   +------------------------+------------------------------------------+
   | ARI String             | Description                              |
   +------------------------+------------------------------------------+
   | "ari:N1/N2/num_bytes"  | Unparameterized num_bytes object in the  |
   |                        | N1/N2 namespace.                         |
   |                        |                                          |
   | "num_bytes"            | Shortform encoding where the N1/N2       |
   |                        | namespace can be assumed.                |
   |                        |                                          |
   | "num_bytes_if(String   | Formal parameter definition of num_bytes |
   | if_name)"              | object that accepts a string interface   |
   |                        | name.                                    |
   |                        |                                          |
   | "num_bytes_if(String   | Formal parameter definition of num_bytes |
   | if_name=eth0)"         | object that accepts a string interface   |
   |                        | name with a default value.               |
   |                        |                                          |
   | "num_bytes_if()"       | Actual parameter using the default value |
   |                        | of eth0.                                 |
   |                        |                                          |
   | "num_bytes_if(eth0)"   | Actual parameter of eth0.                |
   |                        |                                          |
   | "ari:/obj1(Int n1 = 0, | Formal parameter of object obj1 in       |
   | Int n2 = 3)"           | anonymous namespace taking 2 default     |
   |                        | parameters.                              |
   |                        |                                          |
   | "ari:/obj1(, )"        | Actual parameter using the default       |
   |                        | values of 0 for n1 and 3 for n2.         |
   |                        |                                          |
   | "ari:/obj1(, 4)"       | Actual parameter using the default value |
   |                        | of 0 for n1.                             |
   |                        |                                          |
   | "ari:/obj1(4, )"       | Actual parameter using the default value |
   |                        | of 3 for n2.                             |
   |                        |                                          |
   | "ari:/obj1(4,4)"       | Actual parameters provided for all obj1  |
   |                        | parameters.                              |
   |                        |                                          |
   | "ari:/obj1(<input>,4)" | Actual parameters provided for all obj1  |
   |                        | parameters, with the value of the first  |
   |                        | parameter taken from some other          |
   |                        | parameter named "input".                 |
   |                        |                                          |
   | "(UINT) 4"             | The Literal value 4 interpreted as a     |
   |                        | 32-bit unsigned integer.                 |
   +------------------------+------------------------------------------+

                                  Table 1

Birrane, et al.         Expires December 31, 2018              [Page 14]
Internet-Draft                     ADM                         June 2018

5.2.  AMM Type Definitions

   This section describes the type definitions used by the AMM.

5.2.1.  Primitive Types

   The AMM supports a series of primitive types as outlined in Table 2.

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

                         Table 2: Primitive Types

5.2.2.  Derived Types

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

5.2.2.1.  Byte String

   A Byte String is a specialization of the String primitive data type
   used to store binary data using base64 encoding as defined in
   [RFC4648].

Birrane, et al.         Expires December 31, 2018              [Page 15]
Internet-Draft                     ADM                         June 2018

5.2.2.2.  Time Values (TV) and Timestamps (TS)

   A Time Value (TV) is a specialization of the String primitive data
   type whose time interpretation is as given in this section.  There
   are two "types" of time representations within the AMM: relative
   times and absolute times.

   An absolute time represents an instant in time.  It MUST be formatted
   as a date-time in accordance with [RFC3339].

   A relative time is defined as the amount of time after an instant in
   time.  A relative time MUST be formatted as a full-time in accordance
   with [RFC3339].  Relative times have advantages over absolute times:
   they do not require time to be synchronized across Agents and
   Managers, and they are more compact in their representation.  For
   example, expressing the semantics "run control_one 10 seconds after
   receiving it" or "run control_two 20 seconds after running
   control_one" is more appropriate using relative times than absolute
   times.  The initiating event of a relative time MUST be unambiguously
   defined in the context using the time value.

   As a practical matter, encodings of relative times MAY impose a limit
   of no more than 17 years of relative time, which corresponds to
   roughly 29 bits of information and is considered well past an upper
   bound of efficiency for using a relative time versus an absolute
   time.

   An absolute time may be differentiated from a relative time based on
   whether the time specification is a date-time or a full-time.

   For example, "00:00:10Z" is a relative time representing 10 seconds
   after an initiating event.  "2019-01-01T08:00:00Z" is an absolute
   time that refers to 8am, Tuesday January 1st, 2019.

   A Timestamp (TS) represents a specific point in time when an event
   occurred.  As such, it MUST be represented as an absolute time.

5.2.2.3.  Type-Name-Value (TNV)

   A Type-Name-Value (TNV) is a three-tuple of information that
   describes a typed, named value in the AMM.  Since the length of a
   data value is a matter of encoding, there is not an explicit length
   field present for the data value; it is assumed that any encoding
   scheme either explicitly encodes length or that the length is self-
   delineating in the encoding.

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

Birrane, et al.         Expires December 31, 2018              [Page 16]
Internet-Draft                     ADM                         June 2018

   o  Name - A unique identifier for this value.

   o  Value - The value of the data item.

5.2.2.4.  User-Specified Derived Types

   Individual ADMs and network operators may derive other types that
   specialize the types provided by the AMM.  When doing so, AMM data
   types MUST be used to capture the specialization and any user-
   specific verification or validation MUST occur in user-specific
   implementations on Agents and Managers.

5.2.3.  Collections

   AMM objects, or parameters associated with those objects, often need
   to represent groups of related information.  Since the AMM is
   strongly typed, these groups of related information are represented
   by special data types called collections.  AMM collections are
   ordered and may contain duplicate entries.

   The AMM defines three typed collections that capture TNVs, ARIs, and
   mathematical expressions.

5.2.3.1.  Type-Name-Value Collection (TNVC)

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

   TNVCs are often used to capture formal and actual parameters for AMM
   objects.

5.2.3.2.  ARI Collection (AC)

   An ARI Collection (AC) is an ordered set of ARIs.

   ACs are often used when there exists a need to refer to multiple AMM
   objects as a single unit.  For example, when defining a Report
   Template, the definition may have an AC that defines the ordered ARIs
   whose values constitute that report.

5.2.3.3.  Expression (EXPR)

   An Expression (EXPR) is a specialization of an AC where each ARI in
   the collection is either an operand or an operator.  These operands
   and operators form a mathematical expression that is used to compute
   a numerical value.

Birrane, et al.         Expires December 31, 2018              [Page 17]
Internet-Draft                     ADM                         June 2018

   Within an Expression, an operand MUST be an ARI with one of the
   following types: Literal, Constant, Externally Defined Data, or
   Variable.  An operator MUST be an ARI of type Operator.

   Since the Expression is an AC, there are no annotative constructs
   such as parenthesis to enforce certain orders of operation.  To
   preserve an unambiguous calculation of values, the ARIs that form an
   Expression MUST be represented in postfix order.  Postfix notation
   requires no additional symbols to enforce precedence, always results
   in a more efficient encoding, and post-fix engines can be implemented
   efficiently in embedded systems.

   For example, the infix expression A * (B * C) is represented as the
   postfix A B C * *.

   Expressions are often used when assigning values to a Variable or
   when calculating the state of the Agent in the context of a State-
   Based Rule.

5.3.  Object Definitions

   This section identifies the AMM Objects that instantiate the AMA
   logical data model and the processing required to support these
   objects at Agents and Managers in the network.

5.3.1.  Common Object Metadata

   Every object in the AMM includes a set of metadata providing
   annotative or otherwise user-friendly descriptive information for the
   object.  This information may be used as documentation (for example,
   only present in ADMs and on operator consoles) and/or encoded and
   transmitted over the wire as part of a management protocol.

   Metadata is not required to be unique amongst objects and individual
   encodings MAY choose to not encode metadata in cases where the
   information is not needed to uniquely identify objects.  The metadata
   supported by the AMM for objects is as follows:

   (STR) Name
           An object name is a string associated with the object, but
           does not constitute the sole identifier for the object.
           Names provide human-readable and/or user-friendly ways to
           refer to objects within a given context.

   (STR) Description
           An object description is a string describing the purpose or
           usage of the object in a human-readable format.  The
           description serves as documentation for the object and SHOULD

Birrane, et al.         Expires December 31, 2018              [Page 18]
Internet-Draft                     ADM                         June 2018

           be the same regardless of how the object might be
           parameterized.  For example, the description of a CTRL object
           should document the purpose of the CTRL in a way that is
           independent of the value of any particular parameter value
           passed to that CTRL.

5.3.2.  Externally Defined Data (EDD)

   Externally defined data (EDD), as defined in the AMA, represent data
   values that are computed external to the network management system.
   The definition of these values are solely defined in the context of
   an ADM; since their calculation exists outside of the network
   management system, they are not added or removed as part of the
   dynamic configuration of the network management system.

   An EDD consists of an ARI, type, and a description, with the
   following caveats:

   (ARI) Identifier
           This Identifier MUST be of type EDD and MAY be parameterized,
           particularly in cases where the specific computed value can
           be identified by an associative look-up, as discussed in
           Section 7.

   (UINT) Type
           The data type of the EDD value MUST be specified as part of
           the EDD definition and this type MUST be one of the primitive
           data types defined in Table 2.

   (STR) Description
           This represents the human-readable description of the EDD.

5.3.3.  Constant (CONST)

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

   Allowing network operators to define constants dynamically means that
   a Constant could be defined, removed, and then re-defined at a later
   time with a different value, which defeats the purpose of having
   Constants.  Variables MUST be used instead of Constants for the
   purpose of adding new values to the dynamic network configuration.

   A CONST is defined by its ARI, value, and description, with the
   following caveats.

Birrane, et al.         Expires December 31, 2018              [Page 19]
Internet-Draft                     ADM                         June 2018

   (ARI) Identifier
           This Identifier MUST be of type CONST and MUST NOT be
           parameterized.  Parameterizing a Constant implies that its
           value is dependent upon the set of parameters sent to it,
           which defeats the purpose of defining a constant value.

   (TNV) Typed Value
           The value of a constant is the immutable value that should be
           used in lieu of the Constant ARI.

           This value is expressed as a TNV with the following
           requirements.

           *  Type MUST be one of the primitive data types defined in
              Table 2.

           *  Name MUSt be omitted as the CONST ARI defines the name for
              this value.

           *  Value must be present and consistent with the data type
              for this CONST.

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

5.3.4.  Control (CTRL)

   A Control represents a predefined function that can be run on an
   Agent.  Controls are not able to be defined as part of dynamic
   network configuration since their execution is typically part of the
   firmware or other implementation of the Agent outside of the context
   of the network management system.

   Network operators that wish to dynamically execute functions on an
   Agent may use Macros, State-Based Rule, and Time-Based Rule instead.

   Controls are identified by their ARI and their description, with the
   following caveats.

   (ARI) Identifier
           This Identifier MUST be of type CTRL and MAY be parameterized
           in cases where the function executed by that Control takes
           parameters.
           When defined in the context of an ADM, the Control ARI MUST
           match the definition of a Formal Parameter list.  This is
           because the ADM defines the Controls that can be invoked, but
           does not define any particular invocation of a Control.

Birrane, et al.         Expires December 31, 2018              [Page 20]
Internet-Draft                     ADM                         June 2018

           When used as part of network operations, a Control ARI MUST
           match the definition of an Actual Parameter list.  This is
           because when used operationally, a parameterized Control
           required parameters to be run.
           In cases where a Control takes no parameters, the definition
           in the ADM document MUST be considered the definition of the
           Control and the presence of the same ARI in the context of an
           operational system MUST be seen as an invocation of that
           Control.

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

5.3.5.  Macro (MAC)

   Macros are ordered collections of Controls or other Macros.  When run
   by an Agent, each ARI in the AC is run in order.  A Macro may be
   defined as part of an ADM or as part of dynamic network
   configuration.

   In cases where a Macro contains another Macro, implementations MUST
   implement some mechanism for preventing infinite recursions, such as
   defining maximum nesting levels, performing Macro inspection, and/or
   enforcing maximum execution times.

   A Macro is defined by an ARI, a content definition, and a
   description, as follows.

   (ARI) Identifier
           This Identifier MUST be of type MAC and MAY be parameterized
           and, if so, the parameter may be passed-by-name to any
           parameterized elements within the Macro.

   (AC) Definition
           The Macro definition is modeled as an AC, where each ARI
           within the AC MUST be either a Control or a Macro.

   (STR) Description
           This represents the human-readable description of the Macro,
           as a string.

5.3.6.  Operator (OP)

   Operators represent user-defined mathematical functions implemented
   in the firmware of an Agent for the purpose of aiding the evaluation
   of Expressions.

Birrane, et al.         Expires December 31, 2018              [Page 21]
Internet-Draft                     ADM                         June 2018

   The AMM separates the concepts of Operators and Controls to prevent
   side-effects in Expression evaluation (e.g. to avoid constructs such
   as A = B + GenerateReport()).  For this reason, Operators are given
   their own structure type and Controls do not support a return value.

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

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

   (ARI) Identifier
           This Identifier MUST be of type OP and MUST NOT be
           parameterized.  Much like Constants, Operators represent
           immutable mathematical functions.  The operands of an
           Operator are not considered as "parameters" to the Operator.

   (UINT) Out Type
           This is the return value of the Operator and MAY be different
           than the operand types accepted by the Operator.  This type
           MUST be one of the primitive data types defined in Table 2.

   (UINT) Num Operands
           This is the number of operands evaluated by the operator.
           For example, the unary NOT Operator ("!") would operate on a
           single operand.  The binary PLUS Operator ("+") would operate
           on two operands.  A custom operator to calculate the average
           of the last 10 samples of data would operate on 10 operands.

   (TNVC) In Types
           This is the type information for each operand operated on by
           the Operator, modeled as a TNV Collection (TNVC).  There MUST
           be one TNV in the TNVC for each operand, and each TNV MUST
           adhere to the following requirements:

           *  The Type field MUST be present and MUST be one of the
              primitive data types defined in Table 2.

           *  The Name field MAY be present to capture a semantic name
              for the operand.

           *  The Value field MUST NOT be present.

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

Birrane, et al.         Expires December 31, 2018              [Page 22]
Internet-Draft                     ADM                         June 2018

5.3.7.  Reports

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

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

5.3.7.1.  Report Template (RPTT)

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

   Since a RPTT may contain other RPTTs, implementations MUST implement
   some mechanism to prevent the definition of circular references.

   RPTTs are defined by an ARI, the report template definition, and a
   description, as follows.

   (ARI) Identifier
           This Identifier MUST be of type RPTT and MAY be parameterized
           and, if so, the parameter may be passed-by-name to any
           parameterized elements within the RPTT.

   (AC) Definition
           The Report Definition is modeled as an AC, where each ARI
           within the AC MUST identify either a CONST, LIT, EDD, VAR, or
           other RPTT.

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

5.3.7.2.  Report (RPT)

   A Report (RPT) is a set of data values populated in conformance to a
   given data definition.  Reports do not have an individual identifier
   - rather they are uniquely identified by their definition and the
   timestamp at which their data values were collected.

   RPTs are defined by their associated template, the time at which the
   report was generated, and the individual entries in the report, as
   follows.

Birrane, et al.         Expires December 31, 2018              [Page 23]
Internet-Draft                     ADM                         June 2018

   (ARI) Template Id
           This is the ARI of the object that defines the format of the
           report data values.  This ARI MUST define an AMM object of
           type RPTT, EDD, or VAR, or CTRL.
           If this ARI is parameterized, this ARI MUST include the
           actual parameters used in the generation of the report.

   (TV) Generation Time
           This is the absolute time at which the report was generated
           by the Agent.

   (TNVC) Report Entries
           This is the collection of data values that comprise the
           report.  If the template for this report is an EDD, VAR, or
           CTRL then there MUST be one entry for this report.  If the
           template is a RPTT, then there MUST be one entry for every
           item defined in the template.
           Entries are modeled as a TNVC, with each TNV representing a
           report entry with the following requiremnts.

           *  Type MAY be ommitted in cases where checking type safety
              is not required.

           *  Name MAY be omitted in cases where a semantic name for the
              entry can be derived from the template.

           *  Value MUST be present and consistent with the type for
              this entry from the associated template item.

5.3.8.  State-Based Rule (SBR)

   A State-Based Rule (SBR) specifies that starting at a particular time
   an action should be run by the Agent if some condition evaluates to
   true, until the action has been run a maximum number of times.  When
   the SBR is no longer valid it MAY be discarded by the Agent.

   Examples of SBRs include:

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

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

   SBRs are defined by their ARI, start time, condition, maximum run
   count, action, and description, as follows.

   (ARI) Identifier

Birrane, et al.         Expires December 31, 2018              [Page 24]
Internet-Draft                     ADM                         June 2018

           This Identifier MUST be of type SBR and MUST NOT be
           parameterized.

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

   (EXPR) CONDITION
           The Expression which, if true, results in the SBR running the
           associated action.  An Expression is considered true if it
           evaluates to a non-zero number.

   (UVAST) COUNT
           The number of times the SBR action can be run.  The special
           value of 0 indicates there is no limit on how many times the
           action can be run.

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

   (STR) Description
           This represents the human-readable description of the SBR, as
           a string.

5.3.9.  Tables

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

5.3.9.1.  Table Template (TBLT)

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

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

Birrane, et al.         Expires December 31, 2018              [Page 25]
Internet-Draft                     ADM                         June 2018

   (ARI) Identifier
           This Identifier MUST be of type TBLT and MUST be of type
           TBLT, and MUST NOT contain parameters.

   (TNVC) Columns
           A TBLT is defined by its ordered set of columns descriptions
           captured as a TNVC with each TNV in the collection describing
           a table column with the following requirements.

           *  Type MUST be present and MUST be one of the primitive
              types defined in Table 2.

           *  Name MAY be omitted in cases where a semantic name for the
              column can be derived from the template.

           *  Value MUST NOT be present as a column does not contain
              data values.

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

5.3.9.2.  Table (TBL)

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

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

   (ARI) Template Id
           This is the ARI of the Table Template holding the column
           definitions for this table.  This ARI MUST be of type TBLT
           and match a known Table Template.

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

   (TNVC) Rows Information
           Each row in a TBL is represented by a TNVC, with each TNV in
           the collection representing the value for a specific column
           with the following requirements.

           *  Type MAY be present, when necessary to verify that
              elements in the row match the types of table columns.

Birrane, et al.         Expires December 31, 2018              [Page 26]
Internet-Draft                     ADM                         June 2018

           *  Name MUST NOT be present.

           *  Value MUST be present and compatible with the type of the
              associated column.
           The number of TNVs in the collection MUST be equal to the
           number of columns defined for the Table Template.

5.3.10.  Time-Based Rule (TBR)

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

   Examples of TBRs include:

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

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

   TBRs are defined by their ARI, start time, period, maximum run count,
   action, and description, as follows.

   (ARI) Identifier
           This Identifier MUST be of type TBR and MUST NOT be
           parameterized.

   (TV) Start
           The time at which the TBR should start to be evaluated.  This
           will mark the first running of the action associated with the
           TBR.

   (TV) Period
           The time to wait between running the action associated with
           the TBR.  This value MUST be a relative time value.

   (UVAST) Count
           The number of times the TBR action may be run.  The special
           value of 0 indicates the TBR should continue running the
           action indefinitely.

   (AC) Action
           The collection of Controls and/or Macros to run by the TBR.
           This is captured as a AC with the constraint that every ARI
           within the AC represent a Control or Macro.

Birrane, et al.         Expires December 31, 2018              [Page 27]
Internet-Draft                     ADM                         June 2018

   (STR) Description
           This represents the human-readable description of the TBR, as
           a string.

5.3.11.  Variable (VAR)

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

   V1 = E1 * E2

   V2 = V1 + E3

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

   (ARI) Identifier
           The type of this ARI MUST be type VAR, and the ARI MUST NOT
           contain parameters.

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

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

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

Birrane, et al.         Expires December 31, 2018              [Page 28]
Internet-Draft                     ADM                         June 2018

5.3.12.  Common Object Processing

   This section describes the handling and exchange of AMM objects
   between Agents and Managers in a network.

   Managers must:

   o  Store the ARI and definitions for both network-specific and ADM-
      defined AMM Objects.

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

   o  Verify and interpret reports against report templates and tables
      against table templates when receiving these objects from an
      Agent.

   o  Encode ARIs in Objects to Agents, and decode ARIs from Agents.

   o  Provide actual parameters when sending parameterized objects to an
      Agent.

   Agents must:

   o  Store the ARI for all ADM-defined AMM objects.

   o  Calculate the value of an AMM object when required, such as when
      generating a Report or evaluating an Expression.

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

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

   o  Persist custom AMM object definitions.

   o  Add, remove, list, and describe custom AMM objects as requested by
      Managers.

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

   o  Populate Reports and Tables for transmission to Managers when
      required.

Birrane, et al.         Expires December 31, 2018              [Page 29]
Internet-Draft                     ADM                         June 2018

   o  Run the actions associated with SBRs and TBRs in accordance with
      their definitions.

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

5.4.  Data Type Mnemonics and Enumerations

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

   This section defines string (mnemonic) and integer (enumeration)
   mechanisms for referring to AMM data and object types.  Data types
   are separated into 4 major categories:

                      Category           Range
                      ------------------ ------------
                      AMM Objects Types  0x00 - 0x3F

                      Primitive Types    0x40 - 0x7F

                      Compound Types     0x80 - 0xBF

                      Reserved           0xC0 - 0xFF

                        Type Categories and Ranges

   Within each category, the type of information, it's mnemonic, unique
   enumeration value, and whether it is considered a numeric value for
   expression evaluation are listed.

5.4.1.  AMM Objects

   AMM Objects include the set of objects identifiable using the ARI
   construct.  The type field of the ARI MUST be one of these values.
   AMM Objects MUST be identified as follows.

Birrane, et al.         Expires December 31, 2018              [Page 30]
Internet-Draft                     ADM                         June 2018

   Structure                       Mnemonic       Enumeration Numeric
   ------------------------------- -------------- ----------- ----------
   Constant                        CONST          0           No

   Control                         CTRL           1           No

   Externally Defined Data         EDD            2           No

   Literal                         LIT            3           No

   Macro                           MAC            4           No

   Operator                        OPER           5           No

   Report                          RPT            6           No

   Report Template                 RPTT           7           No

   State-Based Rule                SBR            8           No

   Table                           TBL            9           No

   Table Template                  TBLT           10          No

   Time-Based Rule                 TBR            11          No

   Variable                        VAR            12          No

   Reserved                                       13-63       No

5.4.2.  Primitive Data Types

   Primitive data include the basic set of objects that must be encoded
   to transfer AMM objects.  All AMM objects are built from combinations
   of these primitive types.  Primitive types MUST be identified as
   follows.

Birrane, et al.         Expires December 31, 2018              [Page 31]
Internet-Draft                     ADM                         June 2018

   Basic Data Type                 Mnemonic       Enumeration Numeric
   ------------------------------- -------------- ----------- ----------
   Boolean                         BOOL           64          No

   BYTE                            BYTE           65          No

   Character String                STR            66          No

   Signed 32-bit Integer           INT            67          Yes

   Unsigned 32-bit Integer         UINT           68          Yes

   Signed 64-bit Integer           VAST           69          Yes

   Unsigned 64-bit Integer         UVAST          70          Yes

   Single-Precision Floating Point REAL32         71          Yes

   Double-Precision Floating Point REAL64         72          Yes

   Reserved                                       73-127      No

5.4.3.  Compound Data Types

   Compound data include combinations of primitive data types, to
   include collections.  Compound types MUST be identified as follows.

   Compound/Special Data Type      Mnemonic       Enumeration Numeric
   ------------------------------- -------------- ----------- ----------
   Time Value                      TV             128         No

   Timestamp                       TS             129         No

   Type-Name-Value                 TNV            130         No

   Type-Name-Value Collection      TNVC           131         No

   AMM Resource Identifier         ARI            132         No

   ARI Collection                  AC             133         No

   Expression                      EXPR           134         No

   Byte String                     BYTESTR        135         No

   Reserved - Protocol                            136-191     No

Birrane, et al.         Expires December 31, 2018              [Page 32]
Internet-Draft                     ADM                         June 2018

5.4.4.  Numeric Promotions

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

   Listing legal promotion rules is mandatory for ensuring that behavior
   is similar across multiple implementations of Agents and Managers.
   The listing of legal promotions in the AMM are listed in Figure 2.
   In this Figure, operands are listed across the top row and down the
   first column.  The resultant type of the promotion is listed in the
   table at their intersection.

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

                       Figure 2: Numeric Promotions

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

5.4.5.  Numeric Conversions

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

6.  JSON ADM Template

   This section provides an ADM template in the form of a JSON document
   and describes the JSON representation of AMM objects that MUST be
   used to populate this JSON ADM template.

   It is not required that these JSON encodings be used to encode the
   transmission of AMM information over the wire in the context of a
   network deployment.  It is also not required that only these JSON
   encodings be used to document ADMs and other AMM information.  Since

Birrane, et al.         Expires December 31, 2018              [Page 33]
Internet-Draft                     ADM                         June 2018

   the AMM is designed to allow for multiple encodings, the expression
   of ADMs in the provided JSON format is intended to support
   translation to other encodings without loss of information.

6.1.  ADM Inclusion

   ADMs expressed in conformance with this template are captured as
   individual JSON files.  AMM Objects defined in one ADM template MAY
   refer to objects defined in another ADM template file.  To enable
   type checking of these cross-ADM references, the ADM template
   supports the "uses" keyword to identify other ADM files that contain
   objects referenced in the current ADM file.

   The syntax of the uses statement is as follows.

   "uses":["file1","file2",...,"fileN"]

   Where file_# represents a JSON-formatted ADM file defining a
   namespace used in this ADM file.

6.2.  ADMT Object Collections

   The JSON ADM Template is defined as a JSON object containing a series
   of arrays - one for each type of information specified in the
   template.  There are arrays for:

   o  metadata constants

   o  EDD definitions

   o  VAR definitions

   o  RPTT definitions

   o  TBLT definitions

   o  CTRL definitions

   o  CONST definitions

   o  MAC definitions

   o  OP definitions

   Where each array is named after the mnemonic for the particular AMM
   object, as defined in Section 5.4.1, with the exception of the
   metadata (MDAT) array which is unique to the ADM template itself.

Birrane, et al.         Expires December 31, 2018              [Page 34]
Internet-Draft                     ADM                         June 2018

   In particular, the template does not provide definitions for RPT,
   TBL, SBR, or TBR objects as these are defined dynamically in the
   context of a network deployment.

   The general format of the JSON ADM Template is as follows.

   {
     "Mdat" : [],
     "Edd"  : [],
     "Var"  : [],
     "Rptt" : [],
     "Tblt" : [],
     "Ctrl" : [],
     "Const : [],
     "Mac"  : [],
     "Oper" : []
   }

6.3.  ADM Metadata

   The metadata array contains CONST objects that provide information
   about the ADM itself.

   (STR) name
           This is the human-readable name of the ADM that should appear
           in message logs, user-interfaces, and other human-facing
           applications.

   (STR) namespace
           This is the Moderated Namespace of the ADM, as defined in
           Section 5.1.1 and string-encoded in accordance with
           Section 5.1.5.1.

   (STR) version
           This is a string representation of the version of the ADM.
           ADM version representations are formated at the discretion of
           the publishing organization.

   (STR) organization
           This is the name of the issuing organization for this ADM.

   Metadata objects are encoded in the same way as CONST objects, in
   accordance with Section 6.6.2.

Birrane, et al.         Expires December 31, 2018              [Page 35]
Internet-Draft                     ADM                         June 2018

6.4.  Type Encodings

   This section describes the JSON encoding of AMM data types defined in
   Section 5.2.

6.4.1.  Primitive Type Encoding

   JSON data types generally have direct support for the AMM primitive
   data types.  The mapping of AMM primitive types to JSON data types is
   provided in Table 3.

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

                     Table 3: Primitive Type Encoding

6.4.2.  Derived Type Encoding

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

6.4.2.1.  Type-Name-Value

   A TNV is encoded as a JSON object with three elements: "type",
   "name", and "value".  For each item in a TNV, there are three
   acceptable formulations that can be used to represent the item, as

Birrane, et al.         Expires December 31, 2018              [Page 36]
Internet-Draft                     ADM                         June 2018

   illustrated in the following table.  For the examples in this table,
   consider the REAL32 value of PI as 3.14159.

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

                         Table 4: TNV Formulations

6.4.3.  Collection Encoding

   The TNVC and AC collections are encoded as JSON arrays, with each
   object in the array represented in accordance with the JSON encoding
   for that object type (TNV or ARI, respectively).

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

   (UINT) type
           The data type of the evaluation of the initializer
           expression.

   (AC) postfix-expr
           A JSON array of elements where each element is an JSON
           encoding of an ARI in conformance to Section 6.5.

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

   "type": "UINT",
   "postfix-expr": ["Edd.item1","Edd.item2","Oper.+UINT"]

Birrane, et al.         Expires December 31, 2018              [Page 37]
Internet-Draft                     ADM                         June 2018

6.5.  ARI Encoding

   An ARI may be encoded as either a string or as a JSON object, with
   the two representations being unambiguously interchangeable.
   Additionally, there exists a long-form and short-form encoding of the
   ARI.

   String encodings provide a more compact and human-readable
   representation of the ARI.  When an ARI is represented as a string in
   a JSON object, it MUST be encoded in accordance with Section 5.1.5.1.
   If the ARI references an object that is defined in the current ADM,
   then the shortform string encoding may be used, as described in
   Section 5.1.5.1.1.  The object name to be used in the string encoding
   is the same as the "nm" value for the JSON object encoding, as
   described below.

   JSON object encoding of the ARI provides additional structure that
   makes ARI information verification easier.  An ARI is encoded as a
   JSON object with three keys: namespace, object name, and parameters,
   encoded as follows.

   ns
           This element identifies the namespace within which the ARI
           has been defined, and encoded as a string in accordance with
           Section 5.1.5.1.  In cases where the ARI identifies an object
           defined in the ADM in which it is used, the ADM's namespace
           may be assumed as the namespace of the ADM and this element
           can be omitted from the ARI JSON object.

   nm
           The name of an object defined in an ADM is a string defined
           as the concatenation of the ADMT collection defining the
           object, the "." separator, and the string name of the object
           itself.  For example, an EDD defined in the Edd array and
           named edd1 would have the string name "Edd.edd1".

   fp
           ARI formal parameters, if present, are defined as an array
           with each element in the array representing the JSON TNV
           encoding of the parameter.  If a default value is not defined
           for the parameter, then the value of the TNV MUST be omitted.

           The fp element is not used when AMM objects are defined in
           the context of an ADM, as the ADM template for defining
           objects already includes parameter information.  This element
           is used when AMM objects are defined in accordance with the
           JSON ADM syntax, but by network operators as part of network-
           specific configuration.

Birrane, et al.         Expires December 31, 2018              [Page 38]
Internet-Draft                     ADM                         June 2018

           If the ARI JSON object has the fp element, then it MUST NOT
           have the ap element.  An ARI MUST NOT define both formal and
           actual parameters in the same object instance.

   ap
           ARI actual parameters, if present, are defined as an array
           with each element of the array representing the JSON TNV
           encoding of the parameter.  In cases where an optional
           parameter is not present, an empty TNV object will be used in
           its place for that parameter.  The name element of the TNV
           MUST NOT be present for actual parameters.

           In cases where the actual parameter is by value, then the TNV
           value key will hold the JSON encoding of the value of the
           parameter.

           In cases where the actual parameter is by name, then the TNV
           MUST have the type "ParmName" and the value MUST be the
           string name of the parameter whose value should be used to
           populate the value of this actual parameter, as described in
           Section 5.1.3.2.

           If the ARI JSON object has the fp element, then it MUST NOT
           have the ap element.  An ARI MUST NOT define both formal and
           actual parameters in the same object instance.

   The following are examples of JSON encoded ARI objects.

Birrane, et al.         Expires December 31, 2018              [Page 39]
Internet-Draft                     ADM                         June 2018

   +---------------------------+---------------------------------------+
   |      String Encoding      |             JSON Encoding             |
   +---------------------------+---------------------------------------+
   |      "N1/N2/Edd.edd1"     |    {"ns":"N1/N2", "nm":"Edd.edd1"}    |
   |                           |                                       |
   |    "N1/N2/Edd.edd2(UINT   |    {"ns":"N1/N2", "nm":"Edd.edd2",    |
   |          num=3)"          |  "fp":[{"type":"UINT", "name"="num",  |
   |                           |              value":3}]}              |
   |                           |                                       |
   |     "N1/N2/Edd.edd2()"    |    {"ns":"N1/N2", "nm":"Edd.edd2",    |
   |                           |               "ap":[{}]}              |
   |                           |                                       |
   |    "N1/N2/Edd.edd2(4)"    |    {"ns":"N1/N2", "nm":"Edd.edd2",    |
   |                           |   "ap":[{"type":"UINT", "value":4}]}  |
   |                           |                                       |
   | "N1/N2/Edd.edd3(<input>)" |    {"ns":"N1/N2", "nm":"Edd.edd3",    |
   |                           |       "ap":[{"type":"ParmName",       |
   |                           |           "value":"input"}]}          |
   +---------------------------+---------------------------------------+

                    Table 5: Formal Parameter Encoding

6.6.  ADM Structures

6.6.1.  General Notes

   The following guidelines apply to the JSON encoding of AMM objects.

   Identification
           Objects do not include an ARI object as part of their
           definition.  All of the contents of an ARI are derivable in
           the context of the ADM and adding an ARI encoding as part of
           the AMM object definition would be redundant and require
           maintaining naming information in two places in the ADM
           document.

   Common Elements
           Every JSON encoding of an AMM object MUST have the following
           elements:

           *  Name
              The identifier of the AMM Object.  This MUST be unique
              across all name elements defined in the ADM collection of
              these types of objects.

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

Birrane, et al.         Expires December 31, 2018              [Page 40]
Internet-Draft                     ADM                         June 2018

   Formal Parameters
           If an AMM object may be parameterized, then an element MUST
           be present in the JSON object named "parmspec" which is
           defined as a JSON-encoded TNVC.  Each element in the TNVC
           representing the JSON TNV encoding of the formal parameter.
           If a default value is not defined for the parameter, then the
           value of the TNV MUST be omitted.

6.6.2.  Constant (CONST) Encoding

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

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

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

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

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

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

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

6.6.3.  Control (CTRL) Encoding

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

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

           ParmSpec

Birrane, et al.         Expires December 31, 2018              [Page 41]
Internet-Draft                     ADM                         June 2018

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

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

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

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

6.6.4.  Externally Defined Data (EDD) Encoding

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

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

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

           ParmSpec
           The optional array of formal parameters encoded in accordance
           with Paragraph 3.

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

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

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

Birrane, et al.         Expires December 31, 2018              [Page 42]
Internet-Draft                     ADM                         June 2018

6.6.5.  Macro Encoding

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

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

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

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

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

    "name": "user_list",
     "definition": [{
       "nm":"Ctrl.list_vars",
       "ap": []
   },
   {
      "nm":Ctrl.list_rptts"
      "ap": []
   }],
   "description": "List user defined data."

6.6.6.  Operator (OP) Encoding

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

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

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

           In-Type

Birrane, et al.         Expires December 31, 2018              [Page 43]
Internet-Draft                     ADM                         June 2018

           This is an ordered JSON array of operands for the operator.
           Each operand is a data type encoded in accordance with
           Table 2.

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

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

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

6.6.7.  Table Template (TBLT) Encoding

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

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

           Columns
           This is a JSON array of elements, with each element
           representing the definition of the type of information
           represented in each column.  Each column is described using
           the same encoding as a TNV described in Table 4.

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

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

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

6.6.8.  Report Template Encoding

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

           Name

Birrane, et al.         Expires December 31, 2018              [Page 44]
Internet-Draft                     ADM                         June 2018

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

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

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

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

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

Birrane, et al.         Expires December 31, 2018              [Page 45]
Internet-Draft                     ADM                         June 2018

   {
      "name": "default_report",
      "parmspec": [{
         "type": "STR",
         "name": "endpoint_id"
      }],
      "definition": [
        {
           "ns": "DTN:bp",
                                "nm": "Edd.edd_using_a_parm",
           "ap": [{
              "type": "PARMNAME",
              "value": "endpoint_id"
           }]
        },
        {
                                "ns": "DTN:bp",
           "nm": "Edd.edd_with_default ",
           "ap": [{
              "type": "INT",
              "value": ""}
           ]},
        {  "ns": "DTN:bp",
           "nm": "Edd.edd_with_no_parms ",
           "ap": []
        }
      ]
      "description": "A default report."
   }

6.6.9.  Variables Encoding

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

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

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

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

Birrane, et al.         Expires December 31, 2018              [Page 46]
Internet-Draft                     ADM                         June 2018

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

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

   {
      "name": "total_bad_tx_blks",
      "type": "UINT",
      "initializer": {
         "type": "UINT",
         "postfix-expr": [{
            "nm": "Edd.item1",
           "ap": [{
               "type": "UINT",
               "value": 0
            }]
         }, {
            "nm":"Edd.item2",
            "ap":[{
               "type":"UINT",
               "value": 1
            ]}
         }, {
            "nm": "Oper.plusUINT",
            "ap":[]
         }]

      },
      "description": "# total items (# item1 + # item2)."
    }

6.6.10.  Exemptions

   Certain AMM objects are not intended to be statically defined in the
   context of an ADM document.  Literals, Reports, Tables, State-Based
   Rules, and Time-Based Rules all only have meaning in the context of
   an operational network.  These objects are defined by network
   operators as part of network-specific configuration and therefore not
   present in the ADM Template.

7.  ADM Author Considerations

   The AMM model provides multiple ways to represent certain types of
   data.  This section provides informative guidance on how to express
   application management constructs efficiently when authoring an ADM
   document.

Birrane, et al.         Expires December 31, 2018              [Page 47]
Internet-Draft                     ADM                         June 2018

   Use Parameters for Dynamic Information.
       Parameters provide a powerful mechanism for expressing
       associative look-ups of EDD data.  EDDs SHOULD be parameterized
       when the definition of the EDD is dependent upon run-time
       information.  For example, if requesting the number of bytes
       through a specific endpoint, the construct
       num_bytes("endpoint_name") is simpler to understand and more
       robust to new endpoint additions than attempting to enumerate the
       number and name of potential endpoints when defining the ADM.

   Do Not Use Parameters for Static Information.
       Parameters incur bandwidth and processing costs (such as type
       checking) and should only be used where necessary.  If an EDD
       object can be parameterized, but the set of parameters is known
       and unchanging it may be more efficient to define multiple
       unparameterized EDD objects instead.  For example, consider a
       single parameterized EDD object reporting the number of bytes of
       data received for a specific, known set of priorities and a
       request to report on those bytes for the "low", "med", and "high"
       priorities.  Below are two ways to represent these data: using
       parameters and not using parameters.

            +------------------------+------------------------+
            |   Parameterized EDDs   | Non-Parameterized EDDs |
            +------------------------+------------------------+
            | num_bytes_by_pri(low)  | num_bytes_by_low_pri   |
            | num_bytes_by_pri(med)  | num_bytes_by_med_pri   |
            | num_bytes_by_pri(high) | num_bytes_by_high_pri  |
            +------------------------+------------------------+

       The use of parameters in this case only incurs the overhead of
       type checking, parameter encoding/decoding, and associative
       lookups.  This situation should be avoided when deciding when to
       parameterize AMM objects.

   Use Tables for Related Data.
       In cases where multiple EDD or VAR values are likely to be
       evaluated together, then that information SHOULD be placed in a
       Table Template rather than defining multiple EDD and VAR objects.
       By making a Table Template, the relationships amongst various
       data values are preserved.  Otherwise, Managers would need to
       remember to query multiple EDD and/or VAR objects together which
       is burdensome, but also results in high bandwidth and processor
       utilization.

Birrane, et al.         Expires December 31, 2018              [Page 48]
Internet-Draft                     ADM                         June 2018

8.  IANA Considerations

   This document defines a moderated namespace registry in
   Section 5.1.1.1.  This registry is envisioned to be moderated by
   IANA.  Entries in this registry are to be made through Expert Review.

   This document defines a new URI scheme, "ari", as defined in
   Section 5.1.5.

9.  Security Considerations

   This document does not describe any on-the-wire encoding or other
   messaging syntax.  It is assumed that the exchange of AMM objects
   between Agents and Managers occurs within the context of an
   appropriate network environment.

   This AMM model may be extended to include the concept of Access
   Control Lists (ACLs) to enforce roles and responsibilities amongst
   Managers in the network.  This access control would be implemented
   separately from network security mechanisms.

10.  References

10.1.  Normative References

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

   [RFC3339]  Klyne, G. and C. Newman, "Date and Time on the Internet:
              Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002,
              <https://www.rfc-editor.org/info/rfc3339>.

   [RFC3986]  Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
              Resource Identifier (URI): Generic Syntax", STD 66,
              RFC 3986, DOI 10.17487/RFC3986, January 2005,
              <https://www.rfc-editor.org/info/rfc3986>.

   [RFC4648]  Josefsson, S., "The Base16, Base32, and Base64 Data
              Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006,
              <https://www.rfc-editor.org/info/rfc4648>.

10.2.  Informative References

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

Birrane, et al.         Expires December 31, 2018              [Page 49]
Internet-Draft                     ADM                         June 2018

Authors' Addresses

   Edward J. Birrane
   Johns Hopkins Applied Physics Laboratory

   Email: Edward.Birrane@jhuapl.edu

   Evana DiPietro
   Johns Hopkins Applied Physics Laboratory

   Email: Evana.DiPietro@jhuapl.edu

   David Linko
   Johns Hopkins Applied Physics Laboratory

   Email: David.Linko@jhuapl.edu

Birrane, et al.         Expires December 31, 2018              [Page 50]