DTNMA Application Data Model

DTNMA Application Data Model The Johns Hopkins University Applied Physics Laboratory

11100 Johns Hopkins Rd. Laurel MD 20723 US +1 443 778 7423 Edward.Birrane@jhuapl.edu

The Johns Hopkins University Applied Physics Laboratory

David.Linko@jhuapl.edu

The Johns Hopkins University Applied Physics Laboratory

brian.sipos+ietf@gmail.com

Transport Delay-Tolerant Networking DTN Network Management Autonomy This document defines a data model that captures the information necessary to asynchronously manage applications. This model provides a set of common type definitions, data structures, and a template for publishing standardized representations of model elements.

Introduction The DTN Management Architecture (DTNMA) defines a concept for the open-loop control of applications (and protocols) in situations where timely, highly-available connections cannot exist among managing and managed nodes in a network. While the DTNMA provides a conceptual information model, it does not include details necessary to produce interoperable data models.

Scope This document defines a two-level data model suitable for managing applications in accordance with the DTNMA. The two levels of model are:

A meta-model for the DTNMA, called the Application Management Model (AMM), which defines the object structures and literal-value types used in the DTNMA in a concrete way.
An object model, based on the AMM meta-model, which is used in static Application Data Models (ADMs) and dynamic Operational Data Models (ODMs) as instances of the AMM within an Agent.

This document also defines a text representation of an ADM using the types and structures defined by the AMM combined with the syntax and processing semantics of YANG modules . With this representation, individual applications can capture their static management information in YANG modules. Although this document defines a representation for the ADM, it does not define a representation for the objects and literal values modeled by the ADM/ODM. In order to communicate values between DTNMA Agents and Managers in a network, the model must be encoded for transmission. Any such encoding scheme is outside of the scope of this document. Generally, the encoding of the model is a separate concern from the specification of data within the model. Because different networks may use different encodings for data, mandating an encoding format would require incompatible networks to encapsulate data in ways that could introduce inefficiency and obfuscation. It is envisioned that different networks would be able to encode values in their native encodings such that the translation of ADM data from one encoding to another can be completed using mechanical action taken at network borders. Since the specification does not mandate an encoding format, the AMM and ADM must provide enough information to make encoding (and translating from one encoding to another) an unambiguous process. Therefore, where necessary, this document provides identification, enumeration and other schemes that ensure ADMs contain enough information to prevent ambiguities caused by different encoding schemes.

Terminology The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in . The terms "Actor", "Agent", "Externally Defined Data", "Variable", "Constant", Control", "Literal", "Macro", "Manager", "Operator", "Report", "Report Template", "Rule", "State-Based Rule", "Table", "Table Template", and "Time-Based Rule" are used without modification from the definitions provided in . Additional terms defined in this document are as follows.

Application:: A software implementation running on an Agent and being managed by a Manager. This includes software that implements protocol processing on an Agent.
Application Management Model (AMM):: The object and literal-value model defined by this document in and implemented as instances in ADMs and ODMs.
Application Resource Identifier (ARI):: A unique identifier for any AMM object and literal value, syntactically conformant to the Uniform Resource Identifier (URI) syntax documented in and using the scheme name "ari".
Application Data Model (ADM):: The set of statically-defined objects necessary to manage an application asynchronously. This is also the name for the text-based syntax used to express the contents of that ADM, as defined in .
Operational Data Model (ODM):: The set of dynamically-defined objects created and controlled by Managers in the network.
Namespace:: Each ADM and ODM has a universally unique identifier and acts as a namespace for a set of AMM objects.

Data Modeling Concept of Operations In order to asynchronously manage an application in accordance with the , an application-specific data model must be created containing static structure for that application. This model is termed the Application Data Model (ADM) and forms the core set of information for that application in whichever network it is deployed. ADM structure and base ADMs are discussed in detail in . The objects codified in the ADM represents static configurations and definitions that apply to any deployment of the application, regardless of the network in which it is operating. Within any given network, Managers supplement the information provided by ADMs with dynamic objects. Each namespace of dynamic objects is termed an Operational Data Model (ODM) and is discussed in detail in . Both the ADMs and ODMs rely on a common meta-model, the Application Management Model of , which defines the basic structure of what kinds of types and objects are available to use within the DTNMA. The relationships among the AMM, ADM, and ODM are illustrated in . Together, the set of objects in the union of all supported ADMs with dynamic ODM objects forms the data model used to manage an Agent. While an agent hosts the actual object instances, each manager must contain the corresponding ADM and ODM definitions in order to identify and interact with those objects. Those interactions are performed using Application Resource Identifiers (ARIs) as depicted in .

Data Model Relationships +---------------+ | AMM | | (object types)| +-------^-------+ | +-------+-------+ | | +-----+-----+ +-----+-----+ | ADM | | ODM | |(instances)| |(instances)| +-----------+ +-----------+

Agent and Manager Interaction +------------------------------------------+ | | | +-------+ +-------+ +-------+ | | | ADM 1 | | ADM 2 | | ODM 1 | | | | def'n | | def'n | | def'n | |' | +-------+ +-------+ +-------+ | | ... ... | | +-------+ +-------+ | | | ADM N | | ODM M | | | | def'n | | def'n | | | +-------+ +-------+ | | Manager instance | +------------------------------------------+ ^^ || ARI values || vv +------------------------------------------+ | | | +-------+ +-------+ +-------+ | | | ADM 1 | | ADM 2 | | ODM 1 | | | | objs | | objs | | objs | | | +-------+ +-------+ +-------+ | | ... ... | | +-------+ +-------+ | | | ADM N | | ODM M | | | | objs | | objs | | | +-------+ +-------+ | | Agent instance | +------------------------------------------+

Values and Value-Producing Objects The ARI of is used as the basis for the values used internally for activities and for the basis of contents. Of the value-producing object types discussed in and , the functions of these objects are summarized and compared with literals in and the following list. In that table, "internal" means values are managed by the Agent itself and "external" means the source of values is outside the Agent.

:: ARI literals are, by definition, immutable and fully self-contained values. For example, the number 4 is a literal value. The name "4" and the value 4 represent the same thing and are inseparable. Literal values cannot change ("4" could not be used to mean 5) and they are defined external to the autonomy model (the autonomy model is not expected to redefine what 4 means).
:: These objects are named values which are defined in specific revisions of an ADM and produced directly by the Agent implementing the ADM. Both the name and the value of the constant are fixed and cannot be changed (within a revision). An example of a constant would be defining the numerical value pi to some predetermined precision.
:: These objects are named value storage entities which are defined in ADMs or ODMs and managed by the Agent implementing the ADM or ODM. While the name is constant the value can change over time due to controls acting upon the Agent. One standard interface is an ADM-defined initial state expression with a control available to reset to that initial state (which can itself reference other value producing objects and operators). Another standard interface is a control to set a variable to a specific value. An example of a variable using just its initial expression would be an accumulator summing together a list of counter values produced by other objects. An example of a manager-controlled variable would be a threshold value used to compare against a sensor value in a rule predicate.
:: These objects are named entities which are defined in an ADM but produce values based on data provided to an Agent from its environment. These values are the foundation of state-based autonomy as they capture the state of the managed device. The autonomy model treats these values as read-only state. It is an implementation matter to determine how external data is transformed into values of the specific type specified for an EDD. Examples of externally defined values include temperature sensor readings and the instantaneous data rate from a modem or radio.

Value-Producing Object Types

	Immutable	Mutable
Internal	CONST	VAR
External	LIT	EDD

Agent Processing Based on the reasoning described in , much of the closed-loop processing of the state of the DTNMA Agent is performed on the Agent itself using rule objects. The different types of processing performed on the Agent are separated into , , and with corresponding AMM object types related to each of these as indicated in (e.g., execution relates to CTRL objects but not OPER objects). Some of the objects defined in the Agent ADM combine the use of these processing activities, but they are still independent of each other. There is no mixing of activities such as executing a control within an expression; although the execution of a control can result in an expression being evaluated they are independent activities. Within the runtime of an Agent any input, output, and intermediate values can use the concept of a semantic type to do things like restrict the valid numeric range of a value or allow a union of disjoint types to be present (e.g., a certain value can be a boolean or an unsigned integer). This is combined with the literal types available from the ARI to allow complex type information to be present in an ADM or ODM without requiring additional over-the-wire encoding size. A activity is defined for when implicit or explicit type conversion is needed. Processing Activities and Object Types

Activity	Objects	Values
Execution	CTRL	MAC
Evaluation	OPER, TYPEDEF	EXPR
Reporting	N/A	RPTT
Value Production	CONST, EDD, VAR	N/A
Type Casting	TYPEDEF	N/A
Rule Autonomy	SBR, TBR	N/A

Agent-Manager Messaging This document does not define a messaging protocol between agents and managers but full functioning of this data model behavior does rely on the following types of messages being available:

Execute:: This message causes an of a referenced parameterized CTRL object or produced MAC value. This type of message is only sent from Manager to Agent. An optional field of this message is an opaque correlator "nonce" which can be used to indicate that the result of the corresponding CTRL execution is desired to be reported back to the Manager. Each message can reference multiple execution sources (CTRL and MAC) and, unlike the MAC execution itself, can be handled by executing multiple items in parallel. It is an implementation detail whether a Manager sends fewer messages with more sources or more timely messages with fewer sources.
Report:: This message carries the RPT values generated by activities. This type of message is only sent from Agent to Manager. One field of the report message is a correlator nonce which is used to associate report items with specific Execute messages which caused the reports to be generated. Each message can contain multiple RPT values but all must be associated with the same nonce, although it is an implementation detail whether an Agent sends fewer report messages with more report values or more timely messages with fewer values.

The contents of these messages, individual fields, are representable by ARI values so require only small additional message-type identifying and framing overhead to bind to whatever transport is being used (e.g. the Bundle Protocol).

Application Management Model (AMM) This section describes the Application Management Model, which is the meta-model used to implement the DTNMA. This section also provides additional information necessary to work with this model, such as: literal value types, object structure, naming conventions, and processing semantics. The overall AMM is decomposed into two categories:

Objects:: These are the structural and behavioral elements of the AMM, present in ADMs and ODMs. Objects implement the actual purpose of the applications being managed; they extract values from the Agent's environment, operate on expressions, store variables, and execute controls to affect the Agent's environment. Because objects are behavioral they have no complete static representation, objects are only ever described and identified. AMM object types are defined in and objects are instantiated as part of an ADM or ODM.
Values:: These are the runtime state and intermediates of the AMM, present in the Agent's state but not directly in ADMs or ODMs. Objects produce, operate on, and store or consume values and these values are what are present in messaging between Managers and Agents. AMM values are explained in more detail in .

AMM Values Values within the AMM have two top-level classes: literal values, and object references. Each of these is discussed more detail in the following subsections. Both classes of AMM values are related to what can be represented externally as an ARI, as described in .

Literal (LIT) As defined in the DTNMA, Literal (LIT) 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 .
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 and ), 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, but when represented as an ARI a value loses its semantic type.

Object Reference (OBJ-REF) 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 OBJ-REF and the ARI syntax:

ADM Namespace:: These are defined, with text-name and enumeration, in an IANA registry of ADMs in . 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 . 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 . 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 .

Parameters Parameterization is used in the AMM to enable expressive autonomous function and reduce the amount of traffic communicated between Managers and Agents. In the AMM, most objects can be parameterized and the meaning of parameterization for each object type is defined in with behaviors related to parameters defined in . There are two notions of parameters defined in the AMM, which take their name from computer programming vernacular used for discussing function declarations and function calls, those are: formal parameters and actual parameters. Formal parameters are discussed in and actual parameters are discussed here in relation to the object reference. Actual parameters represent the data values passed to a parameterized AMM Object at runtime. They "fulfill" the parameter requirements defined by the formal parameters for that object. Each object type can have a slightly different notion of how its parameters affect its processing activities. An actual parameter MUST specify a value and MAY specify a type. If a type is provided it MUST match the type provided by the formal parameter. There are two ways in which the value of an actual parameter can be used:

Parameter by Value:: This method involves directly supplying the value as part of the actual parameter. It is the most direct method for supplying values.
Parameter by Label:: This method involves supplying the LABEL of some other processing-context-specific value and substituting, at runtime, that named value as the value of this parameter. This method is useful when a parameterized AMM Object contains a value that references another parameterized AMM Object. The contained object's actual parameter can be given as the LABEL of the containing object's parameter. In this way, a containing object's parameters can "flow down" to all of the objects it references.

In cases where a formal parameter contains a default value, the associated actual parameter may be omitted. Default values in formal parameters (and, thus, optional actual parameters) are encouraged as they reduce the size of data items communicated between Managers and Agents in a network.

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 . 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 to handle this.

Literal Types This section describes the literal type definitions used by the AMM. By definition, literal values are self-contained and literal types restrict the form and function of those values. All literal types within the AMM exit within a flat namespace, but some types have complex relationships with other types beyond the "is a" concept of type inheritance. Types are defined within an IANA registry by and explained in this section. The following subsections divide the types into groups to simplify their explanation, not because of an intrinsic relationship within each group.

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 . The simple types are summarized in . Simple Literal Types

Type	Description
`NULL`	The singleton `null` value.
`BOOL`	A native boolean `true` or `false` value.
`BYTE`	An 8-bit unsigned integer.
`INT`	A 32-bit signed integer.
`UINT`	A 32-bit unsigned integer.
`VAST`	A 64-bit signed integer.
`UVAST`	A 64-bit unsigned integer.
`REAL32`	A 32-bit floating point number.
`REAL64`	A 64-bit floating point number.
`TEXTSTR`	A text string composed of (unicode) characters.
`BYTESTR`	A byte string composed of 8-bit values.
`TP`	An absolute time point (TP).
`TD`	A relative time difference (TD) with a sign.
`LABEL`	A text label of a parent object parameter. This is only valid in a nested parameterized ARI.
`CBOR`	A byte string containing an encoded CBOR item. The structure is opaque to the Agent but guaranteed well-formed for the ADM using it.
`LITTYPE`	An integer value representing one of the code points in this Literal Types table.

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

Discrete Value Types The NULL and BOOL types are used to limit to specific discrete values. Because there are CBOR primitive types corresponding exactly with these AMM types, generators of ARIs with these types can always be compressed by eliding the literal type as defined in . The NULL type has only a single value, null, which is not useful for expressions or type casting but is useful for defining union types which have "optional value" semantics where the null value is used to indicate the absence of a normal value. The BOOL type is useful for type casting where an arbitrary value is treated as "truthy" or "falsey" in a context such as a condition.

Numeric Types All of the numeric types (BYTE, UINT, INT, UVAST, VAST, REAL32, and REAL64) exist within a domain where values can be cast between types (). Some cases of implicit casting is done for type promotion as necessary for arithmetic operations.

Absolute (TP) and Relative (TD) Time Types The TP type represents an instant in time in the UTC datum. When in text form it is formatted in accordance with the date-time symbol of and always in the "Z" time-offset. The TD type represents an offset in time from a relative epoch instant, either later than (a positive offset) or earlier than (a negative offset). When in text form it is formatted in accordance with the duration symbol of with a positive or negative sign prefix. The epoch instant of a relative time MUST be unambiguously defined in the context using the time value.

Collections 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 collections, which can only be present in a typed-literal ARI form. The AMM defines two collection literal types, AC and AM, 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 ).

ARI Collection (AC) An ARI Collection (AC) is an ordered list of ARIs. ACs are used when there exists a need to refer to multiple AMM objects as a single unit. For example, when defining a Report Template, the definition has an AC that defines the ordered ARIs whose values constitute that report.

ARI Map (AM) An ARI Map (AM) is a mapping from a set of literal-value "key" ARI to arbitrary-valued "value" ARI. TBD

Custom Literal Types When an application requires a more complex or specialized literal type than one already available the preferred design procedure is as follows:

If an existing ADM already defines a semantic typedef (see ) it is RECOMMENDED to import that ADM and use its typedef.
Otherwise, when it is possible to use an ADM-defined semantic typedef to achieve the desired goals it is RECOMMENDED to do so.
Otherwise, when the desired behavior cannot be accomplished by a semantic typedef, it is RECOMMENDED to use the opaque CBOR type with interface documentation to explain the syntax of the encoded CBOR item.
Otherwise, the application MAY make use of the private-use block of literal type code points.

Implementing a custom literal type requires implementation effort on both an Agent and its associated Manager(s) as well as being more opaque to diagnostic tools and middleboxes.

Semantic Types While literal types control the basic syntax and domain of AMM values, the concept of semantic type is to provide a means to augment literal types by expanding (via union), narrowing (via restrictions), and adding human-friendly attributes. Semantic types can be defined in two ways: a named or an anonymous type. Because this document defines the ADM syntax as an extension of YANG module syntax, the pre-existing type statement logic from YANG is used in the AMM. When a "type" is needed for an AMM value in an object definition it SHALL be either one of the literal types, a namespace-qualified semantic type, or an anonymous semantic type just for that value.

AMM Objects This section identifies the types of objects that make up the AMM and which are instantiated within each ADM and ODM. Each object type is defined by its logical structure and its behavior in "execution" and "evaluation" contexts within Agents. Each type can allow or disallow parameters within objects and, due to processing behaviors, can either allow or disallow use within an ADM or ODM. Unless explicitly specified in the object type subsection, an object SHALL NOT be parameterized.

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 . 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 . 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 to formal parameters is defined in .

Semantic Type Definition (TYPEDEF) An ADM can define a semantic type definition (TYPEDEF) to give a name to a semantic type. 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 .
Type:: A TYPEDEF definition SHALL include the type being named, as described in . The type of a TYPEDEF is fixed and SHALL NOT change between ADM revisions. Because this document defines the ADM syntax as an extension of YANG module, the pre-existing typedef syntax and logic from YANG is used.

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.

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 occurs at the moment the value is needed, by either an or a . 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 . For values managed entirely within the Agent use a or for constant-values use a . For complex tabular data, use an EDD with a type which produces a . The definition of an EDD consists of the following:

Name, Enumeration, Status, Reference, Description:: As defined in .
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 . 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 . 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.

Constant (CONST) A Constant (CONST) represents a named literal value, but unlike an or 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 ), 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 .
Type:: A CONST definition SHALL include the type of the value produced by the object, as described in . 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 MUST be used instead of a Constant.

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 . 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 or . When an execution involves the ordered sequence of controls, a SHOULD be used instead of a more fragile use of CTRL directly. The definition of a CONST consists of the following:

Name, Enumeration, Status, Reference, Description:: As defined in .
Parameters:: A CTRL definition MAY include ARI parameters to be used when the CTRL is executed. Parameterized objects are discussed in .
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).

Operator (OPER) An Operator (OPER) represents a user-defined, typically mathematical, function that operates within the evaluation of an . 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 .
Parameters:: An OPER definition MAY include ARI parameters to be used when the OPER is evaluated. Parameterized objects are discussed in . 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.

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 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 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 .
Action:: An SBR definition SHALL include an action in the form of a . When triggered, the action execution SHALL be executed in accordance with in an execution context with no parameters.
Condition:: An SBR definition SHALL include a condition in the form of an . The condition SHALL be evaluated in accordance with in an evaluation context with no parameters. The result of the condition SHALL be cast 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.

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 for details about what TBR-related controls are in the Base ADM. The definition of an SBR consists of the following:

Name, Enumeration, Status, Reference, Description:: As defined in .
Action:: An SBR definition SHALL include an action in the form of a . When triggered, the action execution SHALL be executed in accordance with in an execution context with no parameters.
Start Time:: An SBR definition SHALL include a start time in the form of a TIME 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.

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 .
Parameters:: A VAR definition MAY include ARI parameters to be used when the VAR is evaluated. Parameterized objects are discussed in . 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 . 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 . The only times the initializer are evaluated are at and when a CTRL is used to reset the state of the VAR.

Application Data Models (ADMs) An ADM is a logical entity for defining static AMM object instances, which are discussed in detail in . Each ADM exists as a separate namespace for its contained objects, but allows importing object names from other ADMs to reuse them. Each Agent can support any number of ADMs at one time (subject to implementation limitations) and each Manager can operate with ADMs of different revisions to support diverse Agents. The following subsections define what is present in an ADM generally and what objects necessary to operate a DTNMA Agent are present in two base ADMs.

ADM Definitions An ADM is "static" in the sense that it is revision-controlled and a released revision of an ADM does not change. Besides AMM object definitions there are metadata and handling rules for the ADM itself, which are discussed in this section.

ADM Metadata This section explains the purposes of the metadata fields of an ADM, while the profile of defines a syntax for how these fields fit into a YANG 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 .
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 . 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 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 .

Features and Conformance Following in the pattern of YANG features and SMIv2 conformance groups , 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.

Contents of an DTNMA ADM The base DTNMA ADM is a necessary part of the AMM typing, execution, and evaluation models. Rather than having some Agent logic defined purely by specification, this document uses a base ADM to define semantic types and controls needed for normal Agent operations. The needed types are still set by specification and are unchanging within an ADM revision, but this avoids having a separate, intermediate typing system between the AMM-defined semantic types and the ARI-defined literal types. This is also in-line with how the SMIv2 and NETCONF/YANG both rely on base modules for some core behavior.

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 .
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 .
timestamp:: An absolute time at which an event happened. This corresponds with the same name defined in SMIv2 and YANG .

Type Unions All of the literal types defined in 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 LITTYPE and TYPEDEF-REF 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 NONE, 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-REF:: The union of CONST-REF, EDD-REF, and VAR-REF reference types. This matches any reference to an object that can produce a value.

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 ), or literal value ARIs (with ). 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 . Expressions are used within an ADM for defining the initializer of a and for defining the condition of a . 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 * *.

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 . Macros are used within an ADM for defining the action of a or . 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.

Report Template (RPTT) A Report Template (RPTT) is an ordered list of object references or expression values used as a source for generating report values. A RPTT takes the form of a semantic typedef refining an AC to be a list of expressions or references to value-producing objects. The object which produces an RPTT can itself be parameterized so that the RPTT flows down parameters as described in . A RPTT can be viewed as a schema that defines how to generate and interpret a Report; they contain no values and are either defined in an ADM or configured between Managers and Agents in an ODM. Reports themselves are ephemeral and not represented in the AMM object model directly, see . The procedure for reporting on a RPTT is defined in . 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.

Report (RPT) A Report (RPT) is an ordered list of data values populated in conformance to a source object being reported on. Reports do not have an individual identifier - rather they are uniquely identified by their source and the timestamp at which their data values were collected. A RPT takes the form of a semantic typedef refining an AC to a sequence of the following:

Source:

The source of the report in the form of an ARI with an object-reference for one of the following types: CONST, EDD, VAR, or CTRL. If the source was parameterized, this ARI SHALL contain the actual parameters used at the time of reporting.

Generation Time:

The timestamp of the time at which the report items were sampled in the form of an ARI containing a literal TP value.

Correlator:

Either a BYTESTR, if the report originated from an execution with a correlator value, or the null value.

Items:

A list of ARIs corresponding to the source object, with cardinality according to the following:

For a VALUE-REF source the item list SHALL be the result of reporting on that object.
For a CTRL-REF source there SHALL be a single value representing the Result of the execution. A result of undefined indicates a failure executing the CTRL.

RPT values SHALL NOT be used directly within any value-producing object. Values within a RPT are generated by an Agent during reporting.

Tabular Report (TBL) A Tabular Report (TBL) is a collection of values which are logically structured as a two dimensional table of rows and columns. Similar to values, tables are instantiated dynamically as part of evaluation and not intended to be user-input. Also similar to RPT values, a TBL can only be interpreted within the context of a Tabular Report Template defined within an ADM. The TBLT takes the form of a structured type definition on a value-producing object which defines the columns of the table, including each of their column names and types and optional constraints on the number of rows in the TBL. A TBL takes the form of a semantic typedef refining an AC to a sequence of the following:

Column Count:: The number of columns in the associated TBLT. This is used to interpret the flat list of table items that follow.
Items:: The items of the table flattened in row-major order. The number of items is the product of the number of rows and columns in the table.

TBL values SHOULD be used only within an EDD. Values within a TBL are generated by an Agent during value production.

Contents of an Agent ADM While the DTNMA ADM described in contains definitions of static aspects of the AMM, the DTNMA Agent ADM is needed to include necessary dynamic aspects of the operation of an Agent. This separation is also helpful in order to allow the dynamic behaviors of an Agent to be modified over time while the AMM definitions stay stable and unchanging.

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.

Basic Operators TBD defining boolean, bitwise, and numeric operators

Operational Data Models (ODMs) An ODM is a logical entity for containing AMM objects, similar to an ADM but in an ODM the objects are not static. An ODM's objects can be added, removed, and (with some restrictions) modified during the runtime of an Agent. Like an ADM, each ODM exists as a separate namespace for its contained objects and an Agent can contain any number of ODMs. Some object types, those which require implementation outside of the Agent proper, are not available to be created in an ODM. These include the CTRL, EDD, and OPER. The actions for inspecting and manipulating the contents of an ODM are available through EDDs and CTRLs of the Agent ADM.

Processing Activities This section discusses logic and requirements for processing of AMM objects and values. Each subsection is a separate class of processing that is performed by an Agent. A Manager (or any other entity) MAY perform some of the same processing, e.g. evaluating an expression, in order to validate values or configurations before sending them to an Agent. That kind of behavior is effectively creating a "digital twin" of the managed Agent to ensure that the processing will behave as expected before it is sent. For this reason, the subject noun used in all of these activities is the "processor".

Agent Initialization The initialization of the Agent state can be associated with a power-on event or, due to the use of volatile memory, can be an explicit activity initiated from outside the Agent runtime. If volatile memory is used the contents of the ODMs on an Agent will be present for the initialization procedure; otherwise the ODMs will be considered empty or absent. The procedure to initialize an Agent is as follows:

All ADM-defined VAR objects SHALL have their value set to one of the following:
- If an Initializer is defined for the VAR, the value is the result of evaluating the associated Initializer expression and then casting to the VAR type.
- Otherwise, the value is undefined.
Any ODM-defined VAR objects MAY retain their state.
All ADM-defined TBR and SBR objects SHALL have their Enabled state set to the Initial Enabled value. Any ODM-defined TBR and SBR objects MAY retain their Enabled state. Any rules which are enabled are ready for processing.

ARI Resolving Within an ADM, ARIs present in the various fields of object definitions are URI References, which can take the form of Relative URIs (see ). Any ARIs within an ADM definition SHALL be handled as URI References and resolved in accordance with the procedure of with the following used as a Base URI:

For ARIs within a single AMM object definition, the non-parameterized ARI of that object SHALL be the Base URI. This includes ARIs used in nested structures under the object definition; the object is the anchor point.
For all other ARIs, the default Base URI ari:/ SHALL be the Base URI. This means that all ARIs within an ADM do not require a URI scheme part.

Dereferencing An object-reference value contains an identity and a parameter part. Dereferencing an OBJ-REF uses the identity to look up a specific defined object available to the agent. The process of dereferencing a value is as follows:

The value has to contain an object reference. If the value is not an object reference, this procedure stops and is considered failed.
The OBJ-REF namespace (whether text or enumeration) is used to search for a defined ADM or ODM namespace. If no corresponding namespace is available, this procedure stops and is considered failed.
Within the namespace the object type and object name (whether text or enumeration) is used to search for a specific defined object. If no corresponding object is available, this procedure stops and is considered failed.

Parameter Handling An object-reference value contains an identity and a parameter part. The parameter part of an OBJ-REF represents the actual parameters being used. The process to validate and reconcile provided actual parameters against an object's formal parameters is as follows:

If the object has formal parameters differing in size from the actual parameters, this procedure stops and is considered failed.
For each actual parameter, the processor performs the following: If the value is a TYPEDEF-REF and the value itself has a parameter, the original value is replaced by the result of a type cast on the parameter value. If the cast fails this procedure stops and is considered failed.
For each correlated pair of single formal and actual parameter, the processor performs the following:
1. If the actual parameter is undefined and the formal parameter defines a default value, that default replaces the actual parameter value. If the actual parameter is still undefined, this procedure stops and is considered failed. FIXME: should this pass through without failure? That's the ECMAscript way.
2. The actual parameter is cast to the type of the formal parameter in accordance with . If the cast fails, this procedure stops and is considered failed.

An implementation MAY perform deferred "lazy" processing of any of the above steps, causing a failure when the actual parameter value is needed. One caveat about deferred validation is that it will not fail if the parameter is unused, which is not necessarily a problem but could mask other issues in whatever generated the parameters.

Value Production Value production can be thought of as a common behavior used for , , and activities. Within the AMM the following entities have a value production procedure: CONST, EDD, and VAR object references.

CONST and VAR References 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 are as follows:

The processor dereferences the OBJ-REF in accordance with . If the dereference fails, this procedure stops and is considered failed.
The processor verifies that the OBJ-REF actual parameters, if any, are consistent with the formal parameters of the object from which production is requested in accordance with . For this procedure it is consistent to have no actual parameters but defined formal parameters, that case is handled below. If there is inconsistency, this procedure stops and is considered failed.
When no actual parameters are present (regardless of formal parameters), the stored value is considered to be the produced value and this procedure is complete. When actual parameters are present, the the stored value is augmented into the produced value by:
1. Substituting any LABEL actual parameters in the value, recursively in the case of a collection value. This augmentation has no effect on the stored value, it occurs only in the produced value.
2. It is valid for an actual parameter to have no substitution occur, but it is not valid for a LABEL in the value to not have a corresponding actual parameter and in such case this procedure stops and is considered failed.

EDD References For EDD object references, 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 value or a Tabular Report. The value production for these are as follows:

The processor dereferences the OBJ-REF in accordance with . If the dereference fails, this procedure stops and is considered failed.
The processor verifies that the OBJ-REF actual parameters, if any, are consistent with the formal parameters of the object from which production is requested in accordance with . If there is inconsistency, this procedure stops and is considered failed.
The processor passes the execution on to the underlying implementation of the EDD or TBLT being produced from. The context given to the implementation is the following:

Object Identity:

This gives visibility into the OBJ-REF which was dereferenced during the production.

Parameters:

The set of actual parameters augmented for the production.

Result 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 to enforce that the produced value is consistent with the type of the object.

Execution Within the AMM only two entities have an execution procedure: controls and macros. Controls are executed by reference, while macros are executed both by value and by reference.

Value-Producing Object References The execution of a VALUE-REF producing a value of any type is as follows:

The value is produced from the OBJ-REF in accordance with . This step includes substitution of any LABEL parameters within the value.
If the value is an MAC type, this value is executed in accordance with . Otherwise, the execution is considered failed.

CTRL References The execution of an OBJ-REF referencing a is as follows:

The processor dereferences the OBJ-REF in accordance with . If the dereference fails, this procedure stops and is considered failed.
The processor verifies that the OBJ-REF actual parameters, if any, are consistent with the formal parameters of the CTRL being executed in accordance with . If there is inconsistency, this procedure stops and is considered failed.
The processor passes the execution on to the underlying implementation of the CTRL being executed. 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 OBJ-REF which was dereferenced during the execution.

Parameters:

The set of actual parameters augmented for the execution.

Result Storage:

The result of the execution is placed here before completion.

The initial state of the Result Storage is taken from the default result the CTRL, if defined, or null otherwise.

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

MAC Values The execution of a value, which is structured as an AC, is as follows:

The processor iterates through all items of the AC recursively, replacing any VALUE-REF with their value produced in accordance with . If any dereference fails this procedure stops and is considered failed.
From this point on the AC contains only CTRL-REF values or nested AC with CTRL-REF. The processor iterates through all items of the AC recursively, in depth-first order, and performs the following: If the item is an CTRL-REF it is executed in accordance with . If the execution fails, this procedure stops and is considered failed. Otherwise, this procedure stops and is considered failed.

One effect of this procedure is that if any referenced MAC values cannot be produced the procedure fails before any CTRL is executed. Another 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.

Evaluation Within the AMM the following entities have an evaluation procedure: references to value-producing objects, OPERs, and TYPEDEFs and and EXPR values. For the purposes of these procedures, it is important to distinguish between an EXPR value and a reference to a value-producing object which is typed to produce an EXPR value.

Value-Producing Object References The evaluation of a VALUE-REF producing a value of any type is as follows:

The value is produced from the OBJ-REF in accordance with . This step includes substitution of any LABEL parameters within the value.
If the value is an EXPR type, this value is considered to be a sub-expression and is evaluated in accordance with . Otherwise, the produced value is considered to be the evaluation result.

OPER References This procedure applies only during the evaluation of a containing expression; an OPER cannot be evaluated in isolation. The evaluation of an OBJ-REF referencing a is as follows:

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.
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 OBJ-REF 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.

TYPEDEF References This procedure applies only during the evaluation of a containing expression; a TYPEDEF cannot be evaluated in isolation. The evaluation of a TYPEDEF reference 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 an OBJ-REF referencing a is as follows:

If the TYPEDEF-REF itself has no parameters, the input value is popped from the stack. If the TYPEDEF-REF itself has one parameter, the input value is that parameter. If the TYPEDEF-REF itself has more than parameter, this procedure stops and is considered failed.
The result value is a type cast on the input value. If the cast fails this procedure stops and is considered failed.
The result value is pushed onto the stack.

EXPR Values The evaluation of an value, which is structured as an AC, is as follows:

An empty value stack is initialized for this evaluation.
For each item of the AC, recursively, the processor performs the following: If the value is a VALUE-REF, the original value is replaced by the value produced in accordance with . If the production fails this procedure stops and is considered failed.
From this point on the AC 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 OPER-REF it is evaluated in accordance with . If the evaluation fails, this procedure stops and is considered failed. Otherwise, the item is pushed onto the stack.
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-REFs, EXPRs, or VALUE-REF references are not evaluated.

Reporting Within the AMM the following entities have a reporting context: CONST, EDD, and VAR objects and RPTT values. The value-producing objects are reported-on by reference, while RPTT are reported-on both by value and by reference.

Value-Producing Object References The reporting on a VALUE-REF producing a value of any type is as follows:

The value is produced from the OBJ-REF in accordance with . This step includes substitution of any LABEL parameters within the value.
If the value is an RPTT type, this value is used to generate report items in accordance with . Otherwise, the produced value is used as the single RPT item.
The RPT value is produced by combining: the source ARI used for this procedure, the current timestamp, and the items generated in the previous step.

RPTT Values The reporting on a value, which is structured as an AC, is as follows:

An empty item list is initialized for this template.
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 . If the evaluation fails the undefined value is used as a substitute. Otherwise, if the item is a VALUE-REF it is replaced by the value produced in accordance with . 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.

Type Casting The type system of the AMM allows conversions of values between different literal and semantic types in a way which is supposed to preserve the "meaning" of the value. In some cases, casting is performed implicitly by the Agent while other cases the casting is explicitly part of an expression. One example of implicit casting is during to ensure each processed parameter meets the formal parameter type signature. Another example of implicit casting is for numeric operators in the Agent ADM.

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 , 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.

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:

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

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

If the input value is outside the domain of the output type, the cast is considered failed.

Numeric Promotion While the earlier discussion of numeric type casting is about converting from an input type to an output type, the concept of a type promotion is about finding a "least compatible type" which can accommodate most, if not all, of the input type range. Casting to a promoted type is called an "up" cast, and from a promoted type a "down" cast. The promotion order for NUMERIC types is as follows:

A promoted type has a larger span of values (the difference between largest and smallest representable value).
A promoted type can gain signed-ness but not lose it.
A promoted type can lose precision for some values.

This promotion logic does not guarantee that an up-cast will always succeed (e.g. some large UVAST values will not fit within a VAST or REAL32) but does provide a strict ordering for finding a compatible type between two NUMERIC values. The "least compatible type" between two types SHALL be defined as the smallest up-cast that will accommodate the input types, as indicated in . This is almost a strict ordering except for the cast of INT and UVAST to VAST to accommodate both the signed-ness and the size of the inputs. NUMERIC Type Promotion

	BYTE	UINT	INT	UVAST	VAST	REAL32	REAL64
BYTE	BYTE	UINT	INT	UVAST	VAST	REAL32	REAL64
UINT		UINT	INT	UVAST	VAST	REAL32	REAL64
INT			INT	VAST	VAST	REAL32	REAL64
UVAST				UVAST	VAST	REAL32	REAL64
VAST					VAST	REAL32	REAL64
REAL32						REAL32	REAL64
REAL64							REAL64

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 cast of an input value to a TYPEDEF is as follows:

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 ) a processor MAY cache this flattened type list.
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.
The result value is associated with the the TYPEDEF being cast to, and that is the result of this procedure.

Translating ARIs and Semantic Types The procedures in this section allow AMM values, which can have a semantic type, to be translated into and out of the ARI syntax, which has no semantic type information. They also describe a way to use type-less literal values to give further compression of values in certain circumstances. The compression of removing type information is possible only when the context in which the value is being used has a specific semantic or literal type associated with it. For example, when a formal object parameter or a report item is typed to either a literal type or a semantic type that doesn't represent a type union then a value being used for the parameter or item can only have that specific type; any other value type will be mismatched and invalid. Another way of looking at this compression is when the value has the same type as its context requires, then the value's type is redundant and can be elided without loss of information. In addition to compression by eliding semantic type within a context, there are also some literal types which have values which only exist in that type. For example, the BOOL value true exists only within that type while the UINT value 5 is also within the domain of INT and several others. For the procedures below, the contexts which provide type information SHALL be: all formal parameters, VALUE-REF values, report template items, tabular columns. When translating from an AMM value into an ARI, the processor performs the following:

If the use context is associated with a TYPEDEF and the value is associated with an ambiguous or incompatible TYPEDEF, the ARI form SHALL be wrapped in a TYPEDEF-as-cast ARI. An ambiguous type is one where the presence of the inner type cast produces a different result than if the cast were absent. An incompatible type is one where the presence of the inner cast results in a failure of the outer cast.
If the use context is associated with a single literal type (no unions) and the literal type is present in Table 2 "Literal Implied Types" of , the ARI form MAY have its literal type removed.

When translating from an ARI into an AMM value, the processor performs the following:

If the use context is associated with a type and the value is associated with a different TYPEDEF or no TYPEDEF, the value SHALL be cast to the context type in accordance with .

