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

Versions: 00 01

Delay-Tolerant Networking                                     E. Birrane
Internet-Draft                                               E. DiPietro
Intended status: Informational                                  D. Linko
Expires: May 3, 2018            Johns Hopkins Applied Physics Laboratory
                                                        October 30, 2017


                     AMA Application Data Modeling
                        draft-birrane-dtn-adm-00

Abstract

   This document defines a data model suitable for managing applications
   in asynchronously managed networks.  This includes a description of
   the data structures and type definitions that comprise the data model
   as well as a template for publishing standardized representations of
   static elements of the model.  A YANG representation of the data
   model and the template are also provided.

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 May 3, 2018.

Copyright Notice

   Copyright (c) 2017 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 May 3, 2018                  [Page 1]


Internet-Draft                     ADM                      October 2017


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

Table of Contents

   1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   3
     1.1.  Purpose . . . . . . . . . . . . . . . . . . . . . . . . .   3
     1.2.  Scope . . . . . . . . . . . . . . . . . . . . . . . . . .   3
   2.  Requirements Language . . . . . . . . . . . . . . . . . . . .   4
   3.  Terminology . . . . . . . . . . . . . . . . . . . . . . . . .   4
   4.  Data Modeling Concept of Operations . . . . . . . . . . . . .   5
   5.  Type Definitions  . . . . . . . . . . . . . . . . . . . . . .   6
     5.1.  Primitive Types . . . . . . . . . . . . . . . . . . . . .   6
     5.2.  Derived Types . . . . . . . . . . . . . . . . . . . . . .   7
       5.2.1.  Hex String  . . . . . . . . . . . . . . . . . . . . .   7
       5.2.2.  Timestamp (TS)  . . . . . . . . . . . . . . . . . . .   8
       5.2.3.  Type-Name-Value Collection  . . . . . . . . . . . . .   8
   6.  Identification  . . . . . . . . . . . . . . . . . . . . . . .   9
     6.1.  Asynchronous Resource Namespace (ARNs)  . . . . . . . . .  10
     6.2.  Managed Identifiers . . . . . . . . . . . . . . . . . . .  10
       6.2.1.  MID Semantic Information  . . . . . . . . . . . . . .  10
       6.2.2.  MID Value . . . . . . . . . . . . . . . . . . . . . .  11
       6.2.3.  MID Parameters  . . . . . . . . . . . . . . . . . . .  12
       6.2.4.  MID References  . . . . . . . . . . . . . . . . . . .  15
   7.  Collections . . . . . . . . . . . . . . . . . . . . . . . . .  15
     7.1.  MID Collection (MC) . . . . . . . . . . . . . . . . . . .  15
     7.2.  Expression (EXPR) . . . . . . . . . . . . . . . . . . . .  16
     7.3.  Predicate (PRED)  . . . . . . . . . . . . . . . . . . . .  16
   8.  ADM Structures  . . . . . . . . . . . . . . . . . . . . . . .  16
     8.1.  AMA Overview  . . . . . . . . . . . . . . . . . . . . . .  16
     8.2.  Externally Defined Data (EDD) . . . . . . . . . . . . . .  18
     8.3.  Variables (VAR) . . . . . . . . . . . . . . . . . . . . .  19
     8.4.  Tables  . . . . . . . . . . . . . . . . . . . . . . . . .  20
       8.4.1.  Table Template (TBLT) . . . . . . . . . . . . . . . .  20
       8.4.2.  Table (TBL) . . . . . . . . . . . . . . . . . . . . .  21
     8.5.  Reports . . . . . . . . . . . . . . . . . . . . . . . . .  22
       8.5.1.  Report Template (RPTT)  . . . . . . . . . . . . . . .  22
       8.5.2.  Report (RPT)  . . . . . . . . . . . . . . . . . . . .  23
     8.6.  Control (CTRL)  . . . . . . . . . . . . . . . . . . . . .  24
     8.7.  Time-Based Rule (TRL) . . . . . . . . . . . . . . . . . .  25
     8.8.  State-Based Rule (SRL)  . . . . . . . . . . . . . . . . .  27
     8.9.  Macro (MAC) . . . . . . . . . . . . . . . . . . . . . . .  28
     8.10. Constant (CONST)  . . . . . . . . . . . . . . . . . . . .  29
     8.11. Operator (OP) . . . . . . . . . . . . . . . . . . . . . .  30
   9.  Data Type IDs and Enumerations  . . . . . . . . . . . . . . .  32
     9.1.  Numeric Promotions  . . . . . . . . . . . . . . . . . . .  33
     9.2.  Numeric Conversions . . . . . . . . . . . . . . . . . . .  34
   10. YANG Modules  . . . . . . . . . . . . . . . . . . . . . . . .  34



Birrane, et al.            Expires May 3, 2018                  [Page 2]


Internet-Draft                     ADM                      October 2017


     10.1.  ADM Types and Structures . . . . . . . . . . . . . . . .  34
     10.2.  Application Data Template  . . . . . . . . . . . . . . .  47
   11. IANA Considerations . . . . . . . . . . . . . . . . . . . . .  49
   12. Security Considerations . . . . . . . . . . . . . . . . . . .  50
   13. Informative References  . . . . . . . . . . . . . . . . . . .  50
   Authors' Addresses  . . . . . . . . . . . . . . . . . . . . . . .  50

1.  Introduction

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

1.1.  Purpose

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

   This document provides a normative physical model, called an
   Application Data Model (ADM), that is compliant with the AMA logical
   data model and can be used to manage individual applications (or
   protocols).  An ADM is comprised of both predefined and dynamic
   information.  Predefined information is represented in an Application
   Data Definition (ADD) document populated in conformance with an an
   Application Data Template (ADT).  Dynamic information is created on-
   the-fly by operators in the context of individual network deployments
   and management scenarios.

1.2.  Scope

   The ADM presented in this document is a data model.  In order to
   communicate this model between agents and managers in a network, the
   model must be encoded for transmission.  Any such encoding scheme is
   outside of the scope of this document.  Generally, encoding of the
   model is a separate concern from the specification of data within the
   model.

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



Birrane, et al.            Expires May 3, 2018                  [Page 3]


Internet-Draft                     ADM                      October 2017


   information necessary to allow for the coherent translation of of
   different encodings.

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

2.  Requirements Language

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

3.  Terminology

   Note: The terms "Actor", "Agent", "Application Data Model", "Atomic
   Data", "Computed Data", "Control", "Literal", "Macro", "Manager",
   "Report Template", "Report Entry", and "Rule" are used without
   modification from the definitions provided in [AMA].

   Additional terms critical to understanding the ADMT 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 Definitions (ADD) - The set of predefined data
      items for an ADM, captured in the format of the ADT.

   o  Application Data Model (ADM) - The full set of data items
      necessary to manage an application (or set of applications)
      asynchronously.  This includes both predefined and dynamically-
      constructed data items.

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

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

   o  Report (RPT) - An ordered collection of report entries gathered by
      an Agent and provided to one or more Managers.  Reports represent
      the fundamental unit of data exchange from an Agent to a Manager.




