DTNMA Application Management Model (AMM) and Data Models

3.1.1. Literal Values

As defined in the DTNMA, Literal values are those whose value and identifier are equivalent. These are the most simple values in the AMM. For example, the literal "4" serves as both an identifier and a value.¶

Because the value of a Literal object serves as its identifier, there is no concept of a parent namespace or parameters. A literal can be completely identified by its data type and data value.¶

Literals have two layers of typing:¶

Literal Type:

This is the lower layer which defines the syntax of the literal value and bounds the domain of the value (e.g. a BOOL has two possible values, while an INT has a large domain of integers). There are a small number of literal types and they are managed with an IANA registry defined in Section 9.3 of [I-D.birrane-dtn-ari].¶

Semantic Type:

This is the higher layer which defines additional semantics to a value, such as a restricted domain of values or a human-friendly text unit or limits on the items of an ARI collection. Semantic types are defined within ADMs (see Section 3.3 and Section 3.4.2), so there can be an arbitrary number of them and they are managed outside of a central authority.¶

All literal values have a concrete and stand-alone representation independent of any ADM or ODM behavior in the form of an ARI (Section 3.1.3), but when represented as an ARI a value loses its semantic type.¶

3.1.2. Object Reference Values

Every object in the AMM is uniquely identifiable, regardless of whether the item is defined statically in an ADM or dynamically in an ODM. Object reference values are composed of four parts: a namespace, an object type, an object name, and object-specific optional parameters.¶

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

Two categories of namespaces available within the object reference value and the ARI syntax:¶

ADM Namespace:

These are defined, with text-name and enumeration, in an IANA registry of ADMs in Section 9.3 of [I-D.birrane-dtn-ari]. There is also a reservation of private-use code points for domain- and mission-specific ADMs. In ARI form, ADM namespaces are present as either their name or enumeration directly.¶

ODM Namespace:

These are defined, with text-name and enumeration, in an IANA registry of ODMs in Section 9.3 of [I-D.birrane-dtn-ari]. It is expected that most ODM use will be domain- and mission-specific. In ARI form, ODM namespaces are present as a "!" prefixed name or as a negative-value enumeration.¶

Object types, each with a text-name and enumeration, are defined in an IANA registry by Section 9.3 of [I-D.birrane-dtn-ari].¶

Object names are text strings and enumerations whose value is determined by the creator of the object. For those objects defined in an ADM, the structure of the object name is given in Section 3.4.1.¶

3.1.3. The Application Resource Identifier (ARI)

The Application Resource Identifier (ARI) is used to represent AMM values outside of an Agent or Manager (i.e. in messaging between them) and is defined in [I-D.birrane-dtn-ari]. Another function of the ARI is for diagnostic or configuration purposes within either Managers or Agents. It is important to make the distinction that within an AMM entity (Agent or Manager) the semantic type of a value is kept, but when exchanged via ARI the semantic type is lost. The AMM defines type compression and reconstruction rules in Section 6.12 to handle this.¶

3.2.1. Simple Types

Simple types are those which cannot be subdivided and represent an "atomic" value within the AMM type system. They correspond roughly with the CBOR primitive types Section 3.3 of [RFC8610]. The simple types are summarized in Table 3.¶

The following subsections discuss nuances in sub-groups of these simple types.¶

3.2.2. Containers

AMM objects, or parameters associated with those objects, often need to represent groups of related data or more complex nesting of data. These are the literal types for AMM value containers, which can only be present in a typed-literal ARI form.¶

The AMM defines three collection literal types (AC, AM, and TBL) and allows ADMs to combine these literal types with a complex pattern syntax to create semantic types constraining their contents (e.g., for macros and expressions in Section 4.2.3).¶

3.4.1. Common Object Fields

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

The metadata supported by the AMM for all objects is as follows:¶

Name:

An object name is a text string associated with the object, but does not constitute the sole identifier for the object. Names provide human-readable and/or user-friendly ways to refer to objects with the text form of an ARI. Each object definition SHALL contain a name field. An object's name SHALL NOT change between ADM revisions. Each name SHALL conform to the id-text ABNF symbol of Section 4 of [I-D.birrane-dtn-ari]. Within each namespace and object type, the name of an object SHALL be unique.¶

Enumeration:

An object enumeration is an integer associated with the object, which identifies the object just like its name. Object enumerations provide a stable and concise identifier for the binary encoded form of an ARI. Each object definition SHOULD contain an enumeration field. An object's enumeration SHALL NOT change between ADM revisions. When present, each enumeration SHALL be an unsigned integer value. Within each namespace and object type, the enumeration of an object SHALL be unique.¶

Status:

Each object definition MAY contain a status field. The valid status values of an object are the same as the valid status values for an ADM in Section 4.1.1. In the absence of a status field, the status of the object SHALL be considered the same as the status of the ADM which contains it.¶

Reference:

Each object definition MAY contain a reference field. A reference is a text string referring to a specification or other document which details the source or purpose of the object.¶

Description:

Each object definition MAY contain a description field. A description is a text string explaining the purpose or usage of the object in a human-readable format. There is no minimum or maximum size of description text for an object. The description serves as documentation for the object and SHOULD be the same regardless of how the object might be parameterized. For example, the description of a CTRL object should document the purpose of the CTRL in a way that is independent of the value of any particular parameter value passed to that CTRL.¶

Formal parameters define a method to customize an AMM object. When used by an object definition, it's formal Parameters SHALL be an ordered list of individual formal parameter definitions. Each formal parameter SHALL include type and name. Each formal parameter MAY include an optional default value. The application of default parameters and relationship of actual parameters (Section 3.1.2.1) to formal parameters is defined in Section 6.4.¶

3.4.2. Semantic Type Definition (TYPEDEF)

An ADM can define a semantic type definition (TYPEDEF) to give a name to a semantic type (Section 3.3). This TYPEDEF name can then be used as a type anywhere else in the same ADM or another one which imports it.¶

The definition of a TYPEDEF consists of the following:¶

Name, Enumeration, Status, Reference, Description:

As defined in Common Object Fields.¶

Type:

A TYPEDEF definition SHALL include the type being named, as described in Section 3.3. The type of a TYPEDEF is fixed and SHALL NOT change between ADM revisions. The type SHALL be either a union of other types or a restriction of or annotation upon another type.¶

As defined in this document, TYPEDEFs and semantic types can only be defined within an ADM. Future capability could allow the use of TYPEDEFs within ODMs.¶

3.4.3. Externally Defined Data (EDD)

Externally defined data (EDD) objects, as defined in the DTNMA, represent data values that are produced based on a source external to the Agent itself. The Value Production occurs at the moment the value is needed, by either an Evaluation or a Reporting. The actual value could come from outside of the Agent proper, or be derived from data outside of the Agent.¶

The value production of an EDD SHOULD be nilpotent and have no side-effects in the processor. This property is not enforced by the Agent but requires consideration of the ADM designers, see Section 8.¶

For values managed entirely within the Agent use a Variable (VAR) or for constant-values use a Constant (CONST). For complex tabular data, use an EDD with a type which produces an ARI Table (TBL).¶

The definition of an EDD consists of the following:¶

Name, Enumeration, Status, Reference, Description:

As defined in Common Object Fields.¶

Parameters:

An EDD definition MAY include ARI parameters to be used when the EDD is used to produce a value. Parameterized objects are discussed in Section 8. The parameters of an EDD are fixed and SHALL NOT change between ADM revisions.¶

Type:

An EDD definition SHALL include the type of the value produced by the object, as described in Section 3.3. The type of an EDD is fixed and SHALL NOT change between ADM revisions.¶

As defined in this document, EDDs can only be defined within an ADM. Future capability could allow the use of EDDs within ODMs.¶

3.4.4. Constant (CONST)

A Constant (CONST) represents a named literal value, but unlike an Externally Defined Data (EDD) or Variable (VAR) a CONST always produces the same value. Examples include common mathematical values such as PI or well-known time epochs such as the UNIX Epoch. A CONST typed to produce a simple value can be used within an expression (see Section 6.7), where the object is used to produce a value at the moment of evaluation. A CONST can also be typed to produce an EXPR value to evaluate, or MAC value to execute.¶

The definition of a CONST consists of the following:¶

Name, Enumeration, Status, Reference, Description:

As defined in Common Object Fields.¶

Type:

A CONST definition SHALL include the type of the value produced by the object, as described in Section 3.3. The type of a CONST is fixed and SHALL NOT change between ADM revisions.¶

Value:

A CONST definition SHALL include the literal value produced during evaluation.¶

As defined in this document, CONSTs can only be defined within an ADM. Allowing network operators to define constants dynamically means that a Constant could be defined, removed, and then re-defined at a later time with a different value, which defeats the purpose of having Constants. When adding new "fixed" values to an ODM, a Variable (VAR) MUST be used instead of a Constant.¶

3.4.5. Control (CTRL)

A Control (CTRL) represents a predefined function that can be executed on an Agent. Controls are not able to be defined as part of dynamic network configuration since their execution is typically part of the firmware or other implementation outside of the Agent proper.¶

The execution of a CTRL SHOULD be idempotent and have no effect if executed multiple times in sequence. This property is not enforced by the Agent but requires consideration of the ADM designers, see Section 8.¶

Controls can be executed in a "one shot" manner as part of messaging from a Manager to an Agent. Network operators that wish to autonomously execute functions on an Agent may use a State-Based Rule (SBR) or Time-Based Rule (TBR). When an execution involves the ordered sequence of controls, a Macro (MAC) SHOULD be used instead of a more fragile use of CTRL directly.¶

The definition of a CTRL consists of the following:¶

Name, Enumeration, Status, Reference, Description:

As defined in Common Object Fields.¶

Parameters:

A CTRL definition MAY include ARI parameters to be used when the CTRL is executed. Parameterized objects are discussed in Section 8.¶

Result:

A CTRL definition MAY include the definition of a result. The result SHALL have a name and a type. The result MAY have a default value. The result of a CTRL is separate from the execution status as being successful or failed.¶

As defined in this document, CTRLs can only be defined within an ADM. Future capability could allow the use of CTRLs within ODMs if there was some mechanism to bind a CTRL definition to some platform-specific execution specification (e.g., a command line sequence).¶

3.4.6. Operator (OPER)

An Operator (OPER) represents a user-defined, typically mathematical, function that operates within the evaluation of an Expression (EXPR). It is expected that operators are implemented in the firmware of an Agent.¶

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

The definition of an OPER consists of the following:¶

Name, Enumeration, Status, Reference, Description:

As defined in Common Object Fields.¶

Parameters:

An OPER definition MAY include ARI parameters to be used when the OPER is evaluated. Parameterized objects are discussed in Section 8. The parameters of an OPER are distinct from the operands from the expression stack.¶

Operands:

An OPER definition MAY include definitions of operand values to be popped from the expression stack when the OPER is evaluated. Each operand SHALL consist of a name, a type, and a cardinality. Any non-trivial OPER will have one or more operands. An OPER can have a non-fixed operand count which is based on a parameter value (e.g., an operator can average the top N values from the stack, where N is a parameter).¶

Result:

An OPER definition SHALL include definition of a result value to be pushed onto the expression stack after the OPER is evaluated. The result SHALL have a name and a type. The result SHALL NOT have a default value.¶

As defined in this document, OPERs can only be defined within an ADM. Future capability could allow the use of OPERs within ODMs if there was some mechanism to bind an OPER definition to some platform-specific evaluation specification.¶

3.4.7. State-Based Rule (SBR)

A State-Based Rule (SBR) is a form of autonomy in which the Agent performs an action upon the change of state to meet a specific condition. The execution model of the SBR is to evaluate the Condition (as often as necessary to handle changes in its expression evaluation) and when it evaluates to a truthy (Section 6.11.1) value and it has been no shorter than the Minimum Interval since the last execution, the Action is executed. When the Maximum Count of executions is reached the TBR is disabled. The execution occurs concurrently with any time processing and may take longer than the Minimum Interval, so it is possible that multiple executions are requested to overlap in time.¶

Each SBR has an enabled state to allow rules to be retained in an ADM or ODM but not enabled during Manager-controlled time periods or under certain Manager-desired conditions. See Section 4.3 for details about what SBR-related controls are in the Agent ADM.¶

The definition of an SBR consists of the following:¶

Name, Enumeration, Status, Reference, Description:

As defined in Common Object Fields.¶

Action:

An SBR definition SHALL include an action in the form of a Macro (MAC). When triggered, the action execution SHALL be executed in accordance with Section 6.6 in an execution context with no parameters.¶

Condition:

An SBR definition SHALL include a condition in the form of an Expression (EXPR). The condition SHALL be evaluated in accordance with Section 6.7 in an evaluation context with no parameters. The result of the condition SHALL be converted to a BOOL value after evaluation and used to determine when to execute the action of the SBR.¶

Minimum Interval:

An SBR definition SHALL include a minimum execution interval in the form of a non-negative TD value. The interval MAY be zero to indicate that there is no minimum. This is not a limit on the interval of evaluations of the condition. This value can be used to limit potentially high processing loads on an Agent.¶

Maximum Count:

An SBR definition SHALL include a maximum execution count in the form of a non-negative UVAST value. The count sentinel value zero SHALL be interpreted as having no maximum. This is not a limit on the number of evaluations of the condition.¶

Initial Enabled:

An SBR definition MAY include an initial value for its enabled state. If not provided, the initial enabled state SHALL be true.¶

3.4.8. Time-Based Rule (TBR)

A Time-Based Rule (TBR) is a form of autonomy in which the Agent performs an action at even intervals of time. The execution model of the TBR is to start a timer at the Start Time of the TBR ticking at an even Period; each time the timer expires the Action is executed. When the Maximum Count of executions is reached the TBR is disabled. The execution occurs concurrently with any time processing and may take longer than the TBR Period, so it is possible that multiple executions are requested to overlap in time.¶

Each TBR has an enabled state to allow rules to be retained in an ADM or ODM but not enabled during Manager-controlled time periods or under certain Manager-desired conditions. See Section 4.3 for details about what TBR-related controls are in the Base ADM.¶

The definition of a TBR consists of the following:¶

Name, Enumeration, Status, Reference, Description:

As defined in Common Object Fields.¶

Action:

A TBR definition SHALL include an action in the form of a Macro (MAC). When triggered, the action execution SHALL be executed in accordance with Section 6.6 in an execution context with no parameters.¶

Start Time:

A TBR definition SHALL include a start time in the form of a TIME (Section 4.2.2) value. A relative start time SHALL be interpreted relative to the absolute time at which the Agent is initialized (for ADM rules) or the rule is created (for ODM rules). The start time MAY be the relative time zero to indicate that the TBR is always active. This is not a limit on the interval of evaluations of the condition.¶

