<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE rfc SYSTEM "rfc2629.dtd">
<?rfc toc="yes"?><rfc ipr="trust200902" category="exp" docName="draft-bsipos-dtn-amp-yang-01">
  <front>
    <title abbrev="A YANG profile for AMP ADMs">
      A YANG profile for defining
      Asynchronous Management Protocol
      Application Data Models
    </title>
    <author initials="B." surname="Sipos" fullname="Brian Sipos">
      <organization abbrev="RKF Engineering">
        RKF Engineering Solutions, LLC
      </organization>
      <address>
        <postal>
        <street>1229 19th Street NW</street>
        <city>Wasington</city>
        <region>DC</region>
        <code>20036</code>
        <country>US</country>
        </postal>
        <email>BSipos@rkf-eng.com</email>
      </address>
    </author>
    <author initials="E." surname="Birrane" fullname="Edward Birrane" role="editor">
      <organization abbrev="JHU APL">
        Johns Hopkins University Applied Physics Laboratory
      </organization>
      <address>
        <email>Edward.Birrane@jhuapl.edu</email>
      </address>
    </author>
    <date year="2016" month="April"/>
    <workgroup>Delay Tolerant Networking</workgroup>

    <abstract><t>
      This document specifies a YANG profile for defining
      Application Data Model (ADM) schema for the
      Asynchronous Management Protocol (AMP).
      The AMP has no relation to NETCONF; YANG is used here only for
      its language syntax, and its module and type systems.
    </t></abstract>
  </front>

  <middle>
    <section title="Introduction">
      <t>
      This profile uses YANG <xref target="RFC6020"/>
      as an encoding for the management schema and
      makes use of the YANG module and type systems.
      The fact that YANG is also used to specify data models for the
      NETCONF protocol has no direct influence over this use of YANG
      to specify data models for AMP.
      </t>
      <t>
      This specification follows <xref target="RFC6087"/> in the definition
      of the "amp-adm" YANG module.
      The amp-adm module defines only subtypes and extensions; it does not
      define any actual data model elements.
      </t>
      <t>
      
      </t>

      <section title="Requirements Language">
        <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>
    
    <section title="Application Data Models">
      <t>
      An AMP application SHALL define its Application Data Model (ADM) by means
      of a YANG module which imports and uses "amp-adm" module extensions.
      An official Pyang tool <xref target="pyang"/> plugin SHOULD be used
      to validate the contents of an ADM YANG module.
      </t>
      
      <section title="Module Restrictions">
        <t>
        A YANG module which defines an AMP ADM SHALL NOT be used to also define
        a data model for NETCONF or any other non-AMP protocol.
        It may be syntatically allowable to mix models for multiple protocols
        but it decreases the intelligability of the module for either purpose.
        </t>
        <t>
        A YANG module which defines an AMP ADM SHALL NOT contain any
        "default" statements.
        </t>
      </section>
      
      <section title="OID Assignment" anchor="oid-assign">
        <t>
        For each ADM-specific YANG statement which requires an OID to be
        assigned to it, it is possible to use one of the
        "fulloid", "suboid", or "compressoid" substatements to make that
        assignment.
        Not all of the OID assignment substatements are available in all
        contexts, so following the allowed substatement table is important.
        </t>
        <t>
        The types of OID assignments are:
          <list style="symbols">
            <t>
            Full OIDs can be used in any situation where an OID is needed.
            </t>
            <t>
            Compressed OIDs can also be used in any situation where an OID is
            needed, but require the use of a module-unique OID nickname ID.
            </t>
            <t>
            Sub-OIDs can be used where the OID being assigned is relative to the
            structural (module-statement-wise) parent of the assignment.
            </t>
          </list>
          An ADM SHOULD make use of sub-OIDs where possible, both to avoid
          typos possible with full OIDs and to avoid nickname assignment for
          every group within the ADM.
          Using sub-OIDs also guarantees that the tree structure of the ADM
          module matches one-for-one with the OID tree.
        </t>
      </section>
    </section>

    <section title="YANG Types for AMP">
      <t>
      This section specifies how AMP types interact with native YANG types.
      All AMP data types are sub-typed from YANG native types solely
      for the purpose of providing a baseline of behavior for YANG
      parsers.
      Any YANG module which defines an AMP ADM SHALL only use types 
      (or derived types) from the "amp-adm" module.
      </t>

      <section anchor="types.integer" title="The Integer Types">
        <t>
        The AMP types of "BYTE", "INT", "UINT", "VAST", and "UVAST" are derived
        directly from the built-in YANG type of the same numeric domain.
        There is no functional difference between these types and the native
        types, other than the namespace of these types.
        Using AMP-specific names allows ADM module authors to keep consistent
        terminology between textual specification and YANG specification.
        </t>
        <t>
        The "SDNV" type is derived from YANG "binary" type due to its domain
        being larger than any of the built-in YANG types.
        </t>
      </section>

      <section anchor="types.float" title="The Floating Point Types">
        <t>
        The AMP types of "REAL32" and "REAL64" are derived from YANG "binary"
        type because the built-in floating point type is not a clear
        superset of the floating point types of 
        <xref target="I-D.birrane-dtn-amp"/>.
        </t>
      </section>
      
      <section anchor="types.othersimple" title="Other Simple Types">
        <t>
        The "SDNV" type is derived from YANG "binary" type due to its domain
        being larger than any of the built-in YANG numeric types.
        </t>
        <t>
        The "TS" type is also derived from YANG "binary" type due to the
        more complex encoding semantics of the TS type.
        </t>
      </section>

      <section anchor="types.compound" title="The Compound Types">
        <t>
        The "STR" type is derived from the YANG "string" type only because
        they both are intended to have the semantics of human-readable text.
        An ADM SHOULD NOT use the amp:STR type for any data other than text
        encoded with UTF-8 (see <xref target="RFC3629"/>).
        The encoding of "STR" type is wholy unrelated to any NETCONF use
        of the YANG "string" type.
        </t>
        <t>
        The "BLOB" type is derived from YANG "binary" type.
        The BLOB is the simplest AMP-specific type which is encoded using
        internal sub-items (the size separate from the bytes).
        </t>
        <t>
        The "DC" and "TDC" types are also derived from YANG "binary" type
        for lack of specific YANG mechanism for type decomposition.
        </t>
      </section>

      <section anchor="types.oids" title="Object Identifier Types">
        <t>
        The "MID" type is derived from YANG "binary" type due to its combined
        use of bit patterns (in its header) and BER-encoded data.
        </t>
        <t>
        The "MC" type is also derived from YANG "binary" type
        for lack of specific YANG mechanism for type decomposition.
        </t>
      </section>

      <section title="Applicaiton Module Subtyping">
        <t>
        An ADM SHOULD subtype any numeric type in order to apply additional
        semantic context to the numerical values
        (similar to the SMIv2 CounterXX and GaugeXX <xref target="RFC2578"/>).
        An ADM SHOULD make use of the YANG "units" substatement when
        numeric types are used (within either a typedef or a type-use).
        </t>
        <t>
        An ADM SHOULD subtype the BLOB type in order to identify
        application-specific encoding formats.
        Using plain BLOB types within an ADM is discouraged due to the
        opaqueness of the 
        </t>
        <t>
        Any ADM subtype SHALL have no effect on the value encoding of AMP.
        Subtypes are purely used to assist applications in managing
        value semantics.
        Any ADM subtype SHALL include a description substatement explaining
        the purpose of the subtype.
        </t>
      </section>

    </section>
    
    <section title="YANG Extensions for AMP">
      <t>
      This section specifies how AMP extension statements interact with
      native YANG statements within an application YANG module.
      </t>

      <section title="Object Identifiers">
        <t>
        This section contains extensions for identifying a data node within
        the YANG model tree by a unique OID value.
        </t>
        <section anchor="stmt.fulloid" title="The fulloid Extension Statement">
          <t>
          A "fulloid" statement is used to anchor an item in the OID
          tree.
          The value of a fulloid is the dotted-numeric notation of the OID
          value. A fulloid value must not be empty.
          Any substatements which are sibling to a "fulloid" will be relative
          to that OID root for the purposes of "suboid" processing.
          </t>
          <t>
          The format of a fulloid argument is a string of period-separated
          numeric components.
          </t>
          <texttable anchor="stmt.fulloid.subs" title="fulloid Substatements">
            <ttcol>substatement</ttcol>
            <ttcol>cardinality</ttcol>
            
            <c>description</c>
            <c>0..1</c>
          </texttable>
        </section>

        <section anchor="stmt.suboid" title="The suboid Extension Statement">
          <t>
          A "suboid" statement is used to define an item's OID relative
          to a sibling statement's full OID.
          The value of a suboid is the dotted-numeric notation of the OID
          parts under the full OID. A suboid value must not be empty.
          </t>
          <t>
          The format of a suboid argument is the same as a fulloid argument.
          The interpretation of a suboid depends upon the context of the 
          statement.
          </t>
          <texttable anchor="stmt.suboid.subs" title="suboid Substatements">
            <ttcol>substatement</ttcol>
            <ttcol>cardinality</ttcol>
            
            <c>description</c>
            <c>0..1</c>
          </texttable>
        </section>
  
        <section anchor="stmt.nickname" title="The nickname Extension Statement">
          <t>
          A "nickname" statement is used to define an application-specific
          numeric identifier for a full OID prefix.
          The nickname is used by both the AMP agent and manager to shorten
          OID encoding.
          </t>
          <t>
          The format of a nickname argument is a single non-negative integer
          value.
          Each nickname is defined within the namespace of the ADM module.
          </t>
          <texttable anchor="stmt.nickname.subs" title="nickname Substatements">
            <ttcol>substatement</ttcol>
            <ttcol>cardinality</ttcol>
            
            <c>description</c>
            <c>0..1</c>
            <c>fulloid</c>
            <c>1</c>
          </texttable>
        </section>
  
        <section anchor="stmt.compressoid" title="The compressoid Extension Statement">
          <t>
          A "compressoid" statement is used to define a full OID based on
          a module-specific nickname (see <xref target="stmt.nickname"/>) as
          a prefix and a suboid suffix.
          </t>
          <t>
          The format of a compressoid argument is a nickname value 
          (see <xref target="stmt.nickname"/>) within square brackets
          followed by a suboid string.
          </t>
          <texttable anchor="stmt.compressoid.subs" title="compressoid Substatements">
            <ttcol>substatement</ttcol>
            <ttcol>cardinality</ttcol>
            
            <c>description</c>
            <c>0..1</c>
          </texttable>
        </section>
      </section>

      <section anchor="stmt.group" title="The group Extension Statement">
        <t>
        The "group" statement is used to define a grouping of other items
        within the ADM.
        Each group is assigned an OID (see <xref target="oid-assign"/>) 
        and used as an OID anchor for its substatements.
        </t>
        <t>
        The order of substatements within a group is not significant.
        Only the OID assignment of each item is significant.
        </t>
        <texttable anchor="stmt.group.subs" title="group Substatements">
          <ttcol>substatement</ttcol>
          <ttcol>cardinality</ttcol>
          
          <c>description</c>
          <c>0..1</c>
          <c>reference</c>
          <c>0..1</c>
          <c>status</c>
          <c>0..1</c>
          
          <c>fulloid | suboid | compressoid</c>
          <c>1</c>
          <c>group</c>
          <c>0..*</c>
          <c>primitive</c>
          <c>0..*</c>
          <c>control</c>
          <c>0..*</c>
          <c>report</c>
          <c>0..*</c>
          <c>macro</c>
          <c>0..*</c>
          <c>operator</c>
          <c>0..*</c>
        </texttable>
      </section>

      <section title="Model Definition Extensions">
        <section anchor="stmt.primitive" title="The primitive Extension Statement">
          <t>
          The "primitive" statement is used to define an atomic value within
          an ADM.
          Each primitive is assigned an OID (see <xref target="oid-assign"/>)
          and a type.
          The primitive has different semantics from the YANG "leaf" statement
          due to the lack of secondary (non-type) attributes (e.g. config/state
          distinction).
          All primitive objects are state; any configuration is performed
          via "control" statements.
          </t>
          <texttable anchor="stmt.primitive.subs" title="primitive Substatements">
            <ttcol>substatement</ttcol>
            <ttcol>cardinality</ttcol>
            
            <c>description</c>
            <c>0..1</c>
            <c>reference</c>
            <c>0..1</c>
            <c>status</c>
            <c>0..1</c>
            
            <c>fulloid | suboid | compressoid</c>
            <c>1</c>
            <c>type</c>
            <c>1</c>
            <c>units</c>
            <c>0..1</c>
          </texttable>
        </section>
  
        <section anchor="stmt.control" title="The control Extension Statement">
          <t>
          The "control" statement is used to define an available control
          within the ADM.
          Each control is assigned an OID (see <xref target="oid-assign"/>)
          and an ordered list of parmeter and result items.
          The control has different semantics from the YANG "rpc" statement
          due to the difference in protocol encoding and to the asynchronous
          nature of the AMP.
          </t>
          <t>
          Each control is parameterized by some number of parameters
          (see <xref target="stmt.parameter"/>) and some number of results
          (see <xref target="stmt.result"/>).
          There is no provision in an ADM for specifying alternative parameters
          or alternative results (i.e. no parameters are optional).
          </t>
          <texttable anchor="stmt.control.subs" title="control Substatements">
            <ttcol>substatement</ttcol>
            <ttcol>cardinality</ttcol>
            
            <c>description</c>
            <c>0..1</c>
            <c>reference</c>
            <c>0..1</c>
            <c>status</c>
            <c>0..1</c>
            
            <c>fulloid | suboid | compressoid</c>
            <c>1</c>
            <c>parameter</c>
            <c>0..*</c>
            <c>result</c>
            <c>0..*</c>
          </texttable>
        </section>
  
        <section anchor="stmt.parameter" title="The parameter Extension Statement">
          <t>
          The "parameter" statement is used to define single expected parameter
          of a "control" statement.
          In the AMP each control has a fixed number of typed parameters, there
          is no provision for overloaded controls which take variable numbers
          of parameters.
          </t>
          <t>
          A control parameter is an atomic value with a distinct type,
          but has no distinct OID.
          The parameter statement's argument is used as the parameter's name.
          Within a single control, each parameter name SHALL be unique.
          The parameter name is not related to any AMP encoding, so is useful
          only for the sake of identifying the parameter within the ADM.
          </t>
          <texttable anchor="stmt.parameter.subs" title="parameter Substatements">
            <ttcol>substatement</ttcol>
            <ttcol>cardinality</ttcol>
            
            <c>description</c>
            <c>0..1</c>
            <c>type</c>
            <c>1</c>
            <c>units</c>
            <c>0..1</c>
          </texttable>
        </section>
  
        <section anchor="stmt.result" title="The result Extension Statement">
          <t>
          The "result" statement is used to define single expected result
          of a "control" statement.
          In the AMP each control has a fixed number of typed results, there
          is no provision for overloaded controls which yield variable numbers
          of results.
          </t>
          <t>
          A control result is an atomic value with a distinct type,
          but has no distinct OID.
          The result statement's argument is used as the result's name.
          Within a single control, each result name SHALL be unique.
          The result name is not related to any AMP encoding, so is useful
          only for the sake of identifying the result within the ADM.
          </t>
          <texttable anchor="stmt.result.subs" title="result Substatements">
            <ttcol>substatement</ttcol>
            <ttcol>cardinality</ttcol>
            
            <c>description</c>
            <c>0..1</c>
            <c>type</c>
            <c>1</c>
            <c>units</c>
            <c>0..1</c>
          </texttable>
        </section>
  
        <section anchor="stmt.report" title="The report Extension Statement">
          <t>
          The "report" statement is used to define the contents of an AMP 
          report, but does not define when any instances of the report may
          be created.
          Each report is assigned an OID (see <xref target="oid-assign"/>)
          and an ordered list of content items.
          Asynchronous reporting is a distinct feature of the AMP from
          other management protocols.
          </t>
          <t>
          Each report is parameterized by some number of items which are to
          be contained in corresponding report instances
          (see <xref target="stmt.reportitem"/>).
          There is no provision in an ADM for specifying alternative report
          contents.
          </t>
          <texttable anchor="stmt.report.subs" title="report Substatements">
            <ttcol>substatement</ttcol>
            <ttcol>cardinality</ttcol>
            
            <c>description</c>
            <c>0..1</c>
            <c>reference</c>
            <c>0..1</c>
            <c>status</c>
            <c>0..1</c>
            
            <c>fulloid | suboid | compressoid</c>
            <c>1</c>
            <c>reportitem</c>
            <c>0..*</c>
          </texttable>
        </section>
  
        <section anchor="stmt.reportitem" title="The reportitem Extension Statement">
          <t>
          The "reportitem" statement is used to define single expected item
          within a report instance.
          In the AMP each report has a fixed number of typed items, there
          is no provision for overloaded reports which yield variable numbers
          of items.
          </t>
          <t>
          A reportitem is an atomic value with a distinct OID of the primitive
          to be included in a report instance.
          A reportitem has no type of its own.
          The reportitem statement's argument is used as the item's name.
          Within a single report, each reportitem name SHALL be unique.
          The reportitem name is not related to any AMP encoding, so is useful
          only for the sake of identifying the item within the ADM.
          </t>
          <texttable anchor="stmt.reportitem.subs" title="reportitem Substatements">
            <ttcol>substatement</ttcol>
            <ttcol>cardinality</ttcol>
            
            <c>description</c>
            <c>0..1</c>
            <c>fulloid | compressoid</c>
            <c>1</c>
          </texttable>
        </section>
  
        <section anchor="stmt.macro" title="The macro Extension Statement">
          <t>
          The "macro" statement is used to declare an AMP macro within an ADM.
          </t>
          <t>
          //FIXME: what value is there in the inline definition?
          </t>
          <texttable anchor="stmt.macro.subs" title="macro Substatements">
            <ttcol>substatement</ttcol>
            <ttcol>cardinality</ttcol>
            
            <c>description</c>
            <c>0..1</c>
            <c>reference</c>
            <c>0..1</c>
            <c>status</c>
            <c>0..1</c>
            
            <c>fulloid | suboid | compressoid</c>
            <c>1</c>
          </texttable>
        </section>
  
        <section anchor="stmt.operator" title="The operator Extension Statement">
          <t>
          The "operator" statement is used to define the syntax of an ADM 
          operator (for use in expressions).
          Each operator is assigned an OID (see <xref target="oid-assign"/>)
          and an ordered list of operands.
          </t>
          <t>
          Each operator is parameterized by some number of items which are to
          be used as operands at statement execution time.
          (see <xref target="stmt.operand"/>).
          </t>
          <texttable anchor="stmt.operator.subs" title="operator Substatements">
            <ttcol>substatement</ttcol>
            <ttcol>cardinality</ttcol>
            
            <c>description</c>
            <c>0..1</c>
            <c>reference</c>
            <c>0..1</c>
            <c>status</c>
            <c>0..1</c>
            
            <c>fulloid | suboid | compressoid</c>
            <c>1</c>
            <c>operand</c>
            <c>0..*</c>
          </texttable>
        </section>
  
        <section anchor="stmt.operand" title="The operand Extension Statement">
          <t>
          The "operand" statement is used to define single expected operand
          within an operator statement.
          In the AMP each operation has a fixed number of untyped operands.
          There is no provision for overloaded operators which take 
          variable numbers of operands.
          </t>
          <t>
          An operand is an atomic value with no associated OID or type.
          The operand statement's argument is used as the item's name.
          Within a single operator, each operand name SHALL be unique.
          The operand name is not related to any AMP encoding, so is useful
          only for the sake of identifying the item within the ADM.
          </t>
          <texttable anchor="stmt.operand.subs" title="operand Substatements">
            <ttcol>substatement</ttcol>
            <ttcol>cardinality</ttcol>
            
            <c>description</c>
            <c>0..1</c>
          </texttable>
        </section>
      </section>
      
      <section title="Data Instance Extensions">
        <t>
        Some aspects of an ADM module require in-line instantiations of data 
        which will eventually be encoded in AMP format.
        Rather than requiring the ADM module author to do the encoding manually,
        and to allow easier inspection by an ADM module reader, each
        to-be-encoded data item is represented in the ADM module by
        one of the "amp:*-instance" statements.
        Examples of uses for these instances are: a numeric value used in
        the definition of a "literal" statement, or OID values used in
        the definition of a "report" statement.
        </t>
        <t>
        Where possible, an ADM author SHOULD supply all data instances
        necessary to interpret the constant-data items within an ADM.
        </t>

        <section anchor="stmt.number-instance" title="The number-instance Extension Statement">
          <t>
          The "number-instance" statement is used to define single value
          of one of the integer data types (BYTE, INT, UINT, VAST, UVAST, SDNV)
          or one of the floating point types (REAL32, REAL64).
          The number-type substatement SHALL be present unless the
          number-instance is a direct substatement of a typed statement
          (e.g. a literal statement).
          </t>
          <t>
          The lexical representation of all AMP integer types SHALL conform to
          the corresponding integer types <xref target="RFC6020"/>.
          The lexical representation of AMP floating point types SHALL conform to
          the "decimal64" type of <xref target="RFC6020"/>.
          The binary-valued floating point domain of the AMP types SHALL
          be enforced by any YANG module parser.
          </t>
          <texttable anchor="stmt.number-instance.subs" title="number-instance Substatements">
            <ttcol>substatement</ttcol>
            <ttcol>cardinality</ttcol>
            
            <c>description</c>
            <c>0..1</c>
            <c>number-type</c>
            <c>0..1</c>
          </texttable>

          <section anchor="stmt.number-type" title="The number-type Extension Statement">
            <t>
            The "number-type" statement is used to identify the specific
            encoding type for a number-instance parent statement.
            A number-type statement's argument SHALL be one of the numeric
            type names:
            <list>
              <t>BYTE</t><t>INT</t><t>UINT</t><t>VAST</t><t>UVAST</t><t>SDNV</t>
              <t>REAL32</t><t>REAL64</t>
            </list>
            </t>
            <t>
            The number-type statement has no substatemnts.
            </t>
          </section>
        </section>

        <section anchor="stmt.string-instance" title="The string-instance Extension Statement">
          <t>
          The "string-instance" statement is used to define single text value
          for the STR data type.
          The string-instance argument SHALL NOT contain the UTF-8 code point
          zero. Code point zero is used to terminate strings in AMP.
          </t>
          <texttable anchor="stmt.string-instance.subs" title="string-instance Substatements">
            <ttcol>substatement</ttcol>
            <ttcol>cardinality</ttcol>
            
            <c>description</c>
            <c>0..1</c>
          </texttable>
        </section>

        <section anchor="stmt.BLOB-instance" title="The BLOB-instance Extension Statement">
          <t>
          The "BLOB-instance" statement is used to define single binary-data
          value for the BLOB data type.
          The BLOB-instance argument SHALL be represented by Base-64 encoded
          text according to <xref target="RFC3548"/>.
          The length of the encoded BLOB is implicit in the BLOB-instance
          representation.
          </t>
          <texttable anchor="stmt.BLOB-instance.subs" title="string-instance Substatements">
            <ttcol>substatement</ttcol>
            <ttcol>cardinality</ttcol>
            
            <c>description</c>
            <c>0..1</c>
          </texttable>
        </section>

        <section anchor="stmt.TS-instance" title="The TS-instance Extension Statement">
          <t>
          The "TS-instance" statement is used to define single time-stamp
          value.
          Although its encoding is identical to the SDNV number-instance,
          the TS-instance YANG representation is different.
          
          The TS-instance argument SHALL contain an fully qualified absolute
          time represented according to <xref target="RFC3339"/>.
          </t>
          <texttable anchor="stmt.TS-instance.subs" title="TS-instance Substatements">
            <ttcol>substatement</ttcol>
            <ttcol>cardinality</ttcol>
            
            <c>description</c>
            <c>0..1</c>
          </texttable>
        </section>

        <section anchor="stmt.MID-instance" title="The MID-instance Extension Statement">
          <t>
          The "MID-instance" statement is used to define single MID value,
          including all of the possible MID variations.
          </t>
          <texttable anchor="stmt.MID-instance.subs" title="MID-instance Substatements">
            <ttcol>substatement</ttcol>
            <ttcol>cardinality</ttcol>
            
            <c>description</c>
            <c>0..1</c>
            <c>MID-type</c>
            <c>1</c>
            <c>MID-category</c>
            <c>1</c>
            <c>MID-issuer</c>
            <c>0..1</c>
            <c>MID-tag</c>
            <c>0..1</c>
          </texttable>

          <section anchor="stmt.MID-issuer" title="The MID-issuer Extension Statement">
            <t>
            The "MID-issuer" statement is used to define the optional Issuer
            payload of the MID value.
            The presence or absense of a MID-issuer statement determines
            the header and payload encoding of the MID value.
            The MID-issuer argument SHALL be a positive integer value.
            </t>
            <texttable anchor="stmt.MID-issuer.subs" title="MID-issuer Substatements">
              <ttcol>substatement</ttcol>
              <ttcol>cardinality</ttcol>
              
              <c>description</c>
              <c>0..1</c>
            </texttable>
          </section>

          <section anchor="stmt.MID-tag" title="The MID-tag Extension Statement">
            <t>
            The "MID-tag" statement is used to define the optional Tag
            payload of the MID value.
            The presence or absense of a MID-tag statement determines
            the header and payload encoding of the MID value.
            The MID-tag argument SHALL be a positive integer value.
            </t>
            <texttable anchor="stmt.MID-tag.subs" title="MID-tag Substatements">
              <ttcol>substatement</ttcol>
              <ttcol>cardinality</ttcol>
              
              <c>description</c>
              <c>0..1</c>
            </texttable>
          </section>

        </section>

        <section anchor="stmt.DC-instance" title="The DC-instance Extension Statement">
          <t>
          The "DC-instance" statement is used to define a list of BLOB values.
          The count of values present in the DC is implicit in the
          number of BLOB-instance substatements.
          The order of BLOB-instance substatements SHALL correpsond with the
          encoded DC value.
          </t>
          <texttable anchor="stmt.DC-instance.subs" title="DC-instance Substatements">
            <ttcol>substatement</ttcol>
            <ttcol>cardinality</ttcol>
            
            <c>description</c>
            <c>0..1</c>
            <c>BLOB-instance</c>
            <c>0..*</c>
          </texttable>
        </section>

        <section anchor="stmt.MC-instance" title="The MC-instance Extension Statement">
          <t>
          The "MC-instance" statement is used to define a list of MID values.
          The count of values present in the MC is implicit in the
          number of MID-instance substatements.
          The order of MID-instance substatements SHALL correpsond with the
          encoded MC value.
          </t>
          <texttable anchor="stmt.MC-instance.subs" title="MC-instance Substatements">
            <ttcol>substatement</ttcol>
            <ttcol>cardinality</ttcol>
            
            <c>description</c>
            <c>0..1</c>
            <c>MID-instance</c>
            <c>0..*</c>
          </texttable>
        </section>

        <section anchor="stmt.TDC-instance" title="The TDC-instance Extension Statement">
          <t>
          The "TDC-instance" statement is used to define a list of typed
          data instance values.
          The count of values present in the TDC is implicit in the
          number of "*-instance" substatements.
          The order of data instance substatements SHALL correpsond with the
          encoded TDC value.
          </t>
          <texttable anchor="stmt.TDC-instance.subs" title="TDC-instance Substatements">
            <ttcol>substatement</ttcol>
            <ttcol>cardinality</ttcol>
            
            <c>description</c>
            <c>0..1</c>
            <c>number-instance | string-instance | BLOB-instance | TS-instance
            | MID-instance | DC-instance | TDC-instance</c>
            <c>0..*</c>
          </texttable>
        </section>

      </section>
    </section>

    <section title="IANA Considerations">
      <t>
        This document registers one URI in the IETF 
        XML registry <xref target="RFC3688"/>.
        NOTE TO EDITOR: module registration is pending I-D approval.
        The following registration has been made:
      </t>
      <texttable>
        <ttcol>Field</ttcol>
        <ttcol>Value</ttcol>
        
        <c>URI</c>
        <c>urn:ietf:params:xml:ns:yang:amp-adm</c>
        <c>Registrant Contact</c>
        <c>The DTN WG of the IETF.</c>
        <c>XML</c>
        <c>N/A, the requested URI is an XML namespace.</c>
      </texttable>
      <t>
        This document registers one module name/namespace in the IETF
        YANG Module Names Registry <xref target="RFC6020"/>.
        NOTE TO EDITOR: module registration is pending I-D approval.
        The following registration has been made:
      </t>
      <texttable>
        <ttcol>Field</ttcol>
        <ttcol>Value</ttcol>
        
        <c>Name</c>
        <c>amp-adm</c>
        <c>Namespace</c>
        <c>urn:ietf:params:xml:ns:yang:amp-adm</c>
        <c>Prefix</c>
        <c>amp</c>
        <c>Reference</c>
        <c>draft-bsipos-dtn-amp-yang</c>
      </texttable>
    </section>

    <section title="Security Considerations">
      <t>
      This memo only defines a mechanism to specify an application schema, it does
      not impose any limitations or requirements on the contents of that schema.
      The amp-adm module defines only subtypes and extensions.
      It does not define any actual data model elements, so there are no
      direct security implications.
      </t>
    </section>
  </middle>

  <back>
    <references title="Normative References">
      <?rfc include="reference.RFC.2119.xml"?>
      <?rfc include="reference.RFC.3339.xml"?>
      <?rfc include="reference.RFC.3548.xml"?>
      <?rfc include="reference.RFC.3629.xml"?>
      <?rfc include="reference.RFC.3688.xml"?>
      <?rfc include="reference.RFC.6020.xml"?>
      <?rfc include="reference.RFC.6087.xml"?>
      <?rfc include="reference.I-D.birrane-dtn-amp.xml"?>
    </references>

    <references title="Informative References">
      <?rfc include="reference.RFC.2578.xml"?>
      <?rfc include="reference.I-D.birrane-dtn-ama.xml"?>
      <reference anchor="pyang">
        <front>
          <title>An extensible YANG validator and converter in python</title>
          <author initials="M." surname="Bjorklund" fullname="Martin Bjorklund">
            <address>
              <uri>http://code.google.com/p/pyang/</uri>
            </address>
          </author>
          <date month="March" year="2016"/>
        </front>
      </reference>
      <!-- <?rfc include="reference.IEEE.754.2008.xml"?> -->
      <?rfc include="reference.CCITT.X690.2002.xml"?>
    </references>
  
    <section title="YANG Definitions">
      <t>
      The contents of this section is the machine-readable specification
      of this YANG module.
      </t>
      
      <section title="AMP Module">
        <t>
        The following YANG definition is the top-level "amp" module.
        </t>
        <figure>
        <artwork>&lt;CODE BEGINS&gt; file "amp-adm.yang"