Birrane, et al.            Expires May 3, 2018                  [Page 4]


Internet-Draft                     ADM                      October 2017


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

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

4.  Data Modeling Concept of Operations

   When a new application is to be asynchronously managed in accordance
   with the [I-D.birrane-dtn-ama], the series of control and data
   information specific to that application must be captured in a data
   model.  Portions of that data model will be predefined and common to
   all instances of the application and portions of the data model will
   be ad-hoc in the context of specific network deployments and
   operational conditions.

   The conceptual set of all information necessary to manage an
   application is defined as the data model for that application and
   termed the Application Data Model (ADM).  The portions of the ADM
   that are predefined can be published as a common set of management
   information that is otherwise agnostic of any specific network
   deployment.  That set of predefined information is termed the
   Application Data Definitions (ADD).

   To aid in the exchange of data model information, a common
   identification scheme and data format should be used to capture
   information.  This is defined in this document as a template that can
   be filled out for each application and is terms the Application Data
   Template (ADT).

   The relationship of the ADM, ADD, and ADT are illustrated in
   Figure 1.


















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


Internet-Draft                     ADM                      October 2017


                          Data Model Relationship


                                             +---------+
                                             |   ADT   |
                                             +----+----+
                                                  |
                                                  V
                          +---------+       +-----------+
                          |  Ad-Hoc |       | Published |
                          |  Info   |       |    ADD    |
                          +----+----+       +-----+-----+
                               |                  |
                               V                  V
                          +-----------------------------+
                          |             ADM             |
                          +-----------------------------+

                                 Figure 1

5.  Type Definitions

   This section describes custom type definitions used by the ADM.
   Specifying basic type definitions is important as it forms the basis
   for interchangeable encodings of the model.

5.1.  Primitive Types

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





















Birrane, et al.            Expires May 3, 2018                  [Page 6]


Internet-Draft                     ADM                      October 2017


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

                         Table 1: Primitive Types

5.2.  Derived Types

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

5.2.1.  Hex String

   A Hex String is a special type of STRING.

   A Hex String contents a written representation of a hexadecimal
   value, without prefix.  In this scheme, byte values are separated by
   colons (:).  While either upper or lower case characters are
   acceptable, by convention lower-case characters should be used for
   increased readability.

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





Birrane, et al.            Expires May 3, 2018                  [Page 7]


Internet-Draft                     ADM                      October 2017


   Hex Strings follow the format of the hex-string derived type as
   defined in RFC6991.

5.2.2.  Timestamp (TS)

   A Timestamp is a special type of UVAST.

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

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

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

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

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


5.2.3.  Type-Name-Value Collection

   A Type-Name-Value Collection (TNV) is a special type of STRING.

   A TNV describes a list of ADM items with each item described as the
   three-tuple of {type, name, value} or certain permitted subsets of
   that three-tuple.  The general form of the string is




Birrane, et al.            Expires May 3, 2018                  [Page 8]


Internet-Draft                     ADM                      October 2017


   <type>:<name>=<value> with each item in the collection separated by
   "&".

   Type refers to the string representation of the ADM item type as
   defined in Section 9.  Name refers to the name of the ADM item.
   Value refers to the string (or hex string) value of the ADM item.

   For each item in a TNV, there are three acceptable formulations that
   can be used to represent the item, as illustrated in the following
   table.  For the examples in this table, consider the REAL32 value of
   PI as 3.14159.

   +----------+---------------------+----------------------------------+
   |   Desc   |        Format       |             Example              |
   +----------+---------------------+----------------------------------+
   |   Full   | <type>:<name>=<valu |  REAL32:PI=3.14159&INT:PI_INT=3  |
   |          |          e>         |                                  |
   |          |                     |                                  |
   |  Named   |    <type>:<name>    |       REAL32:PI&INT:PI_INT       |
   |   Type   |                     |                                  |
   |          |                     |                                  |
   | Anonymou |        <type>       |            REAL32&INT            |
   |  s Type  |                     |                                  |
   |          |                     |                                  |
   | Anonymou |   <type>:=<value>   |      REAL32:=3.14159&INT:=3      |
   |  s Type  |                     |                                  |
   |  Value   |                     |                                  |
   |          |                     |                                  |
   | Anonymou |       =<value>      |           =3.14159&=3            |
   | s Value  |                     |                                  |
   |          |                     |                                  |
   |  Mixed   |        Varies       | REAL32:PI=3.14159&INT:PI_INT&INT |
   |          |                     |               &=3                |
   +----------+---------------------+----------------------------------+

                         Table 2: TNV Formulations

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

6.  Identification

   The primary responsibility of an ADM is to uniquely identify the
   components necessary to asynchronously manage the application.  This
   section describes the two mechanisms used to identify every item
   within every ADM: Asynchronous Resource Names (ARNs) and Managed
   Identifiers (MIDs).




Birrane, et al.            Expires May 3, 2018                  [Page 9]


Internet-Draft                     ADM                      October 2017


6.1.  Asynchronous Resource Namespace (ARNs)

   Every ADM must identify itself by an asynchronous resource namespace
   (ARN).  This is separate from the YANG namespace and provides a
   moderated, formatted way of identifying the ADM in the context of
   other ADMs.  Such a naming provides important semantic information
   necessary for encodings of ADM contents.  The format of an ARN is a
   colon-separated set of moderated scoping keywords, as follows.

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

   For example, the DTN community publishes the Bundle Protocol and the
   ADM for the Bundle Protocol could be assigned the namespace
   arn:Dtn:BundleProtocol.  Another ADM published specifically for
   management of a particular implementation of a Bundle Protocol Agent
   (for example, the Interplanetary Overlay network (ION)) could have
   the separate namespace arn:DTN:ION:BundleProtocolAdmin.

   ARN keywords will be moderated to create a known keyword list and
   associated ontology that provides some semantic structure to ADM
   names beyond the associations that may or may not be present to allow
   groupings in the YANG format.

6.2.  Managed Identifiers

   Every item codified in a published ADM (or generated in operational
   use) must be uniquely identifiable.  The Managed Identifier (MID)
   accomplishes this by providing a variable-length, flexible structure
   with optional fields to capture special identifier-related
   circumstances.

   A MID in an ADM consists of three types of information: (1) human-
   readable semantic information, (2) the identifier value, and (3)
   parameters, if necessary.

6.2.1.  MID Semantic Information

   A MID can have an optional name and description associated with it.
   These help provide documentation of the ADM item identified by the
   MID.

   The MID Name is a string that should uniquely identify the ADM item
   within the context of the ADM.  It is recommended that this name be a
   human-readable and user-friendly alternative to the numeric ID
   portion of the MID.

   The MID Description is a string that captures important information
   describing the purpose of usage of the ADM item.  The description