Period:

A TBR definition SHALL include a period in the form of a positive TD value. The period SHALL NOT be zero but any non-zero small period is valid.¶

Maximum Count:

A TBR definition SHALL include a maximum execution count in the form of a non-negative UVAST value. The count sentinel value zero SHALL be interpreted as having no maximum. This is not a limit on the number of evaluations of the condition.¶

Initial Enabled:

A TBR definition MAY include an initial value for its enabled state. If not provided, the initial enabled state SHALL be true.¶

3.4.9. Variable (VAR)

A Variable (VAR) is a stateful store of a value in an Agent. The evaluation of a VAR is similar to an EDD except that all the behavior of a VAR is entirely within an Agent, while the ultimate source of an EDD value is outside of the Agent. The evaluation of a VAR into a value SHALL be nilpotent and have no side-effects in the processor.¶

A VAR has an initializer, which is used at Agent initialization and to reset the VAR, but the VAR is otherwise stateful and will retain its last value between any actions which edit it.¶

The definition of a VAR consists of the following:¶

Name, Enumeration, Status, Reference, Description:

As defined in Common Object Fields.¶

Parameters:

A VAR definition MAY include ARI parameters to be used when the VAR is evaluated. Parameterized objects are discussed in Section 8. Parameters for a VAR are only meaningful when the VAR contains a value with actual parameters themselves containing a LABEL value.¶

Type:

An VAR definition SHALL include the data type of the value produced during evaluation, as described in Section 3.3. The type of a VAR is fixed and SHALL NOT change between ADM revisions.¶

Initializer:

An VAR definition MAY include an initializer in the form of an Expression (EXPR). The only times the initializer are evaluated are at Agent Initialization and when a CTRL is used to reset the state of the VAR.¶

4.1.1. ADM Metadata

This section explains the purposes of the metadata fields of an ADM, while the profile of Section 7 defines a syntax for how these fields fit into an ADM module.¶

Name:

Each ADM definition SHALL contain a name field. An ADM's name SHALL NOT change between ADM revisions. The name SHALL conform to the id-text ABNF symbol of Section 4 of [I-D.birrane-dtn-ari].¶

Enumeration:

An ADM enumeration is an integer associated with the object, which identifies the object just like its name. ADM enumerations provide a stable and concise identifier for the binary encoded form of an ARI. Each ADM definition SHALL contain an enumeration field. An ADM's enumeration SHALL NOT change between ADM revisions. The enumeration SHALL be an unsigned integer value.¶

Revision History:

Each ADM SHALL contain a history of dated revisions. At least one revision SHALL be present and mark the date at which the ADM was released for use. During development and testing an ADM need not have updated revisions, only when a release occurs should a revision be added.¶

Status:

Each ADM definition SHOULD contain a status field. The valid status value of an ADM SHALL be identical to the Status field of YANG Section 7.21.2 of [RFC7950]. In the absence of a status field, the status of the ADM SHALL be considered the same as the status of the ADM which contains it.¶

Reference:

Each ADM definition SHOULD contain a reference field. A reference is a text string referring to a specification or other document which details the source or purpose of the ADM.¶

Description:

Each ADM definition SHOULD contain a description field. A description is a text string explaining the purpose or usage of the ADM in a human-readable format.¶

Features:

Each ADM definition MAY contain a set of feature definitions, see Section 4.1.2 for details. Each feature SHALL have a name that is unique within the namespace of the ADM. Each name SHALL conform to the id-text ABNF symbol of Section 4 of [I-D.birrane-dtn-ari].¶

4.1.2. Features and Conformance

Following in the pattern of YANG features Section 5.6.2 of [RFC7950] and SMIv2 conformance groups [RFC2580], the AMM has the concept of ADM features and Agent conformance to those features. Each feature is a simple qualified name and each object in an ADM can be conditional on the conformance to a set of features.¶

4.2.1. Simple Semantic Types

The most basic use of a semantic type is to provide additional meaning to simple types. None of these types associates a unit with the value, which it is expected that a derived type or an anonymous type (at the point of use) would add for additional clarity.¶

These are summarized below:¶

counter32 and counter64:

An unsigned integer value with an arbitrary initial value which increments over time and wraps around the maximum value. These correspond with the same names defined in SMIv2 and YANG [RFC6021].¶

gauge32 and gauge64:

An integer value sampling some measurement which can increase or decrease arbitrarily over time. These correspond with the same names defined in SMIv2 and YANG [RFC6021].¶

timestamp:

An absolute time at which an event happened. This corresponds with the same name defined in SMIv2 and YANG [RFC6021].¶

4.2.2. Type Unions

All of the literal types defined in [I-D.birrane-dtn-ari] have a flat structure, with some types sharing the same CBOR primitive encoding but having the concept of a derived "base" of another type. In order to allow types to fit into a more logical taxonomy, the base ADM defines some specific semantic typedefs to group literal types. These groups are not a strict logical hierarchy and are intended only to simplify the effort of an ADM designer when choosing type signatures.¶