module amp-adm {
	namespace "urn:ietf:params:xml:ns:yang:amp-adm";
	prefix "amp";
	
	include amp-types;
	include amp-extensions;
	include amp-instances;
	
	organization
		"IETF Delay Tolerant Networking Working Group";
	contact
		"WG Web: &lt;http://tools.ietf.org/wg/dtn/&gt;
        WG List: &lt;mailto:dtn@ietf.org&gt;

        WG Chairs: Brian Haberman
                   &lt;mailto:brian@innovationslab.net&gt;
                   Marc Blanchet
                   &lt;mailto:Marc.Blanchet@viagenie.ca&gt;

        Editor: Brian Sipos
                &lt;mailto:BSIpos@rkf-eng.com&gt;";
	
	description
		"This module implements the "
		+"Asynchornous Management Protocol (AMP) "
		+"Application Data Model (ADM) profile within YANG";
    reference "draft Asynchronous Management Protocol";
	
    revision "2016-04-01" {
        description "Updated to fix typos.";
        reference "I-D draft-bsipos-dtn-amp-yang";
    }
	revision "2016-03-14" {
		description "Initial draft release.";
		reference "I-D draft-bsipos-dtn-amp-yang";
	}
}

&lt;CODE ENDS&gt;</artwork>
        </figure>
      </section>
      
      <section title="AMP Type Submodule">
        <t>
        The following YANG definition includes types specific to AMP.
        </t>
        <figure>
        <artwork>&lt;CODE BEGINS&gt; file "amp-types.yang"
