DTNMA Application Data Model (ADM) YANG Syntax

Internet-Draft	DTNMA ADM YANG	July 2024
Birrane, et al.	Expires 22 January 2025	[Page]

Status of This Memo

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

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

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

This Internet-Draft will expire on 22 January 2025.¶

Copyright Notice

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

2. ADM Module Syntax

Some aspects of this ADM module profile restrict the allowable definitions to conform with Section 4 of [I-D.ietf-dtn-amm] and by doing so make YANG modules defining ADMs incompatible with YANG modules intended for NETCONF, RESTCONF, or other applications. Because of this, YANG modules defining ADMs SHALL be managed separately from the "YANG Module Names" sub-registry of [IANA-YANG]. See the ADM sub-registry defined in Section 9.3 of [I-D.ietf-dtn-ari] for registration of ADM modules. For the remainder of this document, a YANG module defining an ADM will be referred to as an "ADM module" and a YANG module for any other purpose will be referred to as an "Other Module" to differentiate it.¶

After explanation of extensions in Section 6, the following minimal ADM module will be expanded upon for further examples.¶

module example-adm {
  yang-version 1.1;
  namespace "ari://example-adm/";
  prefix example-adm;

  import ietf-amm {
    prefix amm;
  }

  organization
    "Example Org.";
  description
    "Example ADM module with YANG syntax.";

  amm:enum 65536;
}

3. ADM Module Contents

An ADM module is identified, as defined in Section 4.1, by the module "namespace" having an "ari" scheme. Within an ADM module, this profile makes restrictions in Section 4.2 which are formalized in the following table of allowed module substatements. This table is adapted from Section 7.1 of [RFC7950].¶

The "yang-version" of all ADM modules conforming to this document SHALL be "1.1". Later versions of YANG syntax could introduce incompatible changes and will need to be examined for consistency with the ADM module use.¶

Table 1: ADM `module` Substatements
Substatement	Cardinality	Reference
yang-version	1	Section 7.1.2 of [RFC7950]
namespace	1	Section 7.1.3 of [RFC7950]
prefix	1	Section 7.1.4 of [RFC7950]
include	0..n	Section 7.1.6 of [RFC7950]
import	0..n	Section 7.1.5 of [RFC7950]
status	0..1	Section 7.21.2 of [RFC7950]
reference	0..1	Section 7.21.4 of [RFC7950]
organization	0..1	Section 7.1.7 of [RFC7950]
description	0..1	Section 7.21.3 of [RFC7950]
revision	0..n	Section 7.1.9 of [RFC7950]
extension	0..n	Section 7.19 of [RFC7950]
feature	0..n	Section 7.20.1 of [RFC7950]
deviation	0..n	Section 7.20.3 of [RFC7950]
amm:enum	1	Section 6.1
amm:typedef	0..n	Section 6.4
amm:const	0..n	Section 6.6
amm:ctrl	0..n	Section 6.7
amm:edd	0..n	Section 6.8
amm:oper	0..n	Section 6.9
amm:sbr	0..n	Section 6.10
amm:tbr	0..n	Section 6.11
amm:var	0..n	Section 6.12

4. Inherited YANG Module Processing

The benefit of using the pre-existing YANG syntax is to take advantage of both tools that process YANG modules as well as some of the syntax and module-level semantics provided by YANG.¶

4.1. Direct Reuse

The following statements and behaviors of YANG are usable within an ADM with no modification:¶

Modules and Submodules:: The existing concepts and syntax of modules and submodules defined in Section 5.1 of [RFC7950] is unchanged for ADM modules. Because ADM modules occupy a separate ecosystem than Other Modules, there will not be any cross-imports between the two ecosystems. There is no harm in including an ADM module in an Other Module store, but it will have no data definitions usable with NETCONF, RESTCONF, etc.¶
Module Importing:: The existing concept and syntax of importing a module namespace, to reference objects in another module, defined in Section 5.1.1 of [RFC7950] is unchanged for ADM modules. Because the import includes a specific revision, the ARI references to objects in that imported module do not need any ADM revision information.¶
File Layout:: The existing file naming defined in Section 5.2 of [RFC7950] is unchanged for ADM modules. Because ADM modules occupy a separate ecosystem than Other Modules, their file stores SHALL be kept separate.¶
Namespaces:: Although an ADM module has no use for an XML namespace as defined in Section 5.3 of [RFC7950], the "namespace" statement is preserved for tool compatibility. For ADM modules, the "namespace" statement argument SHALL be the text-form ARI referencing the ADM itself. For example, the ADM "example-adm" will have a namespace of ari://example-adm/ which is valid YANG but does not conform to the guidelines of Section 4.9 of [RFC8407].¶
Name Resolution:: The existing name resolution logic described in Section 5.4 of [RFC7950] is unchanged for ADM modules. Because ADM modules are a flat object namespace, the complexity of namespaces is significantly simplified compared to Other Modules.¶
Features:: The existing definition and use of features as described in Section 5.6.2 of [RFC7950] is unchanged for ADM modules. This includes the declaration of a "feature" within an ADM module and the conditioning of the presence of an object on an "if-feature" expression. This also treats feature identifiers as module-prefix-qualified references.¶
Reusable Groups:: The existing group reuse logic described in Section 4.2.6 of [RFC7950] is unchanged for ADM modules. Because ADM modules are a flat object namespace, the utility of group reuse in an ADM module is limited to formal parameters, VALUE-OBJ definitions, and table columns.¶

4.2. Restrictions and Exclusions

Because of the different interpretation of data definitions for an ADM module, the following restrictions are used to limit pre-existing valid YANG syntax within an ADM module:¶

Built-In Types:: Because ADM modules have data that ultimately follows the AMM value model (see Section 3.1 of [I-D.ietf-dtn-amm]), the built-in types listed in Section 4.2.4 of [RFC7950], the "type" statement of Section 7.4 of [RFC7950], and the "typedef" statement of Section 7.3 of [RFC7950] do not directly apply to ADM modules. As defined in this document, there is no direct deterministic mapping between Other Module typing and ADM module typing. An ADM module SHALL NOT contain any YANG built-in type or any "type" or "typedef" statements.¶
Data Node Structure:: As defined in this document, there is no direct deterministic mapping between the complex, hierarchical, named data nodes of YANG and unnamed AMM values. An ADM module SHALL NOT contain any YANG data node statements, among them "container", "leaf", "leaf-list", "list", "anydata", "anyxml", "choice".¶
Configuration Versus State:: Because of the different semantics of an ADM module from an Other Module, there is no concept of a labeling of some data as "configuration" and other as "state". An ADM module SHALL NOT contain any "config" statements.¶
Data Presence Versus Value:: Rather than being an extrinsic notion of presence or absence, AMM objects can use type unions with the NULL type to indicate optional values and AMM values can use the null value to represent that state. In the case of formal parameters, the use of a "default" statement is used to indicate behavior when an actual parameter is undefined. In any case, the AMM value is always present when defined in the structure of an AMM object. An ADM module SHALL NOT contain any "mandatory" statements.¶
Nested Object Definitions:: Because of the flat structure of an ADM, the nesting allowed and encouraged by Section 5.5 of [RFC7950], are not allowed to be present in an ADM module. An ADM module SHALL contain all AMM object definitions at the top (module) level.¶
XPath Expressions:: The ADM module makes no use of XML or XPath in its definitions or logical constraints, so the behaviors described in Section 6.4 of [RFC7950] and in statements containing XPath expressions ("must", "when", "path", "augment") do not apply to ADM modules. All references in an ADM module take the form of an ARI.¶
NETCONF Operations:: Because an ADM module will not be used for modeling in NETCONF and related protocols, the statements associated with NETCONF operations (notably "action", "notification", "rpc") SHALL NOT be present in an ADM module.¶
Extending Models:: Because the transport of AMM values takes the form of an ARI, which does not include identity information the way XML elements do, the concept of extending an existing Legacy model by another model as described in Section 4.2.8 of [RFC7950] cannot apply to an ADM. The model extension "augment" statement SHALL NOT be present in an ADM module.¶

5. Built-In Types, TYPEDEFs, and Semantic Types

As discussed in Section 4.2, the YANG type and node models are fundamentally different from the AMM value model of Section 3.1 of [I-D.ietf-dtn-amm]. While YANG modules have been used to model data for XML representation for NETCONF (or equivalent representations for equivalent protocols), AMM values do not have explicit identifiers and have ARI representation.¶

Similar to how YANG treats built-in types, the AMM built-in type names are used without any namespace context. Differently to YANG, the AMM type names are encoded in ARI syntax and compared in a case-insensitive manner. One example of naming a built-in type UINT is below.¶

/ARITYPE/UINT

A TYPEDEF is a way for an ADM to apply a name and descriptive metadata to a specific semantic type (see Section 3.3 of [I-D.ietf-dtn-amm]). The TYPEDEF is also a top-level ADM object, as explained in Section 3.4.2 of [I-D.ietf-dtn-amm] with a syntax in Section 6.4. Because they are ADM objects, they can be referenced by ARIs when necessary as in the example below.¶

//example-adm-a/TYPEDEF/mytype

Except for the case of a simple "type" with no restrictions or annotations, anywhere one of the type uses occurs in an object definition can be considered as an "anonymous" semantic type. The behavior in those cases is identical to a TYPEDEF just without a name associated with the semantic type.¶

6. ADM Module Extensions

In order to provide syntax necessary for AMM Object instance definitions this document defines, via the DTNMA ADM (Appendix A), the following extensions for ADM modules.¶

6.1. The `amm:enum` Statement

This statement is used to apply an integer enumeration to an ADM module or object, which enables the compressed form of ARI discussed in Section 3.1 of [I-D.ietf-dtn-ari]. The argument to this statement is an integer in the YANG range 0..2^31-1 to fit within the ARI syntax. There are no substatements defined in this profile.¶

6.2. Semantic Type Statements

The statements within this section enable the various semantic type classes, as explained in Section 3.3 of [I-D.ietf-dtn-amm]. They are all used as substatements within one of the AMM object definition statements, sometimes directly (e.g., for CONST or EDD typing) and sometimes indirectly (e.g., for parameter or operand typing), but always as a choice between the need for one of the semantic type statements.¶

6.2.1. The `amm:type` Statement