These are summarized below:¶

TYPE-REF:

The union of ARITYPE and TYPEDEF types.¶

INTEGER:

The union of BYTE, UINT, INT, UVAST, and VAST types.¶

FLOAT:

The union of REAL32 and REAL64 types.¶

NUMERIC:

The union of INTEGER and FLOAT types.¶

PRIMITIVE:

The union of NULL, BOOL, NUMERIC, TEXTSTR, and BYTESTR types.¶

TIME:

The union of TP and TD types.¶

SIMPLE:

The union of PRIMITIVE, and TIME types.¶

LITERAL:

The union of SIMPLE, LITTYPE, LABEL, CBOR, AC, and AM types. This matches all values that can be in a literal value ARI.¶

VALUE-OBJ:

The union of CONST-REF, EDD-REF, and VAR-REF reference types. This matches any reference to an object that can produce a value (Section 6.5).¶

NONCE:

The union of BYTESTR, UINT64, and NULL types. This is used to correlate Agent-Manager messages.¶

4.2.3. Expression (EXPR)

An Expression (EXPR) is an ordered collection of references to Operators or operands. An EXPR takes the form of a semantic typedef refining an AC to be a list of ARIs referencing OPERs, ARIs referencing evaluate-able objects (see Section 6.7), or literal value ARIs (with Simple Types). These operands and operators form a mathematical expression that is used to compute a resulting value.¶

The evaluation procedure of an EXPR is defined in Section 6.7. Expressions are used within an ADM for defining the initializer of a Variable (VAR) and for defining the condition of a State-Based Rule (SBR).¶

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

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

4.2.4. Macro (MAC)

A Macro (MAC) is an ordered collection of references to Controls or other Macros. A Macro takes the form of a semantic typedef refining an AC to be a list of ARIs referencing Controls or objects which produce other Macros.¶

The execution procedure of an MAC is defined in Section 6.6. Macros are used within an ADM for defining the action of a State-Based Rule (SBR) or Time-Based Rule (TBR).¶

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

4.2.5. Report Template (RPTT)

A Report Template (RPTT) is an ordered list of object references or expression values used as a source for generating items for report (Section 3.2.2.5) containers. A RPTT takes the form of a semantic typedef refining an AC to be a list of references to value-producing objects (VALUE-OBJ (Section 4.2.2)) or expressions (EXPR (Section 4.2.3)). An object which produces an RPTT can itself be parameterized so that the object flows down parameters as described in Section 3.1.2.1.¶

A RPTT can be viewed as a schema that defines how to generate and interpret a Report; they contain no direct values. RPTT values either defined in an ADM or configured between Managers and Agents in an ODM. Reports themselves are ephemeral and represented as ARI built-in type, not as part of the AMM object model. The procedure for reporting on a RPTT is defined in Section 6.8.1.¶

RPTT values SHOULD be used within a CONST where possible. RPTT values MAY be used within a VAR where necessary. This makes correlating a RPT value with its associated RPTT easier over time. Rather than having a VAR object's RPTT value changing over time, it is RECOMMENDED to deprecate earlier RPTT-producing CONST objects and create new objects.¶

4.2.6. Execution Target Type

A convenience typedef exec-tgt is defined to codify the type of values allowed to be used as input for an Execution (or within an Execution-Set (EXECSET) value) or produced by objects referenced as execution targets. The execution target type is defined to be either a direct CTRL reference, a direct MAC value, or a reference to a value-producing object which itself is typed as exec-tgt.¶

4.2.7. Evaluation Target Type

A convenience typedef eval-tgt is defined to codify the type of values allowed to be used as input for an Evaluation activity or produced by objects referenced as evaluation targets. The execution target type is defined to be either a direct SIMPLE value, a direct EXPR value, or a reference to a value-producing object which itself is typed as eval-tgt.¶

4.3.1. Agent State Introspection

The Agent ADM contains the following EDD objects used to introspect the Agent's state, all of which can change over time.¶

• The ADMs supported by the Agent, including the unique name and revision of each. By indicating specific revision and supported feature set, the contained objects in each ADM can be derived. Because of this, the ADM-contained objects do not require additional introspection.¶
• The set of SBRs and TBRs in the Agent's ODMs, along with controls to ensure a specific object is either present or absent. These are all conditioned on whether the Agent actually supports the built-in rule feature.¶
• The set of VARs in the Agent's ODMs, along with controls to ensure a specific object is either present or absent.¶

4.3.2. Basic Operators

TBD defining boolean, bitwise, and numeric operators¶

6.5.1. CONST and VAR Objects

Both CONST and VAR objects act as a store of a single literal value within the Agent. Formal parameters on either CONST or VAR objects are applicable only when the objects store a value which itself contains parameters with at least one LABEL type.¶

The value production for these objects takes the stored value from the object and augments it by label substitution based on the following:¶