submodule amp-types {
	belongs-to amp-adm {
		prefix "amp";
	}
	
    organization
        "IETF Delay Tolerant Networking Working Group";
    contact
        "WG Web: &lt;http://tools.ietf.org/wg/dtn/&gt;
        WG List: &lt;mailto:dtn@ietf.org&gt;

        WG Chairs: Brian Haberman
                   &lt;mailto:brian@innovationslab.net&gt;
                   Marc Blanchet
                   &lt;mailto:Marc.Blanchet@viagenie.ca&gt;

        Editor: Brian Sipos
                &lt;mailto:BSIpos@rkf-eng.com&gt;";
    
	description
		"This submodule contains the set of core types necessary to "
		+"define an Asynchronous Management Protocol data model.";
	reference "draft Asynchronous Management Protocol";
	
    revision "2016-04-01" {
        description "Updated to fix typos.";
        reference "I-D draft-bsipos-dtn-amp-yang";
    }
    revision "2016-03-14" {
        description "Initial draft release.";
        reference "I-D draft-bsipos-dtn-amp-yang";
    }
    
	// These extensions are only used within this submodule for annotation
	extension amp-type-id {
		argument "num";
		description "Internal annotation of the AMP ID number of a type.";
	}
	extension amp-type-item {
		argument "name";
		description "Internal annotation of a sub-type item.";
	}
	extension amp-type-list {
		argument "name";
		description "Internal annotation of a sub-type list-of-items.";
	}
	
	typedef "BYTE" {
		type "uint8";
		amp:amp-type-id 0;
		description "Unsigned 8-bit integer";
		reference "draft Asynchronous Management Protocol";
	}
	typedef "INT" {
		type "int32";
		amp:amp-type-id 1;
        description "Signed 32-bit integer";
		reference "draft Asynchronous Management Protocol";
	}
	typedef "UINT" {
		type "uint32";
		amp:amp-type-id 2;
        description "Unsigned 32-bit integer";
		reference "draft Asynchronous Management Protocol";
	}
	typedef "VAST" {
		type "int64";
		amp:amp-type-id 3;
        description "Signed 64-bit integer";
		reference "draft Asynchronous Management Protocol";
	}
	typedef "UVAST" {
		type "uint64";
		amp:amp-type-id 4;
        description "Unsigned 64-bit integer";
		reference "draft Asynchronous Management Protocol";
	}
	typedef "REAL32" {
		type "binary";
		amp:amp-type-id 5;
		description
			"Binary encoding of IEEE-754 32-bit floating point number.";
		reference "draft Asynchronous Management Protocol";
	}
	typedef "REAL64" {
		type "binary";
		amp:amp-type-id 6;
		description
			"Binary encoding of IEEE-754 64-bit floating point number.";
		reference "draft Asynchronous Management Protocol";
	}
	typedef "SDNV" {
		type "binary";
		amp:amp-type-id 9;
		description
			"Binary encoding of self-delimited numeric value.";
		reference "draft Asynchronous Management Protocol";
	}
	typedef "STR" {
		type "string";
		amp:amp-type-id 7;
		description
			"Same UTF-8 encoding as YANG base type. "
			+"Must be zero-terminated.";
		reference "draft Asynchronous Management Protocol";
	}
	
	typedef "TS" {
		type "binary";
		amp:amp-type-id 10;
		description "A timestamp value.";
		reference "draft Asynchronous Management Protocol";
	}
	
	typedef "MID" {
		type "binary";
		amp:amp-type-id 12;
		description "The basic managed-identifier definition.";
		reference "draft Asynchronous Management Protocol";
	}
	
	typedef "BLOB" {
		type "binary";
		amp:amp-type-id 8;
		description
			"The BLOB type should be used as a base type for "
			+"applicaiton-specific types used in data models.";
		reference "draft Asynchronous Management Protocol";
		
		amp:amp-type-item "count" { type "SDNV"; }
		amp:amp-type-list "octets" { type "BYTE"; }
	}
	
	typedef "DC" {
		type "binary";
		amp:amp-type-id 11;
        description "Untyped data collection";
		
		amp:amp-type-item "count" { type "SDNV"; }
		amp:amp-type-list "items" { type "BLOB"; }
	}
	typedef "TDC" {
		type "binary";
		amp:amp-type-id 18;
        description "Typed data collection";
		
		amp:amp-type-item "entry-count" { type "SDNV"; }
		// These really need not be BLOBs with internal sizes
		amp:amp-type-item "entry-types" { type "BLOB"; }
		amp:amp-type-list "entry-values" { type "BLOB"; }
	}
	typedef "MC" {
		type "binary";
		amp:amp-type-id 13;
		description "Ordered list of MID values.";
		
		amp:amp-type-item "count" { type "SDNV"; }
		amp:amp-type-list "values" { type "MID"; }
	}
	
	// Should be pure MC with no type-id?
	// The only time [EXPR] type is used in AMP spec is 
	// for DEF definition, which is unambiguous on type.
	typedef "EXPR" {
		type "binary";
		amp:amp-type-id 14;
		description
			"Ordered list of MID values representing a "
			+"postfix arithmetic.";
		
		amp:amp-type-item "expression" { type "MC"; }
	}
	// PRED is not a type
	typedef "DEF" {
		type "binary";
		amp:amp-type-id 15;
		description
			"Ordered list of MID values with a corresponding result"
			+"type and overall OID";
		
		amp:amp-type-item "id" { type "MID"; }
		amp:amp-type-item "type" { type "BYTE"; }
		amp:amp-type-item "definition" { type "MC"; }
	}
	typedef "TRL" {
		type "binary";
		amp:amp-type-id 16;
		description
			"Identify and define a time-based macro rule.";
		
		amp:amp-type-item "id" { type "MID"; }
		amp:amp-type-item "start" { type "TS"; }
		amp:amp-type-item "period" { type "SDNV"; units "seconds"; }
		amp:amp-type-item "count" { type "SDNV"; }
		amp:amp-type-item "action" { type "MC"; }
	}
	typedef "SRL" {
		type "binary";
		amp:amp-type-id 17;
		description
			"Identify and define a state-based macro rule.";
		
		amp:amp-type-item "id" { type "MID"; }
		amp:amp-type-item "start" { type "TS"; }
		// Mismatch in AMP spec for PRED type
//		amp:amp-type-item "condition" { type "PRED"; }
		amp:amp-type-item "condition" { type "EXPR"; }
		amp:amp-type-item "count" { type "SDNV"; }
		amp:amp-type-item "action" { type "MC"; }
	}
	// Should be pure TDC with no type-id?
	// The only time [RPT] is used, the RPT type is unnecessary 
	// because there is no alternative but RPT (i.e. TDC) data.
	typedef "RPT" {
		type "binary";
		amp:amp-type-id 19;
		description
			"Identify and define a report template.";
		
		// how is this different from TDC type + MID?
		amp:amp-type-item "id" { type "MID"; }
		amp:amp-type-item "entry-count" { type "SDNV"; }
		// These really need not be BLOBs with internal sizes?
		amp:amp-type-item "entry-types" { type "BLOB"; }
		amp:amp-type-list "entry-values" { type "BLOB"; }
	}
	// May be useful to define a protocol-level CONFIGURE type which 
	// looks similar to...
	//typedef CFG {
	//	amp:amp-type-item "target-id" { type "MID"; }
	//	amp:amp-type-list "value" { type "BLOB"; }
	//}
	// This would allow a simple macro of CFG values
	
	// Should be pure DEF with no type-id?
	// The only time MACRO is used is not for encoding, but for 
	// typing objects in OID tree.
	typedef "MACRO" {
		type "DEF";
		amp:amp-type-id 20;
		description "Ordered list of control/macro MID values.";
	}
	typedef "UNK" {
		type "binary";
		amp:amp-type-id 21;
        description "Invalid type";
	}
}