This statement creates a Named Type Use semantic type (see Section 3.3.1 of [I-D.ietf-dtn-amm]) for its parent statement. The argument to this statement is the text form of the ARI for the type being used, which can either be a built-in ARITYPE or a TYPEDEF object reference.¶

The substatements under this are annotations or constraints on the type being used. The units, range, length, and pattern statements have the same syntax and semantics as defined in [RFC7950] when applied to AMM values.¶

Table 2: `amm:type` Substatements
Substatement	Cardinality	Valid for These Types
reference	0..1	any
description	0..1	any
units	0..1	Any `NUMERIC`
amm:display-hint	0..*	any
range	0..1	Any `INTEGER` or `FLOAT`, with appropriate quantized values in the argument
length	0..1	For `TEXTSTR` as number of characters, `BYTESTR` or `CBOR` as number of bytes
pattern	0..1	For `TEXTSTR` only
amm:int-labels	0..1	Any `INTEGER` type
amm:cddl	0..1	For `CBOR` only
amm:base	0..*	For `IDENT` only

Examples of the "type" statement are below, some as simple use and some as restriction.¶

amm:type uint {
  description
    "unconstrained";
}
amm:type uint {
  range "3..10";
  units "meter";
  description
    "constrained";
}
amm:type textstr {
  length "10..100";
}

6.2.1.1. The `amm:display-hint` Statement

This statement provides general purpose tailoring of how AMM values are intended to be displayed. The argument to this statement is the text form of the ARI referencing an IDENT object derived from the root ari://ietf-amm/IDENT/display-hint object.¶

The description of any leaf IDENT derived from this root object SHALL contain specific requirements for how the display hint affects text form of any associated values, including restrictions on which built-in types the hint can be used with.¶

6.2.1.2. The `amm:int-labels` Statement

This statement provides human-friendly labels for enumerated values or bit positions within an integer type. There is no argument to this statement.¶

The substatements under this are either "enum" or "bit" statements from YANG, each of which define a single value or bit name within the type. A single "amm:int-labels" SHALL NOT use a mix of "enum" and "bit" substatements as this would result in ambiguous interpretation. When present, each "enum" statement SHALL contain an explicit and unique "value" substatement. When present, each "bit" statement SHALL contain an explicit and unique "position" substatement.¶

Table 3: `amm:int-labels` Substatements
Substatement	Cardinality
enum	0..n
bit	0..n

6.2.1.3. The `amm:cddl` Statement

This statement provides annotation of allowed content within a CBOR type byte string in the form of a Concise Data Definition Language (CDDL) fragment. The argument to this statement is a CDDL fragment in accordance with [RFC8610], escaped as necessary to conform to the YANG syntax.¶

There are no substatements within this statement.¶

6.2.1.4. The `amm:base` Statement

This statement constrains an IDENT (Section 6.5) object reference to allow only objects with a particular base themselves. The argument to this statement is the text form of the ARI referencing the required base object.¶

There are no substatements within this statement.¶

6.2.2. The `amm:ulist` Statement

This statement creates a Uniform List semantic type (see Section 3.3.2 of [I-D.ietf-dtn-amm]) for its parent statement. There is no argument to this statement.¶

Table 4: `amm:ulist` Substatements
Substatement	Cardinality
reference	0..1
description	0..1
min-elements	0..1
max-elements	0..1
One of the type uses:
amm:type	0..1
amm:ulist	0..1
amm:dlist	0..1
amm:umap	0..1
amm:union	0..1

Examples of the "amm:ulist" statement are below, some as simple use and some as restriction.¶

amm:ulist {
  amm:type uint;
}
amm:ulist {
  amm:type uint {
    range "3..10";
    units "meter";
  }
  min-elements 2;
  max-elements 10;
}

6.2.3. The `amm:dlist` Statement

This statement creates a Diverse List semantic type (see Section 3.3.3 of [I-D.ietf-dtn-amm]) for its parent statement. There is no argument to this statement.¶

Each of the type use substatements defines a single element within the AC, except for the amm:seq which defines a sequence of type-matching elements within the AC (rather than as a sub-AC).¶

Table 5: `amm:dlist` Substatements
Substatement	Cardinality
reference	0..1
description	0..1
One or more of the type uses:
amm:type	0..n
amm:ulist	0..n
amm:dlist	0..n
amm:umap	0..n
amm:union	0..n
amm:seq	0..n

Examples of the "amm:dlist" statement are below, one as simple structure and the other as a complex sequence.¶

amm:dlist {
  // each "type" substatement is one element of the AC
  amm:type uint;
  amm:type uint;
}
amm:dlist {
  // first AC element is text
  amm:type textstr;
  // remaining 2-10 element are int
  amm:seq {
    amm:type int;
    min-elements 2;
    max-elements 10;
  }
}

6.2.4. The `amm:umap` Statement

This statement creates a Uniform Map semantic type (see Section 3.3.4 of [I-D.ietf-dtn-amm]) for its parent statement. There is no argument to this statement.¶

When present, each of the amm:keys and amm:values substatements constrains the associated aspect of all map items to the specific type; when absent the aspect is left unconstrained. Keep in mind that AM keys are always constrained to untyped literal values and the use of amm:keys can only narrow this constraint.¶

Table 6: `amm:umap` Substatements
Substatement	Cardinality
reference	0..1
description	0..1
amm:keys	0..1
amm:values	0..1

Table 7: `amm:keys` and `amm:values` Substatements
Substatement	Cardinality
reference	0..1
description	0..1
One of the type uses:
amm:type	0..1
amm:ulist	0..1
amm:dlist	0..1
amm:umap	0..1
amm:union	0..1

Examples of the "amm:umap" statement are below, some as simple use and some as restriction.¶

amm:umap {
  amm:keys {
    amm:type uint;
  }
  description
    "restrict only keys";
}
amm:umap {
  amm:keys {
    amm:type uint;
  }
  amm:values {
    amm:type textstr;
  }
  description
    "Map uint to text values.";
}

6.2.5. The `amm:tblt` Statement

This statement creates a Table Template semantic type (see Section 3.3.5 of [I-D.ietf-dtn-amm]) for its parent statement. There is no argument to this statement.¶

The substatements are a combination of "amm:column" statements defining table structure and "amm:key", "amm:unique", "min-elements", "max-elements" statements defining constraints on the table rows.¶

Table 8: `amm:tblt` Substatements
Substatement	Cardinality
reference	0..1
description	0..1
min-elements	0..1
max-elements	0..1
amm:column	0..n
amm:key	0..1
amm:unique	0..n

Examples of the "amm:tblt" statement are below.¶

amm:tblt {
  amm:column first {
    amm:type uint;
  }
  amm:column second {
    amm:type textstr;
  }
  amm:key first;
}

6.2.5.1. The `amm:column` Statement

This statement defines the name and type of each column of a table. The argument to this statement is an identifier for the column. All columns SHALL have unique names within the same parent table.¶

The substatements under this are one of the semantic type statements (Section 6.2) which defines the type for values in this column. The type of a column SHALL NOT itself use a "amm:tblt" or a union which contains a "amm:tblt".¶

Table 9: `amm:column` Substatements
Substatement	Cardinality
reference	0..1
description	0..1
One of the type uses:
amm:type	0..1
amm:ulist	0..1
amm:dlist	0..1
amm:umap	0..1
amm:union	0..1

6.2.6. The `amm:union` Statement

This statement creates a Type Union [I-D.ietf-dtn-amm] semantic type for its parent statement. There is no argument to this statement.¶

Each of the substatements defines one of the possible choices of the union. The order of the list of choices is significant, especially when converting ARI values, because the first choice which matches or converts will be used regardless of any other choices.¶

Table 10: `amm:union` Substatements
Substatement	Cardinality
reference	0..1
description	0..1
amm:type	0..n
amm:ulist	0..n
amm:dlist	0..n
amm:tblt	0..n
amm:umap	0..n

Examples of the "union" statement are below, some as simple use and some as restriction.¶

amm:union {
  amm:type int;
  amm:type null;
  description
    "an optional int";
}
amm:union {
  amm:type uint {
    range "3..10";
    units "meter";
  }
  amm:type textstr;
}

6.2.7. The `amm:seq` Statement

This statement creates a Sequence semantic type (see Section 3.3.7 of [I-D.ietf-dtn-amm]) for its parent statement. There is no argument to this statement.¶

This statement is distinct from the "amm:ulist" statement, which types the AC container itself, while the "amm:seq" types a portion of elements within an AC. The "amm:seq" is not present as a top-level value type except for the special case of a greedy capturing parameter type.¶

Table 11: `amm:seq` Substatements
Substatement	Cardinality
reference	0..1
description	0..1
min-elements	0..1
max-elements	0..1
One of the type uses:
amm:type	0..1
amm:ulist	0..1
amm:dlist	0..1
amm:umap	0..1
amm:union	0..1

Examples of the "seq" statement are below.¶

amm:dlist {
  amm:type textstr;
  amm:seq {
    amm:type uint;
    min-elements 1;
  }
}

6.3. The `amm:parameter` Statement

This statement is used to define one formal parameter that apply to the parent object. The argument to this statement is an identifier for the parameter. All parameters SHALL have unique names within the same parent object.¶

The substatements under this are one of the semantic type statements (Section 6.2) which defines the type of the parameter. When the "amm:seq" statement is used to type a formal parameter, it SHALL be the last parameter in the list and represents a greedy matching of that an all subsequent given parameters.¶

Table 12: `amm:parameter` Substatements
Substatement	Cardinality
reference	0..1
description	0..1
amm:default	0..1
One of the type uses:
amm:type	0..1
amm:ulist	0..1
amm:dlist	0..1
amm:tblt	0..1
amm:umap	0..1
amm:union	0..1
amm:seq	0..1

An example of the "parameter" statement is below, where there are three defined parameters two of which have default values.¶

  amm:parameter first {
    amm:type uint {
      range "3..10";
    }
  }
  amm:parameter second {
    amm:type textstr;
    amm:default "\"value\"";
  }
  amm:parameter third {
    amm:ulist {
      amm:type uint;
    }
    amm:default "/AC/(3,5,8)"
  }

6.3.1. The `amm:default` Statement

This statement is used to define default parameter as an AMM value. The argument to this statement is the text form of the ARI for the default value.¶

The default value is used in the Parameter Handling procedure (see Section 6.4 of [I-D.ietf-dtn-amm]) to normalize given parameters into actual parameters.¶