Birrane, et al.            Expires May 3, 2018                 [Page 10]


Internet-Draft                     ADM                      October 2017


   should also be human-readable and user-friendly.  The MID description
   is not considered part of the uniquely identifying part of the MID
   and may be duplicated across multiple MIDs in an ADM.  No part of the
   MID description should be used to interpret the uniqueness of any ADM
   item.

6.2.2.  MID Value

   There are two categories of information that can be identified by a
   MID in an ADM: named and literal items.  A named item is an item in
   an ADM whose value should not be used as its identifier.  This can be
   because the value is not unique to the item, or the value is of such
   length or complexity as to make its use as an identifier impractical.
   A literal item is one that can be uniquely and succinctly identified
   by its value.

6.2.2.1.  Named Item

   The identification of a named item consists of four parts: (1) The
   type of item being identified, (2) a unique identifying value for the
   item, (3) an optional issuer field, and (4) an optional tag field.
   These four items are represented as a string with the format
   <Type>_<enumeration>:<issuer>:<tag>.  The description of each of
   these types is as follows.

   Item Type
   The type of the ADM item being identified is the string
   representation of the type, as defined in Section 9.

   Unique Identifier
   The identifier may be any uniquely identifying information, such as
   the name of the MID, or a numeric enumeration of the order of the MID
   in the ADM.

   Issuer
   The issuer field is any string (or hex string) representing some
   identification of the organization defining this item.  This value
   may come from a global registry of organizations, an issuing node
   address, a signed known value, or some other network-unique marking.
   When an item is defined in the context of an ADM, the issuer tag MUST
   NOT be present.  ADD-defined items are defined relative to their ARN
   and need no additional information to determine their issuer.
   Therefore, the issuer tag is only present in ADM items created on-
   the-fly as part of an operational network.

   Tag
   The tag field is any string (including a hex string) used to
   disambiguate or otherwise validate a MID created by an issuer.



Birrane, et al.            Expires May 3, 2018                 [Page 11]


Internet-Draft                     ADM                      October 2017


   Similar to the issuer field, the tag field MUST NOT be present in a
   MID identified in an ADM.  Since a tag field has meaning only in the
   context of its issuer it MUST NOT be present in a MID that is lacking
   an issuer field.  The contents of the tag field is left to the
   discretion of the issuer.  Examples of envisioned tag values include
   an issuer-known version number or a signed or unsigned hashing of the
   data associated with the MID.

6.2.2.2.  Literal Item

   The identification of a literal item consists of three parts: (1) The
   type of item being identified, (2) the data type of the value, and
   (3) the value of the item.  These two items are represented as a
   string in the ADM with the format <Type>_<value type>.<value>.  The
   description of each of these types is as follows.

   Item Type
   The type of a literal item MUST be LIT.

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

   Value
   The value is simply the value of the item.

   For example, here are some ways of identifying the literal value "9"
   in an ADM.

              +---------------------------+----------------+
              |        Description        |    Example     |
              +---------------------------+----------------+
              |    As a signed integer    |   LIT_INT.9    |
              |                           |                |
              |   As an unsigned integer  |   LIT_UINT.9   |
              |                           |                |
              | As a floating point value | LIT_REAL32.9.0 |
              |                           |                |
              |        As a string        |  LIT_STR.Nine  |
              +---------------------------+----------------+

                            Sample Literal MIDs

6.2.3.  MID Parameters

   Certain ADM items can be parameterized to support a cleaner and less-
   chatty interface between agents and managers.  When a MID is
   parameterized, a parameter specification is appended to the end of



Birrane, et al.            Expires May 3, 2018                 [Page 12]


Internet-Draft                     ADM                      October 2017


   the string representation of the MID.  This specification may capture
   "formal parameters" or "actual parameters".  The ADM also supports
   the specification of optional parameters.

6.2.3.1.  Formal Parameters

   A "formal parameter" defines the type, name, and order of the
   variables that should be provided to the MID.  Formal parameters are
   defined in the context of an ADM using static, strong typing.  This
   approach is similar to how parameters are defined in a function
   definition, such as "foo(int a, float b)".  In this example, the
   function foo is defined as accepting two variables: an integer named
   "a" and a floating point value named "b".

   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.

   Formal parameters are represented in a MID using a TNV Collection.
   The TNV for the example above could be represented as
   "INT:a&REAL32:b".  Also, if parameter a had a default value of 7, the
   Formal Parameter list could have been represented as
   "INT:a=7&REAL32:b".

6.2.3.2.  Actual Parameters

   An "actual parameter" defines the type, name, and value of a set of
   variables that serve as arguments for a previously-defined formal
   parameter set.  Actual parameters are used when a particular instance
   of a parameterized ADM item is generated by an Agent or a Manager and
   the MID of that instance must contain values that match, in type and
   number, the formal parameters of the ADM item.  Using the "foo"
   example above, an actual parameter list would be represented in the
   call "foo(3, 3.14)".

   An Actual Parameter MAY have any combination of TYPE or VALUE
   information.  If the Formal Parameter list defined a default value,
   then the associated Actual Parameter MAY also be empty.  If a TYPE is
   provided in an Actual Parameter then the type MUST match the type
   provided by the Formal Parameter.  An Actual Parameter MUST NOT
   include NAME information.

   Actual parameters are represented in a MID using a TNV string.  The
   TNV for the example above could be represented as
   "INT:a=3&REAL32:b=3.14".  If parameter a had a default value defined,
   then another possible Actual Parameter list for the above example
   could be represented as "INT:=&b=3.14" or simply "&b=3.14".



Birrane, et al.            Expires May 3, 2018                 [Page 13]


Internet-Draft                     ADM                      October 2017


6.2.3.3.  Optional Parameters

   When parameterizing an ADM item, some parameters may be optional with
   default values defined if parameters are omitted.  The use of
   optional parameters helps keep MID values small when using default
   values for parameters is a common case, rather than forcing all
   parameters to be provided all the time.

   Consider the following TNV string capturing a set of formal
   parameters: "INT:a&REAL32:b&UINT:c=0&INT:d=-1".  The following table
   shows the values of formal parameters c and d given a variety of TNV
   strings representing actual parameters.

   +-------------------------------------+----------+------------------+
   |           Actual Parameter          | C Value  |     D Value      |
   +-------------------------------------+----------+------------------+
   |         INT:=3&REAL32:=3.14         |    0     |        -1        |
   |                                     |          |                  |
   |     INT:=3&REAL32:=3.14&UINT:=1     |    1     |        -1        |
   |                                     |          |                  |
   | INT:=3&REAL32:=3.14&UINT:=1&INT:=-2 |    1     |        -2        |
   |                                     |          |                  |
   |     INT:=3&REAL32:=3.14&&INT:=-2    |    0     |        -2        |
   +-------------------------------------+----------+------------------+

                         Table 3: TNV Formulations