&lt;CODE ENDS&gt;</artwork>
        </figure>
      </section>
      
      <section title="AMP Extensions Submodule">
        <t>
        The following YANG definition includes extensions specific to AMP.
        </t>
        <figure>
        <artwork>&lt;CODE BEGINS&gt; file "amp-extensions.yang"
submodule amp-extensions {
	belongs-to amp-adm {
		prefix "amp";
	}
	
    organization
        "IETF Delay Tolerant Networking Working Group";
    contact
        "WG Web: &lt;http://tools.ietf.org/wg/dtn/&gt;
        WG List: &lt;mailto:dtn@ietf.org&gt;

        WG Chairs: Brian Haberman
                   &lt;mailto:brian@innovationslab.net&gt;
                   Marc Blanchet
                   &lt;mailto:Marc.Blanchet@viagenie.ca&gt;

        Editor: Brian Sipos
                &lt;mailto:BSIpos@rkf-eng.com&gt;";
    
	description
		"This submodule contains the set of core extensions necessary to "
		+"define an Asynchronous Management Protocol data model.";
	reference "draft Asynchronous Management Protocol";
	
    revision "2016-04-01" {
        description "Updated to fix typos.";
        reference "I-D draft-bsipos-dtn-amp-yang";
    }
    revision "2016-03-14" {
        description "Initial draft release.";
        reference "I-D draft-bsipos-dtn-amp-yang";
    }
    
	extension fulloid {
		argument "value";
		description
			"This extension defines the complete OID for the parent "
			+"statement. ";
	}
	extension suboid {
		argument "value";
		description
			"This extension defines a sub-OID of a statement relative "
			+"to a parent-statement OID.";
	}
	
	extension nickname {
		argument "id";
		description
			"A nickname is a single integer ID which correpsonds to a "
			+"full OID value.";
	}
	extension compressoid {
		argument "value";
		description
			"This extension allows using an ADM nickname within the "
			+"ADM itself.";
	}
	
	extension "group" {
		argument "name";
		description
			"A logical grouping of ADM items under a parent OID.";
	}
	
	extension "primitive" {
		argument "name";
		description "A single typed value associated with an OID.";
	}
	
	extension "computed" {
		argument "name";
		description "A single typed value-expression associated with an OID.";
	}
	
	extension "report" {
		argument "name";
		description "Definition of a report within an ADM.";
	}
	extension "reportitem" {
		argument "name";
		description
			"A reference to a primitive within a report definition.";
	}
	
	extension "control" {
		argument "name";
		description "Definition of a control within an ADM.";
	}
	extension "parameter" {
		argument "name";
		description
			"An individual parameter to a \"control\" statement. "
			+"Order of parameters is signifigant within a control.";
	}
	extension "result" {
		argument "name";
		description
			"An individual result value reported as a response to "
			+"a \"control\" statement. "
			+"Order of results is signifigant within a control.";
	}
}