6.4. The `amm:typedef` Statement

This statement is used to define a Semantic Type (TYPEDEF) object (see Section 3.4.2 of [I-D.ietf-dtn-amm]). The argument to this statement is the name of the object instance.¶

The substatements under this are a choice of a top-level semantic type (see Section 6.2) being named by the typedef.¶

Table 13: `amm:typedef` Substatements
Substatement	Cardinality
if-feature	0..1
amm:enum	0..1
status	0..1
reference	0..1
description	0..1
One of the type uses:
amm:type	0..1
amm:ulist	0..1
amm:dlist	0..1
amm:tblt	0..1
amm:umap	0..1
amm:union	0..1

Examples of the "typedef" statement are below, some as restriction and some as union.¶

  amm:typedef restricted-uint {
    amm:type uint {
      range "3..10";
    }
    description
      "Example restriction";
  }
  amm:typedef annotated-uint {
    amm:type uint {
      units "meter";
    }
    description
      "Example units annotation";
  }
  amm:typedef structured-ac {
    amm:ulist {
      amm:type real32;
      amm:units "meter";
      min-elements 3;
      max-elements 10;
    }
    description
      "Example units annotation";
  }

6.5. The `amm:ident` Statement

This statement is used to define an Identity (IDENT) object (see Section 3.4.3 of [I-D.ietf-dtn-amm]). The argument to this statement is the name of the object instance.¶

The substatements under this are the common object metadata, optional formal parameters, and any number of base IDENT objects from which this one is derived.¶

Table 14: `amm:ident` Substatements
Substatement	Cardinality
if-feature	0..1
amm:enum	0..1
amm:parameter	0..n
status	0..1
reference	0..1
description	0..1
amm:base	0..*

An example of a mulitple-base hierarchy of IDENT objects is below.¶

  amm:ident base-a {
    description
      "A base identity object.";
  }
  amm:ident base-b {
    description
      "Another base identity object.";
  }
  amm:ident use-1 {
    amm:base "./IDENT/base-a";
    description
      "An identity derived from base-a.";
  }
  amm:ident use-2 {
    amm:base "./IDENT/use-1";
    amm:base "./IDENT/base-b";
    description
      "An identity derived from base-a (via use-1) and base-b.";
  }
  amm:ident use-3 {
    amm:base "./IDENT/base-b";
    amm:parameter option {
      amm:type "/ARITYPE/INT";
    }
    description
      "An identity derived from base-b which includes a parameter.";
  }

6.5.1. The `amm:base` Statement

This statement causes the parent IDENT (Section 6.5) object to be derived from a referenced base object. The argument to this statement is the text form of the ARI referencing the required base object.¶

Similar to YANG logic, in the AMM derivation of an IDENT from a base has the following properties.¶

It is irreflexive, which means that an identity is not derived from itself.¶
It is transitive, which means that if identity B is derived from A and C is derived from B, then C is also derived from A.¶

There are no substatements within this statement.¶

6.6. The `amm:const` Statement

This statement is used to define a Constant (CONST) object (see Section 3.4.5 of [I-D.ietf-dtn-amm]). The argument to this statement is the name of the object instance.¶

The substatements under this are the common object metadata, optional formal parameters, and one of the semantic type statements (Section 6.2) that represents the produced value of the CONST. The "const" statement SHALL contain a an "init-value", which is the constant represented by this object.¶

Table 15: `amm:const` Substatements
Substatement	Cardinality
if-feature	0..1
amm:enum	0..1
amm:parameter	0..n
status	0..1
reference	0..1
description	0..1
amm:init-value	1
One of the type uses:
amm:type	0..1
amm:ulist	0..1
amm:dlist	0..1
amm:tblt	0..1
amm:umap	0..1
amm:union	0..1

An example of a simple-typed CONST is below.¶

  amm:const pi32 {
    amm:type real32;
    amm:init-value "3.14159";
    description
      "A truncated value of Pi.";
  }

Another example of a semantic-typed MAC-valued CONST (see Section 4.2.4 of [I-D.ietf-dtn-amm]) is below.¶

  amm:const do_thing {
    amm:type amm:MAC;
    amm:init-value "/AC/(../CTRL/first,../CTRL/second(2))";
    description
      "Execute two controls in sequence.";
  }

6.7. The `amm:ctrl` Statement

This statement is used to define a Control (CTRL) object (see Section 3.4.6 of [I-D.ietf-dtn-amm]). The argument to this statement is the name of the object instance.¶

The substatements under this are the common object metadata, optional formal parameters, and an optional execution result. If the amm:result substatement is present it SHALL contain an "init-value" substatement, used to initialize the Result Storage for the execution procedure (see Section 6.6 of [I-D.ietf-dtn-amm]). If the amm:result substatement is omitted the assumed result type SHALL be NULL with a default value of null.¶

Table 16: `amm:ctrl` Substatements
Substatement	Cardinality
if-feature	0..1
amm:enum	0..1
amm:parameter	0..n
status	0..1
reference	0..1
description	0..1
amm:result	0..1

An example of a single-parameter CTRL is below.¶

  amm:ctrl reset_count {
    amm:parameter src {
      type textstr;
      description
        "The name of the source.";
    }
    amm:result previous {
      type UVAST;
      description
        "The value just before reset.";
    }
    description
      "This control resets counts for the given source.";
  }

6.7.1. The `amm:result` Statement

The result statement contains one of the semantic type statements (Section 6.2) which represents the result expected from executing a CTRL or evaluating an OPER. The argument to this statement is an identifier for the result.¶

Table 17: `amm:result` Substatements
Substatement	Cardinality
reference	0..1
description	0..1
One of the type uses:
amm:type	0..1
amm:ulist	0..1
amm:dlist	0..1
amm:tblt	0..1
amm:umap	0..1
amm:union	0..1

6.8. The `amm:edd` Statement

This statement is used to define an Externally Defined Data (EDD) object (see Section 3.4.4 of [I-D.ietf-dtn-amm]). The argument to this statement is the name of the object instance.¶

The substatements under this are the common object metadata, optional formal parameters, and one of the semantic type statements (Section 6.2) that represents the produced value of the EDD.¶

Table 18: `amm:edd` Substatements
Substatement	Cardinality
if-feature	0..1
amm:enum	0..1
amm:parameter	0..n
status	0..1
reference	0..1
description	0..1
One of the type uses:
amm:type	0..1
amm:ulist	0..1
amm:dlist	0..1
amm:tblt	0..1
amm:umap	0..1
amm:union	0..1

An example of a simple-typed EDD is below.¶

  amm:edd tx_count {
    amm:type amm:counter64 {
      units "frames";
    }
    description
      "The count of the number of frames sent.";
  }

6.9. The `amm:oper` Statement

This statement is used to define an Operator (OPER) object (see Section 3.4.7 of [I-D.ietf-dtn-amm]). The argument to this statement is the name of the object instance.¶

The substatements under this are the common object metadata, optional formal parameters, an operands list, and an evaluation result.¶

Table 19: `amm:edd` Substatements
Substatement	Cardinality
if-feature	0..1
amm:enum	0..1
amm:parameter	0..n
status	0..1
reference	0..1
description	0..1
operands	1
result	1

An example of an arithmetic OPER is below.¶

  amm:oper add {
    amm:operand val_a {
      amm:type amm:NUMERIC;
    }
    amm:operand val_b {
      amm:type amm:NUMERIC;
    }
    amm:result sum {
      amm:type amm:NUMERIC;
    }
    description
      "Sum together the two operands.";
  }

A more complex "variadic" OPER with parameters is below. Also note the anonymous semantic type used to restrict the parameter.¶

  amm:oper sum {
    parameter count {
      amm:type amm:UINT {
        range "1..max";
      }
      description
        "The number of operands to pop."
    }
    operand value {
      amm:type amm:NUMERIC;
      description
        "This is not within a container, so does not represent an AC;
        it is multiple operands.";
    }
    result sum {
      type amm:NUMERIC;
    }
    description
      "Sum together a sequence from the stack.";
  }

6.9.1. The `amm:operand` Statement

This statement is used to define one operand that applies to the parent object. The argument to this statement is an identifier for the operand. All operands SHALL have unique names within the same parent object.¶

Table 20: `amm:operand` Substatements
Substatement	Cardinality
reference	0..1
description	0..1
One of the type uses:
amm:type	0..1
amm:ulist	0..1
amm:dlist	0..1
amm:tblt	0..1
amm:umap	0..1
amm:union	0..1

6.10. The `amm:sbr` Statement

This statement is used to define a State Based Rule object (see Section 3.4.8 of [I-D.ietf-dtn-amm]). The argument to this statement is the name of the object instance.¶

The substatements under this are the common object metadata, the action to execute upon trigger, and rule control fields defined below.¶

Table 21: `amm:sbr` Substatements
Substatement	Cardinality
if-feature	0..1
amm:enum	0..1
status	0..1
reference	0..1
description	0..1
amm:action	1
amm:condition	1
amm:min-interval	0..1
amm:max-count	0..1
amm:init-enabled	0..1

An example of an SBR with some default fields is below.¶

  amm:sbr enable_safe_mode {
    amm:action "/AC/(./CTRL/ensure_safe_mode(true))";
    amm:condition "/AC/(./EDD/sensor,./VAR/min_threshold,/ietf-amm/OPER/compare_lt)";
    description
      "Enable safe mode below threshold.";
  }

6.10.1. The `amm:min-interval` Statement

This statement is used to define the Minimum Interval field of SBR (Section 6.10) objects. The argument to this statement is the text form of a TD value. If not present, the default value of zero (meaning no minimum) is used.¶

6.10.2. The `amm:max-count` Statement

This statement is used to define the Maximum Count field of SBR (Section 6.10) and TBR (Section 6.11) objects. The argument to this statement is the text form of a UVAST value. If not present, the default value of zero (meaning no limit) is used.¶

6.10.3. The `amm:init-enabled` Statement

This statement is used to define the Initial Enabled state of SBR (Section 6.10) and TBR (Section 6.11) objects. The argument to this statement is the text form of a BOOL value. If not present, the default value of true is used.¶

6.11. The `amm:tbr` Statement

This statement is used to define a Time-Based Rule (TBR) object (see Section 3.4.9 of [I-D.ietf-dtn-amm]). The argument to this statement is the name of the object instance.¶