6.2.3.4.  Parameter Evaluation

   Actual Parameters in a MID may be represented in one of two ways: the
   parameter itself (parameter by value), or an expression used to
   determine the parameter (parameter by evaluation).

6.2.3.4.1.  Parameter By Value

   When specifying a parameter using a value, the type of the Actual
   Parameter MUST be present and MUST match the expected Formal
   Parameter type.  The Actual Parameter value will be used as the value
   of the parameter.

   For example, consider a Formal Parameter list that takes 1 parameter,
   an unsigned integer (UINT).  When populating this parameter by value,
   the type of the Actual Parameter MUST be UINT and the parameter value
   MUST be the desired unsigned integer.







Birrane, et al.            Expires May 3, 2018                 [Page 14]


Internet-Draft                     ADM                      October 2017


6.2.3.4.2.  Parameter By Evaluation

   When the value of a Actual Parameter is likely to change, an
   Expression (EXPR) may be substituted for the Actual Parameter value.
   The Expression can then be evaluated to calculate the value.

   An Actual Parameter defined by evaluation MUST be of type EXPR, and
   the type of the EXPR must be equal to the expected type.  Expressions
   and Expression types are discussed in Section 3.6.2.

   NOTE: If the type of the Formal Parameter is already EXPR, and an
   Actual Parameter of type EXPR is provided, then the Actual Parameter
   MUST be processed in the same way as Parameter By Value.  The ADM
   does not support an EXPR which references another EXPR as doing so
   leads to significant confusion in implementations and the possibility
   of circular reference.

6.2.3.4.3.  Identifying Parameter Approach

   The determination of whether an Actual Parameter should be
   interpreted by value or by evaluation is made by comparing the given
   type of the Actual Parameter to the expected type of the Formal
   Parameter.

   If the types match, then the Actual Parameter MUST be considered by
   value.  If the Actual Parameter type is an EXPR and the EXPR type
   matches the Formal Parameter type, then the Actual Parameter MUST be
   considered by evaluation of the EXPR.  In any other case, the Actual
   Parameter MUST be considered invalid as being from a type mismatch.

6.2.4.  MID References

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

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

7.  Collections

7.1.  MID Collection (MC)

   Often, in either an ADM or an ADD, it is necessary to discuss
   collections of items that are provided as parameters to other items.
   For example, a Control that is used to generate a series of Report



Birrane, et al.            Expires May 3, 2018                 [Page 15]


Internet-Draft                     ADM                      October 2017


   Entries may accept, as a parameter, a list of the MIDs defining the
   Report Templates to be generated.

   A MC may be represented as a string that contains zero or more MID
   representations separated by whitespace.  A MID within a MC MAY be
   either a MID Reference or a MID Identifier.

   A MC may alternatively be represented as an array with zero or more
   elements, with each element being a MID representation (either a MID
   reference or a MID identifier).

7.2.  Expression (EXPR)

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

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

7.3.  Predicate (PRED)

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

8.  ADM Structures

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

8.1.  AMA Overview

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









Birrane, et al.            Expires May 3, 2018                 [Page 16]


Internet-Draft                     ADM                      October 2017


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

                          AMA Logical Components

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







Birrane, et al.            Expires May 3, 2018                 [Page 17]


Internet-Draft                     ADM                      October 2017


8.2.  Externally Defined Data (EDD)

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

8.2.1.  Definition

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

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

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

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

8.2.2.  Processing

   Managers

   o  Store the MID for each known EDD definition.

   o  Associate a data type to each known EDD definition.

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

   Agents

   o  Store the MID for each known EDD definition.

   o  Associate a data type to each known EDD definition.

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



Birrane, et al.            Expires May 3, 2018                 [Page 18]


Internet-Draft                     ADM                      October 2017


8.3.  Variables (VAR)

   Variables (VAR) may be predefined in an ADD or dynamically 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

8.3.1.  Definition

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

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

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

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

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

8.3.2.  Processing

   Managers

   o  Store the MID for each ADD-defined VAR definition.




Birrane, et al.            Expires May 3, 2018                 [Page 19]


Internet-Draft                     ADM                      October 2017


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

   o  Remember custom VAR definitions.

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

   Agents

   o  Store the MID for each ADD-defined VAR definition.

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

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

8.4.  Tables

   A Table is a named, typed, collection of tabular data.  Columns
   within a table are named and typed.  Rows within a table capture
   individual data sets with one value in each row corresponding to one
   column in the table.

   Tables are represented in two ways in the ADM: Table Definitions and
   Table Instances.  A Table Definition appears in an ADD and describes
   the general format of a table.  A Table Instance is a set of data
   populated according to the structure of a Table Definition.

8.4.1.  Table Template (TBLT)

   Table definitions are predefined items of an ADM and, as such, MUST
   appear in the ADD for an application.

8.4.1.1.  Definition

   TBLTs are defined by a MID, a set of column descriptions, and a
   description, as follows.

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

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




Birrane, et al.            Expires May 3, 2018                 [Page 20]


Internet-Draft                     ADM                      October 2017


           The type of each column MUST be one of the primitive types
           defined in Table 1.
           A column description is represented as a TNV string that MUST
           contain TYPE and NAME information and MUST NOT contain VALUE
           information.  For example, a table with three columns could
           be represented by the TNV string
           "REAL32:col1&INT:col2&UINT:col3".

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

8.4.2.  Table (TBL)

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

8.4.2.1.  Definition

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

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

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

   Rows Information
           Each row in a TBL is represented as the number of data
           elements in the row, followed by the data elements
           themselves.
           The number of data values for each row MUST be equal to the
           number of columns defined for the Table Template.
           The data values for each row are represented by a TNV that
           optionally contains TYPE information and MUST contain value
           information.  Type information MAY be included when necessary
           to verify that elements entered into a table match the type
           expected by a column in the table.
           For example, given the above Table Template example, a valid
           row could be represented as "=3.14&=3&=3" or as
           "REAL32:=3.14&INT:=3&UINT:=3".




Birrane, et al.            Expires May 3, 2018                 [Page 21]


Internet-Draft                     ADM                      October 2017


8.4.3.  Processing

   Managers

   o  Store the MID for each ADD-defined Table Template definition.

   o  Request that Agents populate tables according to this template.

   Agents

   o  Store the MID for each ADD-defined Table Template definition.

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

8.5.  Reports

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

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

8.5.1.  Report Template (RPTT)

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

8.5.1.1.  Definition

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

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




Birrane, et al.            Expires May 3, 2018                 [Page 22]


