<?xml version="1.0" encoding="us-ascii"?>
<!DOCTYPE rfc SYSTEM "rfc2629.dtd" [
<!ENTITY RFC6256 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.6256.xml">
<!ENTITY RFC3986 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.3986.xml">
<!ENTITY RFC2119 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119.xml">
<!ENTITY RFC3339 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.3339.xml">
<!ENTITY RFC4648 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.4648.xml">

]>
<?xml-stylesheet type='text/xsl' href='rfc2629.xslt' ?>
<?rfc strict="yes" ?>
<?rfc toc="yes"?>
<!-- generate a ToC -->
<?rfc symrefs="yes"?>
<!-- use symbolic references tags, i.e, [RFC2119] instead of [1] -->
<?rfc sortrefs="yes" ?>
<!-- sort the reference entries alphabetically -->
<?rfc compact="no" ?>
<!-- do not start each main section on a new page -->
<?rfc subcompact="no" ?>
<rfc category="info" ipr="trust200902" docName="draft-birrane-dtn-adm-03" submissionType="IETF" xml:lang="en">

<!-- ***** FRONT MATTER ***** -->
<front>
   <!-- The abbreviated title is used in the page header - it is only necessary if the
        full title is longer than 39 characters -->
   <title abbrev="ADM">AMA Application Data Model</title>
   <author fullname="Edward J. Birrane" initials="E.B." surname="Birrane">
      <organization>Johns Hopkins Applied Physics Laboratory</organization>
      <address>
        <email>Edward.Birrane@jhuapl.edu</email>
      </address>
   </author>

   <author fullname="Evana DiPietro" initials="E." surname="DiPietro">
      <organization>Johns Hopkins Applied Physics Laboratory</organization>
      <address>
        <email>Evana.DiPietro@jhuapl.edu</email>
      </address>
   </author>
     
   <author fullname="David Linko" initials="D." surname="Linko">
      <organization>Johns Hopkins Applied Physics Laboratory</organization>
      <address>
        <email>David.Linko@jhuapl.edu</email>
      </address>
   </author>

   
   <date month="June" year="2018"/>
   <!-- Meta-data Declarations -->
   <area>General</area>
   <workgroup>Delay-Tolerant Networking</workgroup>
   <keyword>DTN</keyword>
   <keyword>Network Management</keyword>
   <keyword>Autonomy</keyword>

   <abstract>
      <t>
         This document defines a physical data model that captures the 
         information necessary to asynchronously manage applications. This model 
         provides a set of common type definitions, data structures, and a 
         template for publishing standardized representations of model elements.
      </t>
   </abstract>
</front>
 