1. The processor identifies all LABEL type within the stored value, descending into container (Section 3.2.2) contents and object reference parameter contents as necessary.¶
2. If any LABEL text is not present in the formal parameters of the value-producing object then this procedure stops and is considered failed.¶
3. For each LABEL value the corresponding actual parameter is not the undefined value, the LABEL value is replaced by the actual parameter.¶

This augmentation has no effect on the stored value, it occurs only in the produced value. It is valid both for an actual parameter to have no substitution occur with its value and for an undefined actual value not be sued in substitution.¶

6.5.2. EDD Objects

For EDD objects, the actual parameters are used by the underlying implementation to produce the value in an arbitrary way. The produced value is typically either a SIMPLE (Section 4.2.2) value or an ARI Table (Section 3.2.2.3).¶

The value production for these objects occurs outside of the Agent proper within an implementation of the EDD being produced from.¶

The context given to the implementation is the following:¶

Object Identity:

This gives visibility into the EDD value which was dereferenced during the production.¶

Actual Parameters:

The set of actual parameters used for the production.¶

Result Type and Storage:

The result of the production is placed here before completion.¶

The initial state of the Result Storage is the undefined value. It is an implementation matter and author consideration (Section 8) to enforce that the produced value is consistent with the type of the object.¶

6.6.1. Expanded MAC Values

The execution of an Macro (MAC) value after expansion is as follows:¶

1. The processor iterates through all items of the expanded MAC in order and performs the following:¶

   If the item is an CTRL-REF it is executed in accordance with Section 6.6.2. If the execution fails, this procedure stops and is considered failed.¶

   Otherwise the item is an expanded sub-macro and it is executed in accordance with this procedure.¶

An effect of this procedure is that if any referenced CTRL fails during execution the processing fails immediately and subsequent CTRLs or MACs are not executed.¶

6.6.2. CTRL Objects

This activity relies on an object reference value to have been dereferenced in accordance with Section 6.3 and its parameters handled in accordance with Section 6.4.¶

The execution of a Control (CTRL) object occurs outside of the Agent proper within an implementation of the CTRL behavior.¶

The context given to the implementation is the following:¶

Manager:

The manager which directly caused this execution, if available, is provided as context.¶

Object Identity:

This gives visibility into the CTRL value which was dereferenced during the execution.¶

Actual Parameters:

The set of actual parameters augmented for the execution.¶

Result Type and Storage:

The result of the execution is placed here before completion.¶

The initial state of the Result Storage is the null value.¶

If the execution fails, the result value SHALL be treated as the undefined value for the purposes of any subsequent reporting.¶

6.7.1. Expanded EXPR Values

The reduction of an Expression (EXPR) value after expansion is as follows:¶

1. Any sub-expressions are first reduced to their result values which are substituted back into the corresponding expression item. If any sub-evaluation fails this procedure stops and is considered failed. At this point the expression consists of only SIMPLE or ARITYPEvalues, the result value of sub-expression reduction, or dereferenced OPER or TYPEDEF objects.¶
2. An empty value stack is initialized for this reduction.¶

3. The expression is treated as a Reverse Polish Notation (RPN) sequence, where the following is performed on each item in the AC in sequence:¶

   If the item is an ARITYPE value or dereferenced OPER or TYPEDEF object it is evaluated in accordance with Section 6.7.4, Section 6.7.2 or Section 6.7.3 respectively. If the evaluation fails, this procedure stops and is considered failed.¶

   Otherwise, the item is pushed onto the stack.¶

4. After RPN processing if the value stack is empty or has more than one item, this procedure stops and is considered failed. Otherwise, the result of the evaluation is the single literal value in the stack.¶

One effect of this procedure is that if any referenced values cannot be produced the procedure fails before any OPER is evaluated. Another effect of this procedure is that if any referenced OPER fails during evaluation or any value production fails the EXPR processing fails immediately and subsequent OPER values, EXPR values, or VALUE-OBJ references are not evaluated.¶

6.7.2. OPER Objects

This procedure applies only during the evaluation of a containing expression (Section 6.7.1); an OPER cannot be evaluated in isolation.¶

The evaluation of an OBJECT value referencing a Operator (OPER) is as follows:¶

1. The processor verifies that the actual parameters, if any, are consistent with the formal parameter associated with the OPER being evaluated. If there is inconsistency, this procedure stops and is considered failed.¶

2. The processor passes the evaluation on to the underlying implementation of the OPER being evaluated.¶

   The context available to the implementation is the following:¶

   Object Identity:

   This gives visibility into the OBJECT value which was dereferenced during the evaluation.¶

   Parameters:

   The set of actual parameters augmented for the evaluation.¶

   Expression Stack:

   The operands are popped from this stack and the result is pushed here before completion.¶

If the evaluation procedure fails, the failure SHALL propagate up to any expression evaluation.¶

6.7.3. TYPEDEF Objects

This procedure applies only during the evaluation of a containing expanded expression; a TYPEDEF object cannot be evaluated in isolation. The evaluation of a TYPEDEF is handled similarly to a unary OPER but it occurs entirely within the Agent and does not rely on an object-specific implementation.¶