The substatements under this are the common object metadata, the action to execute upon trigger, and rule control fields defined below.¶

Table 22: `amm:tbr` Substatements
Substatement	Cardinality
if-feature	0..1
amm:enum	0..1
status	0..1
reference	0..1
description	0..1
amm:action	1
amm:start	1
amm:period	0..1
amm:max-count	0..1
amm:init-enabled	0..1

An example of an TBR with some default fields is below.¶

  amm:tbr tlm_rule {
    amm:action "/AC/(./CTRL/first,/adm2/CTRL/other)";
    amm:period "/TD/PT30s";
    description
      "Generate telemetry reports.";
  }

6.11.1. The `amm:start` Statement

This statement is used to define the Start field of TBR (Section 6.11) objects. The argument to this statement is the text form of a TIME value (see Appendix A). If not present, the default value of zero (meaning start immediately) is used.¶

6.12. The `amm:var` Statement

This statement is used to define a Variable (VAR) object (see Section 3.4.10 of [I-D.ietf-dtn-amm]). The argument to this statement is the name of the object instance.¶

The substatements under this are the common object metadata, optional formal parameters, one of the semantic type statements (Section 6.2) that represents the stored-and-produced value of the VAR, and an optional initializer expression.¶

Table 23: `amm:var` Substatements
Substatement	Cardinality
if-feature	0..1
amm:enum	0..1
amm:parameter	0..n
status	0..1
reference	0..1
description	0..1
One of the type uses:
amm:type	0..1
amm:ulist	0..1
amm:dlist	0..1
amm:tblt	0..1
amm:umap	0..1
amm:union	0..1
An optional initializer:
amm:init-value	0..1
amm:init-expr	0..1

An example of a simple-typed VAR with an initializer value is below.¶

  amm:var min_threshold {
    amm:type real32 {
      units "meter";
    }
    amm:init-value "1e4";
    description
      "The lower threshold to enable safe mode.";
  }

6.12.1. The `amm:init-value` Statement

This statement is used to define CONST values and VAR initial state as an AMM value. The argument to this statement is the text form of the ARI for the initial value.¶

The initializer is used as part of the Agent Initialization procedure, (see Section 6.1 of [I-D.ietf-dtn-amm]) and when new VAR objects are defined in an ODM.¶

7. IANA Considerations

This section provides guidance to the Internet Assigned Numbers Authority (IANA) regarding registration of schema and namespaces related to core ADMs, in accordance with BCP 26 [RFC1155].¶

7.1. DTN Management Architecture Parameters

This document relies on existing ARI-defined sub-registries defined in [IANA-DTNMA] by Section 9.3 of [I-D.ietf-dtn-ari].¶

This document registers the following entries within the "Application Data Models" sub-registry of the "DTN Management Architecture Parameters" registry [IANA-DTNMA].¶

Table 24: Application Data Models
Enumeration	Name	Reference	Notes
0	ietf-amm	[This document]	This ADM defines YANG extensions for the AMM itself.
1	ietf-dtnma-agent	[This document]
2	ietf-dtnma-agent-acl	[This document]

8. Security Considerations

This document defines a syntax for encoding DTNMA ADMs within a text file, and for interpreting extensions to the YANG language to support modeling of AMM objects and ARI values. It does not address what the contents of those ADMs are or any security considerations associated with the data models themselves.¶

Appendix A. ADM Module for AMM Definitions

The ADM module in this section implements the entities described in Section 4.2 of [I-D.ietf-dtn-amm]. This includes the following:¶

Extensions to support ADM Metadata (see Section 4.1.1 of [I-D.ietf-dtn-amm]) within a YANG module.¶
Extensions to support AMM Object Types (see Section 3.4 of [I-D.ietf-dtn-amm]) within a YANG module.¶
Extensions to support Semantic Types (see Section 3.3 of [I-D.ietf-dtn-amm]) within a YANG module.¶

<CODE BEGINS> file "ietf-amm.yang"
module ietf-amm {
  yang-version 1.1;
  namespace "ari://ietf-amm";
  prefix amm;

  organization
    "IETF Delay Tolerant Networking (DTN) Working Group";
  contact
    "WG Web: <http://tools.ietf.org/wg/dtn/>
     WG List: <mailto:[email protected]>

     Editor: Brian Sipos
             <mailto:[email protected]>";
  description
    "This module defines the DTN Management Architecture (DTNMA)
     Application Management Model (AMM) extensions within YANG.
     It also defines the base TYPEDEF objects.

     The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL
     NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'NOT RECOMMENDED',
     'MAY', and 'OPTIONAL' in this document are to be interpreted as
     described in BCP 14 (RFC 2119) (RFC 8174) when, and only when,
     they appear in all capitals, as shown here.

     Copyright (c) 2024 IETF Trust and the persons identified as
     authors of the code.  All rights reserved.