&lt;CODE ENDS&gt;</artwork>
        </figure>
      </section>
    
      <section title="AMP Instances Submodule">
        <t>
        The following YANG definition includes extensions to define 
        AMP instance values.
        </t>
        <figure>
        <artwork>&lt;CODE BEGINS&gt; file "amp-instances.yang"
submodule amp-instances {
	belongs-to amp-adm {
		prefix "amp";
	}
	
    organization
        "IETF Delay Tolerant Networking Working Group";
    contact
        "WG Web: &lt;http://tools.ietf.org/wg/dtn/&gt;
        WG List: &lt;mailto:dtn@ietf.org&gt;

        WG Chairs: Brian Haberman
                   &lt;mailto:brian@innovationslab.net&gt;
                   Marc Blanchet
                   &lt;mailto:Marc.Blanchet@viagenie.ca&gt;

        Editor: Brian Sipos
                &lt;mailto:BSIpos@rkf-eng.com&gt;";
    
	description
		"This submodule contains the extensions necessary to "
		+"define AMP data instances directly in an ADM.";
	reference "draft Asynchronous Management Protocol";
	
    revision "2016-04-01" {
        description "Updated to fix typos.";
        reference "I-D draft-bsipos-dtn-amp-yang";
    }
    revision "2016-03-14" {
        description "Initial draft release.";
        reference "I-D draft-bsipos-dtn-amp-yang";
    }
    
	extension number-instance {
		argument "value";
		description
			"Instantiate a value of BYTE, INT, UINT, VAST, UVAST, "
			+"SDNV, REAL32, or REAL64 within an ADM.";
	}
	extension number-type {
		argument "name";
		description
			"The type name of a number-instance.";
	}
	
	extension string-instance {
		argument "value";
		description
			"Instantiate a value of STR from a text value.";
	}
	
	extension TS-instance {
		argument "value";
		description
			"Instantiate a value of TS from a text value. "
			+"The value is encoded according to RFC3339.";
	}
	
	extension MID-instance {
		description
			"Instantiate a value of MID from substatements "
			+"specializing the MID.";
		/// Must contain instance-identifer, amp:fulloid, or amp:compressoid
		/// May also contain DC-instance for parameterized OID
	}
	/// are type and cat necessary?
	extension MID-type {
		argument "value";
		description "One of data, control, literal, or operator. "
			+"Default is data.";
	}
	extension MID-category {
		argument "value";
		description "One of atomic, computed, or collection. "
			+"Default is atomic.";
	}
	extension MID-issuer {
		argument "value";
		description "A numeric value identifying an issuer.";
	}
	extension MID-tag {
		argument "value";
		description "A numeric value identifying a tag.";
	}
	
	extension BLOB-instance {
		argument "value";
		description
			"Instantiate a value of BLOB from a text value. "
			+"The value is encoded in Base-64 per RFC3548. ";
	}
	
	extension DC-instance {
		description
			"Instantiate a value of DC from BLOB-instance substatements.";
	}
	extension TDC-instance {
		description
			"Instantiate a value of TDC from *-instance substatements.";
	}
	extension MC-instance {
		description
			"Instantiate a value of MC from MID-instance substatements.";
	}
	
	/// Really is just MC-instance
	extension MACRO-instance {
		description
			"Instantiate a value of MACRO from MID-instance substatements.";
	}

}