Internet-Draft                     ADM                      October 2017


   Entries
           The list of ordered data items to be included in the report
           is represented by the list of identifiers for those items.
           Since every structure in the ADM can be identified by a MID,
           this value is represented by a MC.
           NOTE: Since a RPTT is identified by a MID, it is possible
           that a RPTT contains the MID of another RPTT.  This signifies
           that a report has, as one of its entries, another report.
           This is allowed in the system, but MUST NOT lead to circular
           references.

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

8.5.2.  Report (RPT)

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

8.5.2.1.  Definition

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

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

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






Birrane, et al.            Expires May 3, 2018                 [Page 23]


Internet-Draft                     ADM                      October 2017


8.5.3.  Processing

   Managers

   o  Store the MID for each ADD-defined Report Template.

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

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

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

   Agents

   o  Store the MID for each ADD-defined Report Template.

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

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

8.6.  Control (CTRL)

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

8.6.1.  Definition

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

   MID
           This is the MID identifying the Control.  The MID MUST be of
           type CTRL.  Since Controls are only defined in ADDs, this MID
           MUST NOT have an Issuer field and MUST NOT have a Tag field.
           The MID MAY have parameters.
           When defined in the context of an ADD, the Control MID MUST
           match the definition of a Formal Parameter list (e.g., there
           are no VALUES).  This is because the ADD defines the Controls
           that can be invoked, but does not define any particular
           invocation of a Control.




Birrane, et al.            Expires May 3, 2018                 [Page 24]


Internet-Draft                     ADM                      October 2017


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

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

8.6.2.  Processing

   Managers

   o  Store the MID for each ADD-defined Control definition.

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

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

   Agents

   o  Store the MID for each ADD-defined Control definition.

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

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

8.7.  Time-Based Rule (TRL)

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

   Examples of TRLs include:





Birrane, et al.            Expires May 3, 2018                 [Page 25]


Internet-Draft                     ADM                      October 2017


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

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

8.7.1.  Definition

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

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

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

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

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

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

8.7.2.  Processing

   Managers

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

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




Birrane, et al.            Expires May 3, 2018                 [Page 26]


Internet-Draft                     ADM                      October 2017


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

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

   Agents

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

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

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

   o  Report on the status of TRLs.

8.8.  State-Based Rule (SRL)

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

   Examples of SRLs include:

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

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

8.8.1.  Definition

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

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

   CONDITION



Birrane, et al.            Expires May 3, 2018                 [Page 27]


Internet-Draft                     ADM                      October 2017


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

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

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

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

8.8.2.  Processing

   Managers

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

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

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

   Agents

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

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

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

8.9.  Macro (MAC)

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






Birrane, et al.            Expires May 3, 2018                 [Page 28]


Internet-Draft                     ADM                      October 2017


8.9.1.  Definition

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

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

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

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

8.9.2.  Processing

   Managers

   o  Store the MID for each ADD-defined Macro definition.

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

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

   Agents

   o  Store the MID for each ADD-defined Macro definition.

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

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

8.10.  Constant (CONST)

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




Birrane, et al.            Expires May 3, 2018                 [Page 29]


Internet-Draft                     ADM                      October 2017


8.10.1.  Definition

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

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

   Typed Value
           The value of a constant is the immutable value that should be
           used in lieu of the Constant MID when evaluating Expressions
           and Predicates.
           The typed value of a CONST is represented by a TNV collection
           that MUST have 1 element and MUST contain a TYPE and a VALUE
           and MUST NOT contain a NAME.  An example of a typed value for
           a CONST would be ""REAL32:=3.14".

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

8.10.2.  Processing

   Managers

   o  Store the MID for each ADD-defined Constant definition.

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

   Agents

   o  Store the MID for each ADD-defined Constant definition.

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

8.11.  Operator (OP)

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





Birrane, et al.            Expires May 3, 2018                 [Page 30]


Internet-Draft                     ADM                      October 2017


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

8.11.1.  Definition

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

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

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

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

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

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

8.11.2.  Processing

   Managers

   o  Store the MID for each ADD-defined Operator definition.

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

   Agents

   o  Store the MID for each ADD-defined Operator definition.



Birrane, et al.            Expires May 3, 2018                 [Page 31]


Internet-Draft                     ADM                      October 2017


   o  Store the number of parameters expected for each Operator.

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

9.  Data Type IDs and Enumerations

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

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

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

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

   Variable                        VAR            1           No

   Table Template                  TBLT           2           No

   Report Template                 RPTT           3           No

   Control                         CTRL           4           No

   Time-Based Rule                 TRL            5           No

   State-Based Rule                SRL            6           No

   Macro                           MACRO          7           No

   Constant                        CONST          8           No

   Operator                        OP             9           No







Birrane, et al.            Expires May 3, 2018                 [Page 32]


Internet-Draft                     ADM                      October 2017


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

   Signed 32-bit Integer           INT            11          Yes

   Unsigned 32-bit Integer         UINT           12          Yes

   Signed 64-bit Integer           VAST           13          Yes

   Unsigned 64-bit Integer         UVAST          14          Yes

   Single-Precision Floating Point REAL32         15          Yes

   Double-Precision Floating Point REAL64         16          Yes

   Character String                STR            17          No

   Boolean                         BOOL           18          No

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

   Timestamp                       TS             20          No

   Type-Name-Value Collection      TNV            21          No

   Asynchronous Resource Namespace ARN            22          No

   Managed Identifier              MID            23          No

   MID Collection                  MC             24          No

   Expression                      EXPR           25          No

   Predicate                       EXPR           26          No

9.1.  Numeric Promotions

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

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



Birrane, et al.            Expires May 3, 2018                 [Page 33]


Internet-Draft                     ADM                      October 2017


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


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


                       Figure 2: Numeric Promotions

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

9.2.  Numeric Conversions

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

10.  YANG Modules

   This section contains three sets of YANG modules which capture the
   ADM and ADT concepts.

10.1.  ADM Types and Structures

   There are two YANG modules that capture all elements of the ADM:
   basic structures and complex structures, as follows.

module basic-structures{
  yang-version 1.1;

  namespace "urn:ietf:params:xml:ns:yang:basic-structures";

  prefix basic;




Birrane, et al.            Expires May 3, 2018                 [Page 34]


Internet-Draft                     ADM                      October 2017


  organization "JHUAPL";

  contact
    "Edward.Birrane@jhuapl.edu";

  revision "2017-10-30" {
     description "Initial Revision";
  }

  description
    "This YANG module models the basic structures and collections that make up the complex structures in asynchronous systems.";