     Redistribution and use in source and binary forms, with or
     without modification, is permitted pursuant to, and subject to
     the license terms contained in, the Revised BSD License set
     forth in Section 4.c of the IETF Trust's Legal Provisions
     Relating to IETF Documents
     (https://trustee.ietf.org/license-info).

     This version of this YANG module is part of RFC XXXX
     (https://www.rfc-editor.org/info/rfcXXXX); see the RFC itself
     for full legal notices.";
  reference
    "draft-ietf-dtn-adm-yang";

  revision 2024-07-03 {
    description
      "Updated for latest ADM document.";
    reference
      "draft-ietf-dtn-adm-yang";
  }
  revision 2023-06-08 {
    description
      "Updated for latest AMM contents.";
    reference
      "draft-birrane-dtn-adm";
  }
  revision 2016-04-01 {
    description
      "Updated to fix typos.";
    reference
      "draft-bsipos-dtn-amp-yang";
  }
  revision 2016-03-14 {
    description
      "Initial draft release.";
    reference
      "draft-bsipos-dtn-amp-yang";
  }

  /*
   * This section contains extensions for common behavior of AMM objects.
   */

  extension enum {
    argument value;
    description
      "An enumeration identifies an object within a namespace.
       The argument to this statement is the integer value.";
  }

  extension parameter {
    argument name;
    description
      "The schema for a formal parameter of an object.
       Order of parameters is significant within this statement.";
  }

  extension default {
    argument value;
    description
      "The literal value default for a parameter or result.
       The argument is the text form of the ARI";
  }

  extension init-value {
    argument value;
    description
      "The literal value of a CONST object,
       initial state for a VAR object.
       The argument is the text form of the ARI";
  }

  extension init-expr {
    argument expr;
    description
      "An expression evaluated to initialize a VAR object.
       The argument is the text form of the EXPR AC";
  }

  /*
   * This section contains extensions for AMM object definitions.
   */

  extension typedef {
    argument name;
    description
      "Definition of a TYPEDEF within an ADM.
       The argument to this statement is the object name.
       One of the type use substatements must be present.";
  }

  extension ident {
    argument name;
    description
      "Definition of an IDENT within an ADM.
       The argument to this statement is the object name.
       An 'base' substatement must be present.";
  }

  extension base {
    argument name;
    description
      "The argument is the base of an IDENT object.";
  }

  extension const {
    argument name;
    description
      "Definition of a CONST within an ADM.
       The argument to this statement is the object name.
       An 'init-value' substatement must be present.";
  }

  extension ctrl {
    argument name;
    description
      "Definition of a CTRL within an ADM.
       The argument to this statement is the object name.";
  }

  extension result {
    argument name;
    description
      "A result value reported as a response to a control.
       The substatement is the result type.
       Each CTRL can have a single optional result.";
  }

  extension edd {
    argument name;
    description
      "Definition of an EDD within an ADM.
       The argument to this statement is the object name.";
  }

  extension oper {
    argument name;
    description
      "Definition of an OPER within an ADM.
       The argument to this statement is the object name.";
  }

  extension operand {
    argument name;
    description
      "An individual operand taken from the expression stack
       during evaluation of the OPER.
       Each substatement is an operand as a leaf (ARI).
       Order of operands is significant within an object definition.";
  }

  extension var {
    argument name;
    description
      "Definition of a VAR within an ADM.
       The argument to this statement is the object name.";
  }

  /*
   * This section contains extensions for defining semantic type instances.
   */

  extension type {
    argument name;
    description
      "A reference to a built-in type or prefix-qualified typedef.";
  }

  extension display-hint {
    argument ident;
    description
      "Reference an IDENT object which indicates how a value should be
       displayed for human consumption.
       The base of the IDENT SHALL be the ./IDENT/display-hint object.";
  }

  extension int-labels {
    description
      "Type narrowing for an INTEGER to label enum values or bit positions.";
  }

  extension cddl {
    argument text;
    description
      "Type narrowing for a CBOR item in the form of CDDL syntax.
       The argument to this statement is the actual CDDL text.";
  }

  extension ulist {
    description
      "Type for an AC containing a list of uniform-typed values.";
  }

  extension dlist {
    description
      "Type for an AC containing a list of diverse-typed sequences.";
  }

  extension seq {
    description
      "A sequence of uniform-typed values within a 'dlist'.";
  }

  extension umap {
    description
      "Type for an AM containing a set of uniform-typed key-value pairs.";
  }

  extension keys {
    description
      "The type restriction for 'umap' keys.";
  }

  extension values {
    description
      "The type restriction for 'umap' values.";
  }

  extension tblt {
    description
      "Type for a table of values with a column schema.";
  }

  extension column {
    argument name;
    description
      "An individual column within a 'tblt' definition.";
  }

  extension key {
    argument columns;
    description
      "Names of columns composing the row key, separated by spaces,
       within a 'tblt' definition.";
  }

  extension unique {
    argument columns;
    description
      "Names of columns composing a uniqueness constraint, separated by
       spaces, within a 'tblt' definition.";
  }

  extension union {
    description
      "Type for a union of other types.";
  }

  amm:enum 0;
  amm:ident display-hint {
    amm:enum 0;
    description
      "The base IDENT for objects usable as arguments for the
       'amm:display-hint' extension.
       This object itself provides no display hint purpose.";
  }

  // Named type unions
  amm:typedef TYPE-REF {
    amm:enum 0;
    description
      "Reference to either a literal type or a typedef.";
    amm:union {
      amm:type "/ARITYPE/ARITYPE";
      amm:type "/ARITYPE/TYPEDEF";
    }
  }
  amm:typedef INTEGER {
    amm:enum 1;
    description
      "Any type which represents a discrete integer.";
    amm:union {
      amm:type "/ARITYPE/BYTE";
      amm:type "/ARITYPE/UINT";
      amm:type "/ARITYPE/INT";
      amm:type "/ARITYPE/UVAST";
      amm:type "/ARITYPE/VAST";
    }
  }
  amm:typedef FLOAT {
    amm:enum 2;
    description
      "Any type which represents a floating point number.";
    amm:union {
      amm:type "/ARITYPE/REAL32";
      amm:type "/ARITYPE/REAL64";
    }
  }
  amm:typedef NUMERIC {
    amm:enum 3;
    description
      "Any type which can be used with numeric expressions.";
    amm:union {
      amm:type "./TYPEDEF/INTEGER";
      amm:type "./TYPEDEF/FLOAT";
    }
  }
  amm:typedef PRIMITIVE {
    amm:enum 4;
    description
      "Any primitive type.";
    amm:union {
      amm:type "/ARITYPE/NULL";
      amm:type "/ARITYPE/BOOL";
      amm:type "./TYPEDEF/NUMERIC";
      amm:type "/ARITYPE/TEXTSTR";
      amm:type "/ARITYPE/BYTESTR";
    }
  }
  amm:typedef TIME {
    amm:enum 5;
    description
      "Any type which can be used with time expressions.";
    amm:union {
      amm:type "/ARITYPE/TP";
      amm:type "/ARITYPE/TD";
    }
  }
  amm:typedef SIMPLE {
    amm:enum 6;
    description
      "Any type which contains a single literal value (not nested).";
    amm:union {
      amm:type "./TYPEDEF/PRIMITIVE";
      amm:type "./TYPEDEF/TIME";
    }
  }
  amm:typedef NESTED {
    amm:enum 7;
    description
      "A literal type which contains other ARI values.";
    amm:union {
      amm:type "/ARITYPE/AC";
      amm:type "/ARITYPE/AM";
      amm:type "/ARITYPE/TBL";
    }
  }
  amm:typedef ANY {
    amm:enum 8;
    description
      "Any value representable by an ARI.";
    // These type names are built-in
    amm:union {
      amm:type "/ARITYPE/LITERAL";
      amm:type "/ARITYPE/OBJECT";
    }
  }
  amm:typedef VALUE-OBJ {
    amm:enum 9;
    description
      "A reference to an object which can produce a value.";
    amm:union {
      amm:type "/ARITYPE/CONST";
      amm:type "/ARITYPE/EDD";
      amm:type "/ARITYPE/VAR";
    }
  }
  amm:typedef NONCE {
    amm:enum 10;
    description
      "This type union is used to correlate Agent-Manager messages.";
    amm:union {
      amm:type "/ARITYPE/BYTESTR";
      amm:type "/ARITYPE/UVAST";
      amm:type "/ARITYPE/NULL";
    }
  }

  // operational semantic types
  amm:typedef counter32 {
    amm:enum 11;
    description
      "A 32-bit counter with an arbitrary initial value that only increments.
       When the value reaches the upper range it wraps around to zero.
       At least two samples of this value need to be compared over time.";
    amm:type "/ARITYPE/UINT";
  }
  amm:typedef counter64 {
    amm:enum 12;
    description
      "A 64-bit counter with an arbitrary initial value that only increments.
       When the value reaches the upper range it wraps around to zero.
       At least two samples of this value need to be compared over time.";
    amm:type "/ARITYPE/UVAST";
  }
  amm:typedef gauge32 {
    amm:enum 13;
    description
      "A 32-bit value sampling some quantized measurement.
       The value can increase or decrease arbitrarily over time.";
    amm:type "/ARITYPE/INT";
  }
  amm:typedef gauge64 {
    amm:enum 14;
    description
      "A 64-bit value sampling some quantized measurement.
       The value can increase or decrease arbitrarily over time.";
    amm:type "/ARITYPE/VAST";
  }
  amm:typedef timestamp {
    amm:enum 15;
    description
      "A time point representing the system clock at which a specific
       occurrence happened.
       The specific occurrence must be defined in the description
       of any node defined using this type.";
    amm:type "/ARITYPE/TP";
  }

  // Restrictions on AC item types for Evaluation and EXPR
  amm:typedef eval-tgt {
    amm:enum 16;
    description
      "A value which can be the target of an evaluation.";
    amm:union {
      amm:type "./TYPEDEF/SIMPLE"; // special case of literal value result
      amm:type "./TYPEDEF/VALUE-OBJ"; // produces an eval-tgt
      amm:type "./TYPEDEF/EXPR";
    }
  }
  amm:typedef EXPR-item {
    amm:enum 17;
    description
      "Each item of an EXPR list.";
    amm:union {
      amm:type "./TYPEDEF/SIMPLE";
      amm:type "./TYPEDEF/VALUE-OBJ"; // produces an eval-tgt
      amm:type "./TYPEDEF/TYPE-REF"; // treated as unary operator
      amm:type "/ARITYPE/LABEL"; // substitutable label
      amm:type "/ARITYPE/OPER";
    }
  }
  amm:typedef EXPR {
    amm:enum 18;
    description
      "The contents of an EXPR container.";
    amm:ulist {
      amm:type "./TYPEDEF/EXPR-item";
    }
  }

  // Restrictions on AC item types for Execution and MAC
  amm:typedef exec-tgt {
    amm:enum 19;
    description
      "A value which can be the target of an execution.";
    amm:union {
      amm:type "./TYPEDEF/exec-item";
      amm:type "./TYPEDEF/MAC";
    }
  }
  amm:typedef exec-item {
    amm:enum 20;
    description
      "A reference to an object which can be executed.
       The value-object must be typed to contain an exec-tgt.";
    amm:union {
      amm:type "/ARITYPE/CTRL";
      amm:type "./TYPEDEF/VALUE-OBJ"; // produces an exec-tgt
    }
  }
  amm:typedef MAC {
    amm:enum 21;
    description
      "The contents of a MAC container are an ordered list of
       executable values.";
    amm:ulist {
      amm:type "./TYPEDEF/EXEC-item";
    }
  }

  // Restrictions on AC item types for Reporting and RPTT
  amm:typedef rpt-tgt {
    amm:enum 22;
    description
      "A value which can be the target of reporting.";
    amm:union {
      amm:type "./TYPEDEF/VALUE-OBJ"; // produces an RPTT
      amm:type "./TYPEDEF/RPTT";
    }
  }
  amm:typedef RPTT-item {
    amm:enum 23;
    description
      "Each item of a RPTT.
       Each item references a value-producing object or contains an
       expression to be evaluated.";
    amm:union {
      amm:type "./TYPEDEF/VALUE-OBJ";
      amm:type "./TYPEDEF/EXPR";
    }
  }
  amm:typedef RPTT {
    amm:enum 24;
    description
      "The contents of a report template, encoded as the sequence of items.";
    amm:ulist {
      amm:type "./TYPEDEF/RPTT-item";
    }
  }
}

<CODE ENDS>

Appendix B. IANA Assignments for display-hint

The ADM module in this section defines display-hint-derived IDENT objects described in Section 3.3.1 of [I-D.ietf-dtn-amm] for specific representations.¶

<CODE BEGINS> file "iana-display-hints.yang"
module iana-display-hints {
  yang-version 1.1;
  namespace "ari://iana-display-hints";
  prefix ianadh;

  import ietf-amm {
    prefix amm;
  }

  organization
    "IANA";
  contact
    "WG Web: <http://tools.ietf.org/wg/dtn/>
     WG List: <mailto:[email protected]>

     Editor: Brian Sipos
             <mailto:[email protected]>";
  description
    "This module defines intermediate and leaf IDENT objects usable as
     display-hint annotations derived from the base
     <ari://ietf-amm/IDENT/display-hint> object.

     The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL
     NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'NOT RECOMMENDED',
     'MAY', and 'OPTIONAL' in this document are to be interpreted as
     described in BCP 14 (RFC 2119) (RFC 8174) when, and only when,
     they appear in all capitals, as shown here.

     Copyright (c) 2024 IETF Trust and the persons identified as
     authors of the code.  All rights reserved.

     Redistribution and use in source and binary forms, with or
     without modification, is permitted pursuant to, and subject to
     the license terms contained in, the Revised BSD License set
     forth in Section 4.c of the IETF Trust's Legal Provisions
     Relating to IETF Documents
     (https://trustee.ietf.org/license-info).

     The initial version of this YANG module is part of RFC XXXX
     (https://www.rfc-editor.org/info/rfcXXXX); see the RFC itself
     for full legal notices.";
  reference
    "https://www.iana.org/assignments/DTNMA-TBA";

  revision 2024-07-20 {
    description
      "Updated for latest ADM document.";
    reference
      "draft-ietf-dtn-adm-yang";
  }
  amm:enum 0;

  // Integer number hints
  amm:ident base-integer {
    amm:enum 1;
    description
      "Intermediate base IDENT of display hints for integer values.
       Hints derived from this object SHALL only apply to built-in types
       BYTE, INT, UINT, VAST, and UVAST.";
    amm:base "//ietf-amm/IDENT/display-hint";
  }
  amm:ident display-int-dec {
    amm:enum 2;
    description
      "Display integers as decimal (base 10).";
    amm:base "//ietf-amm/IDENT/base-integer";
  }
  amm:ident display-int-bin {
    amm:enum 3;
    description
      "Display integers as binary (base 2).";
    amm:base "//ietf-amm/IDENT/base-integer";
  }
  amm:ident display-int-hex {
    amm:enum 4;
    description
      "Display integers as hexadecimal (base 16).";
    amm:base "//ietf-amm/IDENT/base-integer";
  }

  // Floating-point number hints
  amm:ident base-float {
    amm:enum 5;
    description
      "Intermediate base IDENT of display hints for floating point values.
       Hints derived from this object SHALL only apply to built-in types
       REAL32 and REAL64.";
    amm:base "//ietf-amm/IDENT/display-hint";
  }
  amm:ident display-float-dec {
    amm:enum 6;
    description
      "Display floating point values as decimal fraction.";
    amm:base "//ietf-amm/IDENT/base-float";
  }
  amm:ident display-float-exp {
    amm:enum 7;
    description
      "Display floating point values as decimal exponential form.";
    amm:base "//ietf-amm/IDENT/base-float";
  }
  amm:ident display-float-hex {
    amm:enum 8;
    description
      "Display floating point values as hexadecimal exponential form.";
    amm:base "//ietf-amm/IDENT/base-float";
  }

  // Byte-string hints
  amm:ident base-bstr {
    amm:enum 9;
    description
      "Intermediate base IDENT of display hints for byte string values.
       Hints derived from this object SHALL only apply to built-in type
       BYTESTR.";
    amm:base "//ietf-amm/IDENT/display-hint";
  }
  amm:ident display-bstr-text {
    amm:enum 10;
    description
      "Display byte string values as UTF-8 text where possible.
       The base16 encoding is used otherwise.";
    reference
      "draft-ietf-dtn-ari";
    amm:base "//ietf-amm/IDENT/base-bstr";
  }
  amm:ident display-bstr-base16 {
    amm:enum 11;
    description
      "Display byte string values as base16-encoded.";
    reference
      "draft-ietf-dtn-ari";
    amm:base "//ietf-amm/IDENT/base-bstr";
  }
  amm:ident display-bstr-base64 {
    amm:enum 12;
    description
      "Display byte string values as base64url-encoded.";
    reference
      "draft-ietf-dtn-ari";
    amm:base "//ietf-amm/IDENT/base-bstr";
  }
  amm:ident display-bstr-ipaddress {
    amm:enum 16;
    description
      "Display byte string values as either IPv4 address (4-octet length)
       or IPv6 address (16-octet length).";
    reference
      "RFC 4001: Textual Conventions for Internet Network Addresses";
    amm:base "//ietf-amm/IDENT/base-bstr";
  }

  // TIME type (TP or TD built-ins) hints
  amm:ident base-time {
    amm:enum 13;
    description
      "Intermediate base IDENT of display hints for time values.
       Hints derived from this object SHALL only apply to built-in types
       TP and TD.";
    amm:base "//ietf-amm/IDENT/display-hint";
  }
  amm:ident display-time-text {
    amm:enum 14;
    description
      "Display TP and TD values as text in accordance with RFC 3339.";
    reference
      "draft-ietf-dtn-ari";
    amm:base "//ietf-amm/IDENT/base-time";
  }
  amm:ident display-time-dec {
    amm:enum 15;
    description
      "Display TP and TD values as decimal fraction.";
    reference
      "draft-ietf-dtn-ari";
    amm:base "//ietf-amm/IDENT/base-time";
  }
}

<CODE ENDS>

Appendix C. ADM Module for DTNMA Agents

The ADM module in this section implements the entities described in Section 4.3 of [I-D.ietf-dtn-amm]. This includes the following:¶

Introspective access to the ADMs supported by the Agent.¶
Introspective access to the VARs in ODMs.¶
A feature and introspective access to rules in ODMs.¶
A report template used to announce presence of an Agent.¶
Base helper controls and arithmetic operators¶

<CODE BEGINS> file "ietf-dtnma-agent.yang"
module ietf-dtnma-agent {
  yang-version 1.1;
  namespace "ari://ietf-dtnma-agent";
  prefix da;

  import ietf-amm {
    prefix amm;
  }

  organization
    "IETF Delay Tolerant Networking (DTN) Working Group";
  contact
    "WG Web: <http://tools.ietf.org/wg/dtn/>
     WG List: <mailto:[email protected]>

     Editor: Brian Sipos
             <mailto:[email protected]>";
  description
    "This module implements the DTN Management Architecture (DTNMA)
     Agent core functionality.

     Copyright (c) 2024 IETF Trust and the persons identified as
     authors of the code.  All rights reserved.

     Redistribution and use in source and binary forms, with or
     without modification, is permitted pursuant to, and subject to
     the license terms contained in, the Revised BSD License set
     forth in Section 4.c of the IETF Trust's Legal Provisions
     Relating to IETF Documents
     (https://trustee.ietf.org/license-info).

     This version of this YANG module is part of RFC XXXX
     (https://www.rfc-editor.org/info/rfcXXXX); see the RFC itself
     for full legal notices.";
  reference
    "draft-ietf-dtn-adm-yang";

  revision 2024-07-03 {
    description
      "Updated for latest ADM document.";
    reference
      "draft-ietf-dtn-adm-yang";
  }
  revision 2023-06-08 {
    description
      "Updated for latest AMM contents.";
    reference
      "draft-birrane-dtn-adm";
  }

  feature rules {
    description
      "Conforming to this feature enables time-based and
       state-based autonomy rules.";
  }

  grouping obj-list-params {
    description
      "Common parameters for object listing";
    amm:parameter include-adm {
      description
        "If true, listings will include objects from ADMs";
      amm:default "false";
      amm:type "/ARITYPE/BOOL";
    }
  }

  grouping any-binary-operands {
    description
      "Any-value bianry operands";
    amm:operand left {
      description
        "The left-side operand.";
      amm:type "//ietf-amm/TYPEDEF/ANY";
    }
    amm:operand right {
      description
        "The left-side operand.";
      amm:type "//ietf-amm/TYPEDEF/ANY";
    }
  }

  grouping numeric-unary-operands {
    description
      "Numeric unary operand";
    amm:operand val {
      description
        "The single value.";
      amm:type "//ietf-amm/TYPEDEF/NUMERIC";
    }
  }

  grouping numeric-binary-operands {
    description
      "Numeric bianry operands";
    amm:operand left {
      description
        "The left-side operand.";
      amm:type "//ietf-amm/TYPEDEF/NUMERIC";
    }
    amm:operand right {
      description
        "The left-side operand.";
      amm:type "//ietf-amm/TYPEDEF/NUMERIC";
    }
  }

  grouping numeric-unary-result {
    description
      "Numeric result";
    amm:result result {
      description
        "The single value.";
      amm:type "//ietf-amm/TYPEDEF/NUMERIC";
    }
  }

  grouping integer-unary-operands {
    description
      "Integer unary operand";
    amm:operand val {
      description
        "The single value.";
      amm:type "//ietf-amm/TYPEDEF/INTEGER";
    }
  }

  grouping integer-binary-operands {
    description
      "Integer bianry operands";
    amm:operand left {
      description
        "The left-side operand.";
      amm:type "//ietf-amm/TYPEDEF/INTEGER";
    }
    amm:operand right {
      description
        "The left-side operand.";
      amm:type "//ietf-amm/TYPEDEF/INTEGER";
    }
  }

  grouping integer-unary-result {
    description
      "Integer result";
    amm:result result {
      description
        "The single value.";
      amm:type "//ietf-amm/TYPEDEF/INTEGER";
    }
  }

  grouping bool-unary-operands {
    description
      "Boolean unary operand";
    amm:operand val {
      description
        "The single value.";
      amm:type "/ARITYPE/BOOL";
    }
  }

  grouping bool-binary-operands {
    description
      "Boolean bianry operands";
    amm:operand left {
      description
        "The left-side operand.";
      amm:type "/ARITYPE/BOOL";
    }
    amm:operand right {
      description
        "The left-side operand.";
      amm:type "/ARITYPE/BOOL";
    }
  }

  grouping bool-unary-result {
    description
      "Boolean result";
    amm:result result {
      description
        "The single value.";
      amm:type "/ARITYPE/BOOL";
    }
  }

  amm:enum 1;
  amm:edd sw-vendor {
    amm:enum 0;
    description
      "The vendor for this Agent implementation.";
    amm:type "/ARITYPE/TEXTSTR";
  }
  amm:edd sw-version {
    amm:enum 1;
    description
      "The version for this Agent implementation.";
    amm:type "/ARITYPE/TEXTSTR";
  }
  amm:edd capability {
    amm:enum 2;
    description
      "A table to indicate the ADM capability of the sending agent.";
    amm:tblt {
      amm:key "adm-name";
      amm:column adm-name {
        description
          "The module name of the ADM";
        amm:type "/ARITYPE/TEXTSTR";
      }
      amm:column enum {
        description
          "The module enumeration of the ADM";
        amm:type "/ARITYPE/VAST";
      }
      amm:column revision {
        description
          "The specific revision the agent supports.";
        amm:type "/ARITYPE/TEXTSTR";
      }
      amm:column features {
        description
          "The features of the ADM which the agent supports.";
        amm:ulist {
          amm:type "/ARITYPE/TEXTSTR";
        }
      }
    }
  }
  amm:const hello {
    amm:enum 0;
    description
      "A report template to indicate the presence of an agent
       on a network.";
    amm:init-value "/AC/(./EDD/sw-vendor,./EDD/sw-version,./EDD/capability)";
    amm:type "//ietf-amm/TYPEDEF/RPTT";
  }

  // Messaging counters
  amm:edd num-msg-rx {
    amm:enum 3;
    amm:type "//ietf-amm/TYPEDEF/counter64";
  }
  amm:edd num-msg-rx-failed {
    amm:enum 4;
    amm:type "//ietf-amm/TYPEDEF/counter64";
  }
  amm:edd num-msg-tx {
    amm:enum 5;
    amm:type "//ietf-amm/TYPEDEF/counter64";
  }

  // Execution counters and states
  amm:edd num-exec-started {
    amm:enum 6;
    amm:type "//ietf-amm/TYPEDEF/counter64";
  }
  amm:edd num-exec-succeeded {
    amm:enum 7;
    amm:type "//ietf-amm/TYPEDEF/counter64";
  }
  amm:edd num-exec-failed {
    amm:enum 8;
    amm:type "//ietf-amm/TYPEDEF/counter64";
  }
  amm:edd exec-running {
    amm:enum 9;
    amm:tblt {
      amm:key "pid";
      amm:column pid {
        amm:type "/ARITYPE/UVAST";
      }
      amm:column target {
        amm:type "//ietf-amm/TYPEDEF/ANY";
      }
      amm:column state {
        amm:type "/ARITYPE/BYTE" {
          amm:int-labels {
            enum waiting {
              value 0;
              description
                "The execution is waiting on a condition or timer to continue.";
            }
            enum running {
              value 1;
              description
                "The execution is currently running.";
            }
          }
        }
      }
    }
  }

  // MAC helper controls
  amm:ctrl if-then-else {
    amm:enum 0;
    description
      "Evaluate an expression and follow one of two branches of
       further evaluation.";
    amm:parameter condition {
      description
        "The condition to evaluate.";
      amm:type "//ietf-amm/TYPEDEF/eval-tgt";
    }
    amm:parameter on-truthy {
      description
        "The object to execute when the condition is truthy.";
      amm:default "null";
      amm:union {
        amm:type "//ietf-amm/TYPEDEF/exec-tgt";
        amm:type "/ARITYPE/NULL";
      }
    }
    amm:parameter on-falsy {
      description
        "An optional execution when the condition is falsey.";
      amm:default "null";
      amm:union {
        amm:type "//ietf-amm/TYPEDEF/exec-tgt";
        amm:type "/ARITYPE/NULL";
      }
    }
    amm:result branch {
      description
        "Indication of which branch was executed.";
      amm:type "/ARITYPE/BOOL";
    }
  }
  amm:ctrl catch {
    amm:enum 1;
    description
      "Attempt to execute a target, and if there is some failure catch it
       and execute an alternative target.";
    amm:parameter try {
      description
        "The object to execute.";
      amm:type "//ietf-amm/TYPEDEF/exec-tgt";
    }
    amm:parameter on-failure {
      description
        "An optional execution after failure.";
      amm:default "null";
      amm:union {
        amm:type "//ietf-amm/TYPEDEF/exec-tgt";
        amm:type "/ARITYPE/NULL";
      }
    }
    amm:result try-success {
      description
        "True if the try target succeeded without exception.";
      amm:type "/ARITYPE/BOOL";
    }
  }
  amm:ctrl wait-for {
    amm:enum 2;
    description
      "This control causes the execution to pause for a given amount of time.
       This is intended to be used within a macro to separate controls
       in time.";
    amm:parameter duration {
      amm:type "/ARITYPE/TD";
    }
  }
  amm:ctrl wait-until {
    amm:enum 3;
    description
      "This control causes the execution to pause until a specific absolute
       time point.
       This is intended to be used within a macro to separate controls
       in time or as a first macro item to delay execution after the time
       of reception.";
    amm:parameter time {
      amm:type "/ARITYPE/TP";
    }
  }
  amm:ctrl wait-cond {
    amm:enum 4;
    description
      "This control causes the execution to pause until a condition expression
       evaluates to truthy.
       This is intended to be used within a macro to separate controls
       in time or as a first macro item to delay execution until the
       condition is met.";
    amm:parameter condition {
      amm:type "//ietf-amm/TYPEDEF/eval-tgt";
    }
  }

  // Value production and reporting
  amm:ctrl inspect {
    amm:enum 5;
    description
      "Produce a result value to inspect the agent state.
       This does not perform any EXPR evaluation or RPTT handling.";
    amm:parameter ref {
      description
        "An object to produce a value from.";
      amm:type "//ietf-amm/TYPEDEF/VALUE-OBJ";
    }
    amm:result val {
      description
        "The produced value.";
      amm:type "//ietf-amm/TYPEDEF/ANY";
    }
  }
  amm:ctrl report-on {
    amm:enum 6;
    description
      "Generate a report on an object without needing to define an object.
       The parameter is a single RPTT list that would be produced by an object.
       If used for more than one-shot diagnostics, defining a RPTT
       (e.g. in a VAR) is more efficient because the RPTT item would not
       be present in the report.";
    amm:parameter rptt {
      amm:type "//ietf-amm/TYPEDEF/rpt-tgt";
    }
  }

  // Helpers for VAR
  amm:ctrl var-reset {
    amm:enum 7;
    description
      "Modify a VAR state to its default value.";
    amm:parameter target {
      description
        "The VAR object to affect.";
      amm:type "/ARITYPE/VAR";
    }
  }
  amm:ctrl var-store {
    amm:enum 8;
    description
      "Modify a VAR state to a specific value.";
    amm:parameter target {
      description
        "The VAR object to affect.";
      amm:type "/ARITYPE/VAR";
    }
    amm:parameter value {
      description
        "The exact value to store in the VAR.";
      amm:type "//ietf-amm/TYPEDEF/ANY";
    }
  }
  amm:typedef hellotyp {
    amm:enum 0;
    amm:union {
      amm:type "/ARITYPE/BYTE";
      amm:type "/ARITYPE/UINT";
    }
  }
  amm:edd typedef-list {
    amm:enum 10;
    description
      "A table of TYPEDEF within the agent.";
    uses obj-list-params;
    amm:tblt {
      amm:key "obj";
      amm:column obj {
        amm:type "/ARITYPE/TYPEDEF";
      }
    }
  }

  // Objects related to VAR handling
  amm:edd var-list {
    amm:enum 11;
    description
      "A table of VAR within the agent.";
    uses obj-list-params;
    amm:tblt {
      amm:key "obj";
      amm:column obj {
        amm:type "/ARITYPE/VAR";
      }
      amm:column type {
        amm:type "//ietf-amm/TYPEDEF/TYPE-REF";
      }
    }
  }
  amm:ctrl ensure-var {
    amm:enum 9;
    description
      "Ensure a specific VAR is present.";
    amm:parameter obj {
      description
        "A reference to a VAR within an ODM only.";
      amm:type "/ARITYPE/VAR";
    }
    amm:parameter type {
      description
        "The type for the VAR object.";
      amm:type "//ietf-amm/TYPEDEF/TYPE-REF";
    }
    amm:parameter init {
      description
        "An optional initializer expression.";
      amm:default "null";
      amm:union {
        amm:type "/ARITYPE/NULL";
        amm:type "//ietf-amm/TYPEDEF/EXPR";
      }
    }
  }
  amm:ctrl discard-var {
    amm:enum 10;
    description
      "Discard a specific VAR if it is present.";
    amm:parameter obj {
      description
        "A reference to a VAR within an ODM only.";
      amm:type "/ARITYPE/VAR";
    }
  }

  // Objects related to SBR handling
  amm:edd sbr-list {
    if-feature "rules";
    amm:enum 12;
    amm:tblt {
      amm:key "obj";
      amm:column obj {
        amm:type "/ARITYPE/SBR";
      }
      amm:column action {
        description
          "The execution when this rule triggers.";
        amm:type "//ietf-amm/TYPEDEF/MAC";
      }
      amm:column start-time {
        amm:type "//ietf-amm/TYPEDEF/TIME";
      }
      amm:column condition {
        amm:type "//ietf-amm/TYPEDEF/EXPR";
      }
      amm:column min-interval {
        amm:type "/ARITYPE/TD";
      }
      amm:column max-count {
        amm:type "/ARITYPE/UVAST";
      }
    }
  }
  amm:edd tbr-list {
    if-feature "rules";
    amm:enum 13;
    amm:tblt {
      amm:key "obj";
      amm:column obj {
        amm:type "/ARITYPE/TBR";
      }
      amm:column action {
        description
          "The execution when this rule triggers.";
        amm:type "//ietf-amm/TYPEDEF/MAC";
      }
      amm:column start-time {
        amm:type "//ietf-amm/TYPEDEF/TIME";
      }
      amm:column period {
        amm:type "/ARITYPE/TD";
      }
      amm:column max-count {
        amm:type "/ARITYPE/UVAST";
      }
    }
  }

  // Numeric operators
  amm:oper negate {
    amm:enum 0;
    description
      "Negate a value.
       This is equivalent to multiplying by -1 but a shorter
       expression.";
    uses numeric-unary-operands;
    uses numeric-unary-result;
  }
  amm:oper add {
    amm:enum 1;
    description
      "Add two numeric values.
       The operands are cast to the least compatible numeric type
       before the arithmetic.";
    uses numeric-binary-operands;
    uses numeric-unary-result;
  }
  amm:oper sub {
    amm:enum 2;
    uses numeric-binary-operands;
    uses numeric-unary-result;
  }
  amm:oper multiply {
    amm:enum 3;
    uses numeric-binary-operands;
    uses numeric-unary-result;
  }
  amm:oper divide {
    amm:enum 4;
    uses numeric-binary-operands;
    uses numeric-unary-result;
  }
  amm:oper remainder {
    amm:enum 5;
    uses numeric-binary-operands;
    uses numeric-unary-result;
  }

  // Bitwise operators
  amm:oper bit-not {
    amm:enum 6;
    uses integer-unary-operands;
    uses integer-unary-result;
  }
  amm:oper bit-and {
    amm:enum 7;
    uses integer-binary-operands;
    uses integer-unary-result;
  }
  amm:oper bit-or {
    amm:enum 8;
    uses integer-binary-operands;
    uses integer-unary-result;
  }
  amm:oper bit-xor {
    amm:enum 9;
    uses integer-binary-operands;
    uses integer-unary-result;
  }

  // Boolean operators
  amm:oper bool-not {
    amm:enum 10;
    uses bool-binary-operands;
    uses bool-unary-result;
  }
  amm:oper bool-and {
    amm:enum 11;
    uses bool-binary-operands;
    uses bool-unary-result;
  }
  amm:oper bool-or {
    amm:enum 12;
    uses bool-binary-operands;
    uses bool-unary-result;
  }
  amm:oper bool-xor {
    amm:enum 13;
    uses bool-binary-operands;
    uses bool-unary-result;
  }

  // Value comparison
  amm:oper compare-eq {
    amm:enum 14;
    uses any-binary-operands;
    uses bool-unary-result;
  }
  amm:oper compare-ne {
    amm:enum 15;
    uses any-binary-operands;
    uses bool-unary-result;
  }

  // Numeric comparison
  amm:oper compare-gt {
    amm:enum 16;
    description
      "Compare two numbers by value.
       The result is true if the left value is greater than the right.
       The operands are cast to the least compatible numeric type
       before the comparison.";
    uses numeric-binary-operands;
    uses bool-unary-result;
  }
  amm:oper compare-ge {
    amm:enum 17;
    description
      "Compare two numbers by value.
       The result is true if the left value is greater than or equal
       to the right.
       The operands are cast to the least compatible numeric type
       before the comparison.";
    uses numeric-binary-operands;
    uses bool-unary-result;
  }
  amm:oper compare-lt {
    amm:enum 18;
    description
      "Compare two operands by value.
       The result is true if the left value is less than the right.
       The operands are cast to the least compatible numeric type
       before the comparison.";
    uses numeric-binary-operands;
    uses bool-unary-result;
  }
  amm:oper compare-le {
    amm:enum 19;
    description
      "Compare two operands by value.
       The result is true if the left value is less than or
       equal to the right.
       The operands are cast to the least compatible numeric type
       before the comparison.";
    uses numeric-binary-operands;
    uses bool-unary-result;
  }

  // Table filtering
  amm:typedef column-id {
    amm:enum 1;
    description
      "Name or index of an individual column in a table.";
    amm:union {
      amm:type "/ARITYPE/UVAST";
      amm:type "/ARITYPE/TEXTSTR";
    }
  }
  amm:oper tbl-filter {
    amm:enum 20;
    description
      "Filter a table first by rows and then by columns.";
    amm:parameter row-match {
      description
        "A filter to match rows with specific cell contents.
         Each key is a column to compare and each value is an expression
         with LABEL values substituted by column names.";
      amm:ulist {
        amm:type "//ietf-amm/TYPEDEF/EXPR";
      }
    }
    amm:parameter columns {
      description
        "A filter to match rows with specific cell contents.
         Each key is a column to compare and each value is an expression
         with LABEL values substituted by column names.";
      amm:ulist {
        amm:type "./TYPEDEF/column-id";
      }
    }
    amm:operand in {
      description
        "Table to filter.";
      amm:type "/ARITYPE/TBL";
    }
    amm:result out {
      description
        "The filtered table.";
      amm:type "/ARITYPE/TBL";
    }
  }
}

<CODE ENDS>

Appendix D. ADM Module for DTNMA Agent Access Control Lists

The ADM module in this section implements the entities described in Appendix A of [I-D.ietf-dtn-amm].¶

<CODE BEGINS> file "ietf-dtnma-agent-acl.yang"
module ietf-dtnma-agent-acl {
  yang-version 1.1;
  namespace "ari://ietf-dtnma-agent-acl";
  prefix acl;

  import ietf-amm {
    prefix amm;
  }
  import ietf-dtnma-agent {
    prefix da;
  }

  organization
    "IETF Delay Tolerant Networking (DTN) Working Group";
  contact
    "WG Web: <http://tools.ietf.org/wg/dtn/>
     WG List: <mailto:[email protected]>

     Editor: Brian Sipos
             <mailto:[email protected]>";
  description
    "This module implements the DTN Management Architecture (DTNMA)
     Agent Access Control List (ACL) functionality.

     Copyright (c) 2024 IETF Trust and the persons identified as
     authors of the code.  All rights reserved.

     Redistribution and use in source and binary forms, with or
     without modification, is permitted pursuant to, and subject to
     the license terms contained in, the Revised BSD License set
     forth in Section 4.c of the IETF Trust's Legal Provisions
     Relating to IETF Documents
     (https://trustee.ietf.org/license-info).

     This version of this YANG module is part of RFC XXXX
     (https://www.rfc-editor.org/info/rfcXXXX); see the RFC itself
     for full legal notices.";
  reference
    "draft-ietf-dtn-adm-yang";

  revision 2024-07-03 {
    description
      "Updated for latest ADM document.";
    reference
      "draft-ietf-dtn-adm-yang";
  }
  revision 2023-12-12 {
    description
      "Initial version for latest AMM document";
    reference
      "draft-birrane-dtn-adm";
  }
  amm:enum 2;
  amm:typedef tag {
    amm:enum 0;
    description
      "Datatype for access control list tags";
    amm:type "./TYPEDEF/permissions";
  }
  amm:typedef permissions {
    amm:enum 1;
    amm:type "/ARITYPE/BYTE" {
      amm:int-labels {
        bit tag-read {
          position 0;
          description
            "Permission bit for Read";
        }
        bit tag-write {
          position 1;
          description
            "Permission bit for Write";
        }
        bit tag-execute {
          position 2;
          description
            "Permission bit for Execute/Evaluate";
        }
      }
    }
  }
  amm:typedef entry-id {
    amm:enum 2;
    description
      "The identifier for an entry in any access control table.";
    amm:type "/ARITYPE/UVAST";
  }
  amm:typedef optional-entry-id {
    amm:enum 3;
    description
      "An optional entry identifier (or a null value).";
    amm:union {
      amm:type "./TYPEDEF/entry-id";
      amm:type "/ARITYPE/null";
    }
  }
  amm:typedef result {
    amm:enum 4;
    amm:type "/ARITYPE/INT" {
      amm:int-labels {
        enum success {
          value 0;
          description
            "Execution was successful";
        }
        enum error-generic {
          value 1;
          description
            "Generic execution failure";
        }
        enum error-permission-denied {
          value 2;
          description
            "Manager does not have permission";
        }
      }
    }
  }

  // Default access permission
  amm:var default-access {
    amm:enum 1;
    description
      "The default permission for any object if no specific access are
       present in the ./EDD/access-list table.";
    amm:type "./TYPEDEF/tag";
  }

  // Access control table and modifier controls
  amm:edd access-list {
    amm:enum 2;
    description
      "List the current group--object access.";
    amm:tblt {
      amm:key "id";
      amm:column id {
        amm:type "./TYPEDEF/entry-id";
      }
      amm:column group {
        description
          "A cross-reference to the group getting access, or null to match all groups.";
        amm:type "./TYPEDEF/optional-entry-id";
      }
      amm:column object-pattern {
        description
          "A pattern for objects being accessed, which may match all objects.";
        amm:type "/ARITYPE/TEXTSTR";
      }
      amm:column tag {
        description
          "A pattern for objects being accessed, which may match all objects.";
        amm:type "./TYPEDEF/tag";
      }
    }
  }
  amm:ctrl ensure-access {
    amm:enum 3;
    description
      "Ensures that an access control permission is set for the given group and ARI pattern.";
    amm:parameter group {
      description
        "Identify the group being assigned the permission";
      amm:type "./TYPEDEF/optional-entry-id";
    }
    amm:parameter object-pattern {
      description
        "ARI pattern to determine which objects shall be assigned the permission";
      amm:type "/ARITYPE/TEXTSTR";
    }
    amm:parameter tag {
      description
        "Permission tag value to set";
      amm:default "0";
      amm:type "./TYPEDEF/tag";
    }
    amm:result error-code {
      description
        "If non-zero, an indicator of an error.";
      amm:type "./TYPEDEF/result";
    }
  }
  amm:ctrl discard-access {
    amm:enum 4;
    description
      "Discard any permissions for the given group and ARI pattern.";
    amm:parameter group {
      description
        "Identify the group";
      amm:type "./TYPEDEF/optional-entry-id";
    }
    amm:parameter object-pattern {
      description
        "ARI pattern";
      amm:type "/ARITYPE/TEXTSTR";
    }
    amm:result error-code {
      description
        "If non-zero, an indicator of an error.";
      amm:type "./TYPEDEF/result";
    }
  }

  //
  // Group management
  //
  amm:typedef transport-endpoint-pattern {
    amm:enum 5;
    amm:type "/ARITYPE/IDENT" {
      amm:base "//ietf-dtnma-agent/IDENT/transport-endpoint-pattern";
    }
  }
  amm:edd current-group-id {
    amm:enum 3;
    description
      "Get the group ID for the current execution context, which may be
       the implicit Agent group ID zero.";
    amm:type "./TYPEDEF/entry-id";
  }
  amm:edd group-list {
    amm:enum 4;
    description
      "Get the defined access control groups.";
    amm:tblt {
      amm:key "id";
      amm:column id {
        description
          "The unique identifier for a group.
           The agent itself has implicit group ID zero.";
        amm:type "./TYPEDEF/entry-id";
      }
      amm:column name {
        description
          "The human-friendly name of the group.";
        amm:type "/ARITYPE/TEXTSTR";
      }
      amm:column members {
        description
          "The list of members of the group, identified by matching transport endpoint.";
        amm:ulist {
          amm:type "./TYPEDEF/transport-endpoint-pattern";
        }
      }
    }
  }
  amm:ctrl ensure-group {
    amm:enum 5;
    description
      "Ensure that after the control completes a group exists with the given information";
    amm:parameter id {
      description
        "Uniquely identify the group";
      amm:type "./TYPEDEF/entry-id";
    }
    amm:parameter name {
      description
        "Name of the group";
      amm:type "/ARITYPE/TEXTSTR";
    }
    amm:result error-code {
      description
        "If non-zero, an indicator of an error.";
      amm:type "./TYPEDEF/result";
    }
  }
  amm:ctrl ensure-group-members {
    amm:enum 7;
    description
      "Ensure that the membership of a group has a specific set of endpoint patterns.";
    amm:parameter id {
      description
        "Uniquely identify the group";
      amm:type "./TYPEDEF/entry-id";
    }
    amm:parameter members {
      amm:ulist {
        amm:type "./TYPEDEF/transport-endpoint-pattern";
      }
    }
    amm:result error-code {
      description
        "If non-zero, an indicator of an error.";
      amm:type "./TYPEDEF/result";
    }
  }
  amm:ctrl discard-group {
    amm:enum 6;
    description
      "Discard any group with the given ID.";
    amm:parameter group {
      description
        "Uniquely identify the group";
      amm:type "./TYPEDEF/entry-id";
    }
    amm:result error-code {
      description
        "If non-zero, an indicator of an error.";
      amm:type "./TYPEDEF/result";
    }
  }
}

<CODE ENDS>

Appendix E. Examples

For the sake of adhering to the proper syntax for ARIs, all of the example reports are timestamped at 2023-01-01T00:00:00Z.¶

ari://dtnma-agent/CTRL/report_on(//example-adm/EDD/intvalue)

Executing that results in a report containing the following:¶

(
  //example-adm/EDD/intvalue,
  /TP/20230101T000000Z,
  /INT/10
)

If the produced value has a semantic type which is ambiguous within the EDD type, the report would instead contain:¶

(
  //example-adm/EDD/intvalue,
  /TP/20230101T000000Z,
  //example-adm/TYPEDEF/mycounter(/INT/10)
)

For a similar CONST that contains an RPTT value, the report would contain:¶

(
  ./EDD/intvalue,
  ./EDD/boolvalue
)

(
  //example-adm/CONST/report1,
  /TP/20230101T000000Z,
  /INT/10,
  /true
)

Authors' Addresses

Edward J. Birrane, III

The Johns Hopkins University Applied Physics Laboratory

11100 Johns Hopkins Rd.

Laurel, MD 20723

United States of America

Phone: +1 443 778 7423

Email: [email protected]

Brian Sipos

The Johns Hopkins University Applied Physics Laboratory

Email: [email protected]

Justin Ethier

The Johns Hopkins University Applied Physics Laboratory

Email: [email protected]