The evaluation of a TYPEDEF object is as follows:¶

1. If the TYPEDEF value itself has no parameters, the input value is popped from the stack. If the TYPEDEF value itself has one parameter, the input value is that parameter. If the TYPEDEF value itself has more than parameter, this procedure stops and is considered failed.¶
2. The result value is a type conversion (Section 6.11.3) on the input value. If the conversion fails this procedure stops and is considered failed.¶
3. The result value is pushed onto the stack.¶

6.7.4. ARITYPE Values

This procedure applies only during the evaluation of a containing expanded expression; an ARITYPE value cannot be evaluated in isolation. The evaluation of an ARITYPE is handled similarly to a TYPEDEF but with no possibility of a parameterized conversion.¶

The evaluation of an ARITYPE value is as follows:¶

1. The input value is popped from the stack.¶
2. The result value is a type conversion (Section 6.11) on the input value. If the conversion fails this procedure stops and is considered failed.¶
3. The result value is pushed onto the stack.¶

6.8.1. RPTT Values

The reporting on a Report Template (RPTT) value, which is structured as an AC, is as follows:¶

1. An empty item list is initialized for this template.¶

2. The processor iterates through all items of the AC, performing the following:¶

   If the item is an EXPR value it is replaced by the result of evaluation in accordance with Section 6.7. If the evaluation fails the undefined value is used as a substitute.¶

   Otherwise, if the item is a VALUE-OBJ it is replaced by the value produced in accordance with Section 6.5. If the production fails the undefined value is used as a substitute.¶

   Otherwise, the result of the production is the value appended to the item list.¶

Because this procedure acts on an RPTT value and not an object reference, the report itself cannot be assembled within this context. One effect of this procedure is that if any item of the RPTT cannot be reported on, the undefined value is used as a sentinel and the other report items are still generated.¶

6.8.2. Value-Producing Objects

This activity relies on an object reference value to have been dereferenced in accordance with Section 6.3 and its parameters handled in accordance with Section 6.4.¶

The reporting on an object producing a value of any type is as follows:¶

1. The value is produced from the object in accordance with Section 6.5. This step includes substitution of any LABEL parameters within the value.¶

2. If the value is an RPTT (Section 4.2.5) type, this value is used to generate an AC containing report items in accordance with Section 6.8.1. Should this be allowed? What is the end structure of sub-reports?¶

   Otherwise, the produced value is used as the single RPT item.¶

3. The report (Section 3.2.2.5) is produced by combining: the source ARI used for this procedure, the current timestamp, and the items generated in the previous step.¶

6.9.1. Execution-Set Aggregation

Managers SHOULD aggregate multiple Execution-Set (EXECSET) values associated with the same Agent and Correlator Nonce into a single Execution-Set. The aggregation MAY be based on a size limit (e.g., number of targets), time limit, or an event (e.g., network availability). This avoids the overhead of transport and processing multiple executions on the same Agent, and due to the requirements in Section 6.9.2 makes no difference to (lack of) guarantees in execution order.¶

6.9.2. Execution-Set Processing

An Agent SHALL process an Execution-Set through the independent Execution of each item in the target list. Execution order is not guaranteed and failures on one target do not affect other target, so targets MAY be executed in any order or concurrently. This is not the same behavior as the execution of a macro, where execution of items is ordered and a failure of any execution causes subsequent items to not be executed.¶

6.9.3. Reporting-Set Aggregation

Agents SHOULD aggregate multiple Reporting-Set (RPTSET) values associated with the same Manager and Correlator Nonce into a single Reporting-Set. The aggregation MAY be based on a size limit (e.g., number of reports or number of total report items), time limit, or an event (e.g., network availability or power-saving wake-up). This avoids the overhead of transport and processing multiple messages on a Manager and improves timestamp compression in the reports, but it does require that all of the items are associated with the same manager and nonce.¶

6.9.4. Reporting-Set Processing

A Manager SHALL process each report within a Reporting-Set independently. Failures in processing any one report do not affect other reports, so reports MAY be processed in any order or concurrently. After using a Report Template to correlate report items with source objects, a Manager SHALL treat each (timestamp, object, item value) tuple independently from its containing Reporting-Set or Report.¶

6.11.1. BOOL Type

The AMM has the concepts of "truthy" and "falsey" as being the result of casting to BOOL type. Similar to the ToBoolean() function from [ECMA-262], the AMM casting treats the following as falsey and every other value as truthy:¶

• undefined¶
• null value of NULL¶
• false value of BOOL¶
• Zero value of BYTE, UINT, INT, UVAST, and VAST¶
• Positive and negative zero, and NaN values of REAL32 and REAL64¶
• Empty value of TEXTSTR and BYTESTR¶

When casting a value to BOOL type, the processor SHALL use the result value false if the original value is falsey and true otherwise.¶

6.11.2. NUMERIC Types

The casting of a value to a NUMERIC type is intended to easily allow mixed-type expressions while keeping the number of operators and parameter unions small.¶