  typedef type-enum{
    type enumeration{
      enum EDD{description "external defined data";}
      enum VAR{description "variable";}
      enum RPT{description "report";}
      enum CTRL{description "control";}
      enum SRL{description "state-based rule";}
      enum TRL{description "time-based rule";}
      enum MACRO{description "macro";}
      enum CONST{description "constant";}
      enum OP{description "operator";}
      enum TBL{description "table";}//moved to capture in a nibble
      enum LIT{description "literal";}
      enum BYTE{description "unsigned byte value";}
      enum INT{description "32bit signed integer";}
      enum UINT{description "32bit unsigned integer";}
      enum VAST{description "64bit signed integer";}
      enum UVAST{description "64bit unsigned integer";}
      enum REAL32{description "32bit floating point";}
      enum REAL64{description "64bit floating point";}
      enum BOOL{description "boolean";}
      enum SDNV{description "self-delimiting numeric value";}
      enum TS{description "timestamp";}
      enum STR{description "string";}
      enum BLOB{description "binary large object";}
      enum MID{description "managed identifier";}
      enum MC{description "MID collection";}
      enum EXPR{description "expression";}
      enum DC{description "data-collection";}
      enum TC{description "type-collection";}
      enum TDC{description "type-data-collection";}
    }
    description "This is the enumeration for the various basic data types.";
  }

  typedef hex-string{



Birrane, et al.            Expires May 3, 2018                 [Page 35]


Internet-Draft                     ADM                      October 2017


    type string{
      pattern
        '[0-9a-fA-F]{2}(:[0-9a-fA-F]{2})*';
    }

    description
      "This defines a hexadecimal string with octets represented as hex digits
      separated by colons. The canonical representation uses
      lowercase characters.";

    reference
      "RFC 6991:Common YANG Data Types";
  }

  typedef mid-ref{
    type string{
      pattern
        '^(EDD|VAR|RPT|CTRL|SRL|TRL|MACRO|CONST|OP|TBL).\w+$';
    }
    description
      "A mid reference uses the MID's type and it's unique name to quickly identify it.
      They are used in MID collections to avoid restating already defined MIDs, helping to reduce space.";
  }

  typedef ts{
    type uint64;
    description
      "A timestamp value can represent either a relative or absolute time.
      A relative time is defined as the number of seconds between two events.
      An absolute time is defined as UTC time using the UNIX/POSIX Epoch.";
  }

  typedef type-name-value-collection{
    type string{
      pattern
        '^((EDD|VAR|RPT|CTRL|SRL|TRL|MACRO|CONST|OP|BYTE|INT|UINT|VAST|UVAST|REAL32|REAL64|BOOL|SDNV|TS|STR|BLOB|MID|MC|EXR|DC|TDC|TBL):\S+(&(EDD|VAR|RPT|CTRL|SRL|TRL|MACRO|CONST|OP|BYTE|INT|UINT|VAST|UVAST|REAL32|REAL64|BOOL|SDNV|TS|STR|BLOB|MID|MC|EXR|DC|TDC|TBL):\S+)*)|(^\S+=\S+(&\S+=\S+)*)|((EDD|VAR|RPT|CTRL|SRL|TRL|MACRO|CONST|OP|BYTE|INT|UINT|VAST|UVAST|REAL32|REAL64|BOOL|SDNV|TS|STR|BLOB|MID|MC|EXR|DC|TDC|TBL):\S+=\S+(&(EDD|VAR|RPT|CTRL|SRL|TRL|MACRO|CONST|OP|BYTE|INT|UINT|VAST|UVAST|REAL32|REAL64|BOOL|SDNV|TS|STR|BLOB|MID|MC|EXR|DC|TDC|TBL):\S+=\S+)*)(&((EDD|VAR|RPT|CTRL|SRL|TRL|MACRO|CONST|OP|BYTE|INT|UINT|VAST|UVAST|REAL32|REAL64|BOOL|SDNV|TS|STR|BLOB|MID|MC|EXR|DC|TDC|TBL):\S+(&(EDD|VAR|RPT|CTRL|SRL|TRL|MACRO|CONST|OP|BYTE|INT|UINT|VAST|UVAST|REAL32|REAL64|BOOL|SDNV|TS|STR|BLOB|MID|MC|EXR|DC|TDC|TBL):\S+)*)|(^\S+=\S+(&\S+=\S+)*)|((EDD|VAR|RPT|CTRL|SRL|TRL|MACRO|CONST|OP|BYTE|INT|UINT|VAST|UVAST|REAL32|REAL64|BOOL|SDNV|TS|STR|BLOB|MID|MC|EXR|DC|TDC|TBL):\S+=\S+(&(EDD|VAR|RPT|CTRL|SRL|TRL|MACRO|CONST|OP|BYTE|INT|UINT|VAST|UVAST|REAL32|REAL64|BOOL|SDNV|TS|STR|BLOB|MID|MC|EXR|DC|TDC|TBL):\S+=\S+)*))*$';
    }
    description
      "A TNV collection describes a list of ADM items where each item is described as a three tuple of {type, name, value}
      or certain permitted subsets of that three-tuple.
      GENERAL FORMAT- <type>:<name>=<value>";
  }

