idnits 2.17.1 draft-ietf-netmod-node-tags-02.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 : ---------------------------------------------------------------------------- ** There are 59 instances of too long lines in the document, the longest one being 19 characters in excess of 72. -- The draft header indicates that this document updates RFC8407, but the abstract doesn't seem to mention this, which it should. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 399 has weird spacing: '...ct-name nac...' == Line 487 has weird spacing: '...dentify multi...' == Line 646 has weird spacing: '...present a pro...' == Line 972 has weird spacing: '...dentify multi...' -- The document date (May 9, 2021) is 1082 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Missing Reference: 'I-D.netconf-notification-capabilities' is mentioned on line 141, but not defined == Missing Reference: 'I-D.ietf-netmod-yang-instance-file-format' is mentioned on line 1074, but not defined Summary: 1 error (**), 0 flaws (~~), 7 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 NETMOD Working Group Q. Wu 3 Internet-Draft B. Claise 4 Updates: 8407 (if approved) Huawei 5 Intended status: Standards Track P. Liu 6 Expires: November 10, 2021 Z. Du 7 China Mobile 8 M. Boucadair 9 Orange 10 May 9, 2021 12 Self Describing Data Object Tags 13 draft-ietf-netmod-node-tags-02 15 Abstract 17 This document defines a method to tag data objects associated with 18 operation and management data in YANG Modules. This YANG data object 19 tagging method can be used to classify data objects from different 20 YANG modules and identify characteristics data. It also can provide 21 input, instruction, indication to selection filter and filter queries 22 of operational state on a server during a "pub/sub" service for YANG 23 datastore updates. When the state of all subscriptions of a 24 particular subscriber to be fetched is huge, the amount of data to be 25 streamed out to the destination can be greatly reduced and only 26 targeted to the characteristics data. These data object tags may be 27 registered as well as assigned during the module definition; assigned 28 by implementations; or dynamically defined and set by users. 30 Status of This Memo 32 This Internet-Draft is submitted in full conformance with the 33 provisions of BCP 78 and BCP 79. 35 Internet-Drafts are working documents of the Internet Engineering 36 Task Force (IETF). Note that other groups may also distribute 37 working documents as Internet-Drafts. The list of current Internet- 38 Drafts is at https://datatracker.ietf.org/drafts/current/. 40 Internet-Drafts are draft documents valid for a maximum of six months 41 and may be updated, replaced, or obsoleted by other documents at any 42 time. It is inappropriate to use Internet-Drafts as reference 43 material or to cite them other than as "work in progress." 45 This Internet-Draft will expire on November 10, 2021. 47 Copyright Notice 49 Copyright (c) 2021 IETF Trust and the persons identified as the 50 document authors. All rights reserved. 52 This document is subject to BCP 78 and the IETF Trust's Legal 53 Provisions Relating to IETF Documents 54 (https://trustee.ietf.org/license-info) in effect on the date of 55 publication of this document. Please review these documents 56 carefully, as they describe your rights and restrictions with respect 57 to this document. Code Components extracted from this document must 58 include Simplified BSD License text as described in Section 4.e of 59 the Trust Legal Provisions and are provided without warranty as 60 described in the Simplified BSD License. 62 Table of Contents 64 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 65 1.1. Self Describing Data Object Tags Use Case . . . . . . . . 4 66 1.1.1. Massive Data Object Collection . . . . . . . . . . . 4 67 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 6 68 1.2.1. Requirements Notation . . . . . . . . . . . . . . . . 6 69 1.2.2. Glossary . . . . . . . . . . . . . . . . . . . . . . 7 70 2. Data Object Tag Values . . . . . . . . . . . . . . . . . . . 7 71 2.1. IETF Tags Prefix . . . . . . . . . . . . . . . . . . . . 7 72 2.2. Vendor Tags Prefix . . . . . . . . . . . . . . . . . . . 7 73 2.3. User Tags Prefix . . . . . . . . . . . . . . . . . . . . 7 74 2.4. Reserved Tags Prefix . . . . . . . . . . . . . . . . . . 7 75 3. Data Object Tag Management . . . . . . . . . . . . . . . . . 8 76 3.1. Module Design Tagging . . . . . . . . . . . . . . . . . . 8 77 3.2. Implementation Tagging . . . . . . . . . . . . . . . . . 9 78 3.3. User Tagging . . . . . . . . . . . . . . . . . . . . . . 9 79 4. Data Object Tags Module Structure . . . . . . . . . . . . . . 9 80 4.1. Data Object Tags Module Tree . . . . . . . . . . . . . . 9 81 5. YANG Module . . . . . . . . . . . . . . . . . . . . . . . . . 9 82 6. Guidelines to Model Writers . . . . . . . . . . . . . . . . . 12 83 6.1. Define Standard Tags . . . . . . . . . . . . . . . . . . 12 84 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 13 85 7.1. YANG Data Object Tag Prefixes Registry . . . . . . . . . 13 86 7.2. IETF YANG Data Object Tags Registry . . . . . . . . . . . 14 87 7.3. Updates to the IETF XML Registry . . . . . . . . . . . . 16 88 7.4. Updates to the YANG Module Names Registry . . . . . . . . 16 89 8. Security Considerations . . . . . . . . . . . . . . . . . . . 17 90 9. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 17 91 10. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 17 92 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 17 93 11.1. Normative References . . . . . . . . . . . . . . . . . . 17 94 11.2. Informative References . . . . . . . . . . . . . . . . . 18 96 Appendix A. NETCONF Example . . . . . . . . . . . . . . . . . . 19 97 Appendix B. Non-NMDA State Module . . . . . . . . . . . . . . . 20 98 Appendix C. Targeted data object collection example . . . . . . 23 99 Appendix D. Changes between Revisions . . . . . . . . . . . . . 26 100 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 27 102 1. Introduction 104 As described in [I.D-ietf-netmod-module-tags], the use of tags for 105 classification and organization is fairly ubiquitous not only within 106 IETF protocols, but in the internet itself (e.g., "#hashtags"). A 107 module tag defined in [I.D-ietf-netmod-module-tags] is a string 108 associated only with a module name at module level. 110 At the time of writing this document (2020), there are many data 111 models that have been specified or are being specified by various 112 different SDOs and Open Souce community. They cover many of the 113 networking protocols and techniques. However data objects defined by 114 these technology specific data models might represent a portion of 115 fault, configuration, accounting, performance, security management 116 categories information at different locations in various different 117 ways, lack consistent classification criteria and representation for 118 a specific service, feature or data source. 120 This document defines self-describing data object tags and associates 121 them with data objects within YANG module, which 123 o Provide dictionary meaning for specific targeted data objects; 125 o Indicate relationship between data objects within the same YANG 126 module or from different YANG modules; 128 o Identify key performance metric data objects and the absolute 129 XPath expression identifying the element path to the node; 131 The self describing data object tags can be used by the client to 132 classify data objects from different YANG modules and identify 133 characteristics data. In addition, it can provide input, 134 instruction, indication to selection filter and filter queries of 135 configuration or operational state on a server based on these data 136 object tags, .e.g., return specific object type of operational state 137 related to system-management. NETCONF clients can discover data 138 objects with self describing data object tags supported by a NETCONF 139 server via operation. The self describing data object 140 tag capability can also be advertised via Capability Notification 141 Model [I-D.netconf-notification-capabilities] by the NETCONF server 142 or some place where offline document are kept. These data object 143 tags may be registered as well as assigned during the module 144 definition; assigned by implementations; or dynamically defined and 145 set by users. 147 This document defines a YANG module [RFC7950] which augments module 148 tag model and provides a list of data object entries to allow for 149 adding or removing of self describing tags as well as viewing the set 150 of self describing tags associated with specific data objects within 151 YANG modules. 153 This document defines an extension statement to be used to indicate 154 self describing tags that SHOULD be added by the module 155 implementation automatically (i.e., outside of configuration). 157 This document also defines an IANA registry for tag prefixes as well 158 as a set of globally assigned tags. 160 Section 6 provides guidelines for authors of YANG data models. 162 The YANG data model in this document conforms to the Network 163 Management Datastore Architecture defined in [RFC8342]. 165 1.1. Self Describing Data Object Tags Use Case 167 1.1.1. Massive Data Object Collection 169 Among data object tags, the opm (object, property, metric) tags can 170 be used to tackle massive data objects collection and only capture 171 YANG data objects associated with performance metrics data modelled 172 with YANG (See Figure 1). 174 /----\ 175 /Object\ 176 | Tag | 177 \- +-/ 178 +---------V--------+ have 179 | YANG Data Node <---------- -----+ 180 | /Data Object 1 | | 181 +--A-------------A-+ | 182 |have |have | 183 | | | 184 +- -----------+-----+ +-+------------V+ +-+------------ + 185 | YANG Data Node | | YANG Data Node| | YANG Data Node| 186 | /Data Object 2 | | /Data Object 3| | /Data Object 4| 187 +---A------ --- ----+ +-A----------- -+ +-A----------- -+ 188 | | | 189 | /-+-\ /-+-\ 190 /-+--\ Metric \ Metric \ 191 Property | Tag | | Tag | 192 \ Tag / \-^-/ \-^-/ 193 \----/ | | 194 | /----\ | 195 | /Metric\ | 196 +----| Group +----| 197 \ Tag / 198 \- --/ 200 Figure 1: The Relation between Object, Property and Metric 202 In Figure 1, data object can contain other data objects called 203 subobjects. Both object and subobjects can be modeled as YANG data 204 nodes [RFC7950]. Data Object containing other data objects can be 205 one of container, leaf-list and list and is tagged with object tag. 206 Subobject tagged with the property tag is a leaf node. Subobject 207 tagged with the metric tag can be one of container, leaf-list, list, 208 leaf node. A data Object contains one single object tag, or one 209 single property tag, or one single metric tag. A data Object tagged 210 with metric tag also can have one single Metric Group tag and/or one 211 single multi-source tag. 213 The use of opm tags would be to help filter discrete categories of 214 YANG data objects scattered across the same or different YANG modules 215 supported by a device and capture all network performance data or all 216 property data in the single view of the truth (see Figure 2). In 217 Figure 2, tunnel-svc data object is a container node in the tunnel-pm 218 module and can be seen as the root object for property tagged 219 subobjects (e.g., tunnel-svc/create-time) and metric tagged 220 subobjects (e.g.,tunnel-svc/avg-latency). Name, create-time, 221 modified-time are property tagged subobjects under tunnel-svc 222 container. Avg-latency,packet -loss are metric tagged subobjects 223 under tunnel-svc container node. Take tunnel-svc data object and 224 tunnel-svc/name data object as an example, tunnel-svc data object has 225 one single object tag (i.e., ietf:object) while tunnel-svc/name data 226 object has one property subobject tag (i.e., ietf:property). In 227 addition, not all metric subobjects need to be tagged, e.g., only 228 specific category (e.g., loss related) metric subobjects need to be 229 tagged with metric-type tag which can further reduce amount data to 230 be fetched. 232 +------------------------+--------------------------------------------+ 233 | Data | Object Property Metric Module | 234 | Object | Tag Tag Tag Name | 235 +------------------------+--------------------------------------------+ 236 | | ietf: | 237 |tunnel-svc | object tunnel-pm| 238 | | ietf: | 239 |tunnel-svc/name | property tunnel-pm| 240 | | ietf: | 241 |tunnel-svc/create-time | property tunnel-pm| 242 | | ietf: | 243 |tunnel-svc/modified-time| property tunnel-pm| 244 | | | 245 |tunnel-svc/avg-latency | ietf: tunnel-pm| 246 | | metric | 247 |tunnel-svc/packet-loss | ietf: tunnel-pm| 248 | | metric | 249 |tunnel-svc/min-latency | ietf: tunnel-pm| 250 | | metric | 251 |tunnel-svc/ max-latency | ietf: tunnel-pm| 252 | | metric | 253 +------------------------+--------------------------------------------+ 255 Figure 2: Example of OPM Tags Used in the YANG Module 257 If data objects in these YANG modules are suitably tagged and learnt 258 by the client from a live server, the client can retrieve paths to 259 all targeted data objects and then use an XPath query defined 260 [RFC8639] [RFC8641] to list all tagged data objects which reflect 261 network characteristics. 263 1.2. Terminology 265 1.2.1. Requirements Notation 267 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 268 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 269 "OPTIONAL" in this document are to be interpreted as described in BCP 270 14 [RFC2119] [RFC8174] when, and only when, they appear in all 271 capitals, as shown here. 273 1.2.2. Glossary 275 OPM - Object Property Metric 277 2. Data Object Tag Values 279 All data object tags SHOULD begin with a prefix indicating who owns 280 their definition. An IANA registry (Section 7.1) is used to support 281 registering data object tag prefixes. Currently 3 prefixes are 282 defined. 284 No further structure is imposed by this document on the value 285 following the registered prefix, and the value can contain any YANG 286 type 'string' characters except carriage-returns, newlines and tabs. 287 Therefore, designers, implementers, and users are free to add or not 288 add any structure they may require to their own tag values. 290 2.1. IETF Tags Prefix 292 An IETF tag is a data object tag that has the prefix "ietf:". All 293 IETF data object tags are registered with IANA in a registry defined 294 later in this document (Section 7.2). 296 2.2. Vendor Tags Prefix 298 A vendor tag is a tag that has the prefix "vendor:". These tags are 299 defined by the vendor that implements the module, and are not 300 registered; however, it is RECOMMENDED that the vendor include extra 301 identification in the tag to avoid collisions such as using the 302 enterprise or organization name following the "vendor:" prefix (e.g., 303 vendor:vendor-defined-classifier). 305 2.3. User Tags Prefix 307 A user tag is any tag that has the prefix "user:". These tags are 308 defined by the user/administrator and are not meant to be registered. 309 Users are not required to use the "user:" prefix; however, doing so 310 is RECOMMENDED as it helps avoid prefix collisions. 312 2.4. Reserved Tags Prefix 314 Any tag not starting with the prefix "ietf:", "vendor:" or "user:" is 315 reserved for future use. These tag values are not invalid, but 316 simply reserved in the context of specifications (e.g., RFCs). 318 3. Data Object Tag Management 320 Tags can become associated with a data object within YANG module in a 321 number of ways. Tags may be defined and associated at the module 322 design time, at implementation time without the need of live server, 323 or via user administrative control . As the main consumer of data 324 object tags are users, users may also remove any tag from a live 325 server, no matter how the tag became associated with a data object 326 within a YANG module. 328 3.1. Module Design Tagging 330 A data object definition MAY indicate a set of data object tags to be 331 added by the module implementer. These design time tags are 332 indicated using a set of extension statements which include: 334 opm-tag extension statement: Classify management and operation data 335 into object, property subobject and metric subobject three 336 categories. data object can contain other data objects called 337 subobjects. Both object and subobjects can be modeled as YANG 338 data nodes [RFC7950]. Data Object containing other data objects 339 can be one of container, leaf-list and list and is tagged with 340 object tag. Subobject tagged with the property tag is a leaf 341 node. Subobject tagged with the metric tag can be one of 342 container, leaf-list, list, leaf node. A data Object contains one 343 single object tag, or one single property tag, or one single 344 metric tag. A data Object tagged with the metric tag also can 345 have one single Metric Group tag and/or one single multi-source 346 tag. See opm-tag example in Figure 2 and Figure 3. 348 metric-type extension statement: Provide meric data objects 349 classification (e.g., loss, jitter, delay, counter, gauage, 350 historgram, summary, unknown) within the YANG module. 352 multi-source-tag extension statement: Identify multi-source 353 aggregation type (e.g., aggregated, non-aggregated) related to 354 metric subobject. 'aggregated' multi-source aggregation type 355 allows a large number of measurements on metric subobjects from 356 different sources of the same type (e.g.,line card, each 357 subinterface of aggregated Ethernet interface) being combined into 358 aggregated statistics and report as one metric subobject. 'non- 359 aggregated' multi-source aggregation type allows measurement from 360 each source of the same type (e.g.,line card, each subinterface of 361 aggregated Ethernet interface) be reported separately. 363 Among these extension statements, the metric-type, multi-source-tag 364 extension statements are context information related and can be used 365 to correlate data object from the different modules. 367 If the data node is defined in an IETF standards track document, the 368 data object tags MUST be IETF Tags (2.1). Thus, new data object can 369 drive the addition of new IETF tags to the IANA registry defined in 370 Section 7, and the IANA registry can serve as a check against 371 duplication. 373 3.2. Implementation Tagging 375 An implementation MAY include additional tags associated with data 376 object within a YANG module. These tags SHOULD be IETF Tags (i.e., 377 registered) or vendor specific tags. 379 3.3. User Tagging 381 Data object tags of any kind, with or without a prefix, can be 382 assigned and removed by the user from a live server using normal 383 configuration mechanisms. In order to remove a data object tag from 384 the operational datastore, the user adds a matching "masked-tag" 385 entry for a given data object within the ietf-data-object-tags 386 Module. 388 4. Data Object Tags Module Structure 390 4.1. Data Object Tags Module Tree 392 The tree associated with the "ietf-data-object-tags" module follows. 393 The meaning of the symbols can be found in [RFC8340]. 395 module: ietf-data-object-tags 396 augment /tags:module-tags/tags:module: 397 +--rw data-object-tags 398 +--rw data-object* [object-name] 399 +--rw object-name nacm:node-instance-identifier 400 +--rw tag* tags:tag 401 +--rw masked-tag* tags:tag 403 5. YANG Module 405 file "ietf-data-object-tags@2019-05-03.yang" 406 module ietf-data-object-tags { 407 yang-version 1.1; 408 namespace "urn:ietf:params:xml:ns:yang:ietf-data-object-tags"; 409 prefix ntags; 411 import ietf-netconf-acm { 412 prefix nacm; 413 } 414 import ietf-module-tags { 415 prefix tags; 416 } 418 organization 419 "IETF NetMod Working Group (NetMod)"; 420 contact 421 "WG Web: 422 WG List: 423 Editor: Qin Wu 424 Editor: Benoit Claise 425 Editor: Peng Liu 426 Editor: Zongpeng Du 427 Editor: Mohamed Boucadair "; 428 description 429 "This module describes a mechanism associating self-describing 430 tags with YANG data object within YANG modules. Tags may be IANA 431 assigned or privately defined. 433 Copyright (c) 2020 IETF Trust and the persons identified as 434 authors of the code. All rights reserved. 436 Redistribution and use in source and binary forms, with or 437 without modification, is permitted pursuant to, and subject to 438 the license terms contained in, the Simplified BSD License set 439 forth in Section 4.c of the IETF Trust's Legal Provisions 440 Relating to IETF Documents 441 (https://trustee.ietf.org/license-info). 443 This version of this YANG module is part of RFC XXXX 444 (https://tools.ietf.org/html/rfcXXXX); see the RFC itself for 445 full legal notices."; 447 revision 2019-05-03 { 448 description 449 "Initial revision."; 450 reference 451 "RFC XXXX: Self Describing Data Object Tags"; 452 } 454 extension opm-tag { 455 argument tag; 456 description 457 "The argument 'tag' is of type 'tag'. This extension statement 458 is used by module authors to indicate the opm tags that SHOULD 459 be added automatically by the system. Opm Tag is used to 460 classify operation and management data object into object, 461 property, and metric three categories. Data Object can contain 462 other data objects called subobjects. Both object and subobjects 463 can be modeled as data nodes. The Data Object tagged with object 464 tag can be one of container, leaf-list and list. Data Object 465 tagged with the Property tag is a leaf node. Data Object tagged with 466 the Metric tag can be one of container, leaf-list, list, leaf. 467 Data objects tagged with either property tag or metric tag are 468 subobjects belonging to specific root data object. Data Object 469 contains One object tag or one property tag, or one metric tag. As 470 such the origin of the value for the pre-defined tags should be set 471 to 'system'[RFC8342]."; 472 } 474 extension metric-type { 475 argument tag; 476 description 477 "The argument 'tag' is of type 'tag'. The metric type can be 478 used to provide metric data object classification 479 (e.g., loss, jitter, packet loss,counter, gauge, histogram, 480 summary, unknown) within the YANG module."; 481 } 483 extension multi-source-tag { 484 argument tag; 485 description 486 "The argument 'tag' is of type 'tag'. The multi-source-tag can be 487 used to identify multi-source aggregation type (e.g., aggregated, 488 non-aggregated) related to metric subobject. 490 'aggregated' multi-source aggregation type allows a large number of 491 measurements on metric subobjects from different sources of the same 492 type (e.g.,line card, each subinterface of aggregated Ethernet interface) 493 being combined into aggregated statistics and report as one metric subobject 494 value. 'non-aggregated' multi-source aggregation type allows measurement from 495 each source of the same type (e.g.,line card, each subinterface of aggregated 496 Ethernet interface) be reported separately."; 497 } 499 augment "/tags:module-tags/tags:module" { 500 description 501 "Augment the Module Tags module with data object tag attributes"; 502 container data-object-tags { 503 description 504 "Contains the list of data objects and their associated data object tags"; 505 list data-object { 506 key "object-name"; 507 description 508 "A list of data objects and their associated data object tags"; 509 leaf object-name { 510 type nacm:node-instance-identifier; 511 mandatory true; 512 description 513 "The YANG data object name."; 514 } 515 leaf-list tag { 516 type tags:tag; 517 description 518 "Tags associated with the data object within the YANG module. See 519 the IANA 'YANG Data Object Tag Prefixes' registry for reserved 520 prefixes and the IANA'IETF YANG Data Object Tags' registry for 521 IETF tags. 523 The 'operational' state [RFC8342] view of this list is 524 constructed using the following steps: 526 1) System tags (i.e., tags of 'system' origin) are added. 527 2) User configured tags (i.e., tags of 'intended' origin) 528 are added. 529 3) Any tag that is equal to a masked-tag is removed."; 530 } 531 leaf-list masked-tag { 532 type tags:tag; 533 description 534 "The list of tags that should not be associated with the data 535 object within the YANG module. The user can remove (mask) tags from the 536 operational state datastore [RFC8342] by adding them to 537 this list. It is not an error to add tags to this list 538 that are not associated with the data object within YANG module, 539 but they have no operational effect."; 540 } 541 } 542 } 543 } 544 } 545 547 6. Guidelines to Model Writers 549 This section updates [RFC8407]. 551 6.1. Define Standard Tags 553 A module MAY indicate, using data object tag extension statements, a 554 set of data object tags that are to be automatically associated with 555 data object within the module (i.e., not added through 556 configuration). 558 module example-module-A { 559 //... 560 import ietf-data-node-tags { prefix ntags; } 561 container top { 562 ntags:opm-tag "ietf:object"; 563 list X { 564 leaf foo { 565 ntags:opm-tag "ietf:property"; 566 } 567 } 568 container Y { 569 leaf bar { 570 ntags:opm-tag "ietf:metric"; 571 } 572 } 573 } 574 // ... 575 } 577 Figure 3: Data object tag example 579 The module writer can use existing standard data object tags, or use 580 new data object tags defined in the data object definition, as 581 appropriate. For IETF standardized modules, new data object tags 582 MUST be assigned in the IANA registry defined below, see 583 Section Section 7.2. 585 7. IANA Considerations 587 7.1. YANG Data Object Tag Prefixes Registry 589 IANA is asked to create a new registry "YANG Data Object Tag 590 Prefixes" grouped under a new "Protocol" category named "YANG Data 591 Object Tag Prefixes". 593 This registry allocates tag prefixes. All YANG Data Object Tags 594 SHOULD begin with one of the prefixes in this registry. 596 Prefix entries in this registry should be short strings consisting of 597 lowercase ASCII alpha-numeric characters and a final ":" character. 599 The allocation policy for this registry is Specification Required 600 [RFC8126]. The Reference and Assignee values should be sufficient to 601 identify and contact the organization that has been allocated the 602 prefix. 604 The initial values for this registry are as follows. 606 +----------+----------------------------------+-----------+----------+ 607 | Prefix | Description | Reference | Assignee | 608 +----------+----------------------------------+-----------+----------+ 609 | ietf: | IETF Tags allocated in the IANA | [This | IETF | 610 | | IETF YANG Data Object Tags registry document]| | 611 | | | | | 612 |vendor: | Non-registered tags allocated by | [This | IETF | 613 | | the module implementer. | document] | | 614 | | | | | 615 | user: | Non-registered tags allocated by | [This | IETF | 616 | | and for the user. | document] | | 617 +----------+----------------------------------+-----------+----------+ 619 Other standards organizations (SDOs) wishing to allocate their own 620 set of tags should allocate a prefix from this registry. 622 7.2. IETF YANG Data Object Tags Registry 624 IANA is asked to create 3 new registries "IETF OPM Tags","IETF Metric 625 Group Tags","IETF Multiple Source Tags" grouped under a new 626 "Protocol" category. These 3 registries should be included below 627 "YANG Data Object Tag Prefixes" when listed on the same page. 629 3 registries allocate tags that have the registered prefix "ietf:". 630 New values should be well considered and not achievable through a 631 combination of already existing IETF tags. 633 The allocation policy for these three registries is IETF Review 634 [RFC8126]. 636 The initial values for these three registries are as follows. 638 +----------------------------+--------------------------+-----------+ 639 | OPM Tag | Description | Reference | 640 +----------------------------+--------------------------+-----------+ 641 | | | | 642 | ietf:object |Represent Root object | [This | 643 | |containing other data |document] | 644 | |object(e.g., interfaces). | | 645 | | | | 646 | ietf:property |Represent a property | [This | 647 | |data object (e.g.,ifindex)| document] | 648 | |assoiciated with specific | | 649 | |root object(e.g.,interfaces) | 650 | | | | 651 | ietf:metric |Represent metric dataobject [This | 652 | |(e.g., ifstatistics) | document] | 653 | |associated with specific | | 654 | |Root object(e.g.,interfaces) | 655 +----------------------------+--------------------------+-----------+ 656 +----------------------------+--------------------------+-----------+ 657 | Metric Type Tag | Description | Reference | 658 +----------------------------+--------------------------+-----------+ 659 | ietf:delay |Represent the delay metric| | 660 | |group which metric data | [This | 661 | |objects belongs to. | document] | 662 | | | | 663 | ietf:jitter |Represent the jitter metric [This | 664 | |group which metric data |document] | 665 | |objects belong to. | | 666 | | | | 667 | ietf:loss |Represent the loss metric | [This | 668 | |group which metric data | document] | 669 | |objectsc belong to. | | 670 | | | | 671 | ietf:counter |Represent any metric value| | 672 | |associated with metric data | 673 | |object that monotonically | [This | 674 | |increases over time, | document] | 675 | |starting from zero. | | 676 | | | | 677 | ietf:gauge |Represent current | | 678 | |measurements associated | [This | 679 | |with metric data object |document] | 680 | |that can can increase, | | 681 | |decrease or stay constant.| | 682 | | | | 683 | ietf:hisogram |Represent the frequency of| [This | 684 | |value observations | document | 685 | |associated with metric data | 686 | |that fall into specific | | 687 | |predefined range. | | 688 | | | | 689 | ietf:hisogram |Represent the metric value| [This | 690 | |associated with metric data document | 691 | |object that measures | | 692 | |distributions of discrete | | 693 | |events without knowing | | 694 | |predefined range. | | 695 | | | | 696 | ietf:unknow |Represent the metric value| [This | 697 | |associated with metric data document | 698 | |object that can not | | 699 | |deterimine the type of metric. | 700 +----------------------------+--------------------------+-----------+ 701 +----------------------------+--------------------------+-----------+ 702 | Multiple Source Tag | Description | Reference | 703 +----------------------------+--------------------------+-----------+ 704 |ietf:non-agg |Relate to multiple source | [This | 705 | |aggregation type(i.e., | document] | 706 | |aggregated statistics) | | 707 | | | | 708 |ietf:agg |Relate to multiple source | [This | 709 | |aggregation type(i.e., non| document] | 710 | |aggregated statistics) | | 711 +----------------------------+--------------------------+-----------+ 713 Each YANG data object can have one opm tag, zero or one metric-type 714 tag, zero or one multi-source tag. 716 7.3. Updates to the IETF XML Registry 718 This document registers a URI in the "IETF XML Registry" [RFC3688]. 719 Following the format in [RFC3688], the following registration has 720 been made: 722 URI: 723 urn:ietf:params:xml:ns:yang:ietf-data-object-tags 724 Registrant Contact: 725 The IESG. 726 XML: 727 N/A; the requested URI is an XML namespace. 729 7.4. Updates to the YANG Module Names Registry 731 This document registers one YANG module in the "YANG Module Names" 732 registry [RFC6020]. Following the format in [RFC6020], the following 733 registration has been made: 735 name: 736 ietf-data-object-tags 737 namespace: 738 urn:ietf:params:xml:ns:yang:ietf-data-object-tags 739 prefix: 740 ntags 741 reference: 742 RFC XXXX (RFC Ed.: replace XXX with actual RFC number and remove 743 this note.) 745 8. Security Considerations 747 The YANG module defined in this memo is designed to be accessed via 748 the NETCONF protocol [RFC6241]. The lowest NETCONF layer is the 749 secure transport layer and the mandatory-to-implement secure 750 transport is SSH [RFC6242]. 752 This document adds the ability to associate data object tag meta-data 753 with data object within the YANG modules. This document does not 754 define any actions based on these associations, and none are yet 755 defined, and therefore it does not by itself introduce any new 756 security considerations. 758 Users of the data object tag meta-data may define various actions to 759 be taken based on the data object tag meta-data. These actions and 760 their definitions are outside the scope of this document. Users will 761 need to consider the security implications of any actions they choose 762 to define. 764 9. Acknowledgements 766 The authors would like to thank Ran Tao for his major contributions 767 to the initial modeling and use cases. The authors would also like 768 to acknowledge the comments and suggestions received from Juergen 769 Schoenwaelder, Andy Bierman, Lou Berger,Jaehoon Paul Jeong, Wei Wang, 770 Yuan Zhang, Ander Liu, Peng Liu, YingZhen Qu, Boyuan Yan. 772 10. Contributors 774 Liang Geng 775 China Mobile 776 32 Xuanwumen West St, Xicheng District 777 Beijing 10053 779 Email: gengliang@chinamobile.com 781 11. References 783 11.1. Normative References 785 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 786 Requirement Levels", BCP 14, RFC 2119, 787 DOI 10.17487/RFC2119, March 1997, 788 . 790 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 791 RFC 7950, DOI 10.17487/RFC7950, August 2016, 792 . 794 [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for 795 Writing an IANA Considerations Section in RFCs", BCP 26, 796 RFC 8126, DOI 10.17487/RFC8126, June 2017, 797 . 799 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 800 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 801 May 2017, . 803 [RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 804 and R. Wilton, "Network Management Datastore Architecture 805 (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018, 806 . 808 [RFC8407] Bierman, A., "Guidelines for Authors and Reviewers of 809 Documents Containing YANG Data Models", BCP 216, RFC 8407, 810 DOI 10.17487/RFC8407, October 2018, 811 . 813 11.2. Informative References 815 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 816 DOI 10.17487/RFC3688, January 2004, 817 . 819 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 820 the Network Configuration Protocol (NETCONF)", RFC 6020, 821 DOI 10.17487/RFC6020, October 2010, 822 . 824 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 825 and A. Bierman, Ed., "Network Configuration Protocol 826 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 827 . 829 [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure 830 Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011, 831 . 833 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 834 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 835 . 837 [RFC8639] Voit, E., Clemm, A., Gonzalez Prieto, A., Nilsen-Nygaard, 838 E., and A. Tripathy, "Subscription to YANG Notifications", 839 RFC 8639, DOI 10.17487/RFC8639, September 2019, 840 . 842 [RFC8641] Clemm, A. and E. Voit, "Subscription to YANG Notifications 843 for Datastore Updates", RFC 8641, DOI 10.17487/RFC8641, 844 September 2019, . 846 Appendix A. NETCONF Example 848 The following is a fictional NETCONF example result from a query of 849 the data object tags list. For the sake of brevity only a few module 850 and associated data object results are imagined. 852 853 854 855 ietf-interfaces 856 857 858 /if:interfaces/if:interface 859 ietf:object 860 861 862 /if:interfaces/if:interface/if:last-change 863 ietf:property 864 865 866 867 /if:interfaces/if:interface/if:statistics/if:in-errors 868 869 ietf:metric 870 871 872 873 874 ietf-ip 875 876 877 /if:interfaces/if:interface/ip:ipv4 878 ietf:object 879 880 881 /if:interfaces/if:interface/ip:ipv4/ip:enable 882 ietf:property 883 884 885 /if:interfaces/if:interface/ip:ipv4/ip:mtu 886 ietf:metric 887 888 889 890 891 893 Appendix B. Non-NMDA State Module 895 As per [RFC8407] the following is a non-NMDA module to support 896 viewing the operational state for non-NMDA compliant servers. 898 file "ietf-data-object-tags-state@2019-05-03.yang" 899 module ietf-data-object-tags-state { 900 yang-version 1.1; 901 namespace "urn:ietf:params:xml:ns:yang:ietf-data-object-tags-state"; 902 prefix ntags-s; 904 import ietf-netconf-acm { 905 prefix nacm; 906 } 907 import ietf-module-tags { 908 prefix tags; 909 } 910 organization 911 "IETF NetMod Working Group (NetMod)"; 912 contact 913 "WG Web: 914 WG List: 915 Editor: Qin Wu 916 Editor: Benoit Claise 917 Editor: Peng Liu 918 Editor: Zongpeng Du "; 919 description 920 "This module describes a mechanism associating self-describing 921 tags with YANG data object within YANG modules. Tags may be IANA 922 assigned or privately defined. 924 Copyright (c) 2020 IETF Trust and the persons identified as 925 authors of the code. All rights reserved. 927 Redistribution and use in source and binary forms, with or 928 without modification, is permitted pursuant to, and subject to 929 the license terms contained in, the Simplified BSD License set 930 forth in Section 4.c of the IETF Trust's Legal Provisions 931 Relating to IETF Documents 932 (https://trustee.ietf.org/license-info). 934 This version of this YANG module is part of RFC XXXX 935 (https://tools.ietf.org/html/rfcXXXX); see the RFC itself for 936 full legal notices."; 938 revision 2019-05-03 { 939 description 940 "Initial revision."; 941 reference 942 "RFC XXXX: Self Describing Data Object Tags"; 943 } 945 extension opm-tag { 946 argument tag; 947 description 948 "The argument 'tag' is of type 'tag'. This extension statement 949 is used by module authors to indicate the opm tags that SHOULD be 950 added automatically by the system. Opm Tag is used to classify 951 operation and management data into object, property subobject, and metric 952 subobject three categories. Object can contain other objects called subobjects. 953 Property and metric objects are both subobjects belonging to specific object. 954 Both object and subobjects can be modeled as data nodes. Object can be one of 955 container, leaf-list and list. Property subobject is a leaf node. Metric subobject 956 can be one of container, leaf-list, list, leaf. Object contains zero or many 957 property subobjects, zero or many metric subobjects. As such the origin of the value 958 for the pre-defined tags should be set to 'system'[RFC8342]."; 959 } 960 extension metric-type { 961 argument tag; 962 description 963 "The argument 'tag' is of type 'tag'.The metric-type can be 964 used to provide metric subobject classification 965 (e.g., loss, jitter, packet loss,guage, counter, histogram,unknow,etc.) 966 within the YANG module."; 967 } 968 extension multi-source-tag { 969 argument tag; 970 description 971 "The argument 'tag' is of type 'tag'.The multi-source-tag can be 972 used to identify multi-source aggregation type (e.g., aggregated, 973 non-aggregated) related to metric subobject. 975 'aggregated' multi-source aggregation type allows a large number of 976 measurements on metric subobjects from different sources of the same 977 type (e.g.,line card, each subinterface of aggregated Ethernet interface) 978 being combined into aggregated statistics and report as one metric subobject 979 value. 'non-aggregated' multi-source aggregation type allows measurement from 980 each source of the same type (e.g.,line card, each subinterface of aggregated 981 Ethernet interface) be reported separately."; 982 } 984 augment "/tags:module-tags/tags:module" { 985 description 986 "Augment the Module Tags module with data object tag attributes."; 987 container data-object-tags { 988 config false; 989 status deprecated; 990 description 991 "Contains the list of data objects and their associated self describing tags."; 992 list data-object { 993 key "object-name"; 994 status deprecated; 995 description 996 "A list of data objects and their associated self describing tags."; 997 leaf object-name { 998 type nacm:node-instance-identifier; 999 mandatory true; 1000 status deprecated; 1001 description 1002 "The YANG data object name."; 1003 } 1004 leaf-list tag { 1005 type tags:tag; 1006 status deprecated; 1007 description 1008 "Tags associated with the data object within the YANG module. See 1009 the IANA 'YANG Data Object Tag Prefixes' registry for reserved 1010 prefixes and the IANA'IETF YANG Data Object Tags' registry for 1011 IETF tags. 1013 The 'operational' state [RFC8342] view of this list is 1014 constructed using the following steps: 1016 1) System tags (i.e., tags of 'system' origin) are added. 1017 2) User configured tags (i.e., tags of 'intended' origin) 1018 are added. 1019 3) Any tag that is equal to a masked-tag is removed."; 1020 } 1021 leaf-list masked-tag { 1022 type tags:tag; 1023 status deprecated; 1024 description 1025 "The list of tags that should not be associated with the data 1026 object within the YANG module. The user can remove (mask) tags from the 1027 operational state datastore [RFC8342] by adding them to 1028 this list. It is not an error to add tags to this list 1029 that are not associated with the data object within YANG module, 1030 but they have no operational effect."; 1031 } 1032 } 1033 } 1034 } 1035 } 1036 1038 Appendix C. Targeted data object collection example 1040 The following subsections provides targeted data object collection 1041 example which helps reduce amount of data to be fetched. The 1042 subscription "id" values of 22 used below is just an example. In 1043 production, the actual values of "id" might not be small integers. 1045 +-----------+ +-----------+ 1046 | Subscriber| | Publisher | 1047 +------+----+ +-----+-----+ 1048 | | 1049 | | 1050 |Telemery data Tagging Advertisement 1051 | (data object name, opm-tag = metric) 1052 |<---------------------------------| 1053 | | 1054 | establish-subscription | 1055 |--------------------------------->| 1056 | | 1057 | | 1058 | RPC Reply: OK, id = 22 | 1059 |<---------------------------------| 1060 | | 1061 | | 1062 | Notification Message (for 22) | 1063 | <--------------------------------| 1064 | | 1065 | | 1067 The publisher advertises telemetry data object capability to the 1068 subscriber to instruct the receiver to subscribe tagged data object 1069 (e.g., performance metric data object) using standard subscribed 1070 notification mechanism [RFC8639]. 1072 The following XML example [W3C.REC-xml-20081126] illustrates the 1073 advertisment of the list of available target objects using YANG 1074 instance file format [I-D.ietf-netmod-yang-instance-file-format]: 1076 1077 1079 acme-router-notification-capabilities 1080 1081 ietf-system-capabilities@2020-03-23 1082 ietf-notification-capabilities@2020-03-23 1083 ietf-data-export-capabilities@2020-03-23 1084 1085 1086 Defines the notification capabilities of an acme-router. 1087 The router only has running, and operational datastores. 1088 Every change can be reported on-change from running, but 1089 only config=true nodes and some config=false data from operational. 1090 Statistics are not reported based on timer based trigger and counter 1091 threshold based trigger. 1092 1093 1094 1099 1100 ds:operational 1101 1102 \ 1103 /if:interfaces/if:interface/if:statistics/if:in-errors\ 1104 1105 1106 metric 1107 loss 1108 1109 1110 1111 1112 1113 1115 With telemetry data tagging information carried in the Telemetry data 1116 Tagging Advertisement, the subscriber identifies targeted data object 1117 and associated data path to the datastore node and sends a standard 1118 establish-subscription RPC [RFC8639] to subscribe tagged data objects 1119 that are interests to the client application from the publisher. 1121 1123 1126 1128 ds:operational 1129 1130 1132 /if:interfaces/if:interface/if:statistics/if:in-errors 1133 1134 1135 500 1136 1137 1138 1140 The publisher returns specific object type of operational state 1141 (e.g., in-errors statistics data) subscribed by the client. 1143 Appendix D. Changes between Revisions 1145 v01-v02 1147 o Clarify the relation between data object, object tag, property tag 1148 and metric tag in figure 1 and figure 2 and related description; 1150 o Change Metric Group into Metric Type in the YANG model; 1152 o Add 5 metric types in section 7.2; 1154 v00 - v01 1156 o Merge self describing data object tag use case section into 1157 introduction section as a subsection; 1159 o Add one glossary section; 1161 o Clarify the relation between data object, object tag, property tag 1162 and metric tag in Self Describing Data Object Tags Use Case 1163 section; 1165 o Add update to RFC8407 in the front page. 1167 Authors' Addresses 1169 Qin Wu 1170 Huawei 1171 101 Software Avenue, Yuhua District 1172 Nanjing, Jiangsu 210012 1173 China 1175 Email: bill.wu@huawei.com 1177 Benoit Claise 1178 Huawei 1179 De Kleetlaan 6a b1 1180 Diegem 1831 1181 Belgium 1183 Email: benoit.claise@huawei.com 1185 Peng Liu 1186 China Mobile 1187 32 Xuanwumen West St, Xicheng District 1188 Beijing 10053 1190 Email: liupengyjy@chinamobile.com 1192 Zongpeng Du 1193 China Mobile 1194 32 Xuanwumen West St, Xicheng District 1195 Beijing 10053 1197 Email: duzongpeng@chinamobile.com 1199 Mohamed Boucadair 1200 Orange 1201 Rennes 35000 1202 France 1204 Email: mohamed.boucadair@orange.com