&lt;CODE ENDS&gt;</artwork>
        </figure>
      </section>
      
    </section>
    
    <section title="Example Application Data Model">
      <t>
      The following YANG definition includes extensions specific to AMP.
      </t>
      <figure>
      <artwork>
module example-adm {
	namespace "urn:example-adm";
	prefix "example-adm";
	
	import amp-adm {
		prefix "amp";
	}
	
	organization "Example Org.";
	description "Example module.";
	
	amp:fulloid "1.3.6.1.2.3.3";
	
	amp:nickname "3" {
		amp:fulloid "1.3.6.1.2";
	}
	
	amp:group "primitives" {
		amp:suboid "1";
		description "Primitive data available for getting or setting";
		
		amp:primitive "example" {
			amp:suboid "1";
			type "amp:UVAST";
			description "Example value.";
		}
	}
	
	amp:group "reports" {
		amp:suboid 3;
		
		amp:report showall {
			amp:suboid 8;
			
			amp:MC-instance {
				amp:MID-instance {
//					instance-identifier "/primitives/example";
				}
			}
		}
	}
	
	amp:group "controls" {
		amp:suboid "4";
		description "Container for all commands in this ADM.";
	
		amp:control "get" {
			amp:suboid "2";
			description "Get a single MIB value from the agent.";
			
			amp:parameter "corrid" {
				type "amp:SDNV";
				description "The correlation identifier for the request.";
			}
			amp:parameter "object" {
				type "amp:MID";
				description "Identity of the object to retrieve.";
			}
			
			amp:result "corrid" {
				type "amp:SDNV";
				description "The correlation identifier for the response.";
			}
			amp:result "errorcode" {
				type "amp:BYTE";
				description "If non-zero, an indicator of an error.";
			}
			amp:result "data" {
				type "amp:BLOB";
				description "Encoded value of the object.";
			}
		}

		amp:control "set" {
			amp:suboid "3";
			description "Set a single MIB value in the agent.";
			
			amp:parameter "corrid" {
				type "amp:SDNV";
				description "The correlation identifier for the request.";
			}
			amp:parameter "object" {
				type "amp:MID";
				description "Identify the value to retrieve.";
			}
			amp:parameter "data" {
				type "amp:BLOB";
				description "Encoded value used to write the object.";
			}
			
			amp:result "corrid" {
				type "amp:SDNV";
				description "The correlation identifier for the response.";
			}
			amp:result "errorcode" {
				type "amp:BYTE";
				description "If non-zero, an indicator of an error.";
			}
		}
	}
	
}

</artwork>
      </figure>
    </section>
  </back>
</rfc>
