idnits 2.17.1 draft-birrane-dtn-adm-03.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (June 30, 2018) is 2127 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- == Outdated reference: A later version (-07) exists of draft-birrane-dtn-ama-06 Summary: 0 errors (**), 0 flaws (~~), 2 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Delay-Tolerant Networking E. Birrane 3 Internet-Draft E. DiPietro 4 Intended status: Informational D. Linko 5 Expires: January 1, 2019 Johns Hopkins Applied Physics Laboratory 6 June 30, 2018 8 AMA Application Data Model 9 draft-birrane-dtn-adm-03 11 Abstract 13 This document defines a physical data model that captures the 14 information necessary to asynchronously manage applications. This 15 model provides a set of common type definitions, data structures, and 16 a template for publishing standardized representations of model 17 elements. 19 Status of This Memo 21 This Internet-Draft is submitted in full conformance with the 22 provisions of BCP 78 and BCP 79. 24 Internet-Drafts are working documents of the Internet Engineering 25 Task Force (IETF). Note that other groups may also distribute 26 working documents as Internet-Drafts. The list of current Internet- 27 Drafts is at https://datatracker.ietf.org/drafts/current/. 29 Internet-Drafts are draft documents valid for a maximum of six months 30 and may be updated, replaced, or obsoleted by other documents at any 31 time. It is inappropriate to use Internet-Drafts as reference 32 material or to cite them other than as "work in progress." 34 This Internet-Draft will expire on January 1, 2019. 36 Copyright Notice 38 Copyright (c) 2018 IETF Trust and the persons identified as the 39 document authors. All rights reserved. 41 This document is subject to BCP 78 and the IETF Trust's Legal 42 Provisions Relating to IETF Documents 43 (https://trustee.ietf.org/license-info) in effect on the date of 44 publication of this document. Please review these documents 45 carefully, as they describe your rights and restrictions with respect 46 to this document. Code Components extracted from this document must 47 include Simplified BSD License text as described in Section 4.e of 48 the Trust Legal Provisions and are provided without warranty as 49 described in the Simplified BSD License. 51 Table of Contents 53 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 54 1.1. Scope . . . . . . . . . . . . . . . . . . . . . . . . . . 3 55 2. Requirements Language . . . . . . . . . . . . . . . . . . . . 4 56 3. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4 57 4. Data Modeling Concept of Operations . . . . . . . . . . . . . 5 58 5. Asynchronous Management Model (AMM) . . . . . . . . . . . . . 6 59 5.1. The AMM Resource Identifier (ARI) . . . . . . . . . . . . 6 60 5.1.1. Namespaces . . . . . . . . . . . . . . . . . . . . . 7 61 5.1.2. Object Names . . . . . . . . . . . . . . . . . . . . 9 62 5.1.3. Parameters . . . . . . . . . . . . . . . . . . . . . 9 63 5.1.4. Special Case: Literal Values . . . . . . . . . . . . 10 64 5.1.5. String Canonical Forms . . . . . . . . . . . . . . . 11 65 5.1.6. Examples . . . . . . . . . . . . . . . . . . . . . . 12 66 5.2. AMM Type Definitions . . . . . . . . . . . . . . . . . . 15 67 5.2.1. Primitive Types . . . . . . . . . . . . . . . . . . . 15 68 5.2.2. Derived Types . . . . . . . . . . . . . . . . . . . . 15 69 5.2.3. Collections . . . . . . . . . . . . . . . . . . . . . 17 70 5.3. Object Definitions . . . . . . . . . . . . . . . . . . . 18 71 5.3.1. Common Object Metadata . . . . . . . . . . . . . . . 18 72 5.3.2. Externally Defined Data (EDD) . . . . . . . . . . . . 19 73 5.3.3. Constant (CONST) . . . . . . . . . . . . . . . . . . 19 74 5.3.4. Control (CTRL) . . . . . . . . . . . . . . . . . . . 20 75 5.3.5. Macro (MAC) . . . . . . . . . . . . . . . . . . . . . 21 76 5.3.6. Operator (OP) . . . . . . . . . . . . . . . . . . . . 21 77 5.3.7. Reports . . . . . . . . . . . . . . . . . . . . . . . 23 78 5.3.8. State-Based Rule (SBR) . . . . . . . . . . . . . . . 24 79 5.3.9. Tables . . . . . . . . . . . . . . . . . . . . . . . 25 80 5.3.10. Time-Based Rule (TBR) . . . . . . . . . . . . . . . . 27 81 5.3.11. Variable (VAR) . . . . . . . . . . . . . . . . . . . 28 82 5.3.12. Common Object Processing . . . . . . . . . . . . . . 29 83 5.4. Data Type Mnemonics and Enumerations . . . . . . . . . . 30 84 5.4.1. AMM Objects . . . . . . . . . . . . . . . . . . . . . 30 85 5.4.2. Primitive Data Types . . . . . . . . . . . . . . . . 31 86 5.4.3. Compound Data Types . . . . . . . . . . . . . . . . . 32 87 5.4.4. Numeric Promotions . . . . . . . . . . . . . . . . . 33 88 5.4.5. Numeric Conversions . . . . . . . . . . . . . . . . . 33 89 6. JSON ADM Template . . . . . . . . . . . . . . . . . . . . . . 33 90 6.1. ADM Inclusion . . . . . . . . . . . . . . . . . . . . . . 34 91 6.2. ADMT Object Collections . . . . . . . . . . . . . . . . . 34 92 6.3. ADM Metadata . . . . . . . . . . . . . . . . . . . . . . 35 93 6.4. Type Encodings . . . . . . . . . . . . . . . . . . . . . 36 94 6.4.1. Primitive Type Encoding . . . . . . . . . . . . . . . 36 95 6.4.2. Derived Type Encoding . . . . . . . . . . . . . . . . 36 96 6.4.3. Collection Encoding . . . . . . . . . . . . . . . . . 37 97 6.5. ARI Encoding . . . . . . . . . . . . . . . . . . . . . . 38 98 6.6. ADM Structures . . . . . . . . . . . . . . . . . . . . . 40 99 6.6.1. General Notes . . . . . . . . . . . . . . . . . . . . 40 100 6.6.2. Constant (CONST) Encoding . . . . . . . . . . . . . . 41 101 6.6.3. Control (CTRL) Encoding . . . . . . . . . . . . . . . 41 102 6.6.4. Externally Defined Data (EDD) Encoding . . . . . . . 42 103 6.6.5. Macro Encoding . . . . . . . . . . . . . . . . . . . 43 104 6.6.6. Operator (OP) Encoding . . . . . . . . . . . . . . . 43 105 6.6.7. Table Template (TBLT) Encoding . . . . . . . . . . . 44 106 6.6.8. Report Template Encoding . . . . . . . . . . . . . . 44 107 6.6.9. Variables Encoding . . . . . . . . . . . . . . . . . 46 108 6.6.10. Exemptions . . . . . . . . . . . . . . . . . . . . . 47 109 7. ADM Author Considerations . . . . . . . . . . . . . . . . . . 47 110 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 49 111 9. Security Considerations . . . . . . . . . . . . . . . . . . . 49 112 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 49 113 10.1. Normative References . . . . . . . . . . . . . . . . . . 49 114 10.2. Informative References . . . . . . . . . . . . . . . . . 49 115 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 50 117 1. Introduction 119 The Asynchronous Management Architecture (AMA) [I-D.birrane-dtn-ama] 120 defines a concept for the open-loop control of applications (and 121 protocols) in situations where timely, highly-available connections 122 cannot exist amongst managing and managed nodes in a network. While 123 the AMA provides a logical data model, it does not include the 124 detailed information necessary to produce interoperable data models. 126 1.1. Scope 128 This document defines a physical data model suitable for managing 129 applications in accordance with the AMA. This physical model is 130 termed the Asynchronous Management Model (AMM) and consists of the 131 data types and data structures needed to manage applications in 132 asynchronous networks. 134 This document also provides a template, called the Application Data 135 Model Template (ADMT), for the standardized representation of 136 application-specific instances of this model. Using the types and 137 structures defined by the AMM, individual applications can capture 138 their unique, static management information in documents compliant 139 with the ADMT. These application-specific documents are called 140 Application Data Models (ADMs). 142 The AMM presented in this document does not assume any specific type 143 of application or underlying network encoding. In order to 144 communicate model elements between AMA Agents and Managers in a 145 network, the model must be encoded for transmission. Any such 146 encoding scheme is outside of the scope of this document. Generally, 147 the encoding of the model is a separate concern from the 148 specification of data within the model. 150 Because different networks may use different encodings for data, 151 mandating an encoding format would require incompatible networks to 152 encapsulate data in ways that could introduce inefficiency and 153 obfuscation. It is envisioned that different networks would be able 154 to encode ADMs in their native encodings such that the translation of 155 ADM data from one encoding to another can be completed using 156 mechanical action taken at network borders. 158 Since the specification does not mandate an encoding format, the AMM 159 and ADMT must provide enough information to make encoding (and 160 translating from one encoding to another) an unambiguous process. 161 Therefore, where necessary, this document provides identification, 162 enumeration and other schemes that ensure ADMs contain enough 163 information to prevent ambiguities caused by different encoding 164 schemes. 166 2. Requirements Language 168 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 169 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 170 document are to be interpreted as described in [RFC2119]. 172 3. Terminology 174 Note: The terms "Actor", "Agent", "Externally Defined Data", 175 "Variable", "Constant", Control", "Literal", "Macro", "Manager", 176 "Operator", "Report", "Report Template", "Rule", "State-Based Rule", 177 "Table", "Table Template", and "Time-Based Rule" are used without 178 modification from the definitions provided in the 179 [I-D.birrane-dtn-ama]. 181 Additional terms defined in this document are as follows. 183 o Application - A software implementation running on an Agent and 184 being managed by a Manager. This includes software that 185 implements protocol processing on an Agent. 187 o Application Data Model (ADM) - The set of statically-defined data 188 items necessary to manage an application asynchronously. 190 o Application Data Model Template (ADMT) - A standard format for 191 expressing predefined data items for an application. 193 o AMM Resource Identifier (ARI) - A unique identifier for any AMM 194 object, syntactically conformant to the Uniform Resource 195 Identifier (URI) syntax documented in [RFC3986] and using the 196 scheme name "ari". 198 o ADM Namespace - A moderated, hierarchical taxonomy of namespaces 199 that describe a set of ADM scopes. Specifically, an individual 200 ADM namespace is a specific sequence of ADM namespaces, from most 201 general to most specific, that uniquely and unambiguously identify 202 the namespace of a particular ADM. 204 o Operational Data Model (ODM) - The operational configuration of an 205 Agent. This includes the union of all ADM information supported 206 by the Agent as well as all operational, dynamic configuration 207 applied to the Agent by Managers in the network. 209 4. Data Modeling Concept of Operations 211 In order to asynchronously manage an application in accordance with 212 the [I-D.birrane-dtn-ama], an application-specific data model must be 213 created containing any predefined management information for that 214 application. This model is termed the Application Data Model (ADM) 215 and forms the core set of information for that application in 216 whichever network it is deployed. The ADM syntactically conforms to 217 the ADMT and uses the data structures and types that comprise the 218 AMM. 220 The information standardized in the ADM represents static 221 configurations and definitions that apply to any deployment of the 222 application, regardless of the network in which it is operating. 223 Within any given network, Managers supplement the information 224 provided by ADMs with dynamic definitions and values. The 225 operational configuration of the network is the union of all 226 supported ADMs and all Manager-defined dynamic configurations. This 227 is termed the Operational Data Model (ODM). 229 The relationships amongst the AMM, ADMT, and ADM are illustrated in 230 Figure 1. 232 Data Model Relationship 234 +---------+ +---------+ 235 | AMM |-------------->| ADMT | 236 +----+----+ +----+----+ 237 | | 238 | +----------+-------------+ 239 V | | | 240 +----------+ V V V 241 | Network | +-------+ +-------+ +-------+ 242 | Specific | | ADM 1 | | ADM 2 | ... | ADM N | 243 | Config. | +---+---+ +---+---+ +---+---+ 244 +----+-----+ | | | 245 | | | | 246 V V V V 247 +---------------------------------------------+ 248 | ODM | 249 +---------------------------------------------+ 251 Figure 1 253 In this figure, AMM data types and structures form the common 254 elements of the management model used by both ADMs and network 255 specific configurations. Together, the set of static information 256 provided by the union of all supported ADMs with the set of operator- 257 specified dynamic AMM objects, forms the operational data model used 258 to manage the network. 260 5. Asynchronous Management Model (AMM) 262 This section describes the Asynchronous Management Model, which is 263 the set of objects used to implement the logical data model provided 264 by the AMA. This section also provides additional information 265 necessary to work with this model, such as data type specifications, 266 identifier constructs, and naming conventions. 268 5.1. The AMM Resource Identifier (ARI) 270 Every object in the AMM must be uniquely identifiable, regardless of 271 whether the item is defined formally in an ADM document or informally 272 by operators in the context of a specific network deployment. The 273 AMM Resource Identifier (ARI) uniquely identifies AMM objects. 275 There are three components to the ARI: namespaces, object names, and 276 parameters. This section defines each of these components, discusses 277 special cases, and presents a string canonicalization of these 278 identifiers, with examples. 280 5.1.1. Namespaces 282 AMM objects exist within unique namespaces to prevent conflicting 283 names within network deployments, particularly in cases where network 284 operators are allowed to define their own object names. In this 285 capacity, namespaces exists to eliminate the chance of a conflicting 286 object name. They MUST NOT be used as a security mechanism. An 287 Agent or Manager MUST NOT infer security information or access 288 control based solely on namespace information. 290 The AMM defines three ways to identify namespaces for AMM object 291 names: Moderated Namespaces, Anonymous Namespaces, and Issuer 292 Namespaces. 294 5.1.1.1. Moderated Namespaces 296 The most effective way to ensure the uniqueness of an AMM Object is 297 to name it in the context of a moderated namespace. These namespaces 298 are assigned by an overseeing organization as part of a maintained 299 namespace registry. 301 Moderated namespaces are hierarchical, which allows the grouping of 302 objects that share common attributes - for example, objects 303 associated with related protocols may have protocol-specific 304 namespaces that are grouped under a single encompassing namespace. 305 Namespaces that are closer to a root node in the moderated hierarchy 306 have broader scope than namespaces closer to leaf nodes in that 307 hierarchy. There is no requirement that the namespace hierarchy be 308 represented as a single tree structure; multiple root nodes are 309 acceptable and likely to exist. 311 In a hierarchical model of namespaces, a particular namespace can be 312 identified as the path to that namespace through the hierarchy. The 313 expression of that path within an ADM is accomplished by listing each 314 namespace along the path, separated by the tokenizing character "/". 315 For example, consider the namespaces in the following figure. 317 +-------+ +-------+ 318 | TOP-A | | TOP-B | 319 +---+---+ +---+---+ 320 | _____|_____ 321 | | | 322 +-------+ +-------+ +-------+ 323 | MID-A | | MID-B | | MID-C | 324 +-------+ +-------+ +-------+ 325 _________|_________ | | 326 | | | | | 327 +-------+ +-------+ +-------+ +-------+ +-------+ 328 | LOW-A | | LOW-B | | LOW-C | | LOW-A | | LOW-A | 329 +-------+ +-------+ +-------+ +-------+ +-------+ 331 Given this hierarchy, the following are all valid namespace 332 representations. 334 TOP-A/ 336 TOP-A/MID-A 338 TOP-A/MID-A/LOW-A 340 TOP-B/MID-B/LOW-A 342 TOP-B/MID-C/LOW-A 344 Moderated namespaces require resources to review and publish and are 345 best suited for static AMM object definitions, such as those found in 346 ADMs. 348 5.1.1.2. Anonymous Namespaces 350 It is possible for network operators to define AMM objects that are 351 not associated with a namespace. In this case, a nil namespace can 352 be defined. This special case is considered the use of an 353 "anonymous" namespace. 355 Policy decisions as to whether anonymous namespaces are allowed in 356 the system should be determined before network deployment. The use 357 of an anonymous namespace greatly increases the chances of naming 358 collisions. 360 5.1.1.3. Informal Namespaces 362 Network-specific configurations, as illustrated in Figure 1, are 363 dynamic, ephemeral, not captured in published ADMs, and do not use 364 moderated namespaces. Instead, AMM objects that comprise network- 365 specific configuration can be uniquely differentiated as a function 366 of their "Issuer" and an issuer-specific "Tag". 368 An Issuer is any string that identifies the organization that is 369 defining an AMM object. This value may come from a global registry 370 of organizations, an issuing node address, a signed known value, or 371 some other network-unique marking. Issuers MUST NOT conflict with 372 known moderated namespaces, and Agents and Managers should not 373 process Issuers that conflict with existing moderated namespaces. 375 A Tag is any string used to disambiguate AMM Objects for an Issuer. 376 The contents of the tag are left to the discretion of the Issuer. 377 Examples of potential tag values include an issuer-known version 378 number or a (signed) hashing of the data item associated with the 379 reference identifier. 381 5.1.2. Object Names 383 Object names are strings whose value is determined by the creator of 384 the object. For those objects defined in accordance with the ADMT 385 Template, the structure of the object name is given in Section 5.3.1. 387 5.1.3. Parameters 389 Parameterization is used in the AMM to enable expressive autonomous 390 function and reduce the amount of traffic communicated between 391 Managers and Agents. In the AMM, most objects can be parameterized 392 and the meaning of parameterization for each object is described in 393 detail in Section 5.3. 395 If there are two instances of an AMM object that have the same 396 namespace and same object name but have different parameters, then 397 those instances are both unique and the ARIs for those instances MUST 398 also be unique. Therefore, parameters are considered part of an AMM 399 object's identifier. 401 There are two types of parameters defined in the AMM: Formal and 402 Actual parameters. The terms formal parameter and actual parameter 403 follow common computer programming vernacular for discussing function 404 declarations and function calls, respectively. 406 5.1.3.1. Formal Parameters 408 Formal parameters define the type, name, and order of the information 409 that customizes an AMM Object. They represent the unchanging 410 "definition" of the parameterized object. 412 Formal parameters MUST include type and name information and MAY 413 include an optional default value. If specified, a default value 414 will be used whenever a set of actual parameters fails to provide a 415 value for this formal parameter. 417 5.1.3.2. Actual Parameters 419 Actual parameters represent the data values passed to a parameterized 420 AMM Object. They "fulfill" the parameter requirements defined by the 421 formal parameters for that object. 423 An actual parameter MUST specify a value and MAY specify a type. If 424 a type is provided it MUST match the type provided by the formal 425 parameter. An actual parameter MUST NOT include NAME information. 427 There are two ways in which the value of an actual parameter can be 428 specified: parameter-by-value and parameter-by-name. 430 Parameter-By-Value 431 This method involves directly supplying the value as part of 432 the actual parameter. It is the default method for supplying 433 values. 435 Parameter-By-Name 436 This method involves specifying the name of some other 437 parameter and using that other parameter's value for the 438 value of this parameter. This method is useful when a 439 parameterized AMM Object contains another parameterized AMM 440 Object. The contained object's actual parameter can be given 441 as the name of the containing object's parameter. In that 442 way, a containing object's parameters can be "pass down" to 443 all of the objects it contains. 445 5.1.3.3. Optional Parameters 447 In cases where a formal parameter contains a default value, the 448 associated actual parameter may be omitted. Default values in formal 449 parameters (and, thus, optional actual parameters) are encouraged as 450 they reduce the size of data items communicated amongst Managers and 451 Agents in a network. 453 5.1.4. Special Case: Literal Values 455 As defined in the AMA, Literal values are those whose value and 456 identifier are equivalent. For example, the literal "4" serves as 457 both an identifier and a value. When literal values are used in 458 objects in the AMM, they are able to have a simplified identification 459 scheme. 461 Because the value of a Literal object serves as its identifier, there 462 is no need for namespaces, object names, or parameters. A literal 463 can be completely identified by its data type and data value. Since 464 Literals in the AMA are used to identify primitive data types, the 465 type of a Literal identifier MUST be as described in Table 2. 467 5.1.5. String Canonical Forms 469 While there may exist multiple encodings of an ARI, to include the 470 JSON encodings presented in Section 6 and other binary encodings in 471 other specifications, this section defines a universal string 472 representation of the ARI, as such a representation is helpful to 473 express examples in this and other documents. 475 This representation is not prescriptive; other string encodings may 476 exist that differ from the one used in this document. 478 5.1.5.1. General ARI String Representation 480 The String Canonical Form of the ARI is expressed as a Uniform 481 Resource Identifier (URI), as documented in [RFC3986]. A URI is 482 syntactically decomposed into a scheme name and a scheme-specific 483 part. The set of known scheme names is moderated by IANA. The 484 scheme-specific part of the URI is dependent on the scheme name. 486 The scheme name of the ARI is "ari". The scheme-specific part of the 487 "ari" scheme follows the format: 489 ari://<(Parameters)> 491 With the string representation of each scheme given as follows. 493 Namespaces 494 Namespaces are represented as "/" separated lists, with 495 individual namespace types represented as follows: 497 * Moderated namespaces are listed in order from the most 498 general namespace to the most specific namespace. For 499 example: "GENERAL/MIDDLE/SPECIFIC/". 501 * Anonymous namespaces are empty and are represented as "/". 503 * Informal namespaces follow the general pattern of 504 moderated namespaces - starting with the general Issuer 505 followed by the more specific issuer tag. For example: 506 "Issuer/Tag". In cases where the Tag is omitted, then the 507 representation is simply "Issuer/". 509 Object Names 510 The object name is a string as specified in Section 5.3.1. 512 Parameters 513 If present, parameters are represented as a comma-separated 514 string enclosed in parenthesis. Different types of 515 parameters are represented as follows. 517 * Formal parameters follow the pattern and if 518 there is a default value, it is represented by the 519 substring "= ". 521 * Actual Parameters-By-Value are represented as the string 522 encoding of their value. 524 * Actual Parameters-By-Name are represented as the name of 525 the parameter enclosed in angle brackets. 527 Note: If an actual parameter is missing for a formal 528 parameter that has a default value, then the ARI string MUST 529 have a blank space where the actual parameter would have 530 been. This missing parameter will also have a comma, 531 separating it from other actual parameters in the ARI string. 533 5.1.5.1.1. Shortform Encoding 535 In cases where a default namespace can be assumed (for example, in 536 the context of an ADM with a defined namespace) the prefix 537 ari:/Namespace/ can be omitted. 539 5.1.5.2. Literal String Encoding 541 The string representation of a Literal ARI is much simpler and 542 consists of simply the data type of the Literal followed by the 543 value, as follows: 545 "(type) value" 547 5.1.6. Examples 549 The ARIs for the following sample AMM objects are encoded in Table 1. 550 Note that these examples are for the identifiers of AMM objects, not 551 their entire definition. 553 o The number of bytes received by an Agent, defined in the N1/N2 554 namespace and called num_bytes. 556 o The number of bytes received through an interface, called 557 num_bytes_if, which takes a single string parameter named 558 "if_name" with a default value oth "eth0". 560 o An anonymous, operator-defined object named "obj1" which takes two 561 unsigned integer parameters, n1 and n2, with default values of 3 562 and 4, respectively. 564 o The typed, Literal value of 4. 566 +------------------------+------------------------------------------+ 567 | ARI String | Description | 568 +------------------------+------------------------------------------+ 569 | "ari:N1/N2/num_bytes" | Unparameterized num_bytes object in the | 570 | | N1/N2 namespace. | 571 | | | 572 | "num_bytes" | Shortform encoding where the N1/N2 | 573 | | namespace can be assumed. | 574 | | | 575 | "num_bytes_if(String | Formal parameter definition of num_bytes | 576 | if_name)" | object that accepts a string interface | 577 | | name. | 578 | | | 579 | "num_bytes_if(String | Formal parameter definition of num_bytes | 580 | if_name=eth0)" | object that accepts a string interface | 581 | | name with a default value. | 582 | | | 583 | "num_bytes_if()" | Actual parameter using the default value | 584 | | of eth0. | 585 | | | 586 | "num_bytes_if(eth0)" | Actual parameter of eth0. | 587 | | | 588 | "ari:/obj1(Int n1 = 0, | Formal parameter of object obj1 in | 589 | Int n2 = 3)" | anonymous namespace taking 2 default | 590 | | parameters. | 591 | | | 592 | "ari:/obj1(, )" | Actual parameter using the default | 593 | | values of 0 for n1 and 3 for n2. | 594 | | | 595 | "ari:/obj1(, 4)" | Actual parameter using the default value | 596 | | of 0 for n1. | 597 | | | 598 | "ari:/obj1(4, )" | Actual parameter using the default value | 599 | | of 3 for n2. | 600 | | | 601 | "ari:/obj1(4,4)" | Actual parameters provided for all obj1 | 602 | | parameters. | 603 | | | 604 | "ari:/obj1(,4)" | Actual parameters provided for all obj1 | 605 | | parameters, with the value of the first | 606 | | parameter taken from some other | 607 | | parameter named "input". | 608 | | | 609 | "(UINT) 4" | The Literal value 4 interpreted as a | 610 | | 32-bit unsigned integer. | 611 +------------------------+------------------------------------------+ 613 Table 1 615 5.2. AMM Type Definitions 617 This section describes the type definitions used by the AMM. 619 5.2.1. Primitive Types 621 The AMM supports a series of primitive types as outlined in Table 2. 623 +--------------------+----------------------------------------------+ 624 | Type | Description | 625 +--------------------+----------------------------------------------+ 626 | BYTE | unsigned byte value | 627 | | | 628 | INT | 32-bit signed integer in 2's complement | 629 | | | 630 | UINT | 32-bit unsigned integer in 2's complement | 631 | | | 632 | VAST | 64-bit signed integer in 2's complement | 633 | | | 634 | UVAST | 64-bit unsigned integer in 2's complement | 635 | | | 636 | REAL32 | Single-precision, 32-bit floating point | 637 | | value in IEEE-754 format. | 638 | | | 639 | REAL64 | Double-precision, 64-bit floating point | 640 | | value in IEEE-754 format. | 641 | | | 642 | STRING | NULL-terminated series of characters in | 643 | | UTF-8 format. | 644 | | | 645 | BOOL | A Boolean value of FALSE (whose integer | 646 | | interpretation is 0) or TRUE (whose integer | 647 | | interpretation is not 0). | 648 +--------------------+----------------------------------------------+ 650 Table 2: Primitive Types 652 5.2.2. Derived Types 654 A derived typed is a primitive type that is interpreted with special 655 semantics. The AMM supports the following derived types. 657 5.2.2.1. Byte String 659 A Byte String is a specialization of the String primitive data type 660 used to store binary data using base64 encoding as defined in 661 [RFC4648]. 663 5.2.2.2. Time Values (TV) and Timestamps (TS) 665 A Time Value (TV) is a specialization of the String primitive data 666 type whose time interpretation is as given in this section. There 667 are two "types" of time representations within the AMM: relative 668 times and absolute times. 670 An absolute time represents an instant in time. It MUST be formatted 671 as a date-time in accordance with [RFC3339]. 673 A relative time is defined as the amount of time after an instant in 674 time. A relative time MUST be formatted as a full-time in accordance 675 with [RFC3339]. Relative times have advantages over absolute times: 676 they do not require time to be synchronized across Agents and 677 Managers, and they are more compact in their representation. For 678 example, expressing the semantics "run control_one 10 seconds after 679 receiving it" or "run control_two 20 seconds after running 680 control_one" is more appropriate using relative times than absolute 681 times. The initiating event of a relative time MUST be unambiguously 682 defined in the context using the time value. 684 As a practical matter, encodings of relative times MAY impose a limit 685 of no more than 17 years of relative time, which corresponds to 686 roughly 29 bits of information and is considered well past an upper 687 bound of efficiency for using a relative time versus an absolute 688 time. 690 An absolute time may be differentiated from a relative time based on 691 whether the time specification is a date-time or a full-time. 693 For example, "00:00:10Z" is a relative time representing 10 seconds 694 after an initiating event. "2019-01-01T08:00:00Z" is an absolute 695 time that refers to 8am, Tuesday January 1st, 2019. 697 A Timestamp (TS) represents a specific point in time when an event 698 occurred. As such, it MUST be represented as an absolute time. 700 5.2.2.3. Type-Name-Value (TNV) 702 A Type-Name-Value (TNV) is a three-tuple of information that 703 describes a typed, named value in the AMM. Since the length of a 704 data value is a matter of encoding, there is not an explicit length 705 field present for the data value; it is assumed that any encoding 706 scheme either explicitly encodes length or that the length is self- 707 delineating in the encoding. 709 o Type - The strong typing for this value. Types MUST be one of 710 those defined in Section 5.4. 712 o Name - A unique identifier for this value. 714 o Value - The value of the data item. 716 5.2.2.4. User-Specified Derived Types 718 Individual ADMs and network operators may derive other types that 719 specialize the types provided by the AMM. When doing so, AMM data 720 types MUST be used to capture the specialization and any user- 721 specific verification or validation MUST occur in user-specific 722 implementations on Agents and Managers. 724 5.2.3. Collections 726 AMM objects, or parameters associated with those objects, often need 727 to represent groups of related information. Since the AMM is 728 strongly typed, these groups of related information are represented 729 by special data types called collections. AMM collections are 730 ordered and may contain duplicate entries. 732 The AMM defines three typed collections that capture TNVs, ARIs, and 733 mathematical expressions. 735 5.2.3.1. Type-Name-Value Collection (TNVC) 737 A Type-Name-Value Collection (TNVC) is an ordered array where each 738 element of the array is a TNV. 740 TNVCs are often used to capture formal and actual parameters for AMM 741 objects. 743 5.2.3.2. ARI Collection (AC) 745 An ARI Collection (AC) is an ordered set of ARIs. 747 ACs are often used when there exists a need to refer to multiple AMM 748 objects as a single unit. For example, when defining a Report 749 Template, the definition may have an AC that defines the ordered ARIs 750 whose values constitute that report. 752 5.2.3.3. Expression (EXPR) 754 An Expression (EXPR) is a specialization of an AC where each ARI in 755 the collection is either an operand or an operator. These operands 756 and operators form a mathematical expression that is used to compute 757 a numerical value. 759 Within an Expression, an operand MUST be an ARI with one of the 760 following types: Literal, Constant, Externally Defined Data, or 761 Variable. An operator MUST be an ARI of type Operator. 763 Since the Expression is an AC, there are no annotative constructs 764 such as parenthesis to enforce certain orders of operation. To 765 preserve an unambiguous calculation of values, the ARIs that form an 766 Expression MUST be represented in postfix order. Postfix notation 767 requires no additional symbols to enforce precedence, always results 768 in a more efficient encoding, and post-fix engines can be implemented 769 efficiently in embedded systems. 771 For example, the infix expression A * (B * C) is represented as the 772 postfix A B C * *. 774 Expressions are often used when assigning values to a Variable or 775 when calculating the state of the Agent in the context of a State- 776 Based Rule. 778 5.3. Object Definitions 780 This section identifies the AMM Objects that instantiate the AMA 781 logical data model and the processing required to support these 782 objects at Agents and Managers in the network. 784 5.3.1. Common Object Metadata 786 Every object in the AMM includes a set of metadata providing 787 annotative or otherwise user-friendly descriptive information for the 788 object. This information may be used as documentation (for example, 789 only present in ADMs and on operator consoles) and/or encoded and 790 transmitted over the wire as part of a management protocol. 792 Metadata is not required to be unique amongst objects and individual 793 encodings MAY choose to not encode metadata in cases where the 794 information is not needed to uniquely identify objects. The metadata 795 supported by the AMM for objects is as follows: 797 (STR) Name 798 An object name is a string associated with the object, but 799 does not constitute the sole identifier for the object. 800 Names provide human-readable and/or user-friendly ways to 801 refer to objects within a given context. 803 (STR) Description 804 An object description is a string describing the purpose or 805 usage of the object in a human-readable format. The 806 description serves as documentation for the object and SHOULD 807 be the same regardless of how the object might be 808 parameterized. For example, the description of a CTRL object 809 should document the purpose of the CTRL in a way that is 810 independent of the value of any particular parameter value 811 passed to that CTRL. 813 5.3.2. Externally Defined Data (EDD) 815 Externally defined data (EDD), as defined in the AMA, represent data 816 values that are computed external to the network management system. 817 The definition of these values are solely defined in the context of 818 an ADM; since their calculation exists outside of the network 819 management system, they are not added or removed as part of the 820 dynamic configuration of the network management system. 822 An EDD consists of an ARI, type, and a description, with the 823 following caveats: 825 (ARI) Identifier 826 This Identifier MUST be of type EDD and MAY be parameterized, 827 particularly in cases where the specific computed value can 828 be identified by an associative look-up, as discussed in 829 Section 7. 831 (UINT) Type 832 The data type of the EDD value MUST be specified as part of 833 the EDD definition and this type MUST be one of the primitive 834 data types defined in Table 2. 836 (STR) Description 837 This represents the human-readable description of the EDD. 839 5.3.3. Constant (CONST) 841 Constants represent named basic values. Examples include common 842 mathematical values such as PI or well-known Epochs such as the UNIX 843 Epoch. Constants are defined solely within the context of ADMs. 844 Constants MUST NOT be defined as part of dynamic network 845 configuration. 847 Allowing network operators to define constants dynamically means that 848 a Constant could be defined, removed, and then re-defined at a later 849 time with a different value, which defeats the purpose of having 850 Constants. Variables MUST be used instead of Constants for the 851 purpose of adding new values to the dynamic network configuration. 853 A CONST is defined by its ARI, value, and description, with the 854 following caveats. 856 (ARI) Identifier 857 This Identifier MUST be of type CONST and MUST NOT be 858 parameterized. Parameterizing a Constant implies that its 859 value is dependent upon the set of parameters sent to it, 860 which defeats the purpose of defining a constant value. 862 (TNV) Typed Value 863 The value of a constant is the immutable value that should be 864 used in lieu of the Constant ARI. 866 This value is expressed as a TNV with the following 867 requirements. 869 * Type MUST be one of the primitive data types defined in 870 Table 2. 872 * Name MUSt be omitted as the CONST ARI defines the name for 873 this value. 875 * Value must be present and consistent with the data type 876 for this CONST. 878 (STR) Description 879 This represents the human-readable description of the CONST, 880 as a string. 882 5.3.4. Control (CTRL) 884 A Control represents a predefined function that can be run on an 885 Agent. Controls are not able to be defined as part of dynamic 886 network configuration since their execution is typically part of the 887 firmware or other implementation of the Agent outside of the context 888 of the network management system. 890 Network operators that wish to dynamically execute functions on an 891 Agent may use Macros, State-Based Rule, and Time-Based Rule instead. 893 Controls are identified by their ARI and their description, with the 894 following caveats. 896 (ARI) Identifier 897 This Identifier MUST be of type CTRL and MAY be parameterized 898 in cases where the function executed by that Control takes 899 parameters. 900 When defined in the context of an ADM, the Control ARI MUST 901 match the definition of a Formal Parameter list. This is 902 because the ADM defines the Controls that can be invoked, but 903 does not define any particular invocation of a Control. 905 When used as part of network operations, a Control ARI MUST 906 match the definition of an Actual Parameter list. This is 907 because when used operationally, a parameterized Control 908 required parameters to be run. 909 In cases where a Control takes no parameters, the definition 910 in the ADM document MUST be considered the definition of the 911 Control and the presence of the same ARI in the context of an 912 operational system MUST be seen as an invocation of that 913 Control. 915 (STR) Description 916 This represents the human-readable description of the 917 Control, as a string. 919 5.3.5. Macro (MAC) 921 Macros are ordered collections of Controls or other Macros. When run 922 by an Agent, each ARI in the AC is run in order. A Macro may be 923 defined as part of an ADM or as part of dynamic network 924 configuration. 926 In cases where a Macro contains another Macro, implementations MUST 927 implement some mechanism for preventing infinite recursions, such as 928 defining maximum nesting levels, performing Macro inspection, and/or 929 enforcing maximum execution times. 931 A Macro is defined by an ARI, a content definition, and a 932 description, as follows. 934 (ARI) Identifier 935 This Identifier MUST be of type MAC and MAY be parameterized 936 and, if so, the parameter may be passed-by-name to any 937 parameterized elements within the Macro. 939 (AC) Definition 940 The Macro definition is modeled as an AC, where each ARI 941 within the AC MUST be either a Control or a Macro. 943 (STR) Description 944 This represents the human-readable description of the Macro, 945 as a string. 947 5.3.6. Operator (OP) 949 Operators represent user-defined mathematical functions implemented 950 in the firmware of an Agent for the purpose of aiding the evaluation 951 of Expressions. 953 The AMM separates the concepts of Operators and Controls to prevent 954 side-effects in Expression evaluation (e.g. to avoid constructs such 955 as A = B + GenerateReport()). For this reason, Operators are given 956 their own structure type and Controls do not support a return value. 958 Because Operators represent custom firmware implemented on the Agent, 959 they are not defined dynamically as part of network operations. 960 Therefore, they may only be defined in an ADM. 962 An Operator is defined by its ARI, its resultant type, the number of 963 operands, the type of operands, and a description, as follows. 965 (ARI) Identifier 966 This Identifier MUST be of type OP and MUST NOT be 967 parameterized. Much like Constants, Operators represent 968 immutable mathematical functions. The operands of an 969 Operator are not considered as "parameters" to the Operator. 971 (UINT) Out Type 972 This is the return value of the Operator and MAY be different 973 than the operand types accepted by the Operator. This type 974 MUST be one of the primitive data types defined in Table 2. 976 (UINT) Num Operands 977 This is the number of operands evaluated by the operator. 978 For example, the unary NOT Operator ("!") would operate on a 979 single operand. The binary PLUS Operator ("+") would operate 980 on two operands. A custom operator to calculate the average 981 of the last 10 samples of data would operate on 10 operands. 983 (TNVC) In Types 984 This is the type information for each operand operated on by 985 the Operator, modeled as a TNV Collection (TNVC). There MUST 986 be one TNV in the TNVC for each operand, and each TNV MUST 987 adhere to the following requirements: 989 * The Type field MUST be present and MUST be one of the 990 primitive data types defined in Table 2. 992 * The Name field MAY be present to capture a semantic name 993 for the operand. 995 * The Value field MUST NOT be present. 997 (STR) Description 998 This represents the human-readable description of the 999 Operator, as a string. 1001 5.3.7. Reports 1003 A Report is a set of non-tabular, potentially nested data items that 1004 may be predefined in the context of an ADM, or defined dynamically in 1005 the context of a deployed network. 1007 Reports are represented in two ways in the AMM: Report Templates and 1008 Reports. A Report Template defines the type of information to be 1009 included in a report, and a Report contains that information. 1011 5.3.7.1. Report Template (RPTT) 1013 A Report Template (RPTT) is the ordered set of data descriptions that 1014 describe how values will be represented in a corresponding Report. 1015 RPTTs can be viewed as a schema that describes how to interpret a 1016 Report; they contain no values and are either defined in an ADM or 1017 configured between Managers and Agents during network operations. 1019 Since a RPTT may contain other RPTTs, implementations MUST implement 1020 some mechanism to prevent the definition of circular references. 1022 RPTTs are defined by an ARI, the report template definition, and a 1023 description, as follows. 1025 (ARI) Identifier 1026 This Identifier MUST be of type RPTT and MAY be parameterized 1027 and, if so, the parameter may be passed-by-name to any 1028 parameterized elements within the RPTT. 1030 (AC) Definition 1031 The Report Definition is modeled as an AC, where each ARI 1032 within the AC MUST identify either a CONST, LIT, EDD, VAR, or 1033 other RPTT. 1035 (STR) Description 1036 This represents the human-readable description of the Report 1037 template, as a string. 1039 5.3.7.2. Report (RPT) 1041 A Report (RPT) is a set of data values populated in conformance to a 1042 given data definition. Reports do not have an individual identifier 1043 - rather they are uniquely identified by their definition and the 1044 timestamp at which their data values were collected. 1046 RPTs are defined by their associated template, the time at which the 1047 report was generated, and the individual entries in the report, as 1048 follows. 1050 (ARI) Template Id 1051 This is the ARI of the object that defines the format of the 1052 report data values. This ARI MUST define an AMM object of 1053 type RPTT, EDD, or VAR, or CTRL. 1054 If this ARI is parameterized, this ARI MUST include the 1055 actual parameters used in the generation of the report. 1057 (TV) Generation Time 1058 This is the absolute time at which the report was generated 1059 by the Agent. 1061 (TNVC) Report Entries 1062 This is the collection of data values that comprise the 1063 report. If the template for this report is an EDD, VAR, or 1064 CTRL then there MUST be one entry for this report. If the 1065 template is a RPTT, then there MUST be one entry for every 1066 item defined in the template. 1067 Entries are modeled as a TNVC, with each TNV representing a 1068 report entry with the following requiremnts. 1070 * Type MAY be ommitted in cases where checking type safety 1071 is not required. 1073 * Name MAY be omitted in cases where a semantic name for the 1074 entry can be derived from the template. 1076 * Value MUST be present and consistent with the type for 1077 this entry from the associated template item. 1079 5.3.8. State-Based Rule (SBR) 1081 A State-Based Rule (SBR) specifies that starting at a particular time 1082 an action should be run by the Agent if some condition evaluates to 1083 true, until the action has been run a maximum number of times. When 1084 the SBR is no longer valid it MAY be discarded by the Agent. 1086 Examples of SBRs include: 1088 Starting 2 hours from receipt, whenever Variable V1 > 10, produce 1089 a Report Entry for Report Template R1 no more than 20 times. 1091 Starting at some future absolute time, whenever Variable V2 != 1092 Variable V4, run Macro M1 no more than 36 times. 1094 SBRs are defined by their ARI, start time, condition, maximum run 1095 count, action, and description, as follows. 1097 (ARI) Identifier 1098 This Identifier MUST be of type SBR and MUST NOT be 1099 parameterized. 1101 (TV) START 1102 The time at which the SBR condition should start to be 1103 evaluated. This will mark the first evaluation of the 1104 condition associated with the SBR. 1106 (EXPR) CONDITION 1107 The Expression which, if true, results in the SBR running the 1108 associated action. An Expression is considered true if it 1109 evaluates to a non-zero number. 1111 (UVAST) COUNT 1112 The number of times the SBR action can be run. The special 1113 value of 0 indicates there is no limit on how many times the 1114 action can be run. 1116 (AC) ACTION 1117 The collection of Controls and/or Macros to run as part of 1118 the action. This is captured as an AC data type with the 1119 constraint that every ARI within the AC represent a Control 1120 or Macro. 1122 (STR) Description 1123 This represents the human-readable description of the SBR, as 1124 a string. 1126 5.3.9. Tables 1128 A Table is a named, typed, collection of tabular data. Columns 1129 within a table are named and typed. Rows within a table capture 1130 individual data sets with one value in each row corresponding to one 1131 column in the table. Tables are represented in two ways in the AMM: 1132 Table Templates and Table Instances. 1134 5.3.9.1. Table Template (TBLT) 1136 A table template identifies the strongly-typed column template that 1137 will be followed by any instance of this table available in the 1138 network. Table templates appear statically in ADMs and may not be 1139 created dynamically within the network by Managers. Changing a table 1140 template within an asynchronously managed network would result in 1141 confusion if differing template definitions for the same table 1142 identifier were to be active in the network at one time. 1144 TBLTs are defined by an ARI, a set of column descriptions, and table 1145 metadata, as follows. 1147 (ARI) Identifier 1148 This Identifier MUST be of type TBLT and MUST be of type 1149 TBLT, and MUST NOT contain parameters. 1151 (TNVC) Columns 1152 A TBLT is defined by its ordered set of columns descriptions 1153 captured as a TNVC with each TNV in the collection describing 1154 a table column with the following requirements. 1156 * Type MUST be present and MUST be one of the primitive 1157 types defined in Table 2. 1159 * Name MAY be omitted in cases where a semantic name for the 1160 column can be derived from the template. 1162 * Value MUST NOT be present as a column does not contain 1163 data values. 1165 (STR) Description 1166 This represents the human-readable description of the TBLT, 1167 as a string. 1169 5.3.9.2. Table (TBL) 1171 Tables are collections of data that MUST be constructed in accordance 1172 with an associated Table Template. Tables MUST NOT appear in the ADM 1173 for an application; they are only instantiated dynamically as part of 1174 the operation of a network. 1176 TBLs are defined by their Table Template, the number of rows in the 1177 table, and the associated set of data values for each row. 1179 (ARI) Template Id 1180 This is the ARI of the Table Template holding the column 1181 definitions for this table. This ARI MUST be of type TBLT 1182 and match a known Table Template. 1184 (UINT) Number of Rows 1185 This is the number of rows in the table. A Table MAY have 1186 zero rows. 1188 (TNVC) Rows Information 1189 Each row in a TBL is represented by a TNVC, with each TNV in 1190 the collection representing the value for a specific column 1191 with the following requirements. 1193 * Type MAY be present, when necessary to verify that 1194 elements in the row match the types of table columns. 1196 * Name MUST NOT be present. 1198 * Value MUST be present and compatible with the type of the 1199 associated column. 1200 The number of TNVs in the collection MUST be equal to the 1201 number of columns defined for the Table Template. 1203 5.3.10. Time-Based Rule (TBR) 1205 A Time-Based Rule (TBR) specifies that starting at a particular start 1206 time, and for every period seconds thereafter, an action should be 1207 run by the Agent until the action has been run for count times. When 1208 the TBR is no longer valid it MAY be discarded by the Agent. 1210 Examples of TBRs include: 1212 Starting 2 hours from receipt, produce a Report for Report 1213 Template R1 every 10 hours ending after 20 times. 1215 Starting at the given absolute time, run Macro M1 every 24 hours 1216 ending after 365 times. 1218 TBRs are defined by their ARI, start time, period, maximum run count, 1219 action, and description, as follows. 1221 (ARI) Identifier 1222 This Identifier MUST be of type TBR and MUST NOT be 1223 parameterized. 1225 (TV) Start 1226 The time at which the TBR should start to be evaluated. This 1227 will mark the first running of the action associated with the 1228 TBR. 1230 (TV) Period 1231 The time to wait between running the action associated with 1232 the TBR. This value MUST be a relative time value. 1234 (UVAST) Count 1235 The number of times the TBR action may be run. The special 1236 value of 0 indicates the TBR should continue running the 1237 action indefinitely. 1239 (AC) Action 1240 The collection of Controls and/or Macros to run by the TBR. 1241 This is captured as a AC with the constraint that every ARI 1242 within the AC represent a Control or Macro. 1244 (STR) Description 1245 This represents the human-readable description of the TBR, as 1246 a string. 1248 5.3.11. Variable (VAR) 1250 Variables (VAR) may be statically defined in an ADM or dynamically by 1251 Managers in a network deployment. VARs differ from EDDs in that they 1252 are completely described by other known data in the system (either 1253 other VARs or other EDDs). For example, letting E# be a EDD item and 1254 V# be a VAR item, the following are examples of VAR definitions. 1256 V1 = E1 * E2 1258 V2 = V1 + E3 1260 VARs are defined by an ARI, a type, an initializing expression, and a 1261 description, as follows. 1263 (ARI) Identifier 1264 The type of this ARI MUST be type VAR, and the ARI MUST NOT 1265 contain parameters. 1267 (UINT) Type 1268 This is the type of the VAR, and acts as a static cast for 1269 the result of the initializing EXPR. This type MUST be one 1270 of the data types defined in Table 2. 1271 Note, it is possible to specify a type different than the 1272 resultant type of the initializing EXPR. For example, if an 1273 EXPR adds two single-precision floating point numbers, the 1274 VAR MAY have an integer type associated with it. 1276 (EXPR) Initializer 1277 The initial value of the VAR is given by an initializing 1278 EXPR. In the case where the type of the VAR itself is EXPR, 1279 the initializer is used as the value of the VAR. In the case 1280 where the type of the VAR is anything other than EXPR, then 1281 the initializer EXPR will be evaluated and the result of that 1282 evaluation will be the initial value of the VAR. 1284 (STR) Description 1285 This represents the human-readable description of the VAR, as 1286 a string. 1288 5.3.12. Common Object Processing 1290 This section describes the handling and exchange of AMM objects 1291 between Agents and Managers in a network. 1293 Managers must: 1295 o Store the ARI and definitions for both network-specific and ADM- 1296 defined AMM Objects. 1298 o Send requests to Agents to add, list, describe, and remove custom 1299 AMM object definitions. 1301 o Verify and interpret reports against report templates and tables 1302 against table templates when receiving these objects from an 1303 Agent. 1305 o Encode ARIs in Objects to Agents, and decode ARIs from Agents. 1307 o Provide actual parameters when sending parameterized objects to an 1308 Agent. 1310 Agents must: 1312 o Store the ARI for all ADM-defined AMM objects. 1314 o Calculate the value of an AMM object when required, such as when 1315 generating a Report or evaluating an Expression. 1317 o Implement Controls in firmware and run Controls and Macros with 1318 appropriate parameters when necessary in the context of Manager 1319 direction and Rule execution. 1321 o Communicate "return" values from Controls back to Managers as 1322 Reports where appropriate. 1324 o Persist custom AMM object definitions. 1326 o Add, remove, list, and describe custom AMM objects as requested by 1327 Managers. 1329 o Calculate the value of applying an Operator to a given set of 1330 operands, such as when evaluating an Expression. 1332 o Populate Reports and Tables for transmission to Managers when 1333 required. 1335 o Run the actions associated with SBRs and TBRs in accordance with 1336 their definitions. 1338 o Calculate the value of VARs when required, such as during Rule 1339 evaluation, calculating other VAR values, and generating Reports. 1341 5.4. Data Type Mnemonics and Enumerations 1343 While the AMM does not specify any encoding of data model elements, a 1344 common set of enumerations help to ensure that various encoding 1345 standards can interoperate. 1347 This section defines string (mnemonic) and integer (enumeration) 1348 mechanisms for referring to AMM data and object types. Data types 1349 are separated into 4 major categories: 1351 Category Range 1352 ------------------ ------------ 1353 AMM Objects Types 0x00 - 0x0F 1355 Primitive Types 0x10 - 0x1F 1357 Compound Types 0x20 - 0x2F 1359 Reserved 0x30 - 0xFF 1361 Type Categories and Ranges 1363 Within each category, the type of information, it's mnemonic, unique 1364 enumeration value, and whether it is considered a numeric value for 1365 expression evaluation are listed. 1367 5.4.1. AMM Objects 1369 AMM Objects include the set of objects identifiable using the ARI 1370 construct. The type field of the ARI MUST be one of these values. 1371 AMM Objects MUST be identified as follows. 1373 Structure Mnemonic Enumeration Numeric 1374 ------------------------------- -------------- ----------- ---------- 1375 Constant CONST 0 No 1377 Control CTRL 1 No 1379 Externally Defined Data EDD 2 No 1381 Literal LIT 3 No 1383 Macro MAC 4 No 1385 Operator OPER 5 No 1387 Report RPT 6 No 1389 Report Template RPTT 7 No 1391 State-Based Rule SBR 8 No 1393 Table TBL 9 No 1395 Table Template TBLT 10 No 1397 Time-Based Rule TBR 11 No 1399 Variable VAR 12 No 1401 Reserved 13-15 No 1403 5.4.2. Primitive Data Types 1405 Primitive data include the basic set of objects that must be encoded 1406 to transfer AMM objects. All AMM objects are built from combinations 1407 of these primitive types. Primitive types MUST be identified as 1408 follows. 1410 Basic Data Type Mnemonic Enumeration Numeric 1411 ------------------------------- -------------- ----------- ---------- 1412 Boolean BOOL 16 No 1414 BYTE BYTE 17 No 1416 Character String STR 18 No 1418 Signed 32-bit Integer INT 19 Yes 1420 Unsigned 32-bit Integer UINT 20 Yes 1422 Signed 64-bit Integer VAST 21 Yes 1424 Unsigned 64-bit Integer UVAST 22 Yes 1426 Single-Precision Floating Point REAL32 23 Yes 1428 Double-Precision Floating Point REAL64 24 Yes 1430 Reserved 25-31 No 1432 5.4.3. Compound Data Types 1434 Compound data include combinations of primitive data types, to 1435 include collections. Compound types MUST be identified as follows. 1437 Compound/Special Data Type Mnemonic Enumeration Numeric 1438 ------------------------------- -------------- ----------- ---------- 1439 Time Value TV 32 No 1441 Timestamp TS 33 No 1443 Type-Name-Value TNV 34 No 1445 Type-Name-Value Collection TNVC 35 No 1447 AMM Resource Identifier ARI 36 No 1449 ARI Collection AC 37 No 1451 Expression EXPR 38 No 1453 Byte String BYTESTR 39 No 1455 Reserved - Protocol 40-47 No 1457 5.4.4. Numeric Promotions 1459 When attempting to evaluate operators of different types, an Agent 1460 may need to promote operands until they are of the correct type. For 1461 example, if an Operator is given both an INT and a REAL32, the INT 1462 should be promoted to a REAL32 before the Operator is applied. 1464 Listing legal promotion rules is mandatory for ensuring that behavior 1465 is similar across multiple implementations of Agents and Managers. 1466 The listing of legal promotions in the AMM are listed in Figure 2. 1467 In this Figure, operands are listed across the top row and down the 1468 first column. The resultant type of the promotion is listed in the 1469 table at their intersection. 1471 INT UINT VAST UVAST REAL32 REAL64 1472 +--------+--------+--------+--------+--------+--------+ 1473 INT | INT | INT | VAST | UNK | REAL32 | REAL64 | 1474 UINT | INT | UINT | VAST | UVAST | REAL32 | REAL64 | 1475 VAST | VAST | VAST | VAST | VAST | REAL32 | REAL64 | 1476 UVAST | UNK | UVAST | VAST | UVAST | REAL32 | REAL64 | 1477 REAL32 | REAL32 | REAL32 | REAL32 | REAL32 | REAL32 | REAL64 | 1478 REAL64 | REAL64 | REAL64 | REAL64 | REAL64 | REAL64 | REAL64 | 1479 +--------+--------+--------+--------+--------+--------+ 1481 Figure 2: Numeric Promotions 1483 The AMM does not permit promotions between non-numeric types, and 1484 numeric promotions not listed in this section are not allowed. Any 1485 attempt to perform an illegal promotion SHOULD result in an error. 1487 5.4.5. Numeric Conversions 1489 Variables, Expressions, and Predicates are typed values. When 1490 attempting to assign a value of a different type, a numeric 1491 conversion must be performed. Any numeric type may be converted to 1492 any other numeric type in accordance with the C rules for arithmetic 1493 type conversions. 1495 6. JSON ADM Template 1497 This section provides an ADM template in the form of a JSON document 1498 and describes the JSON representation of AMM objects that MUST be 1499 used to populate this JSON ADM template. 1501 It is not required that these JSON encodings be used to encode the 1502 transmission of AMM information over the wire in the context of a 1503 network deployment. It is also not required that only these JSON 1504 encodings be used to document ADMs and other AMM information. Since 1505 the AMM is designed to allow for multiple encodings, the expression 1506 of ADMs in the provided JSON format is intended to support 1507 translation to other encodings without loss of information. 1509 6.1. ADM Inclusion 1511 ADMs expressed in conformance with this template are captured as 1512 individual JSON files. AMM Objects defined in one ADM template MAY 1513 refer to objects defined in another ADM template file. To enable 1514 type checking of these cross-ADM references, the ADM template 1515 supports the "uses" keyword to identify other ADM files that contain 1516 objects referenced in the current ADM file. 1518 The syntax of the uses statement is as follows. 1520 "uses":["file1","file2",...,"fileN"] 1522 Where file_# represents a JSON-formatted ADM file defining a 1523 namespace used in this ADM file. 1525 6.2. ADMT Object Collections 1527 The JSON ADM Template is defined as a JSON object containing a series 1528 of arrays - one for each type of information specified in the 1529 template. There are arrays for: 1531 o metadata constants 1533 o EDD definitions 1535 o VAR definitions 1537 o RPTT definitions 1539 o TBLT definitions 1541 o CTRL definitions 1543 o CONST definitions 1545 o MAC definitions 1547 o OP definitions 1549 Where each array is named after the mnemonic for the particular AMM 1550 object, as defined in Section 5.4.1, with the exception of the 1551 metadata (MDAT) array which is unique to the ADM template itself. 1553 In particular, the template does not provide definitions for RPT, 1554 TBL, SBR, or TBR objects as these are defined dynamically in the 1555 context of a network deployment. 1557 The general format of the JSON ADM Template is as follows. 1559 { 1560 "Mdat" : [], 1561 "Edd" : [], 1562 "Var" : [], 1563 "Rptt" : [], 1564 "Tblt" : [], 1565 "Ctrl" : [], 1566 "Const : [], 1567 "Mac" : [], 1568 "Oper" : [] 1569 } 1571 6.3. ADM Metadata 1573 The metadata array contains CONST objects that provide information 1574 about the ADM itself. 1576 (STR) name 1577 This is the human-readable name of the ADM that should appear 1578 in message logs, user-interfaces, and other human-facing 1579 applications. 1581 (STR) namespace 1582 This is the Moderated Namespace of the ADM, as defined in 1583 Section 5.1.1 and string-encoded in accordance with 1584 Section 5.1.5.1. 1586 (STR) version 1587 This is a string representation of the version of the ADM. 1588 ADM version representations are formated at the discretion of 1589 the publishing organization. 1591 (STR) organization 1592 This is the name of the issuing organization for this ADM. 1594 Metadata objects are encoded in the same way as CONST objects, in 1595 accordance with Section 6.6.2. 1597 6.4. Type Encodings 1599 This section describes the JSON encoding of AMM data types defined in 1600 Section 5.2. 1602 6.4.1. Primitive Type Encoding 1604 JSON data types generally have direct support for the AMM primitive 1605 data types. The mapping of AMM primitive types to JSON data types is 1606 provided in Table 3. 1608 +----------+------------------------+ 1609 | AMM Type | JSON Encoding | 1610 +----------+------------------------+ 1611 | BYTE | number (0 <= # <= 256) | 1612 | | | 1613 | INT | number | 1614 | | | 1615 | UINT | number | 1616 | | | 1617 | VAST | number | 1618 | | | 1619 | UVAST | number | 1620 | | | 1621 | REAL32 | number | 1622 | | | 1623 | REAL64 | number | 1624 | | | 1625 | STRING | string | 1626 | | | 1627 | BOOL | boolean | 1628 +----------+------------------------+ 1630 Table 3: Primitive Type Encoding 1632 6.4.2. Derived Type Encoding 1634 In cases where an AMM derived type is simply a special interpretation 1635 of a primitive type, the JSON encoding of the derived type will be 1636 the same as the JSON encoding of the primitive type from which it 1637 derives. 1639 6.4.2.1. Type-Name-Value 1641 A TNV is encoded as a JSON object with three elements: "type", 1642 "name", and "value". For each item in a TNV, there are three 1643 acceptable formulations that can be used to represent the item, as 1644 illustrated in the following table. For the examples in this table, 1645 consider the REAL32 value of PI as 3.14159. 1647 +---------------------+---------------------------------------------+ 1648 | Desc | Example | 1649 +---------------------+---------------------------------------------+ 1650 | Full | {"type":"REAL32", "name":"PI", | 1651 | | "value":3.14159} | 1652 | | | 1653 | Named Type | {"type":"REAL32", "name":"PI", | 1654 | | "value":null} | 1655 | | | 1656 | Anonymous Type | {"type":"REAL32", "name":null, | 1657 | | "value":null} | 1658 | | | 1659 | Anonymous Type | {"type":"REAL32", "name":null, | 1660 | Value | "value":3.14159} | 1661 | | | 1662 | Anonymous Value | {"type":null, "name":null, "value":3.14159} | 1663 +---------------------+---------------------------------------------+ 1665 Table 4: TNV Formulations 1667 6.4.3. Collection Encoding 1669 The TNVC and AC collections are encoded as JSON arrays, with each 1670 object in the array represented in accordance with the JSON encoding 1671 for that object type (TNV or ARI, respectively). 1673 An Expression is encoded as a JSON object with two elements: a type 1674 and a postfix-expr. The description of these elements is as follows. 1676 (UINT) type 1677 The data type of the evaluation of the initializer 1678 expression. 1680 (AC) postfix-expr 1681 A JSON array of elements where each element is an JSON 1682 encoding of an ARI in conformance to Section 6.5. 1684 The following is an example of a JSON encoding of an EXPR object. 1686 "type": "UINT", 1687 "postfix-expr": ["Edd.item1","Edd.item2","Oper.+UINT"] 1689 6.5. ARI Encoding 1691 An ARI may be encoded as either a string or as a JSON object, with 1692 the two representations being unambiguously interchangeable. 1693 Additionally, there exists a long-form and short-form encoding of the 1694 ARI. 1696 String encodings provide a more compact and human-readable 1697 representation of the ARI. When an ARI is represented as a string in 1698 a JSON object, it MUST be encoded in accordance with Section 5.1.5.1. 1699 If the ARI references an object that is defined in the current ADM, 1700 then the shortform string encoding may be used, as described in 1701 Section 5.1.5.1.1. The object name to be used in the string encoding 1702 is the same as the "nm" value for the JSON object encoding, as 1703 described below. 1705 JSON object encoding of the ARI provides additional structure that 1706 makes ARI information verification easier. An ARI is encoded as a 1707 JSON object with three keys: namespace, object name, and parameters, 1708 encoded as follows. 1710 ns 1711 This element identifies the namespace within which the ARI 1712 has been defined, and encoded as a string in accordance with 1713 Section 5.1.5.1. In cases where the ARI identifies an object 1714 defined in the ADM in which it is used, the ADM's namespace 1715 may be assumed as the namespace of the ADM and this element 1716 can be omitted from the ARI JSON object. 1718 nm 1719 The name of an object defined in an ADM is a string defined 1720 as the concatenation of the ADMT collection defining the 1721 object, the "." separator, and the string name of the object 1722 itself. For example, an EDD defined in the Edd array and 1723 named edd1 would have the string name "Edd.edd1". 1725 fp 1726 ARI formal parameters, if present, are defined as an array 1727 with each element in the array representing the JSON TNV 1728 encoding of the parameter. If a default value is not defined 1729 for the parameter, then the value of the TNV MUST be omitted. 1731 The fp element is not used when AMM objects are defined in 1732 the context of an ADM, as the ADM template for defining 1733 objects already includes parameter information. This element 1734 is used when AMM objects are defined in accordance with the 1735 JSON ADM syntax, but by network operators as part of network- 1736 specific configuration. 1738 If the ARI JSON object has the fp element, then it MUST NOT 1739 have the ap element. An ARI MUST NOT define both formal and 1740 actual parameters in the same object instance. 1742 ap 1743 ARI actual parameters, if present, are defined as an array 1744 with each element of the array representing the JSON TNV 1745 encoding of the parameter. In cases where an optional 1746 parameter is not present, an empty TNV object will be used in 1747 its place for that parameter. The name element of the TNV 1748 MUST NOT be present for actual parameters. 1750 In cases where the actual parameter is by value, then the TNV 1751 value key will hold the JSON encoding of the value of the 1752 parameter. 1754 In cases where the actual parameter is by name, then the TNV 1755 MUST have the type "ParmName" and the value MUST be the 1756 string name of the parameter whose value should be used to 1757 populate the value of this actual parameter, as described in 1758 Section 5.1.3.2. 1760 If the ARI JSON object has the fp element, then it MUST NOT 1761 have the ap element. An ARI MUST NOT define both formal and 1762 actual parameters in the same object instance. 1764 The following are examples of JSON encoded ARI objects. 1766 +---------------------------+---------------------------------------+ 1767 | String Encoding | JSON Encoding | 1768 +---------------------------+---------------------------------------+ 1769 | "N1/N2/Edd.edd1" | {"ns":"N1/N2", "nm":"Edd.edd1"} | 1770 | | | 1771 | "N1/N2/Edd.edd2(UINT | {"ns":"N1/N2", "nm":"Edd.edd2", | 1772 | num=3)" | "fp":[{"type":"UINT", "name"="num", | 1773 | | value":3}]} | 1774 | | | 1775 | "N1/N2/Edd.edd2()" | {"ns":"N1/N2", "nm":"Edd.edd2", | 1776 | | "ap":[{}]} | 1777 | | | 1778 | "N1/N2/Edd.edd2(4)" | {"ns":"N1/N2", "nm":"Edd.edd2", | 1779 | | "ap":[{"type":"UINT", "value":4}]} | 1780 | | | 1781 | "N1/N2/Edd.edd3()" | {"ns":"N1/N2", "nm":"Edd.edd3", | 1782 | | "ap":[{"type":"ParmName", | 1783 | | "value":"input"}]} | 1784 +---------------------------+---------------------------------------+ 1786 Table 5: Formal Parameter Encoding 1788 6.6. ADM Structures 1790 6.6.1. General Notes 1792 The following guidelines apply to the JSON encoding of AMM objects. 1794 Identification 1795 Objects do not include an ARI object as part of their 1796 definition. All of the contents of an ARI are derivable in 1797 the context of the ADM and adding an ARI encoding as part of 1798 the AMM object definition would be redundant and require 1799 maintaining naming information in two places in the ADM 1800 document. 1802 Common Elements 1803 Every JSON encoding of an AMM object MUST have the following 1804 elements: 1806 * Name 1807 The identifier of the AMM Object. This MUST be unique 1808 across all name elements defined in the ADM collection of 1809 these types of objects. 1811 * Description 1812 A string description of the kind of data represented by 1813 this data item. 1815 Formal Parameters 1816 If an AMM object may be parameterized, then an element MUST 1817 be present in the JSON object named "parmspec" which is 1818 defined as a JSON-encoded TNVC. Each element in the TNVC 1819 representing the JSON TNV encoding of the formal parameter. 1820 If a default value is not defined for the parameter, then the 1821 value of the TNV MUST be omitted. 1823 6.6.2. Constant (CONST) Encoding 1825 The CONST JSON object is comprised of four elements: "name", "type", 1826 "value, and "description". The description of these elements is as 1827 follows: 1829 Name 1830 The identifier of the constant. This MUST be unique across 1831 all name elements for CONSTs in the ADM. 1833 Type 1834 The strong typing of this data value. Types MUST be one of 1835 those defined in Section 5.4. 1837 Value 1838 The value of the constant, expressed in the JSON encoding of 1839 the data type. 1841 Description 1842 A string description of the kind of data represented by this 1843 data item. 1845 The following is an example of a JSON encoding of a CONST object. 1847 "name": "PI", 1848 "type": "REAL64", 1849 "value": 3.14159, 1850 "description": "The value of PI." 1852 6.6.3. Control (CTRL) Encoding 1854 The CTRL JSON object is comprised of three elements: "name", 1855 "parmspec", and "description". The description of these elements is 1856 as follows: 1858 Name 1859 The identifier of the control. This MUST be unique across 1860 all name elements for CTRLs in the ADM. 1862 ParmSpec 1863 This optional item describes parameters for this control. 1864 This is encoded as an array where each element in the array 1865 is encoded as a formal parameter in accordance with 1866 Paragraph 3. 1868 Description 1869 A string description of the kind of data represented by this 1870 data item. 1872 The following is an example of a JSON encoding of an CTRL object. 1874 "name": "reset_src_cnts", 1875 "parmspec": [{"type":"STR","name":"src"}], 1876 "description": "This control resets counts for the given source." 1878 6.6.4. Externally Defined Data (EDD) Encoding 1880 The EDD JSON object is comprised of four elements: "name", "type", 1881 "parmspec", and "description". The description of these elements is 1882 as follows: 1884 Name 1885 The identifier of the EDD data item. This MUST be unique 1886 across all name elements for EDDs in the ADM. 1888 Type 1889 The strong typing of this data value. Types MUST be one of 1890 those defined in Section 5.4. 1892 ParmSpec 1893 The optional array of formal parameters encoded in accordance 1894 with Paragraph 3. 1896 Description 1897 A string description of the kind of data represented by this 1898 data item. 1900 The following is an example of a JSON encoding of an EDD object. 1902 "name": "num_good_tx_bcb_blks_src", 1903 "type": "UINT", 1904 "parmspec": [{"type":"STR","name":"Src"}], 1905 "description": "Successfully Tx BCB blocks from SRC" 1907 6.6.5. Macro Encoding 1909 The Macro JSON object is comprised of three elements: "name", 1910 "definition", and "description". The description of these elements 1911 is as follows: 1913 Name 1914 The identifier of the macro. This MUST be unique across all 1915 name elements for MACs in the ADM. 1917 Definition 1918 This is a JSON array whose elements are shorthand references 1919 are in accordance with Section 6.5 and are of the type CTRL 1920 or MAC. 1922 Description 1923 A string description of the kind of data represented by this 1924 data item. 1926 The following is an example of a JSON encoding of an MAC object. 1928 "name": "user_list", 1929 "definition": [{ 1930 "nm":"Ctrl.list_vars", 1931 "ap": [] 1932 }, 1933 { 1934 "nm":Ctrl.list_rptts" 1935 "ap": [] 1936 }], 1937 "description": "List user defined data." 1939 6.6.6. Operator (OP) Encoding 1941 The OP JSON object is comprised of four elements: "name", "result- 1942 type", "in-type", and "description". The description of these 1943 elements is as follows. 1945 Name 1946 The identifier of the operator. This MUST be unique across 1947 all name elements for OPs in the ADM. 1949 Result-Type 1950 The numeric result of applying the operator to the series of 1951 operands. This must be one of the encodings for Table 2. 1953 In-Type 1954 This is an ordered JSON array of operands for the operator. 1955 Each operand is a data type encoded in accordance with 1956 Table 2. 1958 Description 1959 A string description of the kind of data represented by this 1960 data item. 1962 The following is an example of a JSON encoding of an OP object. 1964 "name": "plusINT", 1965 "result-type": "INT", 1966 "in-type": ["INT", "INT"], 1967 "description": "Int32 addition" 1969 6.6.7. Table Template (TBLT) Encoding 1971 The TBLT JSON object is comprised of four elements: "name", 1972 "columns", and "description". The description of these elements is 1973 as follows: 1975 Name 1976 The identifier of the table template data item. This MUST be 1977 unique across all name elements for TBLTs in the ADM. 1979 Columns 1980 This is a JSON array of elements, with each element 1981 representing the definition of the type of information 1982 represented in each column. Each column is described using 1983 the same encoding as a TNV described in Table 4. 1985 Description 1986 A string description of the kind of data represented by this 1987 data item. 1989 The following is an example of a JSON encoding of an TBLT object. 1991 "name":"keys", 1992 "columns": [{"type":"STR","name":"ciphersuite_names"}], 1993 "description": "This table lists supported cipher suites." 1995 6.6.8. Report Template Encoding 1997 The RPTT JSON object is comprised of four elements: "name", 1998 "parmspec", "definition", and "description". The description of 1999 these elements is as follows: 2001 Name 2002 The identifier of the report template. This MUST be unique 2003 across all name elements for RPTTs in the ADM. 2005 ParmSpec 2006 This optional item describes parameters for this report. 2007 This is encoded as an array where each element in the array 2008 is encoded as a formal parameter in accordance with 2009 Paragraph 3. 2011 Definition 2012 This is an array of data elements that represent the ordered 2013 set of information associated with the report. Each element 2014 in the array is encoded as a data item shorthand in 2015 accordance with Section 6.5. 2016 Report item elements MAY use reference parameters in their 2017 definition. In those cases, the reference parameters in the 2018 definition list MUST match report entry parameter names from 2019 the ParmSpec element in the report template definition. 2021 Description 2022 A string description of the kind of data represented by this 2023 data item. 2025 The following is an example of a JSON encoding of an RPTT object. 2027 { 2028 "name": "default_report", 2029 "parmspec": [{ 2030 "type": "STR", 2031 "name": "endpoint_id" 2032 }], 2033 "definition": [ 2034 { 2035 "ns": "DTN:bp", 2036 "nm": "Edd.edd_using_a_parm", 2037 "ap": [{ 2038 "type": "PARMNAME", 2039 "value": "endpoint_id" 2040 }] 2041 }, 2042 { 2043 "ns": "DTN:bp", 2044 "nm": "Edd.edd_with_default ", 2045 "ap": [{ 2046 "type": "INT", 2047 "value": ""} 2048 ]}, 2049 { "ns": "DTN:bp", 2050 "nm": "Edd.edd_with_no_parms ", 2051 "ap": [] 2052 } 2053 ] 2054 "description": "A default report." 2055 } 2057 6.6.9. Variables Encoding 2059 The VAR JSON object is comprised of four elements: "name", "type", 2060 "initializer", and "description". The description of these elements 2061 is as follows: 2063 Name 2064 The identifier of the variable data item. This MUST be 2065 unique across all name elements for VARs in the ADM. 2067 Type 2068 The strong typing of this data value. Types MUST be one of 2069 those defined in Section 5.4. 2071 Initializer 2072 The expression used to establish the initial value of the 2073 variable. This initializer is an expression encoded in 2074 conformance with Section 6.4.3. 2076 Description 2077 A string description of the kind of data represented by this 2078 data item. 2080 The following is an example of a JSON encoding of an VAR object. 2082 { 2083 "name": "total_bad_tx_blks", 2084 "type": "UINT", 2085 "initializer": { 2086 "type": "UINT", 2087 "postfix-expr": [{ 2088 "nm": "Edd.item1", 2089 "ap": [{ 2090 "type": "UINT", 2091 "value": 0 2092 }] 2093 }, { 2094 "nm":"Edd.item2", 2095 "ap":[{ 2096 "type":"UINT", 2097 "value": 1 2098 ]} 2099 }, { 2100 "nm": "Oper.plusUINT", 2101 "ap":[] 2102 }] 2104 }, 2105 "description": "# total items (# item1 + # item2)." 2106 } 2108 6.6.10. Exemptions 2110 Certain AMM objects are not intended to be statically defined in the 2111 context of an ADM document. Literals, Reports, Tables, State-Based 2112 Rules, and Time-Based Rules all only have meaning in the context of 2113 an operational network. These objects are defined by network 2114 operators as part of network-specific configuration and therefore not 2115 present in the ADM Template. 2117 7. ADM Author Considerations 2119 The AMM model provides multiple ways to represent certain types of 2120 data. This section provides informative guidance on how to express 2121 application management constructs efficiently when authoring an ADM 2122 document. 2124 Use Parameters for Dynamic Information. 2125 Parameters provide a powerful mechanism for expressing 2126 associative look-ups of EDD data. EDDs SHOULD be parameterized 2127 when the definition of the EDD is dependent upon run-time 2128 information. For example, if requesting the number of bytes 2129 through a specific endpoint, the construct 2130 num_bytes("endpoint_name") is simpler to understand and more 2131 robust to new endpoint additions than attempting to enumerate the 2132 number and name of potential endpoints when defining the ADM. 2134 Do Not Use Parameters for Static Information. 2135 Parameters incur bandwidth and processing costs (such as type 2136 checking) and should only be used where necessary. If an EDD 2137 object can be parameterized, but the set of parameters is known 2138 and unchanging it may be more efficient to define multiple 2139 unparameterized EDD objects instead. For example, consider a 2140 single parameterized EDD object reporting the number of bytes of 2141 data received for a specific, known set of priorities and a 2142 request to report on those bytes for the "low", "med", and "high" 2143 priorities. Below are two ways to represent these data: using 2144 parameters and not using parameters. 2146 +------------------------+------------------------+ 2147 | Parameterized EDDs | Non-Parameterized EDDs | 2148 +------------------------+------------------------+ 2149 | num_bytes_by_pri(low) | num_bytes_by_low_pri | 2150 | num_bytes_by_pri(med) | num_bytes_by_med_pri | 2151 | num_bytes_by_pri(high) | num_bytes_by_high_pri | 2152 +------------------------+------------------------+ 2154 The use of parameters in this case only incurs the overhead of 2155 type checking, parameter encoding/decoding, and associative 2156 lookups. This situation should be avoided when deciding when to 2157 parameterize AMM objects. 2159 Use Tables for Related Data. 2160 In cases where multiple EDD or VAR values are likely to be 2161 evaluated together, then that information SHOULD be placed in a 2162 Table Template rather than defining multiple EDD and VAR objects. 2163 By making a Table Template, the relationships amongst various 2164 data values are preserved. Otherwise, Managers would need to 2165 remember to query multiple EDD and/or VAR objects together which 2166 is burdensome, but also results in high bandwidth and processor 2167 utilization. 2169 8. IANA Considerations 2171 This document defines a moderated namespace registry in 2172 Section 5.1.1.1. This registry is envisioned to be moderated by 2173 IANA. Entries in this registry are to be made through Expert Review. 2175 This document defines a new URI scheme, "ari", as defined in 2176 Section 5.1.5. 2178 9. Security Considerations 2180 This document does not describe any on-the-wire encoding or other 2181 messaging syntax. It is assumed that the exchange of AMM objects 2182 between Agents and Managers occurs within the context of an 2183 appropriate network environment. 2185 This AMM model may be extended to include the concept of Access 2186 Control Lists (ACLs) to enforce roles and responsibilities amongst 2187 Managers in the network. This access control would be implemented 2188 separately from network security mechanisms. 2190 10. References 2192 10.1. Normative References 2194 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2195 Requirement Levels", BCP 14, RFC 2119, 2196 DOI 10.17487/RFC2119, March 1997, 2197 . 2199 [RFC3339] Klyne, G. and C. Newman, "Date and Time on the Internet: 2200 Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002, 2201 . 2203 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 2204 Resource Identifier (URI): Generic Syntax", STD 66, 2205 RFC 3986, DOI 10.17487/RFC3986, January 2005, 2206 . 2208 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 2209 Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006, 2210 . 2212 10.2. Informative References 2214 [I-D.birrane-dtn-ama] 2215 Birrane, E., "Asynchronous Management Architecture", 2216 draft-birrane-dtn-ama-06 (work in progress), October 2017. 2218 Authors' Addresses 2220 Edward J. Birrane 2221 Johns Hopkins Applied Physics Laboratory 2223 Email: Edward.Birrane@jhuapl.edu 2225 Evana DiPietro 2226 Johns Hopkins Applied Physics Laboratory 2228 Email: Evana.DiPietro@jhuapl.edu 2230 David Linko 2231 Johns Hopkins Applied Physics Laboratory 2233 Email: David.Linko@jhuapl.edu