  grouping mid{
    description
      "A managed identifier(MID) is used to provide unique naming for structures.
      There is a general MID format for everything except for Literals.
      Literal MIDs are interpreted in a different way to express numeric values without the need to store numbers as full MIDs.



Birrane, et al.            Expires May 3, 2018                 [Page 36]


Internet-Draft                     ADM                      October 2017


      Regular expressions are used to show a general human readable organization of a MID.";

   leaf name{
      type string;
      description
        "The human readable name identifying the MID. Should act as the key in the structure containing the MIDs.";
    }

    choice mid{
      case reg-mid{
        leaf id{
          type string{
            pattern
              '^(EDD|VAR|RPT|CTRL|SRL|TRL|MACRO|CONST|OP|TBL)_(\w+)(\.\w+)?(:\w+(:\w+)?)?$';
          }
          mandatory true;
          description
            "This pattern organizes the needed information for a MID.
            <TYPE>_<ID>.<opt nicknamed>:<opt issuer>:<opt tag>

            The type and ID field is mandatory. Everything else is optional and can be left as an empty section.
            The type gives the type of the identifed object. The ID is the unique ID of the object.
            The optional but encouraged nickname helps to reduce the total space of the MID.
            The optional issuer represents a predetermined issuer name.
            The optional tag is used to disambiguate multiple MIDs with the same OID/Issuer combination. MIDs can't have a tag without an issuer.

            ex.) VAR_01.14 => MID for a for a non-parameterized compressed variable with nickname 14 and id 01";
        }

        choice params{
          case proto{
            leaf paramspec-proto{
              type type-name-value-collection;
              description
                "In a proto-mid, parameters represents a prototype with parameters being a type collection.";
            }
          }

          case full{
            leaf paramspec{
              type type-name-value-collection;
              description
                "This parameter specification can represent a function call with the parameters being a typed data collection.";
            }
          }
          description
            "Depending on if the MID's parameters have values or not, a type-collection or a type-data-collection could be used.";
        }



Birrane, et al.            Expires May 3, 2018                 [Page 37]


Internet-Draft                     ADM                      October 2017


      }

      case LIT-mid{
        leaf num-id{
          type string{
            pattern
              '^LIT_(INT|UINT|VAST|UVAST|REAL32|REAL64)\.(\d+(\.\d+))?$';
          }
          mandatory true;
          description
            "Literals are specialized MIDs.
            Since Literals are not stored and evaluated when needed, there is no 'name field' associated with them.
            Literals only contain type value information.

            ex.) LIT_INT.9 is how the integer value 9 would be expressed";
        }
      }
      mandatory true;
      description
        "You can use either a standard MID or a specialized literal MID to represent numbers.";
    }
  }

  grouping mid-collection{
    description
      "A mid collection(MC) is a collection of MIDs. The ideal way to show a MC is to list the MIDs using a mid-ref or nickname id pair,
      and use the full-MIDs only when that MID is being defined for the first time.";

    choice mc-type{
      case string{
        leaf string-mc{
          type string;
          description
            "The MID collection is represented using a string to list all the mids.
            If it contains MIDs that have already been defined, then it should use the mid-ref format previously stated.
            MIDs are separated by spaces.";
          }
        }
      case array{
        leaf-list array-mc{
          type string;
          description
            "The MID collection is represented using an array to list all the MIDs.
            If it contains MIDs that have already been defined then it should use the mid-ref format previously stated.";
        }
      }
      mandatory true;
     description



Birrane, et al.            Expires May 3, 2018                 [Page 38]


Internet-Draft                     ADM                      October 2017


      "A MID collection can be modeled as a string, where MIDs are separated by spaces, or by an array of MIDs.";
    }
  }

  grouping expr{
    description
      "Expressions apply operations to values to generate new values.";
      leaf type{
        type type-enum;
        mandatory true;
        description
          "This is the enumeration representing the type of the result of the evaluated expression";
      }

      uses mid-collection{
        description
          'An expression is represented as a MID collection,
          where each MID in the ordered collection represents the data, constants
          and/or operations that comprise the expression. The expression must use the following pattern:
          EDD/VAR/CONST/NUM.name OP.name EDD/VAR/CONST/NUM.name.....
          (((EDD)|(VAR)|(CONST)|(NUM)).(\w+)_?)+op.\S)+
          Uses post fix format.';
    }
  }
}

module complex-structures{
  yang-version 1.1;
  namespace "urn:ietf:params:xml:ns:yang:complex-structures";

  prefix complex;

  import basic-structures{
    prefix basic;
  }

  organization "JHUAPL";

  contact
    "Edward.Birrane@jhuapl.edu";

  revision "2017-10-30" {
     description "Initial Revision";
  }

  description
      "This module models complex structures for asynchronous systems.";




Birrane, et al.            Expires May 3, 2018                 [Page 39]


Internet-Draft                     ADM                      October 2017


  grouping externally-defined-data {
    description
      "Externally defined data (EDD) represents values that are calculated outside of the context of Agents and Managers
      such as values that are measured by firmware.";

    uses basic:mid;

    leaf type {
      type basic:type-enum;
      mandatory true;
      description
        "This is the type of the stored data.";
    }

    leaf description{
      type string;
      description
        "This gives a human readable description of the EDD.";
    }
  }

  grouping variable{
    description
      "Variables are values that are completely described by other known data in the system such as other variables or other EDDs.";

    uses basic:mid{
      description
        "This is the MID for the variable.";
    }

    leaf type{
      type basic:type-enum;
      mandatory true;
      description
        "This is the type of the variable. It acts as a static cast for the result of the initializing expression.";
    }

    container initializer{
      uses basic:expr;
      presence
        "This is the initializer represented by an expression";
      description
        "An expression is used as the initializer for the variable.";
    }

    leaf description{
      type string;
      description



Birrane, et al.            Expires May 3, 2018                 [Page 40]


Internet-Draft                     ADM                      October 2017


        "This is the human readable description of the variable.";
    }
  }

  grouping table-template {
    description
      "This is the template for prototyping tables.";

    uses basic:mid{
      description
        "This is the MID for the table-template.";
    }

    leaf columns{
      type basic:type-name-value-collection;
      mandatory true;
      description
        "A TNV collection is used to store the type and names of the columns in the table-template.";
    }

    leaf description{
      type string;
      description
        "This is the human readable description of the table.";
    }
  }

  grouping table {
    description
      "A table is a names, typed, collection of tabular data with each row represented as a data collection
       and each column defined by both a column name and a column type.";

    uses basic:mid{
      description
        "This is the MID for the table.";
    }

    leaf columns{
      type basic:type-name-value-collection;
      mandatory true;
      description
        "A TNV collection is used to store the type and names of the columns in the table.";
    }

    leaf num-rows{
      type uint64;
      mandatory true;
      description



Birrane, et al.            Expires May 3, 2018                 [Page 41]


Internet-Draft                     ADM                      October 2017


        "This is the number of rows in the TBL.";
    }

    list rows{
      key "num";
      leaf num{
         type uint64;
         description "This is the number of data values in the row.";
      }

      leaf data{
         type basic:type-name-value-collection;
         description
            "A TNV collection is used since col-types gives the types.";
      }

      description
        "These are the rows of the table.";
    }

    leaf description{
        type string;
        description "This is the human readable description of the table.";
   }
  }

  grouping report{
    description
      "A report is a typed data collection that is identified by a mid and generated to capture the return value of a control.";

    uses basic:mid{
      description
        "This contains the MID for the report entry.";
    }

    leaf values{
      type basic:type-name-value-collection;
      description
        "This TNV collection contains the values for the report entry.";
    }


    leaf description{
      type string;
      description
        "This is the human readable description of the report-entry.";
   }
  }



Birrane, et al.            Expires May 3, 2018                 [Page 42]


Internet-Draft                     ADM                      October 2017


  grouping report-template{
    description
      "A report template is the ordered set of data descriptions which describe
      how values will be represented in a corresponding report entry.";

    uses basic:mid{
      description
        "This contains the MID for the report entry.";
    }

    uses basic:mid-collection;
    leaf description{
      type string;
      description
        "This is the human readable description of the report-template.";
    }
  }

  grouping control{
    description
      "A control represents a pre-defined opcode that can be run on an agent.";

    uses basic:mid{
      description
        "This is the MID identifying the control. It must NOT have an issuer field nor a tag field.";
    }

    leaf description{
      type string;
      description
         "This is the human readable description of the control.";
    }
  }