<middle>
   <section title="Introduction" toc="default">
      <t>
         The Asynchronous Management Architecture (AMA) <xref target="I-D.birrane-dtn-ama"/>
         defines a concept for the open-loop control of applications (and protocols) 
         in situations where timely, highly-available connections cannot exist 
         amongst managing and managed nodes in a network. While the AMA 
         provides a logical data model, it does not include the detailed 
         information necessary to produce interoperable data models.
      </t>          
      
      <section title="Scope" toc="default">
         <t>
            This document defines a physical data model suitable for managing 
            applications in accordance with the AMA.  This physical model is
            termed the Asynchronous Management Model (AMM) and consists of the data 
            types and data structures needed to manage applications in asynchronous 
            networks. 
         </t>
         <t>
            This document also provides a template, called the Application Data
            Model Template (ADMT), for the standardized representation of 
            application-specific instances of this model. Using the types and 
            structures defined by the AMM, individual applications can
            capture their unique, static management information in documents 
            compliant with the ADMT. These application-specific documents are called 
            Application Data Models (ADMs).
         </t>
         <t>
            The AMM presented in this document does not assume any specific type 
            of application or underlying network encoding. In order to 
            communicate model elements between AMA Agents and Managers in a 
            network, the model must be encoded for transmission. Any such 
            encoding scheme is outside of the scope of this document. Generally, 
            the encoding of the model is a separate concern from the specification 
            of data within the model.  
         </t>
         <t>           
            Because different networks may use different encodings for data, 
            mandating an encoding format would require incompatible networks to 
            encapsulate data in ways that could introduce inefficiency and 
            obfuscation. It is envisioned that different networks would be able 
            to encode ADMs in their native encodings such that the translation 
            of ADM data from one encoding to another can be completed using 
            mechanical action taken at network borders.
         </t>   
         <t>
            Since the specification does not mandate an encoding format, the 
            AMM and ADMT must provide enough information to make encoding (and 
            translating from one encoding to another) an unambiguous process. 
            Therefore, where necessary, this document provides identification, 
            enumeration and other schemes that ensure ADMs contain enough 
            information to prevent ambiguities caused by different encoding 
            schemes. 
         </t>
         
      </section>
   </section>
      
   <section title="Requirements Language" toc="default">
      <t>
         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 <xref target="RFC2119"/>.
      </t>
   </section>
 
   <section title="Terminology" toc="default">
      <t>
         Note: The terms "Actor", "Agent", "Externally Defined Data",
         "Variable", "Constant", Control", "Literal", "Macro", "Manager", 
         "Operator", "Report", "Report Template", "Rule", "State-Based Rule", 
         "Table", "Table Template", and "Time-Based Rule" are used without 
         modification from the definitions provided in the <xref target="I-D.birrane-dtn-ama"/>.
      </t>
      <t>
         Additional terms defined in this document are as follows.  
          
         <list style="symbols">

            <t>
               Application - A software implementation running on an Agent and 
               being managed by a Manager. This includes software that 
               implements protocol processing on an Agent.              
            </t>
            
            <t>
               Application Data Model (ADM) - The set of statically-defined 
               data items necessary to manage an application asynchronously. 
            </t>

            <t>
               Application Data Model Template (ADMT) - A standard format for 
               expressing predefined data items for an application.
            </t>

         	<t>
               AMM Resource Identifier (ARI) - A unique identifier for any AMM 
               object, syntactically conformant to the Uniform Resource 
               Identifier (URI) syntax documented in <xref target="RFC3986"/>
               and using the scheme name "ari".
            </t>

            <t>
               ADM Namespace - A moderated, hierarchical taxonomy of namespaces
               that describe a set of ADM scopes. Specifically, an individual 
               ADM namespace is a specific sequence of ADM namespaces, from most 
               general to most specific, that uniquely and unambiguously 
               identify the namespace of a particular ADM. 
            </t>
            
            <t>
               Operational Data Model (ODM) - The operational configuration of 
               an Agent. This includes the union of all ADM information 
               supported by the Agent as well as all operational, dynamic
               configuration applied to the Agent by Managers in the network.
            </t>

         </list>
      </t>
   </section>
    
   <section title="Data Modeling Concept of Operations">

      <t>
         In order to asynchronously manage an application in accordance
         with the <xref target="I-D.birrane-dtn-ama"/>, an application-specific 
         data model must be created containing any predefined management 
         information for that application. This model is termed the Application 
         Data Model (ADM) and forms the core set of information for that 
         application in whichever network it is deployed. The ADM syntactically 
         conforms to the ADMT and uses the data structures and types that 
         comprise the AMM.
      </t>

      <t>
         The information standardized in the ADM represents static 
         configurations and definitions that apply to any deployment of the 
         application, regardless of the network in which it is operating. 
         Within any given network, Managers supplement the information provided
         by ADMs with dynamic definitions and values. The operational 
         configuration of the network is the union of all supported ADMs and 
         all Manager-defined dynamic configurations. This is termed the 
         Operational Data Model (ODM).
      </t>
      <t>
         The relationships amongst the AMM, ADMT, and ADM are illustrated in 
         <xref target="system_overview"/>.
      </t>
        
      <figure align="center" anchor="system_overview">
         <preamble>Data Model Relationship</preamble>
          <artwork align="center" xml:space="preserve">&#xA;<!-- 
             --> +---------+               +---------+              &#xA;<!--
             --> |   AMM   |-------------->|  ADMT   |              &#xA;<!--
             --> +----+----+               +----+----+              &#xA;<!--
             -->      |                         |                   &#xA;<!--
             -->      |              +----------+-------------+     &#xA;<!--
             -->      V              |          |             |     &#xA;<!--
             --> +----------+        V          V             V     &#xA;<!--
             --> | Network  |    +-------+  +-------+     +-------+ &#xA;<!--
             --> | Specific |    | ADM 1 |  | ADM 2 | ... | ADM N | &#xA;<!--
             --> | Config.  |    +---+---+  +---+---+     +---+---+ &#xA;<!--
             --> +----+-----+        |          |             |     &#xA;<!--
             -->      |              |          |             |     &#xA;<!--
             -->      V              V          V             V     &#xA;<!--
             -->    +---------------------------------------------+ &#xA;<!--
             -->    |                     ODM                     | &#xA;<!--
             -->    +---------------------------------------------+
           </artwork>
      </figure>

      <t>
         In this figure, AMM data types and structures form the common
         elements of the management model used by both ADMs and network
         specific configurations. Together, the set of static information
         provided by the union of all supported ADMs with the set of
         operator-specified dynamic AMM objects, forms the operational
         data model used to manage the network.
      </t>
   </section>

   <section title="Asynchronous Management Model (AMM)">

      <t>
         This section describes the Asynchronous Management Model, which is
         the set of objects used to implement the logical data model
         provided by the AMA. This section also provides additional information
         necessary to work with this model, such as data type specifications,
         identifier constructs, and naming conventions. 
      </t>

      <section title="The AMM Resource Identifier (ARI)">
         <t>
            Every object in the AMM must be uniquely identifiable, regardless of 
            whether the item is defined formally in an ADM document or informally 
            by operators in the context of a specific network deployment. The AMM 
            Resource Identifier (ARI) uniquely identifies AMM objects.
         </t>
         <t>
            There are three components to the ARI: namespaces, object names, 
            and parameters. This section defines each of these 
            components, discusses special cases, and presents a string 
            canonicalization of these identifiers, with examples.
         </t>

         <section title="Namespaces" anchor="adm_namespace_chp">
            <t>            
               AMM objects exist within unique namespaces to prevent 
               conflicting names within network deployments, particularly in
               cases where network operators are allowed to define their
               own object names. In this capacity, namespaces exists to
               eliminate the chance of a conflicting object name. They 
               MUST NOT be used as a security mechanism. An Agent or Manager 
               MUST NOT infer security information or access control based 
               solely on namespace information.
            </t>
            <t>
               The AMM defines three ways to identify namespaces for AMM
               object names: Moderated Namespaces, Anonymous Namespaces, and
               Issuer Namespaces. 
            </t>

            <section title="Moderated Namespaces" anchor="mod_nmsp_chp">
               <t>
                  The most effective way to ensure the uniqueness of an AMM Object
                  is to name it in the context of a moderated 
                  namespace. These namespaces are assigned by an overseeing
                  organization as part of a maintained namespace registry. 
               </t>
               <t>
                  Moderated namespaces are hierarchical, which allows the 
                  grouping of objects that share common attributes - for 
                  example, objects associated with related protocols may have
                  protocol-specific namespaces that are grouped under a single
                  encompassing namespace. Namespaces that are closer to a 
                  root node in the moderated hierarchy have broader scope than 
                  namespaces closer to leaf nodes in that hierarchy. There is 
                  no requirement that the namespace hierarchy be represented as 
                  a single tree structure; multiple root nodes are acceptable 
                  and likely to exist. 
               </t>
               <t>
                  In a hierarchical model of namespaces, a particular namespace
                  can be identified as the path to that namespace through the
                  hierarchy. The expression of that path within an ADM is
                  accomplished by listing each namespace along the path, 
                  separated by the tokenizing character "/". For example, 
                  consider the namespaces in the following figure.

                  <figure>
                     <artwork align="left">&#xA;<!--
                     -->          +-------+                   +-------+       &#xA;<!--
                     -->          | TOP-A |                   | TOP-B |       &#xA;<!--
                     -->          +---+---+                   +---+---+       &#xA;<!--
                     -->              |                      _____|_____      &#xA;<!--
                     -->              |                     |           |     &#xA;<!--
                     -->          +-------+             +-------+   +-------+ &#xA;<!--
                     -->          | MID-A |             | MID-B |   | MID-C | &#xA;<!--
                     -->          +-------+             +-------+   +-------+ &#xA;<!--
                     -->     _________|_________            |           |     &#xA;<!--
                     -->    |         |         |           |           |     &#xA;<!--
                     -->+-------+ +-------+ +-------+   +-------+   +-------+ &#xA;<!--
                     -->| LOW-A | | LOW-B | | LOW-C |   | LOW-A |   | LOW-A | &#xA;<!--
                     -->+-------+ +-------+ +-------+   +-------+   +-------+
                     </artwork>
                  </figure>

                  Given this hierarchy, the following are all valid namespace
                  representations. 
               </t>
               <t>
                  <list>
                     <t>TOP-A/</t>
                     <t>TOP-A/MID-A</t>
                     <t>TOP-A/MID-A/LOW-A</t>
                     <t>TOP-B/MID-B/LOW-A</t>
                     <t>TOP-B/MID-C/LOW-A</t>
                  </list>
               </t>
               <t>
                  Moderated namespaces require resources to review and publish
                  and are best suited for static AMM object definitions, such
                  as those found in ADMs. 
               </t>

            </section>

            <section title="Anonymous Namespaces">
               <t>
                  It is possible for network operators to define AMM objects that 
                  are not associated with a namespace. In this case, a 
                  nil namespace can be defined. This special case is considered
                  the use of an "anonymous" namespace.
               </t>
               <t>
                  Policy decisions as to whether anonymous namespaces are allowed
                  in the system should be determined before network deployment. The
                  use of an anonymous namespace greatly increases the chances
                  of naming collisions. 
               </t>
            </section>

            <section title="Informal Namespaces">
               <t>
                  Network-specific configurations, as illustrated in
                  <xref target="system_overview"/>, are dynamic, ephemeral,
                  not captured in published ADMs, and do not use moderated
                  namespaces. Instead, AMM objects that comprise network-
                  specific configuration can be uniquely differentiated as a
                  function of their "Issuer" and an issuer-specific "Tag".
               </t>
               <t>
                  An Issuer is any string that identifies the organization
                  that is defining an AMM object. This value may come from 
                  a global registry of organizations, an issuing node address,
                  a signed known value, or some other network-unique marking.  
                  Issuers MUST NOT conflict with known moderated namespaces, 
                  and Agents and Managers should not process Issuers that 
                  conflict with existing moderated namespaces. 
               </t>               
               <t>
                  A Tag is any string used to disambiguate AMM Objects for
                  an Issuer. The contents of the tag are left to the discretion 
                  of the Issuer. Examples of potential tag values include an
                  issuer-known version number or a (signed) hashing of the
                  data item associated with the reference identifier.
               </t>               
            </section>
         </section>

         <section title="Object Names">
            <t>
               Object names are strings whose value is determined by the creator
               of the object. For those objects defined in accordance with the 
               ADMT Template, the structure of the object name is given in 
               <xref target="amm_obj_name"/>.
            </t>        
         </section>

         <section title="Parameters">
            <t>
               Parameterization is used in the AMM to enable expressive autonomous 
               function and reduce the amount of traffic communicated between 
               Managers and Agents. In the AMM, most objects can be 
               parameterized and the meaning of parameterization for each object
               is described in detail in <xref target="amm_obj"/>.
            </t>
            <t>
               If there are two instances of an AMM object that have the same 
               namespace and same object name but have different parameters,
               then those instances are both unique and the ARIs for those
               instances MUST also be unique. Therefore, parameters are
               considered part of an AMM object's identifier. 
            </t>
            <t>
               There are two types of parameters defined in the AMM: Formal
               and Actual parameters. The terms formal parameter and actual 
               parameter follow common computer programming vernacular
               for discussing function declarations and function calls,
               respectively.
            </t>  
                  
            <section title="Formal Parameters">
               <t>
                  Formal parameters define the type, name, and order of the 
                  information that customizes an AMM Object. They represent the
                  unchanging "definition" of the parameterized object.
               </t>

               <t>
                  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.
               </t>            
            </section>
                  
            <section title="Actual Parameters" anchor="ap_descr">
               <t>
                  Actual parameters represent the data values passed to a
                  parameterized AMM Object. They "fulfill" the parameter
                  requirements defined by the formal parameters for that
                  object. 
               </t>
               <t>
                  An actual parameter MUST specify a value and MAY specify a type. 
                  If a type is provided it MUST match the type provided by the 
                  formal parameter.  An actual parameter MUST NOT include NAME
                  information.
               </t>
               <t>
                  There are two ways in which the value of an actual parameter
                  can be specified: parameter-by-value and parameter-by-name.
                  <list hangIndent="8" style="hanging">
                     <t hangText="Parameter-By-Value"><vspace blankLines="0" /> 
                        This method involves directly supplying the value as
                        part of the actual parameter. It is the default 
                        method for supplying values.
                     </t>
                     <t hangText="Parameter-By-Name"><vspace blankLines="0" /> 
                        This method involves specifying the name of some other
                        parameter and using that other parameter's value for
                        the value of this parameter. This method is useful
                        when a parameterized AMM Object contains another
                        parameterized AMM Object. The contained object's actual
                        parameter can be given as the name of the containing
                        object's parameter. In that way, a containing object's
                        parameters can be "pass down" to all of the objects 
                        it contains. 
                     </t>
                  </list>
               </t>
            </section>

            <section title="Optional Parameters">
               <t>
                  In cases where a formal parameter contains a default value, the
                  associated actual parameter may be omitted. Default values in formal
                  parameters (and, thus, optional actual parameters) 
                  are encouraged as they reduce the size of data items communicated
                  amongst Managers and Agents in a network.
               </t>
            </section>
         </section>

         <section title="Special Case: Literal Values">
            <t>
               As defined in the AMA, Literal values are those whose value and
               identifier are equivalent. For example, the literal "4" serves
               as both an identifier and a value. When literal values are
               used in objects in the AMM, they are able to have a simplified
               identification scheme.
            </t>
            <t>
               Because the value of a Literal object serves as its identifier,
               there is no need for namespaces, object names, or parameters. A
               literal can be completely identified by its data type and data
               value. Since Literals in the AMA are used to identify primitive
               data types, the type of a Literal identifier MUST be 
               as described in <xref target="prim_types"/>.
            </t>
         </section>

         <section title="String Canonical Forms" anchor="ari_str_can_form">
            <t>
               While there may exist multiple encodings of an ARI, to include
               the JSON encodings presented in <xref target="adm_template"/> and
               other binary encodings in other specifications, this section
               defines a universal string representation of the ARI, as such
               a representation is helpful to express examples in this
               and other documents. 
            </t>
            <t>
               This representation is not prescriptive; other string encodings 
               may exist that differ from the one used in this document.
            </t>

            <section title="General ARI String Representation" anchor="ari_str_enc">
               <t>
                  The String Canonical Form of the ARI is expressed as a Uniform 
                  Resource Identifier (URI), as documented in 
                  <xref target="RFC3986"/>. A URI is syntactically decomposed into 
                  a scheme name and a scheme-specific part. The set of known scheme 
                  names is moderated by IANA. The scheme-specific part of the URI 
                  is dependent on the scheme name. 
               </t>
               <t>
                  The scheme name of the ARI is "ari". The scheme-specific part 
                  of the "ari" scheme follows the format:
                  <vspace blankLines="1"/>
                  ari:/&lt;Namespace&gt;/&lt;ObjectName&gt;&lt;(Parameters)&gt;
                  <vspace blankLines="1"/>

                  With the string representation of each scheme given as
                  follows. 

                  <list hangIndent="8" style="hanging">
                     <t hangText="Namespaces"><vspace blankLines="0" /> 
                        Namespaces are represented as "/" 
                        separated lists, with individual namespace types
                        represented as follows:
                        <list style="symbols">
                           <t> 
                              Moderated namespaces are listed in order from 
                              the most general namespace to the most specific 
                              namespace.
                              For example: "GENERAL/MIDDLE/SPECIFIC/".
                           </t>
                           <t>
                              Anonymous namespaces are empty and are
                              represented as "/". 
                           </t>
                           <t>
                              Informal namespaces follow the general pattern
                              of moderated namespaces - starting with the
                              general Issuer followed by the more
                              specific issuer tag. For example: 
                              "Issuer/Tag". In cases where the Tag is omitted,
                              then the representation is simply "Issuer/". 
                           </t>
                        </list>
                     </t>

                     <t hangText="Object Names"><vspace blankLines="0" />
                        The object name is a string as specified in 
                        <xref target="amm_obj_name"/>.
                     </t>
                     <t hangText="Parameters"><vspace blankLines="0" />
                        If present, parameters are represented as a 
                        comma-separated string enclosed in parenthesis. Different
                        types of parameters are represented as follows.
                        <list style="symbols">
                           <t>
                              Formal parameters follow the pattern &lt;type&gt; 
                              &lt;name&gt; and if there is a default value, it 
                              is represented by the substring "= &lt;value&gt;".
                           </t>
                           <t>
                              Actual Parameters-By-Value are represented as the
                              string encoding of their value. 
                           </t>
                           <t>
                              Actual Parameters-By-Name are represented as the
                              name of the parameter enclosed in angle brackets.
                           </t>
                        </list>
                        <vspace blankLines="1"/>
                        Note: If an actual parameter is missing for a formal 
                        parameter that has a default value, then the ARI string
                        MUST have a blank space where the actual parameter would 
                        have been. This missing parameter will also have 
                        a comma, separating it from other actual parameters in 
                        the ARI string.
                     </t>
                  </list>
               </t>
               <section title="Shortform Encoding" anchor="ari_str_short">
                  <t>
                     In cases where a default namespace can be assumed (for
                     example, in the context of an ADM with a defined
                     namespace) the prefix ari:/Namespace/ can be omitted. 
                  </t>
               </section>
            </section>            
            <section title="Literal String Encoding">
               <t>
                  The string representation of a Literal ARI is much simpler
                  and consists of simply the data type of the Literal followed
                  by the value, as follows:
               </t>
               <t>
                  "(type) value"
               </t>
            </section>
         </section>
         
         
         <section title="Examples">
            <t>
               The ARIs for the following sample AMM objects are encoded in
                <xref target="ari_str_ex"/>. Note that these examples are for
                the identifiers of AMM objects, not their entire definition.

               <list style="symbols">
                  <t> 
                     The number of bytes received by an Agent, defined in the 
                     N1/N2 namespace and called num_bytes.
                  </t>
                  <t>
                     The number of bytes received through an interface,
                     called num_bytes_if, which takes a single string 
                     parameter named "if_name" with a default value oth "eth0".
                  </t>
                  <t>
                     An anonymous, operator-defined object named "obj1" which takes
                     two unsigned integer parameters, n1 and n2, with
                     default values of 3 and 4, respectively. 
                  </t>
                  <t>
                     The typed, Literal value of 4. 
                  </t>
               </list>
            </t>

            <texttable anchor="ari_str_ex">
               <ttcol>ARI String</ttcol>
               <ttcol>Description</ttcol>

               <c>"ari:N1/N2/num_bytes"</c>
               <c>Unparameterized num_bytes object in the N1/N2 
                  namespace.</c>

               <c>"num_bytes"</c>
               <c>Shortform encoding where the N1/N2 namespace can be
                  assumed.</c>

               <c>"num_bytes_if(String if_name)"</c>
               <c>Formal parameter definition of num_bytes object that accepts a 
                  string interface name.</c>

               <c>"num_bytes_if(String if_name=eth0)"</c>
               <c>Formal parameter definition of num_bytes object that accepts a 
                  string interface name with a default value.</c>

               <c>"num_bytes_if()"</c>
               <c>Actual parameter using the default value of eth0.</c>

               <c>"num_bytes_if(eth0)"</c>
               <c>Actual parameter of eth0.</c>

               <c>"ari:/obj1(Int n1 = 0, Int n2 = 3)"</c>
               <c>Formal parameter of object obj1 in anonymous namespace
               taking 2 default parameters.</c>

               <c>"ari:/obj1(, )"</c>
               <c>Actual parameter using the default values of 0 for n1 and 3 
                  for n2.</c>

               <c>"ari:/obj1(, 4)"</c>
               <c>Actual parameter using the default value of 0 for n1.</c>

               <c>"ari:/obj1(4, )"</c>
               <c>Actual parameter using the default value of 3 for n2.</c>

               <c>"ari:/obj1(4,4)"</c>
               <c>Actual parameters provided for all obj1 parameters.</c>

               <c>"ari:/obj1(&lt;input&gt;,4)"</c>
               <c>Actual parameters provided for all obj1 parameters,
                  with the value of the first parameter taken from some
                  other parameter named "input".</c>

               <c>"(UINT) 4"</c>
               <c>The Literal value 4 interpreted as a 32-bit unsigned 
                  integer.</c>
            </texttable>
         </section>
      </section>

      <section title="AMM Type Definitions" anchor="amm_data_type_chp">
         <t>
            This section describes the type definitions used by the AMM. 
         </t>

         <section title="Primitive Types" toc="default">
            <t>
               The AMM supports a series of primitive types as 
               outlined in <xref target="prim_types"/>.
            </t>
            
            <texttable anchor="prim_types" title="Primitive Types">
               <ttcol align="center" width="30%">Type</ttcol>
               <ttcol align="center" width="70%">Description</ttcol>
            
               <c>BYTE</c>
               <c>unsigned byte value</c>
            
               <c>INT</c>
               <c>32-bit signed integer in 2's complement</c>

               <c>UINT</c>
               <c>32-bit unsigned integer in 2's complement</c>

               <c>VAST</c>
               <c>64-bit signed integer in 2's complement</c>

               <c>UVAST</c>
               <c>64-bit unsigned integer in 2's complement</c>

               <c>REAL32</c>
               <c>Single-precision, 32-bit floating point value in IEEE-754 
                  format.</c>

               <c>REAL64</c>
               <c>Double-precision, 64-bit floating point value in IEEE-754 
                  format.</c>

               <c>STRING</c>
               <c>NULL-terminated series of characters in UTF-8 format.</c>

               <c>BOOL</c>
               <c>A Boolean value of FALSE (whose integer interpretation is 0) 
                  or TRUE (whose integer interpretation is not 0).</c>
               
            </texttable>            
         </section>
        
         <section title="Derived Types" toc="default">
            <t>
               A derived typed is a primitive type that is interpreted with 
               special semantics. The AMM supports the following derived types.
            </t>

            <section title="Byte String">
               <t>
                  A Byte String is a specialization of the String primitive 
                  data type used to store binary data using base64 encoding
                  as defined in <xref target="RFC4648"/>. 
               </t>
            </section>

            <section title="Time Values (TV) and Timestamps (TS)">
               <t>
                  A Time Value (TV) is a specialization of the String
                  primitive data type whose time interpretation is as given
                  in this section. There are two "types" of time representations 
                  within the AMM: relative times and absolute times.
               </t>
               <t>
                  An absolute time represents an instant in time. It MUST
                  be formatted as a date-time in accordance with 
                  <xref target="RFC3339"/>.
               </t>
               <t>
                  A relative time is defined as the amount of time after an
                  instant in time. A relative time MUST be formatted as a
                  full-time in accordance with <xref target="RFC3339"/>.
                  Relative times have advantages over absolute times: they do 
                  not require time to be synchronized across Agents and 
                  Managers, and they are more compact in their representation. 
                  For example, expressing the semantics "run control_one 10 
                  seconds after receiving it" or "run control_two 20 seconds 
                  after running control_one" is more appropriate using relative 
                  times than absolute times. The initiating event of a relative
                  time MUST be unambiguously defined in the context using the
                  time value.
               </t>
               <t>
                  As a practical matter, encodings of relative times MAY impose
                  a limit of no more than 17 years of relative time, which 
                  corresponds to roughly 29 bits of information and is 
                  considered well past an upper bound of efficiency for using
                  a relative time versus an absolute time. 
               </t>
               <t>
                  An absolute time may be differentiated from a relative time 
                  based on whether the time specification is a date-time or 
                  a full-time. 
               </t>
               <t>
                  For example, "00:00:10Z" is a relative time
                  representing 10 seconds after an initiating event. 
                  "2019-01-01T08:00:00Z" is an absolute time that 
                  refers to 8am, Tuesday January 1st, 2019.
               </t>
               <t>
                  A Timestamp (TS) represents a specific point in time when
                  an event occurred. As such, it MUST be represented as an
                  absolute time.
               </t>

            </section>

            <section title="Type-Name-Value (TNV)">
               <t>
                  A Type-Name-Value (TNV) is a three-tuple of information that 
                  describes a typed, named value in the AMM. Since the length 
                  of a data value is a matter of encoding, there is not an 
                  explicit length field present for the data value; it is 
                  assumed that any encoding scheme either explicitly encodes 
                  length or that the length is self-delineating in the encoding.

                  <list style="symbols">
                     <t>
                        Type - The strong typing for this value. Types MUST 
                        be one of those defined in <xref target="type_enum"/>. 
                     </t>
                     <t>
                        Name - A unique identifier for this value.
                     </t>
                     <t>
                        Value - The value of the data item.
                     </t>
                  </list>
               </t>
            </section>

            <section title="User-Specified Derived Types">
               <t>
                  Individual ADMs and network operators may derive other 
                  types that specialize the types provided by the AMM. When
                  doing so, AMM data types MUST be used to capture the 
                  specialization and any user-specific verification or
                  validation MUST occur in user-specific implementations on
                  Agents and Managers.
               </t>
            </section>         
         </section>            
         
         <section title="Collections">
            <t>
               AMM objects, or parameters associated with those 
               objects, often need to represent groups of related information.
               Since the AMM is strongly typed, these groups of related 
               information are represented by special data types called 
               collections. AMM collections are ordered and may contain 
               duplicate entries.
            </t>
            <t>
               The AMM defines three typed collections that capture TNVs, ARIs,
               and mathematical expressions.
            </t>

            <section title="Type-Name-Value Collection (TNVC)">
               <t>
                  A Type-Name-Value Collection (TNVC) is an ordered array where 
                  each element of the array is a TNV.
               </t>                     
               <t>
                  TNVCs are often used to capture formal and actual parameters
                  for AMM objects.
               </t>
            </section>

            <section title="ARI Collection (AC)">
               <t>
                  An ARI Collection (AC) is an ordered set of ARIs. 
               </t>
               <t>
                  ACs are often used when there exists a need to refer to multiple
                  AMM objects as a single unit. For example, when defining a
                  Report Template, the definition may have an AC that defines 
                  the ordered ARIs whose values constitute that report. 
               </t>
            </section>
              
            <section title="Expression (EXPR)">
               <t>
                  An Expression (EXPR) is a specialization of an AC where
                  each ARI in the collection is either an operand or an
                  operator. These operands and operators form a mathematical
                  expression that is used to compute a numerical value. 
               </t>

               <t>
                  Within an Expression, an operand MUST be an ARI with one
                  of the following types: Literal, Constant, Externally Defined 
                  Data, or Variable. An operator MUST be an ARI of type 
                  Operator. 
               </t>
                              
               <t>
                  Since the Expression is an AC, there are no annotative 
                  constructs such as parenthesis to enforce certain orders of
                  operation. To preserve an unambiguous calculation of values,
                  the ARIs that form an Expression MUST be represented in
                  postfix order. Postfix notation requires no additional 
                  symbols to enforce precedence, always results in a more 
                  efficient encoding, and post-fix engines can be implemented
                  efficiently in embedded systems. 
               </t>
               <t>
                  For example, the infix expression A * (B * C) is represented 
                  as the postfix A B C * *.
               </t>
               <t>
                  Expressions are often used when assigning values to a
                  Variable or when calculating the state of the Agent
                  in the context of a State-Based Rule. 
               </t>
            </section>
         </section>

      </section>

      <section title="Object Definitions" anchor="amm_obj">

         <t>
            This section identifies the AMM Objects that instantiate the AMA 
         	logical data model and the processing required to support these
            objects at Agents and Managers in the network.
         </t>

         <section title="Common Object Metadata" anchor="amm_obj_name">
            <t>
               Every object in the AMM includes a set of metadata providing
               annotative or otherwise user-friendly descriptive 
               information for the object. This information may be used as
               documentation (for example, only present in ADMs and
               on operator consoles) and/or encoded and transmitted over
               the wire as part of a management protocol. 
            </t>
            <t>
               Metadata is not required to be unique amongst objects and 
               individual encodings MAY choose to not encode metadata in
               cases where the information is not needed to uniquely identify
               objects. The metadata supported by the AMM for objects is as 
               follows: 

               <list hangIndent="8" style="hanging">
                  <t hangText="(STR) Name"> <vspace blankLines="0"/>
                     An object name is a string associated 
                     with the object, but does not constitute the sole 
                     identifier for the object. Names provide human-readable 
                     and/or user-friendly ways to refer to objects within a
                     given context. 
                  </t>
                  <t hangText="(STR) Description"> <vspace blankLines="0"/>
                     An object description is a string 
                     describing the purpose or usage of the object in a 
                     human-readable format. The description serves as 
                     documentation for the object and SHOULD be the same
                     regardless of how the object might be parameterized. For
                     example, the description of a CTRL object should 
                     document the purpose of the CTRL in a way that is 
                     independent of the value of any particular parameter value
                     passed to that CTRL. 
                  </t>
                </list>
            </t>
         </section>         

         <section title="Externally Defined Data (EDD)">
            <t>
               Externally defined data (EDD), as defined in the AMA, represent
               data values that are computed external to the network
               management system. The definition of these values are solely
               defined in the context of an ADM; since their
               calculation exists outside of the network management system, 
               they are not added or removed as part of the dynamic 
               configuration of the network management system. 
            </t>
            
            <t>
               An EDD consists of an ARI, type, and a description, with
               the following caveats:

               <list hangIndent="8" style="hanging">
                  <t hangText="(ARI) Identifier"><vspace blankLines="0" /> 
                     This Identifier MUST be of type EDD and MAY be 
                     parameterized, particularly in cases
                     where the specific computed value can be identified by
                     an associative look-up, as discussed in 
                     <xref target="auth_consid"/>.
                  </t>

                  <t hangText="(UINT) Type"><vspace blankLines="0" /> 
                     The data type of the EDD value MUST be specified as 
                     part of the EDD definition and this type MUST be one
                     of the primitive data types defined in 
                     <xref target="prim_types"/>.
                  </t>

                  <t hangText="(STR) Description"><vspace blankLines="0" /> 
                     This represents the human-readable description of the 
                     EDD. 
                  </t>                                                                           
               </list>  
            </t>
         </section>
            
         <section title="Constant (CONST)" toc="default">
            <t>
               Constants represent named basic values. Examples include 
               common mathematical values such as PI or well-known Epochs 
               such as the UNIX Epoch. Constants are defined solely within 
               the context of ADMs. Constants MUST NOT be defined as part
               of dynamic network configuration.
            </t>
            <t>
               Allowing network operators to define constants dynamically means 
               that a Constant could be defined, removed, and then re-defined 
               at a later time with a different value, which defeats the purpose 
               of having Constants. Variables MUST be used instead of Constants 
               for the purpose of adding new values to the dynamic network 
               configuration. 
            </t>
                     
            <t>
               A CONST is defined by its ARI, value, and description, with
               the following caveats.

               <list hangIndent="8" style="hanging">
                  <t hangText="(ARI) Identifier"><vspace blankLines="0" />
                     This Identifier MUST be of type CONST and MUST NOT 
                     be parameterized. 
                     Parameterizing a Constant implies that its value is
                     dependent upon the set of parameters sent to it, which
                     defeats the purpose of defining a constant value.
                  </t>
                  <t hangText="(TNV) Typed Value"><vspace blankLines="0" />
                     The value of a constant is the immutable value that 
                     should be used in lieu of the Constant ARI.
                     <vspace blankLines="1"/>
                     This value is expressed as a TNV with the following
                     requirements.
                     <list style="symbols">
                        <t> 
                           Type MUST be one of the primitive data types 
                           defined in <xref target="prim_types"/>. 
                        </t>
                        <t>
                           Name MUSt be omitted as the CONST ARI defines
                           the name for this value.
                        </t>
                        <t> 
                           Value must be present and consistent with the
                           data type for this CONST.
                        </t>
                     </list>
                  </t>
                  <t hangText="(STR) Description"><vspace blankLines="0" /> 
                     This represents the human-readable description of the 
                     CONST, as a string.
                  </t>                  
               </list>               
            </t>
         </section>

         <section title="Control (CTRL)" toc="default">
            <t>
               A Control represents a predefined function that can be run on an 
               Agent. Controls are not able to be defined as part of dynamic
               network configuration since their execution is typically part
               of the firmware or other implementation of the Agent outside
               of the context of the network management system.
            </t>
            <t>
               Network operators that wish to dynamically execute functions on
               an Agent may use Macros, State-Based Rule, and Time-Based Rule
               instead.
            </t>
            <t>
               Controls are identified by their ARI and their description, 
               with the following caveats.
               
               <list hangIndent="8" style="hanging">
                  <t hangText="(ARI) Identifier"><vspace blankLines="0" /> 
                     This Identifier MUST be of type CTRL and MAY be 
                     parameterized in cases where
                     the function executed by that Control takes parameters.
                     <vspace/>
                     When defined in the context of an ADM, the Control ARI 
                     MUST match the definition of a Formal Parameter list. 
                     This is because the ADM defines the Controls that can 
                     be invoked, but does not define any particular 
                     invocation of a Control.
                     <vspace/>
                     When used as part of network operations, a Control ARI 
                     MUST match the definition of an Actual Parameter list. 
                     This is because when used operationally, a 
                     parameterized Control required parameters to be run.
                     <vspace/>
                     In cases where a Control takes no parameters, the 
                     definition in the ADM document MUST be considered the 
                     definition of the Control and the presence of the same
                     ARI in the context of an operational system MUST be seen 
                     as an invocation of that Control. 
                  </t>
                  <t hangText="(STR) Description"><vspace blankLines="0" /> 
                     This represents the human-readable description of the 
                     Control, as a string.
                  </t>                  
               </list>               
            </t>
         </section>

         <section title="Macro (MAC)" toc="default">
            <t>
               Macros are ordered collections of Controls or other Macros. When 
               run by an Agent, each ARI in the AC is run in order. A Macro 
               may be defined as part of an ADM or as part of dynamic
               network configuration. 
            </t>
            <t>
               In cases where a Macro contains another Macro, implementations
               MUST implement some mechanism for preventing infinite
               recursions, such as defining maximum nesting levels, performing
               Macro inspection, and/or enforcing maximum execution times.
            </t>
            <t>
               A Macro is defined by an ARI, a content definition, and a 
               description, as follows.
               
               <list hangIndent="8" style="hanging">
                  <t hangText="(ARI) Identifier"><vspace blankLines="0" /> 
                     This Identifier MUST be of type MAC and MAY be 
                     parameterized and, if so, the
                     parameter may be passed-by-name to any parameterized
                     elements within the Macro. 
                  </t>
                  <t hangText="(AC) Definition"><vspace blankLines="0" />
                     The Macro definition is modeled as an AC, where each
                     ARI within the AC MUST be either a Control or a 
                     Macro. 
                  </t>               
                  <t hangText="(STR) Description"><vspace blankLines="0" /> 
                     This represents the human-readable description of the 
                     Macro, as a string.
                  </t>                                       
               </list>               
            </t>            
         </section>
            
         <section title="Operator (OP)" toc="default">
            <t>
               Operators represent user-defined mathematical functions implemented
               in the firmware of an Agent for the purpose of aiding the evaluation 
               of Expressions.
            </t>
            <t>
               The AMM separates the concepts of Operators and Controls to 
               prevent side-effects in Expression evaluation (e.g. to avoid 
               constructs such as A = B + GenerateReport()). For this reason,
               Operators are given their own structure type and Controls do
               not support a return value. 
            </t>
            
            <t>
               Because Operators represent custom firmware implemented on the 
               Agent, they are not defined dynamically as part of network 
               operations. Therefore, they may only be defined in an ADM.
            </t>
            <t>
               An Operator is defined by its ARI, its resultant type, the 
               number of operands, the type of operands, and a description, 
               as follows.
                   
               <list hangIndent="8" style="hanging">
                  <t hangText="(ARI) Identifier"><vspace blankLines="0" /> 
                     This Identifier MUST be of type OP and MUST NOT be 
                     parameterized. 
                     Much like Constants, Operators represent immutable
                     mathematical functions. The operands of an Operator are
                     not considered as "parameters" to the Operator. 
                  </t>
                  <t hangText="(UINT) Out Type"><vspace blankLines="0" />
                     This is the return value of the Operator and MAY be 
                     different than the operand types accepted by the 
                     Operator. This type MUST be one of the primitive data types 
                     defined in <xref target="prim_types"/>.
                  </t>
                  <t hangText="(UINT) Num Operands"><vspace blankLines="0" />
                     This is the number of operands evaluated by the operator. 
                     For example, the unary NOT Operator ("!") would 
                     operate on a single operand. The binary PLUS Operator 
                     ("+") would operate on two operands. A custom operator
                     to calculate the average of the last 10 samples of data 
                     would operate on 10 operands.
                  </t>
                  <t hangText="(TNVC) In Types"><vspace blankLines="0" />
                     This is the type information for each operand operated 
                     on by the Operator, modeled as a TNV Collection (TNVC). 
                     There MUST be one TNV in the TNVC for each operand,
                     and each TNV MUST adhere to the following 
                     requirements:
                     <list style ="symbols">
                        <t> 
                           The Type field MUST be present and MUST be one 
                           of the primitive data types defined in 
                           <xref target="prim_types"/>.
                        </t>
                        <t>
                           The Name field MAY be present to capture a
                           semantic name for the operand.
                        </t>
                        <t>
                           The Value field MUST NOT be present.
                        </t>
                     </list>
                  </t>
                  <t hangText="(STR) Description"><vspace blankLines="0" /> 
                     This represents the human-readable description of the 
                     Operator, as a string.
                  </t>                                    
               </list>               
            </t>
         </section>

         <section title="Reports">
            <t>
               A Report is a set of non-tabular, potentially nested data items 
               that may be predefined in the context of an ADM, or defined 
               dynamically in the context of a deployed network.
            </t>
            
            <t>
               Reports are represented in two ways in the AMM: Report 
               Templates and Reports. A Report Template defines the type of 
               information to be included in a report, and a Report contains 
               that information.
            </t>
            
            <section title="Report Template (RPTT)">
               <t>
                  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. 
               </t>
               <t>
                  Since a RPTT may contain other RPTTs, implementations MUST
                  implement some mechanism to prevent the definition of
                  circular references.
               </t>
               <t>
                  RPTTs are defined by an ARI, the report template
                  definition, and a description, as follows.
                   
                  <list hangIndent="8" style="hanging">
                     <t hangText="(ARI) Identifier"><vspace blankLines="0" /> 
                        This Identifier MUST be of type RPTT and MAY be 
                        parameterized and, if so, the
                        parameter may be passed-by-name to any parameterized
                        elements within the RPTT. 
                     </t>

                     <t hangText="(AC) Definition"><vspace blankLines="0" /> 
                        The Report Definition is modeled as an AC, where each
                        ARI within the AC MUST identify either a CONST, LIT, 
                        EDD, VAR, or other RPTT. 
                     </t>

                     <t hangText="(STR) Description"><vspace blankLines="0" /> 
                        This represents the human-readable description of the 
                        Report template, as a string.
                     </t>
                  </list>                                    
               </t>          
            </section>

            <section title="Report (RPT)">
               <t>
                  A Report (RPT) is a set of data values populated in 
                  conformance to a given data definition. Reports do not have
                  an individual identifier - rather they are uniquely identified
                  by their definition and the timestamp at which their data
                  values were collected.  
               </t>
               <t>
                  RPTs are defined by their associated template,
                  the time at which the report was generated, and 
                  the individual entries in the report, as follows. 
            
                  <list hangIndent="8" style="hanging">
                     <t hangText="(ARI) Template Id"><vspace blankLines="0" /> 
                        This is the ARI of the object that defines the format
                        of the report data values. This ARI MUST define 
                        an AMM object of type RPTT, EDD, or VAR, or CTRL.
                        <vspace/>
                        If this ARI is parameterized, this ARI MUST include
                        the actual parameters used in the generation of
                        the report.
                     </t>
                     <t hangText="(TV) Generation Time"><vspace blankLines="0" /> 
                        This is the absolute time at which the report was
                        generated by the Agent. 
                     </t>

                     <t hangText="(TNVC) Report Entries"><vspace blankLines="0" />
                        This is the collection of data values that comprise
                        the report. If the template for this report is an
                        EDD, VAR, or CTRL then there MUST be one entry for this 
                        report. If the template is a RPTT, then there MUST
                        be one entry for every item defined in the template.
                        <vspace/>
                        Entries are modeled as a TNVC, with each TNV 
                        representing a report entry with the following
                        requiremnts. 
                        <list style="symbols">
                           <t> 
                              Type MAY be ommitted in cases where checking
                              type safety is not required.
                           </t>
                           <t>
                              Name MAY be omitted in cases where a semantic
                              name for the entry can be derived from the 
                              template.
                           </t>
                           <t> 
                              Value MUST be present and consistent with the
                              type for this entry from the associated
                              template item.
                           </t>
                        </list>  
                     </t>
                  </list>                                    
               </t>
            </section>                     
         </section>                  
         
         <section title="State-Based Rule (SBR)" anchor="sbr_chp">
            <t>
               A State-Based Rule (SBR) specifies that starting at 
               a particular time an action should be run by the
               Agent if some condition evaluates to true, until the action has 
               been run a maximum number of times. When the
               SBR is no longer valid it MAY be discarded by the Agent.                         
            </t>
            <t>
               Examples of SBRs include:
               <list>
                  <t>
                     Starting 2 hours from receipt, whenever Variable V1 > 10, 
                     produce a Report Entry for Report Template R1 no more 
                     than 20 times.                                    
                  </t>
                  <t>
                     Starting at some future absolute time, whenever Variable 
                     V2 != Variable V4, run Macro M1 no more than 36 times.
                  </t>
               </list> 
            </t>            
            <t>   
               SBRs are defined by their ARI, start time, condition,
               maximum run count, action, and description, as follows. 

               <list hangIndent="8" style="hanging">
                  <t hangText="(ARI) Identifier"><vspace blankLines="0" /> 
                     This Identifier MUST be of type SBR and MUST NOT 
                     be parameterized.
                  </t>
                  <t hangText="(TV) START"><vspace blankLines="0" />
                     The time at which the SBR condition should start to be 
                     evaluated. This will mark the first evaluation of the 
                     condition associated with the SBR.  
                  </t>
                  <t hangText="(EXPR) CONDITION"><vspace blankLines="0" />
                     The Expression which, if true, results in the SBR 
                     running the associated action. An Expression is 
                     considered true if it evaluates to a non-zero
                     number. 
                  </t>
                  <t hangText="(UVAST) COUNT"><vspace blankLines="0" />
                     The number of times the SBR action can be run.  
                     The special value of 0 indicates there is no limit
                     on how many times the action can be run.
                  </t>
                  <t hangText="(AC) ACTION"><vspace blankLines="0" />
                     The collection of Controls and/or Macros to
                     run as part of the action. This is captured as an AC
                     data type with the constraint that every ARI within the
                     AC represent a Control or Macro.
                  </t>
                  <t hangText="(STR) Description"><vspace blankLines="0" /> 
                     This represents the human-readable description of the 
                     SBR, as a string.
                  </t>                  
                  
               </list>               
            </t>
         </section> 

         <section title="Tables">
            <t>
               A Table is a named, typed, collection of tabular data. Columns 
               within a table are named and typed. Rows within a table capture 
               individual data sets with one value in each row corresponding to 
               one column in the table. Tables are represented in two ways in 
               the AMM: Table Templates and Table Instances.
            </t>
            
            <section title="Table Template (TBLT)">
               <t>
                  A table template identifies the strongly-typed column 
                  template that will be followed by any instance of this table 
                  available in the network. Table templates appear statically 
                  in ADMs and may not be created dynamically within the network 
                  by Managers. Changing a table template within an 
                  asynchronously managed network would result in confusion if 
                  differing template definitions for the same table identifier 
                  were to be active in the network at one time.
               </t>               
               <t>
                  TBLTs are defined by an ARI, a set of column descriptions, 
                  and table metadata, as follows. 
            
                  <list hangIndent="8" style="hanging">
                     <t hangText="(ARI) Identifier"><vspace blankLines="0" /> 
                        This Identifier MUST be of type TBLT and MUST be 
                        of type TBLT, and MUST NOT contain parameters.
                     </t>

                     <t hangText="(TNVC) Columns"><vspace blankLines="0" /> 
                        A TBLT is defined by its ordered set of columns 
                        descriptions captured as a TNVC with each TNV
                        in the collection describing a table column with
                        the following requirements. 
                        <list style="symbols">
                           <t> 
                              Type MUST be present and MUST be one of the 
                              primitive types defined in 
                              <xref target="prim_types"/>.
                           </t>
                           <t>
                              Name MAY be omitted in cases where a semantic
                              name for the column can be derived from the 
                              template.
                           </t>
                           <t> 
                              Value MUST NOT be present as a column does
                              not contain data values.
                           </t>
                        </list>
                     </t>

                     <t hangText="(STR) Description"><vspace blankLines="0" /> 
                        This represents the human-readable description of 
                        the TBLT, as a string.
                     </t>
                  </list>                                    
               </t>               
            </section>

            <section title="Table (TBL)">
               <t>
                  Tables are collections of data that MUST be constructed in 
                  accordance with an associated Table Template. Tables MUST NOT 
                  appear in the ADM for an application; they are only 
                  instantiated dynamically as part of the operation of a network.
               </t>
               <t>
                  TBLs are defined by their Table Template, the number of 
                  rows in the table, and the associated set of data values 
                  for each row.
            
                  <list hangIndent="8" style="hanging">
                     <t hangText="(ARI) Template Id"><vspace blankLines="0" /> 
                        This is the ARI of the Table Template holding the 
                        column definitions for this table. This ARI MUST 
                        be of type TBLT and match a known Table Template.
                     </t>

                     <t hangText="(UINT) Number of Rows"><vspace blankLines="0" />
                        This is the number of rows in the table. A Table 
                        MAY have zero rows. 
                     </t>
                     <t hangText="(TNVC) Rows Information"><vspace blankLines="0" />
                        Each row in a TBL is represented by a TNVC, with each
                        TNV in the collection representing the value for
                        a specific column with the following requirements. 
                        <list style="symbols">
                           <t> 
                              Type MAY be present, when necessary to
                              verify that elements in the row match the
                              types of table columns.
                           </t>
                           <t>
                              Name MUST NOT be present.
                           </t>
                           <t> 
                              Value MUST be present and compatible with the
                              type of the associated column.
                           </t>
                        </list>
                        <vspace/>
                        The number of TNVs in the collection MUST be equal 
                        to the number of columns defined for the Table 
                        Template. 
                     </t>
                  </list>                                    
               </t>
            </section>                        
         </section>

         <section title="Time-Based Rule (TBR)" anchor="tbr_chp">
            <t>
               A Time-Based Rule (TBR) specifies that starting at a particular 
               start time, and for every period seconds thereafter, an action 
               should be run by the Agent until the action has been run for 
               count times. When the TBR is no longer valid it MAY be discarded 
               by the Agent. 
            </t>
            <t>
               Examples of TBRs include:
               <list>
                  <t>
                     Starting 2 hours from receipt, produce a Report for 
                     Report Template R1 every 10 hours ending after 20 times.                                    
                  </t>
                  <t>
                     Starting at the given absolute time, run Macro M1 every
                     24 hours ending after 365 times.
                  </t>
               </list> 
            </t>               
            <t>                      
               TBRs are defined by their ARI, start time, period,
               maximum run count, action, and description, as follows. 

               <list hangIndent="8" style="hanging">
                  <t hangText="(ARI) Identifier"><vspace blankLines="0" /> 
                     This Identifier MUST be of type TBR and MUST NOT 
                     be parameterized.
                  </t>
                  <t hangText="(TV) Start"><vspace blankLines="0" />
                     The time at which the TBR should start to be evaluated. 
                     This will mark the first running of the action 
                     associated with the TBR.  
                  </t>
                  <t hangText="(TV) Period"><vspace blankLines="0" />
                     The time to wait between running the action
                     associated with the TBR. This value MUST be a relative
                     time value.
                  </t>
                  <t hangText="(UVAST) Count"><vspace blankLines="0" />
                     The number of times the TBR action may be run.  
                     The special value of 0 indicates the TBR should continue 
                     running the action indefinitely.
                  </t>
                  <t hangText="(AC) Action"><vspace blankLines="0" />
                     The collection of Controls and/or Macros to
                     run by the TBR. This is captured as a AC
                     with the constraint that every ARI within the AC
                     represent a Control or Macro.
                  </t>
                  <t hangText="(STR) Description"><vspace blankLines="0" /> 
                     This represents the human-readable description of the 
                     TBR, as a string.
                  </t>                  
                  
               </list>               
            </t>
         </section>
         
         <section title="Variable (VAR)" anchor="var_def">
            <t>
               Variables (VAR) may be statically defined in an ADM or 
               dynamically by Managers in a network deployment. VARs differ 
               from EDDs in that they are completely described by other known
               data in the system (either other VARs or other EDDs). 
               For example, letting E# be a EDD item and V# be
               a VAR item, the following are examples of VAR definitions.   
            </t>
            <t>
               V1 = E1 * E2
            </t>
            <t>
               V2 = V1 + E3
            </t>
            <t>
               VARs are defined by an ARI, a type, an initializing 
               expression, and a description, as follows.

               <list hangIndent="8" style="hanging">
                  <t hangText="(ARI) Identifier"><vspace blankLines="0" /> 
                     The type of this ARI MUST be type VAR, and 
                     the ARI MUST NOT contain parameters.
                  </t>
                  <t hangText="(UINT) Type"><vspace blankLines="0" />
                     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 <xref target="prim_types"/>.
                     <vspace/>
                     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. 
                  </t>
                  <t hangText="(EXPR) Initializer"><vspace blankLines="0" />
                     The initial value of the VAR is given by an 
                     initializing EXPR. In the case where the type of the 
                     VAR itself is EXPR, the initializer is used as the value 
                     of the VAR.  In the case where the type of the VAR is 
                     anything other than EXPR, then the initializer EXPR will 
                     be evaluated and the result of that evaluation will be 
                     the initial value of the VAR. 
                  </t>
                  
                  <t hangText="(STR) Description"><vspace blankLines="0" /> 
                     This represents the human-readable description of the 
                     VAR, as a string.
                  </t>
                                    
               </list>  
            </t>                     
         </section>  

         <section title="Common Object Processing">
            <t>
               This section describes the handling and exchange of AMM objects 
               between Agents and Managers in a network.
            </t>
            <t>
               Managers must:
               <list style="symbols">
                  <t> 
                     Store the ARI and definitions for both network-specific 
                     and ADM-defined AMM Objects.
                  </t>
                  <t> 
                     Send requests to Agents to add, list, describe, and remove 
                     custom AMM object definitions.
                  </t>    
                  <t> 
                     Verify and interpret reports against report templates and 
                     tables against table templates when receiving these objects 
                     from an Agent. 
                  </t>
                  <t> 
                     Encode ARIs in Objects to Agents, and decode ARIs from
                     Agents.
                  </t>     
                  <t>
                     Provide actual parameters when sending parameterized
                     objects to an Agent.
                  </t>           
               </list>
            </t>
            <t>
               Agents must:
               <list  style="symbols">
                  <t> 
                     Store the ARI for all ADM-defined AMM objects.
                  </t>
                  <t> 
                     Calculate the value of an AMM object when required, such
                     as when generating a Report or evaluating an Expression. 
                  </t>   
                  <t> 
                     Implement Controls in firmware and run Controls and
                     Macros with appropriate parameters when necessary in the 
                     context of Manager direction and Rule execution.
                  </t>
                  <t> 
                     Communicate "return" values from Controls back to 
                     Managers as Reports where appropriate. 
                  </t>   
                  <t> 
                     Persist custom AMM object definitions.
                  </t>     
                  <t> 
                     Add, remove, list, and describe custom AMM objects as
                     requested by Managers.
                  </t>
                  <t> 
                     Calculate the value of applying an Operator to a given set
                     of operands, such as when evaluating an Expression.
                  </t> 
                  <t> 
                     Populate Reports and Tables for transmission to Managers
                     when required.
                  </t>  
                  <t> 
                     Run the actions associated with SBRs and TBRs in accordance 
                     with their definitions.
                  </t>
                  <t> 
                     Calculate the value of VARs when required, such as during 
                     Rule evaluation, calculating other VAR values, and 
                     generating Reports. 
                  </t>
               </list>
            </t>
         </section>

      </section>
         
      <section title="Data Type Mnemonics and Enumerations" anchor="type_enum">
         <t>
            While the AMM does not specify any encoding of data model elements, 
            a common set of enumerations help to ensure that various encoding 
            standards can interoperate.
         </t>  
         <t>
            This section defines string (mnemonic) and integer (enumeration)
            mechanisms for referring to AMM data and object types. Data types
            are separated into 4 major categories:
         </t>

         <texttable title="Type Categories and Ranges" align="center" style="headers">
            <ttcol> Category </ttcol>
            <ttcol> Range </ttcol>

            <c> AMM Objects Types </c>
            <c> 0x00 - 0x0F </c>

            <c> Primitive Types </c>
            <c> 0x10 - 0x1F </c>

            <c> Compound Types </c>
            <c> 0x20 - 0x2F </c>

            <c> Reserved </c>
            <c> 0x30 - 0xFF </c>
         </texttable>
          
         <t>
            Within each category, the type of information, it's mnemonic,
            unique enumeration value, and whether it is considered a numeric
            value for expression evaluation are listed.
         </t>
         
         <section title="AMM Objects" anchor="amm_obj_enc">
            <t>
               AMM Objects include the set of objects identifiable using the
               ARI construct. The type field of the ARI MUST be one of these
               values. AMM Objects MUST be identified as follows. 
            </t>

            <texttable title="" suppress-title="true" align="center" style="headers">
               <ttcol width="50%" align="left">Structure</ttcol>
               <ttcol width="20%" align="left">Mnemonic</ttcol>
               <ttcol width="15%" align="left">Enumeration</ttcol>
               <ttcol width="15%" align="left">Numeric</ttcol>
                  
               <c>Constant</c>
               <c>CONST</c>
               <c>0</c>
               <c>No</c>

               <c>Control</c>
               <c>CTRL</c>
               <c>1</c>
               <c>No</c>

               <c>Externally Defined Data</c>
               <c>EDD</c>
               <c>2</c>
               <c>No</c>

               <c>Literal</c>
               <c>LIT</c>
               <c>3</c>
               <c>No</c>

               <c>Macro</c>
               <c>MAC</c>
               <c>4</c>
               <c>No</c>
         
               <c>Operator</c>
               <c>OPER</c>
               <c>5</c>
               <c>No</c>

               <c>Report</c>
               <c>RPT</c>
               <c>6</c>
               <c>No</c>

               <c>Report Template</c>
               <c>RPTT</c>
               <c>7</c>
               <c>No</c>

               <c>State-Based Rule</c>
               <c>SBR</c>
               <c>8</c>
               <c>No</c>

               <c>Table</c>
               <c>TBL</c>
               <c>9</c>
               <c>No</c>

               <c>Table Template</c>
               <c>TBLT</c>
               <c>10</c>
               <c>No</c>

               <c>Time-Based Rule</c>
               <c>TBR</c>
               <c>11</c>
               <c>No</c>

               <c>Variable</c>
               <c>VAR</c>
               <c>12</c>
               <c>No</c>

               <c>Reserved</c>
               <c></c>
               <c>13-15</c>
               <c>No</c>
            </texttable>
         </section>

         <section title="Primitive Data Types">
            <t>
               Primitive data include the basic set of objects that must be
               encoded to transfer AMM objects. All AMM objects are built 
               from combinations of these primitive types. Primitive types
               MUST be identified as follows.
            </t>
            <texttable title="" suppress-title="true" align="center" style="headers">
               <ttcol width="50%" align="left">Basic Data Type</ttcol>
               <ttcol width="20%" align="left">Mnemonic</ttcol>
               <ttcol width="15%" align="left">Enumeration</ttcol>
               <ttcol width="15%" align="left">Numeric</ttcol>
               
               <c>Boolean</c>
               <c>BOOL</c>
               <c>16</c>
               <c>No</c>

               <c>BYTE</c>
               <c>BYTE</c>
               <c>17</c>
               <c>No</c>

               <c>Character String</c>
               <c>STR</c>
               <c>18</c>
               <c>No</c>
               
               <c>Signed 32-bit Integer</c>
               <c>INT</c>
               <c>19</c>
               <c>Yes</c>

               <c>Unsigned 32-bit Integer</c>
               <c>UINT</c>
               <c>20</c>
               <c>Yes</c>

               <c>Signed 64-bit Integer</c>
               <c>VAST</c>
               <c>21</c>
               <c>Yes</c>

               <c>Unsigned 64-bit Integer</c>
               <c>UVAST</c>
               <c>22</c>
               <c>Yes</c>

               <c>Single-Precision Floating Point</c>
               <c>REAL32</c>
               <c>23</c>
               <c>Yes</c>
               
               <c>Double-Precision Floating Point</c>
               <c>REAL64</c>
               <c>24</c>
               <c>Yes</c>

               <c>Reserved</c>
               <c></c>
               <c>25-31</c>
               <c>No</c>                           
            </texttable>
         </section>

         <section title="Compound Data Types">
            <t>
               Compound data include combinations of primitive data types, to
               include collections. Compound types MUST be identified as follows.
            </t>
            <texttable title="" suppress-title="true" align="center" style="headers">
               <ttcol width="50%" align="left">Compound/Special Data Type</ttcol>
               <ttcol width="20%" align="left">Mnemonic</ttcol>
               <ttcol width="15%" align="left">Enumeration</ttcol>
               <ttcol width="15%" align="left">Numeric</ttcol>

               <c>Time Value</c>
               <c>TV</c>
               <c>32</c>
               <c>No</c>

               <c>Timestamp</c>
               <c>TS</c>
               <c>33</c>
               <c>No</c>

               <c>Type-Name-Value</c>
               <c>TNV</c>
               <c>34</c>
               <c>No</c>

               <c>Type-Name-Value Collection</c>
               <c>TNVC</c>
               <c>35</c>
               <c>No</c>

               <c>AMM Resource Identifier</c>
               <c>ARI</c>
               <c>36</c>
               <c>No</c>
                                                   
               <c>ARI Collection</c>
               <c>AC</c>
               <c>37</c>
               <c>No</c>

               <c>Expression</c>
               <c>EXPR</c>
               <c>38</c>
               <c>No</c>         

               <c>Byte String</c>
               <c>BYTESTR</c>
               <c>39</c>
               <c>No</c>         

               <c>Reserved - Protocol</c>
               <c></c>
               <c>40-47</c>
               <c>No</c>
            </texttable>
         </section>

         <section title="Numeric Promotions" toc="default">
         
            <t>
               When attempting to evaluate operators of different types, 
               an Agent may need to promote operands until 
               they are of the correct type. For example, if an Operator is 
               given both an INT and a REAL32, the INT should be promoted to a
         	   REAL32 before the Operator is applied.   
            </t>
         
            <t>
               Listing legal promotion rules is mandatory for ensuring that 
               behavior is similar across multiple implementations of Agents 
               and Managers. The listing of legal promotions in the AMM are 
               listed in <xref target="num_promo"/>. 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.
                         
               <figure align="center" anchor="num_promo" title="Numeric Promotions" suppress-title="false">
               <artwork align="center" xml:space="preserve">&#xA;<!--
               -->            INT     UINT     VAST     UVAST     REAL32   REAL64  &#xA;<!--
               -->          +--------+--------+--------+--------+--------+--------+&#xA;<!--
               -->   INT    | INT    | INT    | VAST   | UNK    | REAL32 | REAL64 |&#xA;<!--
               -->   UINT   | INT    | UINT   | VAST   | UVAST  | REAL32 | REAL64 |&#xA;<!--
               -->   VAST   | VAST   | VAST   | VAST   | VAST   | REAL32 | REAL64 |&#xA;<!--
               -->   UVAST  | UNK    | UVAST  | VAST   | UVAST  | REAL32 | REAL64 |&#xA;<!--
               -->   REAL32 | REAL32 | REAL32 | REAL32 | REAL32 | REAL32 | REAL64 |&#xA;<!--
               -->   REAL64 | REAL64 | REAL64 | REAL64 | REAL64 | REAL64 | REAL64 |&#xA;<!--
               -->          +--------+--------+--------+--------+--------+--------+
               </artwork>
               </figure>
           </t>
           <t>
         	   The AMM does not permit promotions between non-numeric types, and numeric
            	promotions not listed in this section are not allowed. Any attempt
            	to perform an illegal promotion SHOULD result in an error.
           </t>                      
         </section>   
         
         <section title="Numeric Conversions" toc="default">
           <t>
        	      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.
           </t>	
         </section>
      </section>
   </section>

   <section title="JSON ADM Template" anchor="adm_template">
      <t>
         This section provides an ADM template in the form of a JSON document
         and describes the JSON representation of AMM objects that MUST be used
         to populate this JSON ADM template.
      </t>
      <t>
         It is not required that these JSON encodings be used to
         encode the transmission of AMM information over the wire in the
         context of a network deployment. It is also not required that
         only these JSON encodings be used to document ADMs and other
         AMM information. Since the AMM is designed to allow
         for multiple encodings, the expression of ADMs in the
         provided JSON format is intended to support translation to other
         encodings without loss of information.
      </t>

      <section title="ADM Inclusion">
         <t>
            ADMs expressed in conformance with this template are captured
            as individual JSON files. AMM Objects defined in one ADM template 
            MAY refer to objects defined in another ADM template file. To
            enable type checking of these cross-ADM references, the ADM
            template supports the "uses" keyword to identify other ADM
            files that contain objects referenced in the current ADM file.
         </t>
         <t>
            The syntax of the uses statement is as follows.
            <vspace blankLines="1"/>
            "uses":["file1","file2",...,"fileN"] 
            <vspace blankLines="1"/>
            Where file_# represents a JSON-formatted ADM file defining a 
            namespace used in this ADM file.
         </t>
      </section>

      <section title="ADMT Object Collections">
         <t>
            The JSON ADM Template is defined as a JSON object containing a
            series of arrays - one for each type of information specified
            in the template. There are arrays for:
            <list style="symbols">
               <t>metadata constants</t>
               <t>EDD definitions</t>
               <t>VAR definitions</t>
               <t>RPTT definitions</t>
               <t>TBLT definitions</t>
               <t>CTRL definitions</t>
               <t>CONST definitions</t>
               <t>MAC definitions</t>
               <t>OP definitions</t>
            </list>
            Where each array is named after the mnemonic for the particular AMM
            object, as defined in <xref target="amm_obj_enc"/>, with the
            exception of the metadata (MDAT) array which is unique to the ADM template itself.
         </t>
         <t>
            In particular, the template does not provide definitions for RPT,
            TBL, SBR, or TBR objects as these are defined dynamically in the
            context of a network deployment. 
         </t>
         <t>
            The general format of the JSON ADM Template is as follows.

            <figure>
               <artwork>&#xA;<!--
               -->{&#xA;<!--
               -->  "Mdat" : [],&#xA;<!--
               -->  "Edd"  : [],&#xA;<!--
               -->  "Var"  : [],&#xA;<!--
               -->  "Rptt" : [],&#xA;<!--
               -->  "Tblt" : [],&#xA;<!--
               -->  "Ctrl" : [],&#xA;<!--
               -->  "Const : [],&#xA;<!--
               -->  "Mac"  : [],&#xA;<!--
               -->  "Oper" : []&#xA;<!--
               -->}
               </artwork>
            </figure>
         </t>
      </section>

      <section title="ADM Metadata">
         <t>
            The metadata array contains CONST objects that provide information 
            about the ADM itself.

            <list hangIndent="8" style="hanging">
               <t hangText="(STR) name"><vspace blankLines="0"/>                     
                  This is the human-readable name of the ADM that should 
                  appear in message logs, user-interfaces, and other
                  human-facing applications.
               </t>
               <t hangText="(STR) namespace"><vspace blankLines="0"/>                     
                  This is the Moderated Namespace of the ADM, as defined in
                  <xref target="adm_namespace_chp"/> and string-encoded
                  in accordance with <xref target="ari_str_enc"/>. 
               </t>
               <t hangText="(STR) version"><vspace blankLines="0"/>
                  This is a string representation of the version of the
                  ADM. ADM version representations are formated at the
                  discretion of the publishing organization. 
               </t>
               <t hangText="(STR) organization"><vspace blankLines="0"/>                     
                  This is the name of the issuing organization for this ADM.
               </t>
            </list>
         </t>
         <t>
            Metadata objects are encoded in the same way as CONST
            objects, in accordance with <xref target="const_json_enc"/>.
         </t>            
      </section>

      <section title="Type Encodings">
         <t>
            This section describes the JSON encoding of AMM data types
            defined in <xref target="amm_data_type_chp"/>. 
         </t>

         <section title="Primitive Type Encoding">
            <t>
               JSON data types generally have direct support for the AMM 
               primitive data types. The mapping of AMM primitive types to 
               JSON data types is provided in <xref target="prim_type_enc"/>.
            </t>
               
            <texttable anchor="prim_type_enc" title="Primitive Type Encoding">
               <ttcol align="center">AMM Type</ttcol>
               <ttcol align="center">JSON Encoding</ttcol>
            
               <c>BYTE</c>
               <c>number (0 &lt;= # &lt;= 256)</c>
            
               <c>INT</c>
               <c>number</c>

               <c>UINT</c>
               <c>number</c>

               <c>VAST</c>
               <c>number</c>

               <c>UVAST</c>
               <c>number</c>

               <c>REAL32</c>
               <c>number</c>

               <c>REAL64</c>
               <c>number</c>

               <c>STRING</c>
               <c>string</c>

               <c>BOOL</c>
               <c>boolean</c>         
            </texttable>               
         </section>

         <section title="Derived Type Encoding">
            <t>
               In cases where an AMM derived type is simply a special 
               interpretation of a primitive type, the JSON encoding of the 
               derived type will be the same as the JSON encoding of the 
               primitive type from which it derives.
            </t>

            <section title="Type-Name-Value">   
               <t>
                  A TNV is encoded as a JSON object with three elements: "type", 
                  "name", and "value". For each item in a TNV, there are three 
                  acceptable formulations that can be used to represent the
                  item, as illustrated in the following table. For the examples in 
                  this table, consider the REAL32 value of PI as 3.14159.
               </t>
                        
               <texttable anchor="tnv_types" title="TNV Formulations">
                  <ttcol align="center"> Desc</ttcol>
                  <ttcol align="center">Example</ttcol>
               
                  <c>Full</c>
                  <c>{"type":"REAL32", "name":"PI", "value":3.14159}</c>
                  
                  <c>Named Type</c>
                  <c>{"type":"REAL32", "name":"PI", "value":null}</c>

                  <c>Anonymous Type</c>
                  <c>{"type":"REAL32", "name":null, "value":null}</c>

                  <c>Anonymous Type Value</c>
                  <c>{"type":"REAL32", "name":null, "value":3.14159}</c>

                  <c>Anonymous Value</c>
                  <c>{"type":null, "name":null, "value":3.14159}</c>
               </texttable>             
            </section>
         </section>

         <section title="Collection Encoding" anchor="expr_enc">
            <t>
               The TNVC and AC collections are encoded as JSON arrays, with 
               each object in the array represented in accordance with the JSON 
               encoding for that object type (TNV or ARI, respectively). 
            </t>
            <t>
               An Expression is encoded as a JSON object with two elements: a
               type and a postfix-expr. The description of these elements is as 
               follows.
            
               <list hangIndent="8" style="hanging">
                  <t hangText="(UINT) type"><vspace blankLines="0"/>
                     The data type of the evaluation of the initializer 
                     expression.
                  </t>
                  <t hangText="(AC) postfix-expr"><vspace blankLines="0"/>
                     A JSON array of elements where each element is an JSON 
                     encoding of an ARI in conformance to 
                     <xref target="aid_json_enc"/>.
                  </t>
               </list>
            </t>
            <t>
               The following is an example of a JSON encoding of an EXPR object.
               <figure>
                  <artwork>&#xA;<!--
                  -->"type": "UINT", &#xA;<!--
                  -->"postfix-expr": ["Edd.item1","Edd.item2","Oper.+UINT"]
                  </artwork>
               </figure>
            </t>
         </section>
      </section>

      <section title="ARI Encoding" anchor="aid_json_enc">
         <t>
            An ARI may be encoded as either a string or as a JSON object, with
            the two representations being unambiguously interchangeable. 
            Additionally, there exists a long-form and short-form encoding
            of the ARI.
         </t>

         <t>
            String encodings provide a more compact and human-readable 
            representation of the ARI. When an ARI is represented as a
            string in a JSON object, it MUST be encoded in accordance with
            <xref target="ari_str_enc"/>. If the ARI references an object that 
            is defined in the current ADM, then the shortform string encoding
            may be used, as described in <xref target="ari_str_short"/>. The
            object name to be used in the string encoding is the same as the
            "nm" value for the JSON object encoding, as described below.
         </t>
         <t>
            JSON object encoding of the ARI provides additional structure that
            makes ARI information verification easier. An ARI is encoded as a 
            JSON object with three keys: namespace, object name, and parameters, 
            encoded as follows.

            <list hangIndent="8" style="hanging">
               <t hangText="ns"><vspace blankLines="0"/> 
                  This element identifies the namespace within which the
                  ARI has been defined, and encoded as a string in accordance
                  with <xref target="ari_str_enc"/>. In cases where the ARI 
                  identifies an object defined in the ADM in which it is used, 
                  the ADM's namespace may be assumed as the namespace of the 
                  ADM and this element can be omitted from the ARI JSON object.
               </t>
               <t hangText="nm"><vspace blankLines="0"/> 
                  The name of an object defined in an ADM is a string defined
                  as the concatenation of the ADMT collection defining the
                  object, the "." separator, and the string name of the
                  object itself. For example, an EDD defined in the Edd
                  array and named edd1 would have the string name "Edd.edd1".
               </t>
               <t hangText="fp"><vspace blankLines="0"/> 
                  ARI formal parameters, if present, are defined as an array
                  with each element in the array representing the JSON TNV
                  encoding of the parameter. If a default value is not defined
                  for the parameter, then the value of the TNV MUST be omitted.
                  <vspace blankLines="1"/>
                  The fp element is not used when AMM objects are defined in
                  the context of an ADM, as the ADM template for defining
                  objects already includes parameter information. This 
                  element is used when AMM objects are defined in accordance
                  with the JSON ADM syntax, but by network operators as
                  part of network-specific configuration.
                  <vspace blankLines="1"/>
                  If the ARI JSON object has the fp element, then it MUST NOT
                  have the ap element. An ARI MUST NOT define both formal and
                  actual parameters in the same object instance.
               </t>
               <t hangText="ap"><vspace blankLines="0"/> 
                  ARI actual parameters, if present, are defined as an 
                  array with each element of the array representing the JSON TNV
                  encoding of the parameter. In cases where an optional 
                  parameter is not present, an empty TNV object will be used
                  in its place for that parameter. The name element of the
                  TNV MUST NOT be present for actual parameters. 
                  <vspace blankLines="1"/>
                  In cases where the actual parameter is by value, then the
                  TNV value key will hold the JSON encoding of the value of
                  the parameter.
                  <vspace blankLines="1"/>
                  In cases where the actual parameter is by name, then the
                  TNV MUST have the type "ParmName" and the value MUST be
                  the string name of the parameter whose value should be
                  used to populate the value of this actual parameter,
                  as described in <xref target="ap_descr"/>.   
                  <vspace blankLines="1"/>
                  If the ARI JSON object has the fp element, then it MUST NOT
                  have the ap element. An ARI MUST NOT define both formal and
                  actual parameters in the same object instance.               
               </t>
            </list>
         </t>

         <t>            
            The following are examples of JSON encoded ARI objects.
         </t>

         <texttable anchor="parm_encode" title="Formal Parameter Encoding">
            <ttcol align="center">String Encoding</ttcol>
            <ttcol align="center">JSON Encoding</ttcol>
         
            <c>"N1/N2/Edd.edd1"</c>
            <c>{"ns":"N1/N2", "nm":"Edd.edd1"}</c>

            <c>"N1/N2/Edd.edd2(UINT num=3)"</c>
            <c>{"ns":"N1/N2", "nm":"Edd.edd2", "fp":[{"type":"UINT", "name"="num", value":3}]}</c>

            <c>"N1/N2/Edd.edd2()"</c>
            <c>{"ns":"N1/N2", "nm":"Edd.edd2", "ap":[{}]}</c>

            <c>"N1/N2/Edd.edd2(4)"</c>
            <c>{"ns":"N1/N2", "nm":"Edd.edd2", "ap":[{"type":"UINT", "value":4}]}</c>

            <c>"N1/N2/Edd.edd3(&lt;input&gt;)"</c>
            <c>{"ns":"N1/N2", "nm":"Edd.edd3", "ap":[{"type":"ParmName", "value":"input"}]}</c>
         </texttable>
      </section>

      <section title="ADM Structures">

         <section title="General Notes" anchor="gen_parm">
            <t>
               The following guidelines apply to the JSON encoding of AMM 
               objects. 

               <list hangIndent="8" style="hanging">
                  <t hangText="Identification"><vspace blankLines="0"/> 
                     Objects do not include an ARI object as part of their
                     definition. All of the contents of an
                     ARI are derivable in the context of the ADM and adding 
                     an ARI encoding as part of the AMM object definition 
                     would be redundant and require maintaining naming 
                     information in two places in the ADM document. 
                  </t>
                  <t hangText="Common Elements"><vspace blankLines="0"/> 
                     Every JSON encoding of an AMM object MUST have the
                     following elements:
                     <list style="symbols">
                        <t> Name<vspace/>
                           The identifier of the AMM Object. This MUST be 
                           unique across all name elements defined in the
                           ADM collection of these types of objects. 
                        </t>
                        <t> Description<vspace/>
                           A string description of the kind of data represented 
                           by this data item.
                        </t>
                     </list>
                  </t>
                  <t hangText="Formal Parameters" anchor="fp_enc"><vspace blankLines="0"/> 
                     If an AMM object may be parameterized, then an element
                     MUST be present in the JSON object named "parmspec" which
                     is defined as a JSON-encoded TNVC. Each element in the TNVC 
                     representing the JSON TNV encoding of the formal parameter. 
                     If a default value is not defined for the parameter, then 
                     the value of the TNV MUST be omitted.
                  </t>                  
               </list>
            </t>             
         </section>

         <section title="Constant (CONST) Encoding" anchor="const_json_enc">
            <t>
               The CONST JSON object is comprised of four elements: "name", "type",
               "value, and "description". The description of these elements is as follows:

               <list hangIndent="8" style="hanging">
                  <t>
                     Name<vspace/>
                     The identifier of the constant. This MUST be unique across all
                     name elements for CONSTs in the ADM.
                  </t>
                  <t>
                     Type<vspace/>
                     The strong typing of this data value. Types MUST be one of those defined in
                     <xref target="type_enum"/>.
                  </t>
                  <t>
                     Value<vspace/>
                     The value of the constant, expressed in the JSON encoding of the data
                     type.
                  </t>
                  <t>
                     Description<vspace/>
                     A string description of the kind of data represented by this data item.
                  </t>
               </list>
            </t>
            <t>
               The following is an example of a JSON encoding of a CONST object.
               <figure>
                  <artwork>&#xA;<!--
                  -->"name": "PI",                    &#xA;<!--
                  -->"type": "REAL64",                 &#xA;<!--
                  -->"value": 3.14159,                &#xA;<!--
                  -->"description": "The value of PI."                  
                  </artwork>
               </figure>
            </t>
         </section>

         <section title="Control (CTRL) Encoding">
            <t>
               The CTRL JSON object is comprised of three elements: "name", "parmspec", 
               and "description". The description of these elements is as follows:

               <list hangIndent="8" style="hanging">
                  <t>
                     Name<vspace/>
                     The identifier of the control. This MUST be unique across all
                     name elements for CTRLs in the ADM.
                  </t>
                  <t>
                     ParmSpec<vspace/>
                     This optional item describes parameters for this control. This is
                     encoded as an array where each element in the array is encoded as
                     a formal parameter in accordance with <xref target="fp_enc"/>.
                  </t>    
                  <t>
                     Description<vspace/>
                     A string description of the kind of data represented by this data item.
                  </t>
               </list>
            </t>
            <t>
               The following is an example of a JSON encoding of an CTRL object.
               <figure>
                  <artwork>&#xA;<!--
                  -->"name": "reset_src_cnts",                                   &#xA;<!--
                  -->"parmspec": [{"type":"STR","name":"src"}],                  &#xA;<!--
                  -->"description": "This control resets counts for the given source."
                  </artwork>
               </figure>
            </t>
         </section>
         <section title="Externally Defined Data (EDD) Encoding">
            <t>
               The EDD JSON object is comprised of four elements: "name", 
               "type", "parmspec", and "description". The description of these 
               elements is as follows:

               <list hangIndent="8" style="hanging">
                  <t>
                     Name<vspace/>
                     The identifier of the EDD data item. This MUST be unique 
                     across all name elements for EDDs in the ADM.
                  </t>
                  <t>
                     Type<vspace/>
                     The strong typing of this data value. Types MUST be one of 
                     those defined in <xref target="type_enum"/>.
                  </t>
                  <t>
                     ParmSpec<vspace/>
                     The optional array of formal parameters encoded in 
                     accordance with <xref target="fp_enc"/>.
                  </t>
                  <t>
                     Description<vspace/>
                     A string description of the kind of data represented by 
                     this data item.
                  </t>
               </list>
            </t>
            <t>
               The following is an example of a JSON encoding of an EDD object.
               <figure>
                  <artwork>&#xA;<!--
                   -->"name": "num_good_tx_bcb_blks_src",             &#xA;<!--
                   -->"type": "UINT",                                 &#xA;<!--
                   -->"parmspec": [{"type":"STR","name":"Src"}],      &#xA;<!--
                   -->"description": "Successfully Tx BCB blocks from SRC"
                  </artwork>
               </figure>
            </t>
         </section>


         <section title="Macro Encoding">
            <t>
               The Macro JSON object is comprised of three elements: "name", "definition", 
               and "description". The description of these elements is as follows:

               <list hangIndent="8" style="hanging">
                  <t>
                     Name<vspace/>
                     The identifier of the macro. This MUST be unique across all
                     name elements for MACs in the ADM.
                  </t>
                  <t>
                     Definition<vspace/>
                     This is a JSON array whose elements are shorthand references are
                     in accordance with <xref target="aid_json_enc"/> and are of the
                     type CTRL or MAC.
                  </t>
                  <t>
                     Description<vspace/>
                     A string description of the kind of data represented by this data item.
                  </t>
               </list>
            </t>
            <t>
               The following is an example of a JSON encoding of an MAC object.
               <figure>
                  <artwork>&#xA;<!--
                  --> "name": "user_list",                          &#xA;<!--
                  -->  "definition": [{                           &#xA;<!--
                  -->    "nm":"Ctrl.list_vars",                   &#xA;<!--
                  -->    "ap": []                                 &#xA;<!--
                  -->},                                           &#xA;<!--
                  -->{                                            &#xA;<!--
                  -->   "nm":Ctrl.list_rptts"                     &#xA;<!--
                  -->   "ap": []                                  &#xA;<!--
                  -->}],                                          &#xA;<!--
                  -->"description": "List user defined data."    
                  </artwork>
               </figure>
            </t>
         </section>


         <section title="Operator (OP) Encoding">
            <t>
               The OP JSON object is comprised of four elements: "name", "result-type",
               "in-type", and "description". The description of these elements is as follows.

               <list hangIndent="8" style="hanging">
                  <t>
                     Name<vspace/>
                     The identifier of the operator. This MUST be unique across all
                     name elements for OPs in the ADM.
                  </t>
                  <t>
                     Result-Type<vspace/>
                     The numeric result of applying the operator to the series of operands.
                     This must be one of the encodings for <xref target="prim_types"/>.
                  </t>
                  <t>
                     In-Type<vspace/>
                     This is an ordered JSON array of operands for the operator. Each
                     operand is a data type encoded in
                     accordance with <xref target="prim_types"/>. 
                  </t>
                  <t>
                     Description<vspace/>
                     A string description of the kind of data represented by this data item.
                  </t>
               </list>
            </t>
            <t>
               The following is an example of a JSON encoding of an OP object.
               <figure>
                  <artwork>&#xA;<!--
                  -->"name": "plusINT",            &#xA;<!--
                  -->"result-type": "INT",      &#xA;<!--
                  -->"in-type": ["INT", "INT"], &#xA;<!--
                  -->"description": "Int32 addition"                  
                  </artwork>
               </figure>
            </t>
         </section>


         <section title="Table Template (TBLT) Encoding">
            <t>
               The TBLT JSON object is comprised of four elements: "name", "columns", 
               and "description". The description of these elements is as follows:

               <list hangIndent="8" style="hanging">
                  <t>
                     Name<vspace/>
                     The identifier of the table template data item. This MUST be unique across all
                     name elements for TBLTs in the ADM.
                  </t>
                  <t>
                     Columns<vspace/>
                     This is a JSON array of elements, with each element representing
                     the definition of the type of information represented in each column.
                     Each column is described using the same encoding as a TNV
                     described in  <xref target="tnv_types"/>.
                  </t>
                  <t>
                     Description<vspace/>
                     A string description of the kind of data represented by this data item.
                  </t>
               </list>
            </t>
            <t>
               The following is an example of a JSON encoding of an TBLT object.
               <figure>
                  <artwork>&#xA;<!--
                  -->"name":"keys",                                          &#xA;<!--
                  -->"columns": [{"type":"STR","name":"ciphersuite_names"}], &#xA;<!--
                  -->"description": "This table lists supported cipher suites."
                  </artwork>
               </figure>
            </t>
         </section>

         <section title="Report Template Encoding">
            <t>
               The RPTT JSON object is comprised of four elements: "name", "parmspec", 
               "definition", and "description". The description of these elements is as follows:

               <list hangIndent="8" style="hanging">
                  <t>
                     Name<vspace/>
                     The identifier of the report template. This MUST be unique across all
                     name elements for RPTTs in the ADM.
                  </t>
                  <t>
                     ParmSpec<vspace/>
                     This optional item describes parameters for this report. This is
                     encoded as an array where each element in the array is encoded as
                     a formal parameter in accordance with <xref target="fp_enc"/>.
                  </t>
                  <t>
                     Definition<vspace/>
                     This is an array of data elements that represent the ordered set of
                     information associated with the report. Each element in the array
                     is encoded as a data item shorthand in accordance with <xref target="aid_json_enc"/>.
                     <vspace/>
                     Report item elements MAY use reference parameters in their definition.
                     In those cases, the reference parameters in the definition list MUST
                     match report entry parameter names from the ParmSpec element in the
                     report template definition.
                  </t>
                  <t>
                     Description<vspace/>
                     A string description of the kind of data represented by this data item.
                  </t>
               </list>
            </t>
            <t>
               The following is an example of a JSON encoding of an RPTT object.
               <figure>
                  <artwork>&#xA;<!--
                  -->{                                                  &#xA;<!--
                  -->   "name": "default_report",                       &#xA;<!--
                  -->   "parmspec": [{                                  &#xA;<!--
                  -->      "type": "STR",                               &#xA;<!--
                  -->      "name": "endpoint_id"                        &#xA;<!--
                  -->   }],                                             &#xA;<!--
                  -->   "definition": [                                 &#xA;<!--
                  -->     {                                             &#xA;<!--
                  -->        "ns": "DTN:bp",
                             "nm": "Edd.edd_using_a_parm",    &#xA;<!--
                  -->        "ap": [{                                &#xA;<!--
                  -->           "type": "PARMNAME",                    &#xA;<!--
                  -->           "value": "endpoint_id"                  &#xA;<!--
                  -->        }]                                         &#xA;<!--
                  -->     },                                            &#xA;<!--
                  -->     {  
                             "ns": "DTN:bp",                                            &#xA;<!--
                  -->        "nm": "Edd.edd_with_default ",   &#xA;<!--
                  -->        "ap": [{                                &#xA;<!--
                  -->           "type": "INT",                          &#xA;<!--
                  -->           "value": ""}                            &#xA;<!--
                  -->        ]},                                        &#xA;<!--
                  -->     {  "ns": "DTN:bp",                                            &#xA;<!--
                  -->        "nm": "Edd.edd_with_no_parms ",  &#xA;<!--
                  -->        "ap": []                                &#xA;<!--
                  -->     }                                             &#xA;<!--
                  -->   ]                                               &#xA;<!--
                  -->   "description": "A default report."              &#xA;<!--
                  -->}
                  </artwork>
               </figure>
            </t>
         </section>

         <section title="Variables Encoding">
            <t>
               The VAR JSON object is comprised of four elements: "name", "type", 
               "initializer", and "description". The description of these 
               elements is as follows:

               <list hangIndent="8" style="hanging">
                  <t>
                     Name<vspace/>
                     The identifier of the variable data item. This MUST be unique across all
                     name elements for VARs in the ADM.
                  </t>
                  <t>
                     Type<vspace/>
                     The strong typing of this data value. Types MUST be one of those defined in
                     <xref target="type_enum"/>.
                  </t>
                  <t>
                     Initializer<vspace/>
                     The expression used to establish the initial value of the variable.
                     This initializer is an expression encoded in conformance with 
                     <xref target="expr_enc"/>.
                  </t>
                  <t>
                     Description<vspace/>
                     A string description of the kind of data represented by this data item.
                  </t>
               </list>
            </t>
            <t>
               The following is an example of a JSON encoding of an VAR object.
                <figure>
                     <artwork>&#xA;<!--
                     -->{                                                                 &#xA;<!--
                     -->   "name": "total_bad_tx_blks",                                       &#xA;<!--
                     -->   "type": "UINT",                                                 &#xA;<!--
                     -->   "initializer": {                                                &#xA;<!--
                     -->      "type": "UINT",                                               &#xA;<!--
                     -->      "postfix-expr": [{                                           &#xA;<!--
                     -->         "nm": "Edd.item1",                                        &#xA;<!--
                     -->        "ap": [{                                                   &#xA;<!--
                     -->            "type": "UINT",                                        &#xA;<!--
                     -->            "value": 0                                             &#xA;<!--
                     -->         }]                                                        &#xA;<!--
                     -->      }, {                                                         &#xA;<!--
                     -->         "nm":"Edd.item2",                                         &#xA;<!--
                     -->         "ap":[{                                                   &#xA;<!--
                     -->            "type":"UINT",                                         &#xA;<!--
                     -->            "value": 1                                             &#xA;<!--
                     -->         ]}                                                        &#xA;<!--
                     -->      }, {                                                         &#xA;<!--
                     -->         "nm": "Oper.plusUINT",                                      &#xA;<!--
                     -->         "ap":[]                                                   &#xA;<!--
                     -->      }]                                                           &#xA;<!--
                     -->                                                                   &#xA;<!--
                     -->   },                                                              &#xA;<!--
                     -->   "description": "# total items (# item1 + # item2)."             &#xA;<!--
                     --> }
                     </artwork>
                  </figure>
            </t>
         </section>

         
         <section title="Exemptions">
            <t>
               Certain AMM objects are not intended to be statically defined
               in the context of an ADM document. Literals, Reports, Tables,
               State-Based Rules, and Time-Based Rules all only have 
               meaning in the context of an operational network. These 
               objects are defined by network operators as part of network-specific
               configuration and therefore not present in the ADM Template.
            </t>
         </section>

      </section>
   </section>

   <section title="ADM Author Considerations" anchor="auth_consid">
      <t>
         The AMM model provides multiple ways to represent certain types of
         data. This section provides informative guidance on how to express
         application management constructs efficiently when authoring an
         ADM document.
      </t>

      <t>
         <list style="hanging" hangIndent="4">
            <t hangText="Use Parameters for Dynamic Information."><vspace blankLines="0"/>
               Parameters provide a powerful mechanism for expressing associative
               look-ups of EDD data. EDDs SHOULD be parameterized when the definition
               of the EDD is dependent upon run-time information. For example, if
               requesting the number of bytes through a specific endpoint, the
               construct num_bytes("endpoint_name") is simpler to understand and
               more robust to new endpoint additions than attempting to enumerate the
               number and name of potential endpoints when defining the ADM.
            </t>

            <t hangText="Do Not Use Parameters for Static Information."><vspace blankLines="0"/>
               Parameters incur bandwidth and processing costs (such as type
               checking) and should only be used where necessary. 
               If an EDD object can be parameterized, but the set of parameters
               is known and unchanging it may be more efficient to define
               multiple unparameterized EDD objects instead. For example, consider
               a single parameterized EDD object reporting the number of bytes 
               of data received for a specific, known set of priorities and a
               request to report on those bytes for the "low", "med", and "high"
               priorities. Below are two ways to represent these data: using
               parameters and not using parameters.

                <figure align="center">
                     <artwork align="center">&#xA;<!--
                     --> +------------------------+------------------------+&#xA;<!--
                     --> |   Parameterized EDDs   | Non-Parameterized EDDs |&#xA;<!--
                     --> +------------------------+------------------------+&#xA;<!--
                     --> | num_bytes_by_pri(low)  | num_bytes_by_low_pri   |&#xA;<!--
                     --> | num_bytes_by_pri(med)  | num_bytes_by_med_pri   |&#xA;<!--
                     --> | num_bytes_by_pri(high) | num_bytes_by_high_pri  |&#xA;<!--
                     --> +------------------------+------------------------+
                  </artwork>
               </figure>
               
               The use of parameters in this case only incurs the
               overhead of type checking, parameter encoding/decoding, and 
               associative lookups. This situation should be avoided when 
               deciding when to parameterize AMM objects.
            </t>

            <t hangText="Use Tables for Related Data."><vspace blankLines="0"/>
               In cases where multiple EDD or VAR values are likely to be
               evaluated together, then that information SHOULD be placed in a
               Table Template rather than defining multiple EDD and VAR objects.
               By making a Table Template, the relationships amongst various
               data values are preserved. Otherwise, Managers would need to
               remember to query multiple EDD and/or VAR objects together which
               is burdensome, but also results in high bandwidth and processor
               utilization.
            </t>
         </list>
      </t>
   </section>

   <section anchor="IANA" title="IANA Considerations">
      <t>
         This document defines a moderated namespace registry in
         <xref target="mod_nmsp_chp"/>. This registry is envisioned to be 
         moderated by IANA. Entries in this registry are to be made through
         Expert Review. 
      </t>
      <t>
         This document defines a new URI scheme, "ari", as defined in
         <xref target="ari_str_can_form"/>.
      </t>
   </section>
   
   <section anchor="Security" title="Security Considerations">
      <t>
         This document does not describe any on-the-wire encoding or other
         messaging syntax. It is assumed that the exchange of AMM objects
         between Agents and Managers occurs within the context of an 
         appropriate network environment. 
      </t>
      <t>
         This AMM model may be extended to include the concept of Access
         Control Lists (ACLs) to enforce roles and responsibilities
         amongst Managers in the network. This access control would be
         implemented separately from network security mechanisms.
      </t>
   </section>

</middle>
  
  <!--  *****BACK MATTER ***** -->
<back>
   <references title="Normative References">
      &RFC2119;
      &RFC3986;
      &RFC3339;
      &RFC4648;
   </references>
  
   <references title="Informative References">
      <?rfc include="reference.I-D.draft-birrane-dtn-ama-06"?>      
   </references>
  
</back>

</rfc>