YANG Module Profile This section provides an ADM syntax in the form of a YANG module conforming to a profile of defined in this section. It is not required that this encoding be used for transmission of ADM information over the wire in the context of a network deployment. Since the AMM is designed to allow for multiple encodings, the expression of ADMs in a YANG module is intended to support translation to other encodings without loss of information. Some aspects of this YANG profile restrict the allowable definitions to conform with 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 . See the ADM sub-registry defined in for registration of ADM modules. For the remainder of this section, 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 a "Legacy module" to differentiate it. After explanation of extensions in , 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 module."; amm:enum "4294967296"; }

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 the syntax and semantics provided by YANG.

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 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 entities usable with NETCONF, etc.
Module Importing:: The existing concept and syntax of importing a module namespace, to reference objects in the other module, defined in 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 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 , 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 is unchanged for ADM modules. Because ADM modules are a flat object namespace, the complexity of namespaces is significantly simplified compared to Legacy modules.
Reusable Groups:: The existing group reuse logic described in 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-REF definitions, and table columns.

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, the built-in types listed in do not directly apply to ADM modules. In order to maintain some amount of tool compatibility, the Base ADM treats AMM literal types as YANG typedefs. An ADM module SHALL NOT use any YANG built-in type or any typedef defined outside of an ADM module. As defined in this document, there is no direct deterministic mapping between Legacy module typing and ADM module typing.
Node Structure:: The data node statements "container", "leaf", "leaf-list", "list" have modified interpretations for this profile as defined in . The data node statements "anydata", or "anyxml" have no use in an ADM module and SHALL NOT be present.
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.
Node 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 , 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 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 ("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 cannot apply to an ADM. The model extension "augment" statement SHALL NOT be present in an ADM module.

YANG Node Interpretations Rather than fully redefine a data model for ADM module use, this profile reinterprets existing YANG node structure of in the context of the AMM. One difference in how the nodes are interpreted for an ADM module is related to the arguments to the node statements as identifiers. While Legacy modules have been used to model data for XML representation for NETCONF (or equivalent representations for equivalent protocols), in the AMM values do not have explicit identifiers. Because of this, data node identifiers in ADM modules are for local processing only and never appear in messages between Agents and Managers. They are still valuable and are used by parameter handling procedures and in report and table visualization tools. The AMM interpretation of YANG nodes is defined in the following subsections.

Leaf Nodes A leaf node is used to indicate the presence of an AMM value of a specific literal or semantic type. A leaf can either be top-level, to define the type of an object or parameter, or can be nested within a container node to define an AMM value within an AC. As stated earlier, leaf nodes are always mandatory but can be typed to have a union with the NULL type in order to represent optional values. The substatements of "type", "units", "status", "reference", and "description" are valid in this profile. The "default" substatement applies only in certain circumstances, notably formal parameters and has no effect otherwise.

Leaf-List Nodes A leaf-list node is used to indicate the presence of an AMM value of a specific literal or semantic type. Because this node corresponds with multiple AMM values, this node applies only within a container node (see ). The substatements of "min-elements", "max-elements", "type", "units", "status", "reference", and "description" are valid in this profile.

Container Nodes A container node is used to indicate the presence of an AMM value that is an with a constrained internal structure (specified by child nodes). The substatements of "leaf", "leaf-list", "container", "status", "reference", and "description" are valid in this profile. The leaf, leaf-list, and container substatements are interpreted as specification of the AC contents. This profile disallows definition of nested tables, so the "list" substatement is not valid.

List Nodes A list node is used to define the structure of a table within a TBLT, which is used to produce a . Each leaf node within a list corresponds to a single column of the table. The substatements of "key", "unique", "min-elements", "max-elements", "leaf", "container", "status", "reference", and "description" are valid in this profile. The leaf and container substatements are interpreted as specification of the column content, being either a single value or an AC respectively.

Choices Although this profile makes no specific prohibitions against the use of the "choice" statement as a data node, it is expected that a choice will have limited utility in an ADM module. Most alternative specifying can be done with semantic types containing type unions; leaving the only use of a choice between a simple value and an structured AC.

Grouping and Uses The mechanisms of "grouping" and "uses" statements are allowed with an ADM module unchanged, however because an ADM does not allow nested object structure the utility of grouping/uses is more limited. One contrived example is a situation where sets of parameters are reused between multiple objects, which can define the formal parameters in a grouping statement and each "parameters" can apply "uses" substatement to pull in those formal parameter nodes.

ADM Module Extensions In order to provide syntax necessary for definitions this document defines, via the DTNMA ADM, the following extensions for ADM modules.

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

The amm:parameters Statement This statement is used to define the set of formal parameters that apply to the parent object. There is no argument to this statement. The substatements under this are an ordered sequence of formal parameter definitions, each a choice between data node statements interpreted according to . The parameters list itself does not contain metadata statements. amm:parameters Substatements

Substatement	Cardinality
leaf	0..n
container	0..n
choice	0..n
uses	0..n

An example of the parameters statement is below, where there are three defined parameters two of which have default values. amm:parameters { leaf first { type amm:uint { range "3..10"; } leaf second { type amm:textstr; default "\"value\""; } container third { leaf-list _ { type amm:uint; } default "/AC/(3,5,8)" }

The amm:const Statement This statement is used to define a object. The argument to this statement is the name of the AMM object. The substatements under this are the common object metadata, optional formal parameters, and a single node that represents the produced value of the CONST. The node statement SHALL contain a default value, which is the constant represented by this object. amm:const Substatements

Substatement	Cardinality
if-feature	0..1
amm:enum	0..1
amm:parameters	0..1
status	0..1
reference	0..1
description	0..1
One data node:
leaf	0..1
container	0..1
choice	0..1
uses	0..1

An example of a simple-typed CONST is below. amm:const pi32 { leaf _ { type amm:real32; default "3.14159"; } description "A truncated value of Pi."; } Another example of a semantic-typed MAC-valued CONST is below. amm:const do_thing { container { leaf-list _ { type amm:MAC-item; } default "/AC/(../CTRL/first,../CTRL/second(2))"; } description "Execute two controls in sequence."; }

The amm:ctrl Statement This statement is used to define a object. The argument to this statement is the name of the AMM object. 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 a default value, used to initialize the Result Storage for the execution procedure. If the amm:result substatement is omitted the assumed result type SHALL be NULL with a default value of null. amm:ctrl Substatements

Substatement	Cardinality
if-feature	0..1
amm:enum	0..1
amm:parameters	0..1
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 { parameters { leaf src { type amm:textstr; description "The name of the source."; } } result { leaf previous { type amm:UVAST; description "The value just before reset."; } } description "This control resets counts for the given source."; }

The amm:result Statement The result statement contains a single node which represents the result expected from executing a CTRL or evaluating an OPER. amm:result Substatements

Substatement	Cardinality
leaf	0..1
container	0..1
choice	0..1
uses	0..1

The amm:edd Statement This statement is used to define a object. The argument to this statement is the name of the AMM object. The substatements under this are the common object metadata, optional formal parameters, and a single node that represents the produced value of the EDD. The node substatement SHALL NOT contain a default value. amm:edd Substatements

Substatement	Cardinality
if-feature	0..1
amm:enum	0..1
amm:parameters	0..1
status	0..1
reference	0..1
description	0..1
One data node:
leaf	0..1
container	0..1
choice	0..1
uses	0..1

An example of a simple-typed EDD is below. amm:edd tx_count { leaf _ { type amm:counter64; unit "frames"; } description "The count of the number of frames sent."; }

The amm:oper Statement This statement is used to define a object. The argument to this statement is the name of the AMM object. The substatements under this are the common object metadata, optional formal parameters, an operands list, and an evaluation result. amm:edd Substatements

Substatement	Cardinality
if-feature	0..1
amm:enum	0..1
amm:parameters	0..1
status	0..1
reference	0..1
description	0..1
operands	1
result	1

An example of an arithmetic OPER is below. amm:oper add { operands { leaf val_a { type amm:NUMERIC; } leaf val_b { type amm:NUMERIC; } } result { leaf _ { 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 { parameters { leaf count { type amm:UINT { range "1..max"; } description "The number of operands to pop." } } operands { leaf-list value { type amm:NUMERIC; description "This is not within a container, so does not represent an AC; it is multiple operands."; } } result { leaf sum { type amm:NUMERIC; } } description "Sum together a sequence from the stack."; }

The amm:operands Statement This statement is used to define the set of operands that apply to the parent object. There is no argument to this statement. The node substatement SHALL NOT contain a default value. amm:operands Substatements

Substatement	Cardinality
leaf	0..1
leaf-list	0..1
container	0..1
choice	0..1
uses	0..1

The amm:sbr Statement This statement is used to define a object. The argument to this statement is the name of the AMM object. The substatements under this are the common object metadata, the action to execute upon trigger, and rule control fields defined below. 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 "TBD"; amm:condition "(../EDD/sensor,../VAR/min_threshold,/ietf-amm/OPER/lessthan)"; description "Enable safe mode below threshold."; }

The amm:min-interval Statement This statement is used to define the Minimum Interval field of 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.

The amm:max-count Statement This statement is used to define the Maximum Count field of and 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.

The amm:init-enabled Statement This statement is used to define the Initial Enabled state of and objects. The argument to this statement is the text form of a BOOL value. If not present, the default value of true is used.

The amm:tbr Statement This statement is used to define a object. The argument to this statement is the name of the AMM object. The substatements under this are the common object metadata, the action to execute upon trigger, and rule control fields defined below. 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 "(../CTRL/first,/adm2/CTRL/other)"; amm:period "/TD/PT30s"; description "Generate telemetry reports."; }

The amm:start Statement This statement is used to define the Start field of objects. The argument to this statement is the text form of a TIME value. If not present, the default value of zero (meaning start immediately) is used.

The amm:var Statement This statement is used to define a object. The argument to this statement is the name of the AMM object. The substatements under this are the common object metadata, optional formal parameters, a single node that represents the stored-and-produced value of the VAR, and an optional initializer expression. The node substatement SHALL NOT contain a default value. amm:var Substatements

Substatement	Cardinality
if-feature	0..1
amm:enum	0..1
amm:parameters	0..1
status	0..1
reference	0..1
description	0..1
amm:initializer	0..1
One data node:
leaf	0..1
container	0..1
choice	0..1
uses	0..1

An example of a simple-typed VAR with an initializer value is below. amm:var min_threshold { leaf _ { type amm:real32; unit "meters"; } amm:initializer "1e4"; description "The lower threshold to enable safe mode."; }

The amm:initializer Statement This statement is used to define an initial variable state as either an AMM value or an . The argument to this statement is the text form of the ARI encoding the expression. The initializer is used as part of the procedure and when new VAR objects are defined in an ODM.

ADM Module Contents An ADM module is identified, as defined in , by the module "namespace" having an "ari" scheme. Within an ADM module, this profile makes restrictions in which are formalized in the following table of allowed module substatements. This table is adapted from . ADM module Substatements

Substatement	Cardinality
yang-version	1
namespace	1
prefix	1
include	0..n
import	0..n
status	0..1
reference	0..1
organization	0..1
description	0..1
revision	0..n
extension	0..n
feature	0..n
deviation	0..n
amm:enum	1
typedef	0..n
amm:const	0..n
amm:ctrl	0..n
amm:edd	0..n
amm:oper	0..n
amm:sbr	0..n
amm:tbr	0..n
amm:var	0..n

The AMM model provides multiple ways to represent certain types of data. This section provides informative guidance on how to express application management constructs efficiently when authoring an ADM document.

Use Parameters for Dynamic Information:: Parameters provide a powerful mechanism for expressing associative look-ups of EDD data. EDDs SHOULD be parameterized when the definition of the EDD is dependent upon run-time information. For example, if requesting the number of bytes through a specific endpoint, the construct num_bytes("endpoint_name") is simpler to understand and more robust to new endpoint additions than attempting to enumerate the number and name of potential endpoints when defining the ADM.
Do Not Use Parameters for Static Information:: Parameters incur bandwidth and processing costs (such as type checking) and should only be used where necessary. If an EDD object can be parameterized, but the set of parameters is known and unchanging it may be more efficient to define multiple non-parameterized EDD objects instead. For example, consider a single parameterized EDD object reporting the number of bytes of data received for a specific, known set of priorities and a request to report on those bytes for the "low", "med", and "high" priorities. Below are two ways to represent these data: using parameters and not using parameters.
+------------------------+------------------------+ | Parameterized EDDs | Non-Parameterized EDDs | +------------------------+------------------------+ | num_bytes_by_pri(low) | num_bytes_by_low_pri | | num_bytes_by_pri(med) | num_bytes_by_med_pri | | num_bytes_by_pri(high) | num_bytes_by_high_pri | +------------------------+------------------------+
The use of parameters in this case only incurs the overhead of type checking, parameter encoding/decoding, and associative lookup. This situation should be avoided when deciding when to parameterize AMM objects.
Use Tables for Related Data:: In cases where multiple EDD or VAR values are likely to be evaluated together, then that information SHOULD be placed in a Table Template rather than defining multiple EDD and VAR objects. By making a Table Template, the relationships among various data values are preserved. Otherwise, Managers would need to remember to query multiple EDD and/or VAR objects together which is burdensome, but also results in high bandwidth and processor utilization.

This document does not define or modify any existing IANA registries. It does rely on the ARI-defined sub-registries defined in by .

This document does not describe any on-the-wire encoding or other messaging syntax. It is assumed that the exchange of AMM objects between Agents and Managers occurs within the context of an appropriate network environment. This AMM model may be extended to include the concept of Access Control Lists (ACLs) to enforce roles and responsibilities among Managers in the network. This access control would be implemented separately from network security mechanisms.

References Normative References Delay-Tolerant Networking (DTN) Management Protocol IANA IEEE Standard for Floating-Point Arithmetic Institute of Electrical and Electronics Engineers

USA New York http://www.ieee.org

This standard specifies interchange and arithmetic formats and methods for binary and decimal floating-point arithmetic in computer programming environments. This standard specifies exception conditions and their default handling. An implementation of a floating-point system conforming to this standard may be realized entirely in software, entirely in hardware, or in any combination of software and hardware. For operations specified in the normative part of this standard, numerical results and exceptions are uniquely determined by the values of the input data, sequence of operations, and destination formats, all under user control. Key words for use in RFCs to Indicate Requirement Levels In many standards track documents several words are used to signify the requirements in the specification. These words are often capitalized. This document defines these words as they should be interpreted in IETF documents. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements. Uniform Resource Identifier (URI): Generic Syntax A Uniform Resource Identifier (URI) is a compact sequence of characters that identifies an abstract or physical resource. This specification defines the generic URI syntax and a process for resolving URI references that might be in relative form, along with guidelines and security considerations for the use of URIs on the Internet. The URI syntax defines a grammar that is a superset of all valid URIs, allowing an implementation to parse the common components of a URI reference without knowing the scheme-specific requirements of every possible identifier. This specification does not define a generative grammar for URIs; that task is performed by the individual specifications of each URI scheme. [STANDARDS-TRACK] Date and Time on the Internet: Timestamps This document defines a date and time format for use in Internet protocols that is a profile of the ISO 8601 standard for representation of dates and times using the Gregorian calendar. The YANG 1.1 Data Modeling Language YANG is a data modeling language used to model configuration data, state data, Remote Procedure Calls, and notifications for network management protocols. This document describes the syntax and semantics of version 1.1 of the YANG language. YANG version 1.1 is a maintenance release of the YANG language, addressing ambiguities and defects in the original specification. There are a small number of backward incompatibilities from YANG version 1. This document also specifies the YANG mappings to the Network Configuration Protocol (NETCONF). Asynchronous Resource Identifier The Johns Hopkins University Applied Physics Laboratory The Johns Hopkins University Applied Physics Laboratory The Johns Hopkins University Applied Physics Laboratory This document defines the structure, format, and features of the naming scheme for the objects defined in the Delay-Tolerant Networking (DTN) Application Data Model (ADM), in support of challenged network management solutions described in the Delay- Tolerant Networking Autonomous Management Architecture (AMA). This document defines a new Asynchronous Resource Identifier (ARI), based on the structure of a common URI, meeting the needs for a concise, typed, parameterized, and hierarchically organized set of data elements. Informative References ECMA-262 12th Edition, June 2021. ECMAScript 2021 language specification Ecma International YANG Parameters IANA Structure of Management Information Version 2 (SMIv2) It is the purpose of this document, the Structure of Management Information Version 2 (SMIv2), to define that adapted subset, and to assign a set of associated administrative values. [STANDARDS-TRACK] Conformance Statements for SMIv2 Collections of related objects are defined in MIB modules. It may be useful to define the acceptable lower-bounds of implementation, along with the actual level of implementation achieved. It is the purpose of this document to define the notation used for these purposes. [STANDARDS-TRACK] Common YANG Data Types This document introduces a collection of common data types to be used with the YANG data modeling language. [STANDARDS-TRACK] Common YANG Data Types This document introduces a collection of common data types to be used with the YANG data modeling language. This document obsoletes RFC 6021. Concise Data Definition Language (CDDL): A Notational Convention to Express Concise Binary Object Representation (CBOR) and JSON Data Structures This document proposes a notational convention to express Concise Binary Object Representation (CBOR) data structures (RFC 7049). Its main goal is to provide an easy and unambiguous way to express structures for protocol messages and data formats that use CBOR or JSON. DTN Management Architecture Johns Hopkins Applied Physics Laboratory Johns Hopkins Applied Physics Laboratory Johns Hopkins Applied Physics Laboratory The Delay-Tolerant Networking (DTN) architecture describes a type of challenged network in which communications may be significantly affected by long signal propagation delays, frequent link disruptions, or both. The unique characteristics of this environment require a unique approach to network management that supports asynchronous transport, autonomous local control, and a small footprint (in both resources and dependencies) so as to deploy on constrained devices. This document describes a DTN management architecture (DTNMA) suitable for managing devices in any challenged environment but, in particular, those communicating using the DTN Bundle Protocol (BP). Operating over BP requires an architecture that neither presumes synchronized transport behavior nor relies on query-response mechanisms. Implementations compliant with this DTNMA should expect to successfully operate in extremely challenging conditions, such as over uni-directional links and other places where BP is the preferred transport.

YANG Module for AMM Definitions The following is the YANG module implementing the entities described in :

Extensions to support within a YANG module.
Extensions to support within a YANG module.
The literal and object-reference types of ARI usable as YANG leaf types.

module ietf-amm { namespace "ari:/ietf-amm"; prefix "amm"; amm:enum "0"; organization "IETF Delay Tolerant Networking Working Group"; contact "WG Web: <http://tools.ietf.org/wg/dtn/> WG List: <mailto:dtn@ietf.org> WG Chairs: Brian Haberman <mailto:brian@innovationslab.net> Marc Blanchet <mailto:Marc.Blanchet@viagenie.ca> Editor: Brian Sipos <mailto:brian.sipos@jhuapl.edu>"; description "This module implements the DTN Management Architecture (DTNMA) Application Data Model (ADM) base module within YANG"; reference "draft-birrane-dtn-adm"; 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 extension for AMM object definitions ****/ // This group of extensions are for common behavior for 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 parameters { description "A container for the formal parameters for an object. Each substatement is a parameter as either a leaf (ARI) or container (AC). Order of parameters is signifigant within this statement."; } // This group are AMM object keywords and their parameters extension const { argument "name"; description "Definition of a CONST within an ADM. The argument to this statement is the object name. A 'value' substatement must be present."; } extension value { argument "ari"; description "The literal value of a CONST object. The argument is the text form of the ARI"; } extension ctrl { argument "name"; description "Definition of a CTRL within an ADM. The argument to this statement is the object name."; } extension result { description "An result value reported as a response to a control. The substatement is the result value as either a leaf (ARI) or container (AC). 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 operands { 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 signifigant 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."; } extension init { argument "expr"; description "An EXPR value used to initialize a VAR."; } /**** * This section contains ARI (literal and object-reference) value types. ****/ 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."; } // Simple literal types as YANG typedefs typedef NULL { type enumeration { enum null { description "The only allowed value."; } } description "A single-valued type to represent a null value."; } typedef BOOL { type boolean; description "The same semantics as the YANG 'boolean' type."; } typedef BYTE { type uint8; description "The same semantics as the YANG 8-bit unsigned type."; } typedef UINT { type uint32; description "The same semantics as the YANG 32-bit unsigned type. Can contain an 'int-labels' substatement for documentation."; } typedef INT { type int32; description "The same semantics as the YANG 32-bit signed type. Can contain an 'int-labels' substatement for documentation."; } typedef UVAST { type uint64; description "The same semantics as the YANG 64-bit unsigned type. Can contain an 'int-labels' substatement for documentation."; } typedef VAST { type int64; description "The same semantics as the YANG 64-bit signed type. Can contain an 'int-labels' substatement for documentation."; } typedef REAL32 { type decimal64 { fraction-digits 10; } description "An IEEE-754 float32 value with a text representation in YANG. The ARI representation is different than the YANG type used here. Allows range restriction."; } typedef REAL64 { type decimal64 { fraction-digits 10; } description "An IEEE-754 float64 value with a text representation in YANG. The ARI representation is different than the YANG type used here. Allows range restriction."; } typedef TEXTSTR { type string; description "The same semantics as the YANG 'string' type. Allows length and pattern restriction."; } typedef BYTESTR { type binary; description "The same semantics as the YANG 'binary' type. Allows length restriction."; } typedef TP { type string; description "An absolute instant in time. The ARI representation is different than the YANG type used here. This is represented as either (narrowed RFC 3339) text or (fractional) seconds from the DTN epoch."; } typedef TD { type string; description "A relative time as a difference between two time instants. The ARI representation is different than the YANG type used here. This is represented as either (narrowed RFC 3339) text or (fractional) seconds."; } typedef LITTYPE { type string; description "An enumeration from IANA table of literal types."; } typedef LABEL { type string { pattern "[a-zA-Z_][a-zA-Z0-9_\\-\\.]*"; } description "An identifier label which fits the YANG 'identifier' pattern."; } typedef CBOR { type BYTESTR; description "A bytestr which contains a single well-formed CBOR item. Can contain a 'cddl' substatement for documentation."; } // Complex literals typedef AC { type string; description "When present within an ADM this uses the text encoding of an ARI Collection (AC)."; } typedef AM { type string; description "When present within an ADM this uses the text encoding of an ARI Map (AM)."; } // Object references typedef OBJ-REF { type string; description "A text representation of an ARI containing an object reference."; } typedef TYPEDEF-REF { type OBJ-REF; description "A reference to a TYPEDEF object."; } typedef CONST-REF { type OBJ-REF; description "A reference to a CONST object."; } typedef CTRL-REF { type OBJ-REF; description "A reference to a CTRL object."; } typedef EDD-REF { type OBJ-REF; description "A reference to an EDD object."; } typedef OPER-REF { type OBJ-REF; description "A reference to a OPER object."; } typedef SBR-REF { type OBJ-REF; description "A reference to an SBR object."; } typedef TBR-REF { type OBJ-REF; description "A reference to a TBR object."; } typedef VAR-REF { type OBJ-REF; description "A reference to a VAR object."; } // Named type unions for literals typedef TYPE-REF { type union { type LITTYPE; type TYPEDEF-REF; } description "Reference to either a literal type or a typedef."; } typedef INTEGER { type union { type BYTE; type UINT; type INT; type UVAST; type VAST; } description "Any type which represents a discrete integer."; } typedef FLOAT { type union { type REAL32; type REAL64; } description "Any type which represents a floating point number."; } typedef NUMERIC { type union { type INTEGER; type FLOAT; } description "Any type which can be used with numeric expressions."; } typedef TIME { type union { type TP; type TD; } description "Any type which can be used with time expressions."; } typedef SIMPLE { type union { type NULL; type BOOL; type NUMERIC; type TEXTSTR; type BYTESTR; type TIME; type LABEL; type CBOR; } description "Any type which contains a single value usable within an expression."; } typedef COMPLEX { type union { type AC; type AM; } description "A literal type which is not SIMPLE."; } typedef LITERAL { type union { type TYPE-REF; //FIXME: is typeref a literal or something else? type SIMPLE; type COMPLEX; } description "Any type which is represented as a literal ARI."; } typedef ANY { type union { type LITERAL; type OBJ-REF; } description "Any type representable by an ARI."; } typedef VALUE-REF { type union { type CONST-REF; type EDD-REF; type VAR-REF; } description "A reference to an object which can produce a value."; } // operational semantic types typedef counter32 { type UINT; 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."; } typedef counter64 { type UVAST; 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."; } typedef gauge32 { type INT; description "A 32-bit value sampling some quantized measurement. The value can increase or decrease arbitrarily over time."; } typedef gauge64 { type VAST; description "A 64-bit value sampling some quantized measurement. The value can increase or decrease arbitrarily over time."; } typedef timestamp { type TP; 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."; } // Restrictions on AC item types for specific purposes typedef EXPR-item { type union { type SIMPLE; type VALUE-REF; type TYPEDEF-REF; type OPER-REF; } description "Each item of an EXPR list. The value-object must be typed to contain a SIMPLE."; } grouping EXPR { leaf-list _ { type EXPR-item; description "All items are the same type."; } description "The contents of an EXPR container."; } typedef EXEC-REF { type union { type VALUE-REF; type CTRL-REF; } description "A reference to an object which can be executed. The value-object must be typed to contain a MAC."; } grouping MAC { leaf-list _ { type EXEC-REF; description "All items are the same type."; } description "The contents of a MAC container."; } grouping RPTT-item { choice item { case value-ref { leaf ref { type VALUE-REF; description "An object to produce a report value."; } } case expr { container expr { uses EXPR; description "An expression to evaluate into a report value."; } } description "Each item references a value-producing object or contains an expression to be evaluated."; } description "Each item of a RPTT."; } grouping RPTT { container _ { uses RPTT-item; description "The sequence of items in the template."; } description "The contents of a report template, encoded as the sequence of items."; } grouping RPT-items { leaf-list item { type ANY; description "The sequence of items in the report."; } description "The contents of a report, encoded as the sequence of values reported. The semantics of each item are contained in the associated RPTT."; } grouping TBL { leaf col-count { type UVAST; description "The number of columns in the table."; } leaf-list tbl-item { type ANY; description "All table values listed in row-major order."; } description "The flattened contents of a table. The semantics of each column are contained in the associated TBLT."; } grouping RPT { leaf source { type OBJ-REF; description "Reference to the reported object."; } leaf generated-at { type timestamp; description "The generation timestamp."; } choice entries { case value-ref { leaf value { type ANY; } } case rptt { uses RPT-items; } case tblt { uses TBL; } case ctrl-ref { leaf result { type ANY; } } description "Each report content depends on the reported object."; } description "The contents of an RPT container."; } }

YANG Module for DTNMA Agents The following is the YANG module implementing the entities described in :

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

module ietf-dtnma-agent { namespace "ari:/ietf-dtnma-agent"; prefix "da"; import "ietf-amm" { prefix amm; } organization "IETF Delay Tolerant Networking Working Group"; contact "WG Web: <http://tools.ietf.org/wg/dtn/> WG List: <mailto:dtn@ietf.org> WG Chairs: Brian Haberman <mailto:brian@innovationslab.net> Marc Blanchet <mailto:Marc.Blanchet@viagenie.ca> Editor: Brian Sipos <mailto:brian.sipos@jhuapl.edu>"; description "This module implements the DTN Management Architecture (DTNMA) Agent core functionality."; reference "draft-birrane-dtn-adm"; revision "2023-06-08" { description "Updated for latest AMM contents."; reference "draft-birrane-dtn-adm"; } amm:enum "0"; feature rules { description "Conforming to this feature enables time-based and state-based autonomy rules."; } amm:edd amp_version { leaf _ { type amm:TEXTSTR; } description "The version of AMP which this agent supports."; } amm:edd capability { list columns { key adm_name; leaf adm_name { type amm:LABEL; description "The module name of the ADM"; } leaf revision { type amm:TEXTSTR; description "The specific revision the agent supports."; } container features { leaf-list _ { type amm:LABEL; } description "The features of the ADM which the agent supports."; } } description "A table to indicate the ADM capability of the sending agent."; } amm:const hello { uses amm:RPTT; amm:value "(../EDD/amp_version,../EDD/capability)"; description "A report template to indicate the presence of an agent on a network."; } // MAC helper controls amm:ctrl if_then_else { amm:parameters { container condition { uses amm:EXPR; description "The condition to evaluate."; } leaf on_truthy { type amm:EXEC-REF; description "The object to execute when the condition is truthy."; } leaf on_falsy { type union { type amm:NULL; type amm:EXEC-REF; } default "null"; description "An optional execution when the condition is falsey."; } } description "Evaluate an expression and follow one of two branches of further evaluation."; } amm:ctrl catch { amm:parameters { leaf try { type amm:EXEC-REF; description "The object to execute."; } leaf on_failure { type union { type amm:NULL; type amm:EXEC-REF; } default "null"; description "An optional execution after failure."; } } description "Attempt to execute an object, and if there is some failure catch it and execute an alternative object."; } amm:ctrl inspect { amm:parameters { leaf ref { type amm:VALUE-REF; description "An object to produce a value from."; } } amm:result { leaf val { type amm:ANY; description "The produced value."; } } description "Produce a result value to inspect the agent state. This does not perform any EXPR evaluation or RPTT handling."; } amm:ctrl report_on { amm:parameters { uses amm:RPTT-item; } description "Generate a report on an object without needing to define a RPTT. The parameter is a single item that would be in a RPTT. 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."; } grouping obj-list-params { leaf include_adm { type amm:BOOL; default "false"; description "If true, listings will include objects from ADMs"; } description "Common parameters for object listing"; } amm:edd typedef_list { amm:parameters { uses obj-list-params; } list _ { key obj; leaf obj { type amm:TYPEDEF-REF; } } description "A table of TYPEDEF within the agent."; } // Objects related to VAR handling amm:edd var_list { amm:parameters { uses obj-list-params; } list _ { key obj; leaf obj { type amm:VAR-REF; } leaf type { type amm:TYPE-REF; } } description "A table of VAR within the agent."; } amm:ctrl var_present { amm:parameters { leaf obj { type amm:VAR-REF; description "A reference to a VAR within an ODM only."; } leaf type { type amm:TYPE-REF; description "The type for the VAR object."; } choice init { case without { leaf _ { type amm:NULL; } } case with { container expr { uses amm:EXPR; } } default "null"; description "An optional initializer expression."; } } description "Ensure a specific VAR is present."; } amm:ctrl var_absent { amm:parameters { leaf obj { type amm:VAR-REF; description "A reference to a VAR within an ODM only."; } } description "Ensure a specific VAR is not present."; } // Objects related to SBR handling grouping sbr-fields { container action { uses amm:MAC; description "The execution when this rule triggers."; } leaf start_time { type amm:TIME; } container condition { uses amm:EXPR; } leaf min_interval { type amm:TD; } leaf max_count { type amm:UVAST; } } amm:edd sbr_list { if-feature rules; list _ { key obj; leaf obj { type amm:SBR-REF; } uses sbr-fields; } } amm:edd tbr_list { if-feature rules; list _ { key obj; leaf obj { type amm:OBJ-REF; } container action { uses amm:MAC; description "The execution when this rule triggers."; } leaf start_time { type amm:TIME; } leaf period { type amm:TD; } leaf max_count { type amm:UVAST; } } } grouping numeric-unary { leaf val { type amm:NUMERIC; description "The single value."; } } grouping numeric-binary { leaf left { type amm:NUMERIC; description "The left-side operand."; } leaf right { type amm:NUMERIC; description "The left-side operand."; } } amm:oper negate { amm:operands { uses numeric-unary; } amm:result { uses numeric-unary; } description "Negate a value. This is equivalent to multiplying by -1 but a shorter expression."; } amm:oper add { amm:operands { uses numeric-binary; } amm:result { uses numeric-unary; } description "Add two numeric values. The operands are cast to the least compatible numeric type before the arithmetic."; } // amm:oper sub // amm:oper multiply // amm:oper divide // amm:oper add // amm:oper bit_not // amm:oper bit_and // amm:oper bit_or // amm:oper bit_xor // amm:oper bool_not // amm:oper bool_and // amm:oper bool_or // amm:oper bool_xor // amm:oper compare_eq // amm:oper compare_ne // amm:oper compare_gt // amm:oper compare_ge amm:oper compare_lt { amm:operands { uses numeric-binary; } amm:result { uses numeric-unary; } 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."; } amm:oper compare_le { amm:operands { uses numeric-binary; } amm:result { uses numeric-unary; } 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."; } }

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 )