  grouping time-based-rule{
    description
      "A time based rule specifies that a particular action should be taken by an agent
      based on some time interval.";

    uses basic:mid{
      description
        "This is the MID identifying the time-based rule.";
    }

    leaf start{
        type basic:ts;
        mandatory true;
        description



Birrane, et al.            Expires May 3, 2018                 [Page 43]


Internet-Draft                     ADM                      October 2017


           "This is the time at which the TRL should start.";
    }

    leaf period{
      type uint64;
      default 1;
      description
        "This is the length of time to wait in between running the action associated with the TRL.";
    }

    leaf count{
      type uint64;
      mandatory true;
      description
        "This is the number of times that action is performed. 0 = inf";
    }

    container action{
      uses basic:mid-collection;
      presence
        "The action is a mid-collection;";
      description
        "This is the collection of controls and/or macros to be run by the TRL.";
    }

    leaf description{
      type string;
      description
        "This is the human readable description of the time-based-rule.";
    }
  }

  grouping state-based-rule{
    description
      "A state based rule(SRL) specifies that a particular action should be taken by an agent
      based on some evaluation of the internal state of the agent.";

    uses basic:mid{
      description
        "This is the MID identifying the SRL.";
    }

    leaf start{
        type basic:ts;
        mandatory true;
        description
          "This is the time at which the SRL should start to be evaluated.";
    }



Birrane, et al.            Expires May 3, 2018                 [Page 44]


Internet-Draft                     ADM                      October 2017


    container condition{
        uses basic:expr;
        presence
          "The condition is represented by an expression.";
        description
          "This contains the boolean expression, which, if true, results in the SRL running the associated action.";
    }
    leaf count{
        type uint64;
        mandatory true;
        description
          "This is the number of times the action is run. 0 = inf";
    }

    container action{
      uses basic:mid-collection;
      presence
        "The action is a mid-collection.";
      description
        "This is the collection of controls and/or macros to be run as part of the action.";
    }

    leaf description{
      type string;
      description
        "This is the human readable description of the state-based-rule.";
    }
  }

  grouping macro{
    description
      "This is the ordered collections of MIDs that contain controls or other macros. When run by an agent, each MID in the mid-collection
      is run in order.";

    uses basic:mid{
      description
        "This is the MID identifying the Macro.";
    }

    container definition{
      uses basic:mid-collection;
      presence
        "The definition is represented by a mid collection.";
      description
        "This is the ordered collections of MIDs which identify the controls and
        other macros that should be run as part of the running macro.";
    }




Birrane, et al.            Expires May 3, 2018                 [Page 45]


Internet-Draft                     ADM                      October 2017


    leaf description{
      type string;
      description
        "This is the human readable description of the macro.";
   }

  }

  grouping constant{
    description
      "Constants represent named values defined in an ADM.";
    uses basic:mid{
      description
        "This is the MID that corresponds to the constant.";
    }

    leaf typed-value{
      type basic:type-name-value-collection{
      pattern
   }
   mandatory true;
   description
      "This is the type and value of the constant.";
    }

    leaf description{
      type string;
      description
        "This is the human readable description of the constant.";
    }
  }

  grouping operator{
    description
      "Operators are always defined in the context of an ADM. They represent functions
      implemented by the firmware of the agent.";

    uses basic:mid{
      description
        "Since Operators are always defined soley in the context of an ADM,
        the issuer and tag field should not be used.";
    }

    leaf out-type{
      type basic:type-enum;
         description
         "This is the type of the return value of the operator.";
    }



Birrane, et al.            Expires May 3, 2018                 [Page 46]


Internet-Draft                     ADM                      October 2017


    leaf in-type{
         type basic:type-name-value-collection{
            pattern

   }
         description
         "This is the type(s) of the inputs of the operator.";
    }

    leaf num-operands{
      type uint32;
      mandatory true;
      description
         "This is the number of operands needed to utilize the operator.";
    }

    leaf description{
      type string;
      description
         "This is the human readable description of the operator.";
    }
  }
}

10.2.  Application Data Template

   The ADT lists the set of predefined information necessary to capture
   the non-dynamic parts of an application data model, as follows.

module adm{
  yang-version 1.1;
  namespace "urn:ietf:params:xml:ns:yang:adm";

  prefix adm;

  import complex-structures{
    prefix complex;
  }

  organization "JHUAPL";
  contact
    "Edward.Birrane@jhuapl.edu";

  revision "2017-10-30" {
    description "Initial Revision";
  }

  description



Birrane, et al.            Expires May 3, 2018                 [Page 47]


Internet-Draft                     ADM                      October 2017


    "This YANG module is used for modeling Application Data Models (ADMs). All keys in the list of the information uses the associated with the data's MIDs.";

  list metadata{
    key "name";
    uses complex:constant;
    description
      "This is the metadata for the ADM. Should contain Name, Version, Namespace, and Issuing organization of the adm";
  }

  list externally-defined-data{
    key "name";

    uses complex:externally-defined-data{
      description
        "These are the EDD definitions that are defined by the ADM and its firmware";
    }

    description
      "This is the listing of all the EDDs that are defined in the ADM.";
  }

  list tables{
    key "name";

    uses complex:table-template;
    description
      "This is the list of all the table/table-templates in the ADM.";
  }

  list variables{
    key "name";

    uses complex:variable{
      description "These are the variables created and defined by the ADM.";
    }

    description
      "Variable definitions are expressions used to calculate data values, on the fly,
      from a set of other variable definitions, EDDs, constants, or numerics using any
      of the operators defined.";
  }

  list report-templates{
    key "name";

    uses complex:report-template;

    description



Birrane, et al.            Expires May 3, 2018                 [Page 48]


Internet-Draft                     ADM                      October 2017


      "This is the collection of report templates, which is the ordered set of data descriptions that
      describe how values will be represented in a corresponding Report Entry.";
  }

  list controls{
      key "name";

      uses complex:control;

      description
        "This is the collection of controls which represent well-known command opcodes
        that can be run by the Agent in response to direct request by an AMP manager or
        in response to time- or state-based rules on the agent itself.";
  }

  list constants{
    key "name";

    uses complex:constant;

    description
      "These are the constants made available in the ADM.";
  }

  list macros{
    key "name";

    uses complex:macro;

    description
      "Macro definitions are ordered collections of controls that can be sequentially run.";
  }

  list operators{
    key "name";

    uses complex:operator;

    description
      "This is the set of operators that are made available in the ADM";
  }
}

11.  IANA Considerations

   TBD.





Birrane, et al.            Expires May 3, 2018                 [Page 49]


Internet-Draft                     ADM                      October 2017


12.  Security Considerations

   TBD

13.  Informative References

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

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

Authors' Addresses

   Edward J. Birrane
   Johns Hopkins Applied Physics Laboratory

   Email: Edward.Birrane@jhuapl.edu


   Evana DiPietro
   Johns Hopkins Applied Physics Laboratory

   Email: Evana.DiPietro@jhuapl.edu


   David Linko
   Johns Hopkins Applied Physics Laboratory

   Email: David.Linko@jhuapl.edu


















Birrane, et al.            Expires May 3, 2018                 [Page 50]


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