When casting a value to an INTEGER type from any other NUMERIC type, the processor SHALL perform the following:¶

1. If the input is one of the FLOAT types and is not finite, the conversion is considered failed.¶
2. If the input is one of the FLOAT types, the value is truncated to an integer by rounding toward zero.¶
3. If the input value is outside the domain of the output type, the conversion is considered failed.¶

When casting a value to an FLOAT type from any other NUMERIC type, the processor SHALL perform the following:¶

1. If the input value is outside the domain of the output type, the conversion is considered failed.¶

6.11.3. Semantic Types

Unlike literal type casting, which has the potential to change the form of the value itself, casting to a semantic type is meant to either affirm or add an association between an AMM value and a TYPEDEF object. All of this processing is performed independently of any literal-type-specific handling, so none of it needs to be specialized to specific TYPEDEF objects.¶

The conversion of an input value to a TYPEDEF is as follows:¶

1. The underlying literal types usable with a TYPEDEF are obtained by recursively flattening the TYPEDEF union(s) down to literal types and removing duplicate literal types after the first instance of them. This defines a priority list of acceptable literal types for the result. Because a TYPEDEF union is unchanging within an ADM (see Section 3.4.2) a processor MAY cache this flattened type list.¶
2. The input value is cast to each literal type in the list, and the first successful cast is taken as the literal type of the result value. If none of the literal types can successfully cast the input value, this procedure stops and is considered failed.¶
3. The result value is associated with the the TYPEDEF being cast to, and that is the result of this procedure.¶

7.1.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 Legacy modules, there will not be any cross-imports between the two ecosystems. There is no harm in including an ADM module in a Legacy 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 the other 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 other 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 Legacy 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.¶

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 Legacy 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.¶

7.1.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 (Section 3.1) model, 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 Legacy 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 a Legacy 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.¶

7.2.2. Type Uses

There are a number of extensions defined in Section 7.3 related to how AMM value types and type definitions are used by object definitions. These include the following purposes.¶

Simple Type Use:

The simplest case is where an existing type is used directly and unchanged. This is a "type" statement (Section 7.3.2.1) with no constraining substatements.¶

Simple Constraint:

Beyond the simple type use, constraints and annotations can be added to an existing type (either built-in or typedef). This is a "type" statement (Section 7.3.2.1) with substatements to constrain or annotate it.¶

Uniform List:

This is the case of a list of AMM values within an AC where the type of each value is uniform for the whole list. This is a "ulist" statement (Section 7.3.2.2) with substatements to establish the list contents.¶

Diverse List:

This is the case of a list of AMM values within an AC where the type of each value is different throughout the list. Some of the values can be repeated a fixed or variable number of times. This is a "dlist" statement (Section 7.3.2.3) with substatements to establish the list contents.¶

Uniform Map:

This is the case of a map of AMM values within an AM where the type of each key and each value is uniform for the whole map. This is a "umap" statement (Section 7.3.2.4) with substatements to establish types of the keys and values respectively.¶

Table Template:

This is the case of a list of AMM values within an AC where the values are interpreted as rows and columns of a table. The number of columns is fixed and the number of rows present in any particular table instance is variable (but possibly bounded by restriction). This is a "tblt" statement (Section 7.3.2.5) with substatements to establish the column schema, uniqueness criteria, sorting, and size constraints.¶

Type Union:

This creates a choice between a combination of other type uses. Each of the type uses in a union SHOULD be exclusive to avoid ambiguity in interpretation by a value processor. This is a "union" statement (Section 7.3.2.6) with substatements to establish the type uses being combined.¶

Sequence:

This creates a subset of a diverse list which matches multiple sequential elements of the list. This is a "seq" statement (Section 7.3.2.7) with substatements to establish the sequence contents.¶

7.2.3. Type Definitions

A type definition is a way for an ADM to apply a name and descriptive metadata to a specific type use (see Section 7.2.2). The type definition (TYPEDEF) is also a top-level ADM object, as explained in Section 3.4.2 with a syntax in Section 7.3.4.¶

An imported module "prefix" and object name of a TYPEDEF can be used wherever a type name is needed by one of the type uses. The syntax for this is the same as for YANG types and uses, where the prefix and typedef name are joined by a colon (":"). For example, importing a module with a prefix of "mod" containing a typedef "mytype" is used by the type name:¶

mod:mytype

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

7.3.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.birrane-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.¶

7.3.2. Type Use Statements

The statements within this section enable the various type uses as explained in Section 7.2.2. 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 type use statements.¶

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

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

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;
  }
}

amm:umap {
  amm:keys {
    amm:type uint;
  }
  description "restrict only keys";
}
amm:umap {
  amm:keys {
    amm:type uint;
  }
  amm:values {
    amm:type textstr;
  }
}

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

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;
}

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

7.3.4. The amm:typedef Statement

This statement is used to define a Semantic Type Definition (TYPEDEF) object. The argument to this statement is the name of the AMM object.¶

The substatements under this are a choice of the type use (see Section 7.2.2) being named by the typedef.¶

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";
  }