idnits 2.17.1 draft-ietf-netmod-rfc6991-bis-01.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 1 instance of lines with non-RFC6890-compliant IPv4 addresses in the document. If these are example addresses, they should be changed. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == The document seems to contain a disclaimer for pre-RFC5378 work, but was first submitted on or after 10 November 2008. The disclaimer is usually necessary only for documents that revise or obsolete older RFCs, and that take significant amounts of text from those RFCs. If you can contact all authors of the source material and they are willing to grant the BCP78 rights to the IETF Trust, you can and should remove the disclaimer. Otherwise, the disclaimer is needed and you can ignore this comment. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (July 21, 2019) is 1741 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) -- Possible downref: Non-RFC (?) normative reference: ref. 'XPATH' -- Obsolete informational reference (is this intentional?): RFC 793 (Obsoleted by RFC 9293) -- Obsolete informational reference (is this intentional?): RFC 2460 (Obsoleted by RFC 8200) -- Obsolete informational reference (is this intentional?): RFC 4960 (Obsoleted by RFC 9260) Summary: 0 errors (**), 0 flaws (~~), 3 warnings (==), 5 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group J. Schoenwaelder, Ed. 3 Internet-Draft Jacobs University 4 Obsoletes: 6991 (if approved) July 21, 2019 5 Intended status: Standards Track 6 Expires: January 22, 2020 8 Common YANG Data Types 9 draft-ietf-netmod-rfc6991-bis-01 11 Abstract 13 This document introduces a collection of common data types to be used 14 with the YANG data modeling language. This document obsoletes RFC 15 6991. 17 Status of this Memo 19 This Internet-Draft is submitted in full conformance with the 20 provisions of BCP 78 and BCP 79. 22 Internet-Drafts are working documents of the Internet Engineering 23 Task Force (IETF). Note that other groups may also distribute 24 working documents as Internet-Drafts. The list of current Internet- 25 Drafts is at http://datatracker.ietf.org/drafts/current/. 27 Internet-Drafts are draft documents valid for a maximum of six months 28 and may be updated, replaced, or obsoleted by other documents at any 29 time. It is inappropriate to use Internet-Drafts as reference 30 material or to cite them other than as "work in progress." 32 This Internet-Draft will expire on January 22, 2020. 34 Copyright Notice 36 Copyright (c) 2019 IETF Trust and the persons identified as the 37 document authors. All rights reserved. 39 This document is subject to BCP 78 and the IETF Trust's Legal 40 Provisions Relating to IETF Documents 41 (http://trustee.ietf.org/license-info) in effect on the date of 42 publication of this document. Please review these documents 43 carefully, as they describe your rights and restrictions with respect 44 to this document. Code Components extracted from this document must 45 include Simplified BSD License text as described in Section 4.e of 46 the Trust Legal Provisions and are provided without warranty as 47 described in the Simplified BSD License. 49 This document may contain material from IETF Documents or IETF 50 Contributions published or made publicly available before November 51 10, 2008. The person(s) controlling the copyright in some of this 52 material may not have granted the IETF Trust the right to allow 53 modifications of such material outside the IETF Standards Process. 54 Without obtaining an adequate license from the person(s) controlling 55 the copyright in such materials, this document may not be modified 56 outside the IETF Standards Process, and derivative works of it may 57 not be created outside the IETF Standards Process, except to format 58 it for publication as an RFC or to translate it into languages other 59 than English. 61 Table of Contents 63 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 64 2. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 65 3. Core YANG Derived Types . . . . . . . . . . . . . . . . . . . 6 66 4. Internet-Specific Derived Types . . . . . . . . . . . . . . . 22 67 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 35 68 6. Security Considerations . . . . . . . . . . . . . . . . . . . 36 69 7. Contributors . . . . . . . . . . . . . . . . . . . . . . . . . 37 70 8. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 38 71 9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 39 72 9.1. Normative References . . . . . . . . . . . . . . . . . . . 39 73 9.2. Informative References . . . . . . . . . . . . . . . . . . 40 74 Appendix A. Changes from RFC 6991 . . . . . . . . . . . . . . . . 44 75 Appendix B. Changes from RFC 6021 . . . . . . . . . . . . . . . . 45 76 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 46 78 1. Introduction 80 YANG [RFC7950] is a data modeling language used to model 81 configuration and state data manipulated by the Network Configuration 82 Protocol (NETCONF) [RFC6241]. The YANG language supports a small set 83 of built-in data types and provides mechanisms to derive other types 84 from the built-in types. 86 This document introduces a collection of common data types derived 87 from the built-in YANG data types. The derived types are designed to 88 be applicable for modeling all areas of management information. The 89 definitions are organized in several YANG modules. The 90 "ietf-yang-types" module contains generally useful data types. The 91 "ietf-inet-types" module contains definitions that are relevant for 92 the Internet protocol suite. 94 This document adds new type definitions to the YANG modules and 95 obsoletes [RFC6991]. For further details, see the revision 96 statements of the YANG modules in Section 3 and Section 4 and the 97 summary in Appendix A. 99 This document uses the YANG terminology defined in Section 3 of 100 [RFC7950]. 102 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 103 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 104 "OPTIONAL" in this document are to be interpreted as described in BCP 105 14 [RFC2119] [RFC8174] when, and only when, they appear in all 106 capitals, as shown here. 108 2. Overview 110 This section provides a short overview of the types defined in 111 subsequent sections and their equivalent Structure of Management 112 Information Version 2 (SMIv2) [RFC2578][RFC2579] data types. A YANG 113 data type is equivalent to an SMIv2 data type if the data types have 114 the same set of values and the semantics of the values are 115 equivalent. 117 Table 1 lists the types defined in the ietf-yang-types YANG module 118 and the corresponding SMIv2 types (- indicates there is no 119 corresponding SMIv2 type). 121 +--------------------------+--------------------------------+ 122 | YANG type | Equivalent SMIv2 type (module) | 123 +--------------------------+--------------------------------+ 124 | counter32 | Counter32 (SNMPv2-SMI) | 125 | zero-based-counter32 | ZeroBasedCounter32 (RMON2-MIB) | 126 | counter64 | Counter64 (SNMPv2-SMI) | 127 | zero-based-counter64 | ZeroBasedCounter64 (HCNUM-TC) | 128 | gauge32 | Gauge32 (SNMPv2-SMI) | 129 | gauge64 | CounterBasedGauge64 (HCNUM-TC) | 130 | object-identifier | - | 131 | object-identifier-128 | OBJECT IDENTIFIER | 132 | date-and-time | - | 133 | date | - | 134 | time | - | 135 | hours | - | 136 | minutes | - | 137 | seconds | - | 138 | centiseconds | - | 139 | milliseconds | - | 140 | microseconds | - | 141 | nanoseconds | - | 142 | timeticks | TimeTicks (SNMPv2-SMI) | 143 | timestamp | TimeStamp (SNMPv2-TC) | 144 | phys-address | PhysAddress (SNMPv2-TC) | 145 | mac-address | MacAddress (SNMPv2-TC) | 146 | xpath1.0 | - | 147 | hex-string | - | 148 | uuid | - | 149 | dotted-quad | - | 150 | yang-identifier | - | 151 | revision-identifier | - | 152 | node-instance-identifier | - | 153 +--------------------------+--------------------------------+ 155 Table 1: ietf-yang-types 157 Table 2 lists the types defined in the ietf-inet-types YANG module 158 and the corresponding SMIv2 types (if any). 160 +----------------------+--------------------------------------------+ 161 | YANG type | Equivalent SMIv2 type (module) | 162 +----------------------+--------------------------------------------+ 163 | ip-version | InetVersion (INET-ADDRESS-MIB) | 164 | dscp | Dscp (DIFFSERV-DSCP-TC) | 165 | ipv6-flow-label | IPv6FlowLabel (IPV6-FLOW-LABEL-MIB) | 166 | port-number | InetPortNumber (INET-ADDRESS-MIB) | 167 | as-number | InetAutonomousSystemNumber | 168 | | (INET-ADDRESS-MIB) | 169 | ip-address | - | 170 | ipv4-address | - | 171 | ipv6-address | - | 172 | ip-address-no-zone | - | 173 | ipv4-address-no-zone | - | 174 | ipv6-address-no-zone | - | 175 | ip-prefix | - | 176 | ipv4-prefix | - | 177 | ipv6-prefix | - | 178 | domain-name | - | 179 | host | - | 180 | uri | Uri (URI-TC-MIB) | 181 | email-address | - | 182 +----------------------+--------------------------------------------+ 184 Table 2: ietf-inet-types 186 3. Core YANG Derived Types 188 The ietf-yang-types YANG module references [IEEE802], [ISO9834-1], 189 [RFC2578], [RFC2579], [RFC2856], [RFC3339], [RFC4122], [RFC4502], 190 [RFC5322], [RFC7950], [XPATH], and [XSD-TYPES]. 192 file "ietf-yang-types@2019-07-21.yang" 194 module ietf-yang-types { 196 namespace "urn:ietf:params:xml:ns:yang:ietf-yang-types"; 197 prefix "yang"; 199 organization 200 "IETF Network Modeling (NETMOD) Working Group"; 202 contact 203 "WG Web: 204 WG List: 206 Editor: Juergen Schoenwaelder 207 "; 209 description 210 "This module contains a collection of generally useful derived 211 YANG data types. 213 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL 214 NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'NOT RECOMMENDED', 215 'MAY', and 'OPTIONAL' in this document are to be interpreted as 216 described in BCP 14 (RFC 2119) (RFC 8174) when, and only when, 217 they appear in all capitals, as shown here. 219 Copyright (c) 2019 IETF Trust and the persons identified as 220 authors of the code. All rights reserved. 222 Redistribution and use in source and binary forms, with or 223 without modification, is permitted pursuant to, and subject 224 to the license terms contained in, the Simplified BSD License 225 set forth in Section 4.c of the IETF Trust's Legal Provisions 226 Relating to IETF Documents 227 (http://trustee.ietf.org/license-info). 229 This version of this YANG module is part of RFC XXXX; 230 see the RFC itself for full legal notices."; 232 revision 2019-07-21 { 233 description 234 "This revision adds the following new data types: 235 - date, time 236 - hours, minutes, seconds 237 - centiseconds, milliseconds, microseconds, nanoseconds 238 - revision-identifier, node-instance-identifier"; 239 reference 240 "RFC XXXX: Common YANG Data Types"; 241 } 243 revision 2013-07-15 { 244 description 245 "This revision adds the following new data types: 246 - yang-identifier 247 - hex-string 248 - uuid 249 - dotted-quad"; 250 reference 251 "RFC 6991: Common YANG Data Types"; 252 } 254 revision 2010-09-24 { 255 description 256 "Initial revision."; 257 reference 258 "RFC 6021: Common YANG Data Types"; 259 } 261 /*** collection of counter and gauge types ***/ 263 typedef counter32 { 264 type uint32; 265 description 266 "The counter32 type represents a non-negative integer 267 that monotonically increases until it reaches a 268 maximum value of 2^32-1 (4294967295 decimal), when it 269 wraps around and starts increasing again from zero. 271 Counters have no defined 'initial' value, and thus, a 272 single value of a counter has (in general) no information 273 content. Discontinuities in the monotonically increasing 274 value normally occur at re-initialization of the 275 management system, and at other times as specified in the 276 description of a schema node using this type. If such 277 other times can occur, for example, the instantiation of 278 a schema node of type counter32 at times other than 279 re-initialization, then a corresponding schema node 280 should be defined, with an appropriate type, to indicate 281 the last discontinuity. 283 The counter32 type should not be used for configuration 284 schema nodes. A default statement SHOULD NOT be used in 285 combination with the type counter32. 287 In the value set and its semantics, this type is equivalent 288 to the Counter32 type of the SMIv2."; 289 reference 290 "RFC 2578: Structure of Management Information Version 2 291 (SMIv2)"; 292 } 294 typedef zero-based-counter32 { 295 type yang:counter32; 296 default "0"; 297 description 298 "The zero-based-counter32 type represents a counter32 299 that has the defined 'initial' value zero. 301 A schema node instance of this type will be set to zero (0) 302 on creation and will thereafter increase monotonically until 303 it reaches a maximum value of 2^32-1 (4294967295 decimal), 304 when it wraps around and starts increasing again from zero. 306 Provided that an application discovers a new schema node 307 instance of this type within the minimum time to wrap, it 308 can use the 'initial' value as a delta. It is important for 309 a management station to be aware of this minimum time and the 310 actual time between polls, and to discard data if the actual 311 time is too long or there is no defined minimum time. 313 In the value set and its semantics, this type is equivalent 314 to the ZeroBasedCounter32 textual convention of the SMIv2."; 315 reference 316 "RFC 4502: Remote Network Monitoring Management Information 317 Base Version 2"; 318 } 320 typedef counter64 { 321 type uint64; 322 description 323 "The counter64 type represents a non-negative integer 324 that monotonically increases until it reaches a 325 maximum value of 2^64-1 (18446744073709551615 decimal), 326 when it wraps around and starts increasing again from zero. 328 Counters have no defined 'initial' value, and thus, a 329 single value of a counter has (in general) no information 330 content. Discontinuities in the monotonically increasing 331 value normally occur at re-initialization of the 332 management system, and at other times as specified in the 333 description of a schema node using this type. If such 334 other times can occur, for example, the instantiation of 335 a schema node of type counter64 at times other than 336 re-initialization, then a corresponding schema node 337 should be defined, with an appropriate type, to indicate 338 the last discontinuity. 340 The counter64 type should not be used for configuration 341 schema nodes. A default statement SHOULD NOT be used in 342 combination with the type counter64. 344 In the value set and its semantics, this type is equivalent 345 to the Counter64 type of the SMIv2."; 346 reference 347 "RFC 2578: Structure of Management Information Version 2 348 (SMIv2)"; 349 } 351 typedef zero-based-counter64 { 352 type yang:counter64; 353 default "0"; 354 description 355 "The zero-based-counter64 type represents a counter64 that 356 has the defined 'initial' value zero. 358 A schema node instance of this type will be set to zero (0) 359 on creation and will thereafter increase monotonically until 360 it reaches a maximum value of 2^64-1 (18446744073709551615 361 decimal), when it wraps around and starts increasing again 362 from zero. 364 Provided that an application discovers a new schema node 365 instance of this type within the minimum time to wrap, it 366 can use the 'initial' value as a delta. It is important for 367 a management station to be aware of this minimum time and the 368 actual time between polls, and to discard data if the actual 369 time is too long or there is no defined minimum time. 371 In the value set and its semantics, this type is equivalent 372 to the ZeroBasedCounter64 textual convention of the SMIv2."; 373 reference 374 "RFC 2856: Textual Conventions for Additional High Capacity 375 Data Types"; 376 } 378 typedef gauge32 { 379 type uint32; 380 description 381 "The gauge32 type represents a non-negative integer, which 382 may increase or decrease, but shall never exceed a maximum 383 value, nor fall below a minimum value. The maximum value 384 cannot be greater than 2^32-1 (4294967295 decimal), and 385 the minimum value cannot be smaller than 0. The value of 386 a gauge32 has its maximum value whenever the information 387 being modeled is greater than or equal to its maximum 388 value, and has its minimum value whenever the information 389 being modeled is smaller than or equal to its minimum value. 390 If the information being modeled subsequently decreases 391 below (increases above) the maximum (minimum) value, the 392 gauge32 also decreases (increases). 394 In the value set and its semantics, this type is equivalent 395 to the Gauge32 type of the SMIv2."; 396 reference 397 "RFC 2578: Structure of Management Information Version 2 398 (SMIv2)"; 399 } 401 typedef gauge64 { 402 type uint64; 403 description 404 "The gauge64 type represents a non-negative integer, which 405 may increase or decrease, but shall never exceed a maximum 406 value, nor fall below a minimum value. The maximum value 407 cannot be greater than 2^64-1 (18446744073709551615), and 408 the minimum value cannot be smaller than 0. The value of 409 a gauge64 has its maximum value whenever the information 410 being modeled is greater than or equal to its maximum 411 value, and has its minimum value whenever the information 412 being modeled is smaller than or equal to its minimum value. 413 If the information being modeled subsequently decreases 414 below (increases above) the maximum (minimum) value, the 415 gauge64 also decreases (increases). 417 In the value set and its semantics, this type is equivalent 418 to the CounterBasedGauge64 SMIv2 textual convention defined 419 in RFC 2856"; 420 reference 421 "RFC 2856: Textual Conventions for Additional High Capacity 422 Data Types"; 423 } 425 /*** collection of identifier-related types ***/ 426 typedef object-identifier { 427 type string { 428 pattern '(([0-1](\.[1-3]?[0-9]))|(2\.(0|([1-9]\d*))))' 429 + '(\.(0|([1-9]\d*)))*'; 430 } 431 description 432 "The object-identifier type represents administratively 433 assigned names in a registration-hierarchical-name tree. 435 Values of this type are denoted as a sequence of numerical 436 non-negative sub-identifier values. Each sub-identifier 437 value MUST NOT exceed 2^32-1 (4294967295). Sub-identifiers 438 are separated by single dots and without any intermediate 439 whitespace. 441 The ASN.1 standard restricts the value space of the first 442 sub-identifier to 0, 1, or 2. Furthermore, the value space 443 of the second sub-identifier is restricted to the range 444 0 to 39 if the first sub-identifier is 0 or 1. Finally, 445 the ASN.1 standard requires that an object identifier 446 has always at least two sub-identifiers. The pattern 447 captures these restrictions. 449 Although the number of sub-identifiers is not limited, 450 module designers should realize that there may be 451 implementations that stick with the SMIv2 limit of 128 452 sub-identifiers. 454 This type is a superset of the SMIv2 OBJECT IDENTIFIER type 455 since it is not restricted to 128 sub-identifiers. Hence, 456 this type SHOULD NOT be used to represent the SMIv2 OBJECT 457 IDENTIFIER type; the object-identifier-128 type SHOULD be 458 used instead."; 459 reference 460 "ISO9834-1: Information technology -- Open Systems 461 Interconnection -- Procedures for the operation of OSI 462 Registration Authorities: General procedures and top 463 arcs of the ASN.1 Object Identifier tree"; 464 } 466 typedef object-identifier-128 { 467 type object-identifier { 468 pattern '\d*(\.\d*){1,127}'; 469 } 470 description 471 "This type represents object-identifiers restricted to 128 472 sub-identifiers. 474 In the value set and its semantics, this type is equivalent 475 to the OBJECT IDENTIFIER type of the SMIv2."; 476 reference 477 "RFC 2578: Structure of Management Information Version 2 478 (SMIv2)"; 479 } 481 /*** collection of types related to date and time ***/ 483 typedef date-and-time { 484 type string { 485 pattern '\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?' 486 + '(Z|[\+\-]\d{2}:\d{2})'; 487 } 488 description 489 "The date-and-time type is a profile of the ISO 8601 490 standard for representation of dates and times using the 491 Gregorian calendar. The profile is defined by the 492 date-time production in Section 5.6 of RFC 3339. 494 The date-and-time type is compatible with the dateTime XML 495 schema type with the following notable exceptions: 497 (a) The date-and-time type does not allow negative years. 499 (b) The date-and-time time-offset -00:00 indicates an unknown 500 time zone (see RFC 3339) while -00:00 and +00:00 and Z 501 all represent the same time zone in dateTime. 503 (c) The canonical format (see below) of date-and-time values 504 differs from the canonical format used by the dateTime XML 505 schema type, which requires all times to be in UTC using 506 the time-offset 'Z'. 508 This type is not equivalent to the DateAndTime textual 509 convention of the SMIv2 since RFC 3339 uses a different 510 separator between full-date and full-time and provides 511 higher resolution of time-secfrac. 513 The canonical format for date-and-time values with a known time 514 zone uses a numeric time zone offset that is calculated using 515 the device's configured known offset to UTC time. A change of 516 the device's offset to UTC time will cause date-and-time values 517 to change accordingly. Such changes might happen periodically 518 in case a server follows automatically daylight saving time 519 (DST) time zone offset changes. The canonical format for 520 date-and-time values with an unknown time zone (usually 521 referring to the notion of local time) uses the time-offset 522 -00:00."; 523 reference 524 "RFC 3339: Date and Time on the Internet: Timestamps 525 RFC 2579: Textual Conventions for SMIv2 526 XSD-TYPES: XML Schema Part 2: Datatypes Second Edition"; 527 } 529 typedef date { 530 type string { 531 pattern '\d{4}-\d{2}-\d{2}' 532 + '(Z|[\+\-]\d{2}:\d{2})'; 533 } 534 description 535 "The date type represents a time-interval of the length 536 of a day, i.e., 24 hours. 538 The date type is compatible with the date XML schema 539 type with the following notable exceptions: 541 (a) The date type does not allow negative years. 543 (b) The date time-offset -00:00 indicates an unknown 544 time zone (see RFC 3339) while -00:00 and +00:00 and Z 545 all represent the same time zone in date. 547 (c) The canonical format (see below) of data values 548 differs from the canonical format used by the date XML 549 schema type, which requires all times to be in UTC using 550 the time-offset 'Z'. 552 The canonical format for date values with a known time 553 zone uses a numeric time zone offset that is calculated using 554 the device's configured known offset to UTC time. A change of 555 the device's offset to UTC time will cause date values 556 to change accordingly. Such changes might happen periodically 557 in case a server follows automatically daylight saving time 558 (DST) time zone offset changes. The canonical format for 559 date values with an unknown time zone (usually referring 560 to the notion of local time) uses the time-offset -00:00."; 561 reference 562 "RFC 3339: Date and Time on the Internet: Timestamps 563 XSD-TYPES: XML Schema Part 2: Datatypes Second Edition"; 564 } 566 /* 567 * DISCUSS: 568 * - XML schema seems to use a different canonical format, we 569 * need to take a closer look how to define the canonical format 570 * given that a data really identifies a 24 hour interval and 571 * what XSD means with 'interval midpoint'. 572 */ 574 typedef time { 575 type string { 576 pattern '\d{2}:\d{2}:\d{2}(\.\d+)?' 577 + '(Z|[\+\-]\d{2}:\d{2})'; 578 } 579 description 580 "The time type represents an instance of time of zero-duration 581 that recurs every day. 583 The time type is compatible with the time XML schema 584 type with the following notable exceptions: 586 (a) The time time-offset -00:00 indicates an unknown 587 time zone (see RFC 3339) while -00:00 and +00:00 and Z 588 all represent the same time zone in time. 590 (c) The canonical format (see below) of time values 591 differs from the canonical format used by the time XML 592 schema type, which requires all times to be in UTC using 593 the time-offset 'Z'. 595 The canonical format for time values with a known time 596 zone uses a numeric time zone offset that is calculated using 597 the device's configured known offset to UTC time. A change of 598 the device's offset to UTC time will cause time values 599 to change accordingly. Such changes might happen periodically 600 in case a server follows automatically daylight saving time 601 (DST) time zone offset changes. The canonical format for 602 time values with an unknown time zone (usually referring 603 to the notion of local time) uses the time-offset -00:00."; 604 reference 605 "RFC 3339: Date and Time on the Internet: Timestamps 606 XSD-TYPES: XML Schema Part 2: Datatypes Second Edition"; 607 } 609 typedef hours { 610 type uint32; 611 units "hours"; 612 description 613 "A period of time, measured in units of hours."; 614 } 616 typedef minutes { 617 type uint32; 618 units "minutes"; 619 description 620 "A period of time, measured in units of minutes."; 621 } 623 typedef seconds { 624 type uint32; 625 units "seconds"; 626 description 627 "A period of time, measured in units of seconds. 628 The maximum duration that can be expressed is in the 629 order of 49710 days and 6 hours and 28 minutes and 15 630 seconds."; 631 } 633 typedef centiseconds { 634 type uint32; 635 units "centiseconds"; 636 description 637 "A period of time, measured in units of 10^-2 seconds. 638 The maximum duration that can be expressed is in the 639 order of 497 days and 2 hours and 27 minutes and 52 640 seconds."; 641 } 643 typedef milliseconds { 644 type uint32; 645 units "milliseconds"; 646 description 647 "A period of time, measured in units of 10^-3 seconds. 648 The maximum duration that can be expressed is in the 649 order of 49 days and 17 hours and 2 minutes and 47 650 seconds."; 651 } 653 typedef microseconds { 654 type uint32; 655 units "microseconds"; 656 description 657 "A period of time, measured in units of 10^-6 seconds. 658 The maximum duration that can be expressed is in the 659 order of 1 hour and 11 minutes and 34 seconds."; 660 } 662 typedef nanoseconds { 663 type uint32; 664 units "nanoseconds"; 665 description 666 "A period of time, measured in units of 10^-9 seconds. 667 The maximum duration that can be expressed is in the 668 order of 4 seconds."; 669 } 671 /* 672 * DISCUSS: 673 * - do we need (nano|micro|milli)seconds with 64 bits? 674 * - do we add typedef timeinterval { type centiseconds 675 * { range 0..2147483647 } } for compatibility with SMIv2? 676 * - some modules use negative minutes, do we care? A _duration_ 677 * does likely not need negative values. However, if minutes are 678 * used to represent a relative time offset, then negative minutes 679 * do make sense. Do we have to support durations as well as 680 * time offsets? 681 */ 683 typedef timeticks { 684 type uint32; 685 description 686 "The timeticks type represents a non-negative integer that 687 represents the time, modulo 2^32 (4294967296 decimal), in 688 hundredths of a second between two epochs. When a schema 689 node is defined that uses this type, the description of 690 the schema node identifies both of the reference epochs. 692 In the value set and its semantics, this type is equivalent 693 to the TimeTicks type of the SMIv2."; 694 reference 695 "RFC 2578: Structure of Management Information Version 2 696 (SMIv2)"; 697 } 699 typedef timestamp { 700 type yang:timeticks; 701 description 702 "The timestamp type represents the value of an associated 703 timeticks schema node instance at which a specific occurrence 704 happened. The specific occurrence must be defined in the 705 description of any schema node defined using this type. When 706 the specific occurrence occurred prior to the last time the 707 associated timeticks schema node instance was zero, then the 708 timestamp value is zero. 710 Note that this requires all timestamp values to be reset to 711 zero when the value of the associated timeticks schema node 712 instance reaches 497+ days and wraps around to zero. 714 The associated timeticks schema node must be specified 715 in the description of any schema node using this type. 717 In the value set and its semantics, this type is equivalent 718 to the TimeStamp textual convention of the SMIv2."; 719 reference 720 "RFC 2579: Textual Conventions for SMIv2"; 721 } 723 /*** collection of generic address types ***/ 725 typedef phys-address { 726 type string { 727 pattern '([0-9a-fA-F]{2}(:[0-9a-fA-F]{2})*)?'; 728 } 729 description 730 "Represents media- or physical-level addresses represented 731 as a sequence octets, each octet represented by two hexadecimal 732 numbers. Octets are separated by colons. The canonical 733 representation uses lowercase characters. 735 In the value set and its semantics, this type is equivalent 736 to the PhysAddress textual convention of the SMIv2."; 737 reference 738 "RFC 2579: Textual Conventions for SMIv2"; 739 } 741 typedef mac-address { 742 type string { 743 pattern '[0-9a-fA-F]{2}(:[0-9a-fA-F]{2}){5}'; 744 } 745 description 746 "The mac-address type represents an IEEE 802 MAC address. 747 The canonical representation uses lowercase characters. 749 In the value set and its semantics, this type is equivalent 750 to the MacAddress textual convention of the SMIv2."; 751 reference 752 "IEEE 802: IEEE Standard for Local and Metropolitan Area 753 Networks: Overview and Architecture 754 RFC 2579: Textual Conventions for SMIv2"; 755 } 757 /*** collection of XML-specific types ***/ 759 typedef xpath1.0 { 760 type string; 761 description 762 "This type represents an XPATH 1.0 expression. 764 When a schema node is defined that uses this type, the 765 description of the schema node MUST specify the XPath 766 context in which the XPath expression is evaluated."; 767 reference 768 "XPATH: XML Path Language (XPath) Version 1.0"; 769 } 771 /* 772 * DISCUSS: 773 * - How do we deal with xpath expressions in other encodings 774 * such as JSON. Do we assume an xpath context populated with 775 * module names such that module names can be used to qualify 776 * path expressions. This may need discussion and/or a new 777 * definition. 778 * - This interacts with the definition of node-instance-identifier. 779 */ 781 /*** collection of string types ***/ 783 typedef hex-string { 784 type string { 785 pattern '([0-9a-fA-F]{2}(:[0-9a-fA-F]{2})*)?'; 786 } 787 description 788 "A hexadecimal string with octets represented as hex digits 789 separated by colons. The canonical representation uses 790 lowercase characters."; 791 } 793 typedef uuid { 794 type string { 795 pattern '[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-' 796 + '[0-9a-fA-F]{4}-[0-9a-fA-F]{12}'; 797 } 798 description 799 "A Universally Unique IDentifier in the string representation 800 defined in RFC 4122. The canonical representation uses 801 lowercase characters. 803 The following is an example of a UUID in string representation: 804 f81d4fae-7dec-11d0-a765-00a0c91e6bf6 805 "; 806 reference 807 "RFC 4122: A Universally Unique IDentifier (UUID) URN 808 Namespace"; 809 } 810 typedef dotted-quad { 811 type string { 812 pattern 813 '(([0-9]|[1-9][0-9]|1[0-9][0-9]|2[0-4][0-9]|25[0-5])\.){3}' 814 + '([0-9]|[1-9][0-9]|1[0-9][0-9]|2[0-4][0-9]|25[0-5])'; 815 } 816 description 817 "An unsigned 32-bit number expressed in the dotted-quad 818 notation, i.e., four octets written as decimal numbers 819 and separated with the '.' (full stop) character."; 820 } 822 /*** collection of YANG specific types ***/ 824 typedef yang-identifier { 825 type string { 826 length "1..max"; 827 pattern '[a-zA-Z_][a-zA-Z0-9\-_.]*'; 828 pattern '.|..|[^xX].*|.[^mM].*|..[^lL].*'; 829 } 830 description 831 "A YANG identifier string as defined by the 'identifier' 832 rule in Section 12 of RFC 6020. An identifier must 833 start with an alphabetic character or an underscore 834 followed by an arbitrary sequence of alphabetic or 835 numeric characters, underscores, hyphens, or dots. 837 A YANG identifier MUST NOT start with any possible 838 combination of the lowercase or uppercase character 839 sequence 'xml'."; 840 reference 841 "RFC 6020: YANG - A Data Modeling Language for the Network 842 Configuration Protocol (NETCONF)"; 843 } 845 typedef revision-identifier { 846 type date { 847 pattern '\d{4}-\d{2}-\d{2}'; 848 } 849 description 850 "Represents a specific revision of a YANG module by means of 851 a date value without a time zone."; 852 } 854 typedef node-instance-identifier { 855 type xpath1.0; 856 description 857 "Path expression used to represent a special 858 data node, action, or notification instance-identifier 859 string. 861 A node-instance-identifier value is an 862 unrestricted YANG instance-identifier expression. 864 All the same rules as an instance-identifier apply, 865 except that predicates for keys are optional. If a key 866 predicate is missing, then the node-instance-identifier 867 represents all possible server instances for that key. 869 This XML Path Language (XPath) expression is evaluated in the 870 following context: 872 o The set of namespace declarations are those in scope on 873 the leaf element where this type is used. 875 o The set of variable bindings contains one variable, 876 'USER', which contains the name of the user of the 877 current session. 879 o The function library is the core function library, but 880 note that due to the syntax restrictions of an 881 instance-identifier, no functions are allowed. 883 o The context node is the root node in the data tree. 885 The accessible tree includes actions and notifications tied 886 to data nodes."; 887 } 889 /* 890 * DISCUSS: 891 * - This is taken from RFC 8341 and the idea is that this definition 892 * is useful without requiring a dependency on NACM 893 * - What does the second bullet actually do? Do we keep this? 894 * - How does this work with JSON? Can we make this encoding neutral 895 * (but then we knowingly depart from NACM)? 896 * - This interacts with the definition of xpath1.0. 897 */ 899 /* DISCUSS: 900 * - It was suggested to add types for longitude, latitude, 901 * postal code, country-code. Do we go there or do we leave 902 * these for other modules to define? It seems such definitions 903 * should go into draft-ietf-netmod-geo-location. 904 */ 906 /* DISCUSS: 907 * - It was suggested to add percentage types but they tend to differ 908 * widely. However, percentages are also widely used. 909 */ 910 } 912 914 4. Internet-Specific Derived Types 916 The ietf-inet-types YANG module references [RFC0768], [RFC0791], 917 [RFC0793], [RFC0952], [RFC1034], [RFC1123], [RFC1930], [RFC2460], 918 [RFC2474], [RFC2780], [RFC2782], [RFC3289], [RFC3305], [RFC3595], 919 [RFC3986], [RFC4001], [RFC4007], [RFC4271], [RFC4291], [RFC4340], 920 [RFC4960], [RFC5017], [RFC5890], [RFC5952], and [RFC6793]. 922 file "ietf-inet-types@2019-07-021.yang" 924 module ietf-inet-types { 926 namespace "urn:ietf:params:xml:ns:yang:ietf-inet-types"; 927 prefix "inet"; 929 organization 930 "IETF Network Modeling (NETMOD) Working Group"; 932 contact 933 "WG Web: 934 WG List: 936 Editor: Juergen Schoenwaelder 937 "; 939 description 940 "This module contains a collection of generally useful derived 941 YANG data types for Internet addresses and related things. 943 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL 944 NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'NOT RECOMMENDED', 945 'MAY', and 'OPTIONAL' in this document are to be interpreted as 946 described in BCP 14 (RFC 2119) (RFC 8174) when, and only when, 947 they appear in all capitals, as shown here. 949 Copyright (c) 2019 IETF Trust and the persons identified as 950 authors of the code. All rights reserved. 952 Redistribution and use in source and binary forms, with or 953 without modification, is permitted pursuant to, and subject 954 to the license terms contained in, the Simplified BSD License 955 set forth in Section 4.c of the IETF Trust's Legal Provisions 956 Relating to IETF Documents 957 (http://trustee.ietf.org/license-info). 959 This version of this YANG module is part of RFC XXXX; 960 see the RFC itself for full legal notices."; 962 revision 2019-07-21 { 963 description 964 "This revision adds the following new data types: 965 - ip-address-and-prefix 966 - ipv4-address-and-prefix 967 - ipv6-address-and-prefix 968 - email-address"; 969 reference 970 "RFC XXXX: Common YANG Data Types"; 971 } 973 revision 2013-07-15 { 974 description 975 "This revision adds the following new data types: 976 - ip-address-no-zone 977 - ipv4-address-no-zone 978 - ipv6-address-no-zone"; 979 reference 980 "RFC 6991: Common YANG Data Types"; 981 } 983 revision 2010-09-24 { 984 description 985 "Initial revision."; 986 reference 987 "RFC 6021: Common YANG Data Types"; 988 } 990 /*** collection of types related to protocol fields ***/ 992 typedef ip-version { 993 type enumeration { 994 enum unknown { 995 value "0"; 996 description 997 "An unknown or unspecified version of the Internet 998 protocol."; 999 } 1000 enum ipv4 { 1001 value "1"; 1002 description 1003 "The IPv4 protocol as defined in RFC 791."; 1004 } 1005 enum ipv6 { 1006 value "2"; 1007 description 1008 "The IPv6 protocol as defined in RFC 2460."; 1009 } 1011 } 1012 description 1013 "This value represents the version of the IP protocol. 1015 In the value set and its semantics, this type is equivalent 1016 to the InetVersion textual convention of the SMIv2."; 1017 reference 1018 "RFC 791: Internet Protocol 1019 RFC 2460: Internet Protocol, Version 6 (IPv6) Specification 1020 RFC 4001: Textual Conventions for Internet Network Addresses"; 1021 } 1023 typedef dscp { 1024 type uint8 { 1025 range "0..63"; 1026 } 1027 description 1028 "The dscp type represents a Differentiated Services Code Point 1029 that may be used for marking packets in a traffic stream. 1031 In the value set and its semantics, this type is equivalent 1032 to the Dscp textual convention of the SMIv2."; 1033 reference 1034 "RFC 3289: Management Information Base for the Differentiated 1035 Services Architecture 1036 RFC 2474: Definition of the Differentiated Services Field 1037 (DS Field) in the IPv4 and IPv6 Headers 1038 RFC 2780: IANA Allocation Guidelines For Values In 1039 the Internet Protocol and Related Headers"; 1040 } 1042 typedef ipv6-flow-label { 1043 type uint32 { 1044 range "0..1048575"; 1045 } 1046 description 1047 "The ipv6-flow-label type represents the flow identifier or 1048 Flow Label in an IPv6 packet header that may be used to 1049 discriminate traffic flows. 1051 In the value set and its semantics, this type is equivalent 1052 to the IPv6FlowLabel textual convention of the SMIv2."; 1053 reference 1054 "RFC 3595: Textual Conventions for IPv6 Flow Label 1055 RFC 2460: Internet Protocol, Version 6 (IPv6) Specification"; 1056 } 1058 typedef port-number { 1059 type uint16 { 1060 range "0..65535"; 1061 } 1062 description 1063 "The port-number type represents a 16-bit port number of an 1064 Internet transport-layer protocol such as UDP, TCP, DCCP, or 1065 SCTP. Port numbers are assigned by IANA. A current list of 1066 all assignments is available from . 1068 Note that the port number value zero is reserved by IANA. In 1069 situations where the value zero does not make sense, it can 1070 be excluded by subtyping the port-number type. 1072 In the value set and its semantics, this type is equivalent 1073 to the InetPortNumber textual convention of the SMIv2."; 1074 reference 1075 "RFC 768: User Datagram Protocol 1076 RFC 793: Transmission Control Protocol 1077 RFC 4960: Stream Control Transmission Protocol 1078 RFC 4340: Datagram Congestion Control Protocol (DCCP) 1079 RFC 4001: Textual Conventions for Internet Network Addresses"; 1080 } 1082 /*** collection of types related to autonomous systems ***/ 1084 typedef as-number { 1085 type uint32; 1086 description 1087 "The as-number type represents autonomous system numbers 1088 which identify an Autonomous System (AS). An AS is a set 1089 of routers under a single technical administration, using 1090 an interior gateway protocol and common metrics to route 1091 packets within the AS, and using an exterior gateway 1092 protocol to route packets to other ASes. IANA maintains 1093 the AS number space and has delegated large parts to the 1094 regional registries. 1096 Autonomous system numbers were originally limited to 16 1097 bits. BGP extensions have enlarged the autonomous system 1098 number space to 32 bits. This type therefore uses an uint32 1099 base type without a range restriction in order to support 1100 a larger autonomous system number space. 1102 In the value set and its semantics, this type is equivalent 1103 to the InetAutonomousSystemNumber textual convention of 1104 the SMIv2."; 1105 reference 1106 "RFC 1930: Guidelines for creation, selection, and registration 1107 of an Autonomous System (AS) 1108 RFC 4271: A Border Gateway Protocol 4 (BGP-4) 1109 RFC 4001: Textual Conventions for Internet Network Addresses 1110 RFC 6793: BGP Support for Four-Octet Autonomous System (AS) 1111 Number Space"; 1112 } 1114 /*** collection of types related to IP addresses and hostnames ***/ 1116 typedef ip-address { 1117 type union { 1118 type inet:ipv4-address; 1119 type inet:ipv6-address; 1120 } 1121 description 1122 "The ip-address type represents an IP address and is IP 1123 version neutral. The format of the textual representation 1124 implies the IP version. This type supports scoped addresses 1125 by allowing zone identifiers in the address format."; 1126 reference 1127 "RFC 4007: IPv6 Scoped Address Architecture"; 1128 } 1130 typedef ipv4-address { 1131 type string { 1132 pattern 1133 '(([0-9]|[1-9][0-9]|1[0-9][0-9]|2[0-4][0-9]|25[0-5])\.){3}' 1134 + '([0-9]|[1-9][0-9]|1[0-9][0-9]|2[0-4][0-9]|25[0-5])' 1135 + '(%[\p{N}\p{L}]+)?'; 1136 } 1137 description 1138 "The ipv4-address type represents an IPv4 address in 1139 dotted-quad notation. The IPv4 address may include a zone 1140 index, separated by a % sign. 1142 The zone index is used to disambiguate identical address 1143 values. For link-local addresses, the zone index will 1144 typically be the interface index number or the name of an 1145 interface. If the zone index is not present, the default 1146 zone of the device will be used. 1148 The canonical format for the zone index is the numerical 1149 format"; 1150 } 1152 typedef ipv6-address { 1153 type string { 1154 pattern '((:|[0-9a-fA-F]{0,4}):)([0-9a-fA-F]{0,4}:){0,5}' 1155 + '((([0-9a-fA-F]{0,4}:)?(:|[0-9a-fA-F]{0,4}))|' 1156 + '(((25[0-5]|2[0-4][0-9]|[01]?[0-9]?[0-9])\.){3}' 1157 + '(25[0-5]|2[0-4][0-9]|[01]?[0-9]?[0-9])))' 1158 + '(%[\p{N}\p{L}]+)?'; 1159 pattern '(([^:]+:){6}(([^:]+:[^:]+)|(.*\..*)))|' 1160 + '((([^:]+:)*[^:]+)?::(([^:]+:)*[^:]+)?)' 1161 + '(%.+)?'; 1162 } 1163 description 1164 "The ipv6-address type represents an IPv6 address in full, 1165 mixed, shortened, and shortened-mixed notation. The IPv6 1166 address may include a zone index, separated by a % sign. 1168 The zone index is used to disambiguate identical address 1169 values. For link-local addresses, the zone index will 1170 typically be the interface index number or the name of an 1171 interface. If the zone index is not present, the default 1172 zone of the device will be used. 1174 The canonical format of IPv6 addresses uses the textual 1175 representation defined in Section 4 of RFC 5952. The 1176 canonical format for the zone index is the numerical 1177 format as described in Section 11.2 of RFC 4007."; 1178 reference 1179 "RFC 4291: IP Version 6 Addressing Architecture 1180 RFC 4007: IPv6 Scoped Address Architecture 1181 RFC 5952: A Recommendation for IPv6 Address Text 1182 Representation"; 1183 } 1185 typedef ip-address-no-zone { 1186 type union { 1187 type inet:ipv4-address-no-zone; 1188 type inet:ipv6-address-no-zone; 1189 } 1190 description 1191 "The ip-address-no-zone type represents an IP address and is 1192 IP version neutral. The format of the textual representation 1193 implies the IP version. This type does not support scoped 1194 addresses since it does not allow zone identifiers in the 1195 address format."; 1196 reference 1197 "RFC 4007: IPv6 Scoped Address Architecture"; 1198 } 1200 typedef ipv4-address-no-zone { 1201 type inet:ipv4-address { 1202 pattern '[0-9\.]*'; 1204 } 1205 description 1206 "An IPv4 address without a zone index. This type, derived from 1207 ipv4-address, may be used in situations where the zone is known 1208 from the context and hence no zone index is needed."; 1209 } 1211 typedef ipv6-address-no-zone { 1212 type inet:ipv6-address { 1213 pattern '[0-9a-fA-F:\.]*'; 1214 } 1215 description 1216 "An IPv6 address without a zone index. This type, derived from 1217 ipv6-address, may be used in situations where the zone is known 1218 from the context and hence no zone index is needed."; 1219 reference 1220 "RFC 4291: IP Version 6 Addressing Architecture 1221 RFC 4007: IPv6 Scoped Address Architecture 1222 RFC 5952: A Recommendation for IPv6 Address Text 1223 Representation"; 1224 } 1226 typedef ip-prefix { 1227 type union { 1228 type inet:ipv4-prefix; 1229 type inet:ipv6-prefix; 1230 } 1231 description 1232 "The ip-prefix type represents an IP prefix and is IP 1233 version neutral. The format of the textual representations 1234 implies the IP version."; 1235 } 1237 typedef ipv4-prefix { 1238 type string { 1239 pattern 1240 '(([0-9]|[1-9][0-9]|1[0-9][0-9]|2[0-4][0-9]|25[0-5])\.){3}' 1241 + '([0-9]|[1-9][0-9]|1[0-9][0-9]|2[0-4][0-9]|25[0-5])' 1242 + '/(([0-9])|([1-2][0-9])|(3[0-2]))'; 1243 } 1244 description 1245 "The ipv4-prefix type represents an IPv4 prefix. 1246 The prefix length is given by the number following the 1247 slash character and must be less than or equal to 32. 1249 A prefix length value of n corresponds to an IP address 1250 mask that has n contiguous 1-bits from the most 1251 significant bit (MSB) and all other bits set to 0. 1253 The canonical format of an IPv4 prefix has all bits of 1254 the IPv4 address set to zero that are not part of the 1255 IPv4 prefix. 1257 The definition of ipv4-prefix does not require that bits, 1258 which are not part of the prefix, are set to zero. However, 1259 implementations have to return values in canonical format, 1260 which requires non-prefix bits to be set to zero. This means 1261 that 192.0.2.1/24 must be accepted as a valid value but it 1262 will be converted into the canonical format 192.0.2.0/24."; 1263 } 1265 typedef ipv6-prefix { 1266 type string { 1267 pattern '((:|[0-9a-fA-F]{0,4}):)([0-9a-fA-F]{0,4}:){0,5}' 1268 + '((([0-9a-fA-F]{0,4}:)?(:|[0-9a-fA-F]{0,4}))|' 1269 + '(((25[0-5]|2[0-4][0-9]|[01]?[0-9]?[0-9])\.){3}' 1270 + '(25[0-5]|2[0-4][0-9]|[01]?[0-9]?[0-9])))' 1271 + '(/(([0-9])|([0-9]{2})|(1[0-1][0-9])|(12[0-8])))'; 1272 pattern '(([^:]+:){6}(([^:]+:[^:]+)|(.*\..*)))|' 1273 + '((([^:]+:)*[^:]+)?::(([^:]+:)*[^:]+)?)' 1274 + '(/.+)'; 1275 } 1276 description 1277 "The ipv6-prefix type represents an IPv6 prefix. 1278 The prefix length is given by the number following the 1279 slash character and must be less than or equal to 128. 1281 A prefix length value of n corresponds to an IP address 1282 mask that has n contiguous 1-bits from the most 1283 significant bit (MSB) and all other bits set to 0. 1285 The canonical format of an IPv6 prefix has all bits of 1286 the IPv6 address set to zero that are not part of the 1287 IPv6 prefix. Furthermore, the IPv6 address is represented 1288 as defined in Section 4 of RFC 5952. 1290 The definition of ipv6-prefix does not require that bits, 1291 which are not part of the prefix, are set to zero. However, 1292 implementations have to return values in canonical format, 1293 which requires non-prefix bits to be set to zero. This means 1294 that 2001:db8::1/64 must be accepted as a valid value but it 1295 will be converted into the canonical format 2001:db8::/64."; 1296 reference 1297 "RFC 5952: A Recommendation for IPv6 Address Text 1298 Representation"; 1299 } 1300 typedef ip-address-and-prefix { 1301 type union { 1302 type inet:ipv4-address-and-prefix; 1303 type inet:ipv6-address-and-prefix; 1304 } 1305 description 1306 "The ip-address-and-prefix type represents an IP address and 1307 prefix and is IP version neutral. The format of the textual 1308 representations implies the IP version."; 1309 } 1311 typedef ipv4-address-and-prefix { 1312 type string { 1313 pattern 1314 '(([0-9]|[1-9][0-9]|1[0-9][0-9]|2[0-4][0-9]|25[0-5])\.){3}' 1315 + '([0-9]|[1-9][0-9]|1[0-9][0-9]|2[0-4][0-9]|25[0-5])' 1316 + '/(([0-9])|([1-2][0-9])|(3[0-2]))'; 1317 } 1318 description 1319 "The ipv4-address-and-prefix type represents an IPv4 1320 address and an associated ipv4 prefix. 1321 The prefix length is given by the number following the 1322 slash character and must be less than or equal to 32. 1324 A prefix length value of n corresponds to an IP address 1325 mask that has n contiguous 1-bits from the most 1326 significant bit (MSB) and all other bits set to 0."; 1327 } 1329 typedef ipv6-address-and-prefix { 1330 type string { 1331 pattern '((:|[0-9a-fA-F]{0,4}):)([0-9a-fA-F]{0,4}:){0,5}' 1332 + '((([0-9a-fA-F]{0,4}:)?(:|[0-9a-fA-F]{0,4}))|' 1333 + '(((25[0-5]|2[0-4][0-9]|[01]?[0-9]?[0-9])\.){3}' 1334 + '(25[0-5]|2[0-4][0-9]|[01]?[0-9]?[0-9])))' 1335 + '(/(([0-9])|([0-9]{2})|(1[0-1][0-9])|(12[0-8])))'; 1336 pattern '(([^:]+:){6}(([^:]+:[^:]+)|(.*\..*)))|' 1337 + '((([^:]+:)*[^:]+)?::(([^:]+:)*[^:]+)?)' 1338 + '(/.+)'; 1339 } 1340 description 1341 "The ipv6-address-and-prefix type represents an IPv6 1342 address and an associated ipv4 prefix. 1343 The prefix length is given by the number following the 1344 slash character and must be less than or equal to 128. 1346 A prefix length value of n corresponds to an IP address 1347 mask that has n contiguous 1-bits from the most 1348 significant bit (MSB) and all other bits set to 0. 1350 The canonical format requires that the IPv6 address is 1351 represented as defined in Section 4 of RFC 5952."; 1352 reference 1353 "RFC 5952: A Recommendation for IPv6 Address Text 1354 Representation"; 1355 } 1357 /*** collection of domain name and URI types ***/ 1359 typedef domain-name { 1360 type string { 1361 length "1..253"; 1362 pattern 1363 '((([a-zA-Z0-9_]([a-zA-Z0-9\-_]){0,61})?[a-zA-Z0-9]\.)*' 1364 + '([a-zA-Z0-9_]([a-zA-Z0-9\-_]){0,61})?[a-zA-Z0-9]\.?)' 1365 + '|\.'; 1366 } 1367 description 1368 "The domain-name type represents a DNS domain name. The 1369 name SHOULD be fully qualified whenever possible. 1371 Internet domain names are only loosely specified. Section 1372 3.5 of RFC 1034 recommends a syntax (modified in Section 1373 2.1 of RFC 1123). The pattern above is intended to allow 1374 for current practice in domain name use, and some possible 1375 future expansion. It is designed to hold various types of 1376 domain names, including names used for A or AAAA records 1377 (host names) and other records, such as SRV records. Note 1378 that Internet host names have a stricter syntax (described 1379 in RFC 952) than the DNS recommendations in RFCs 1034 and 1380 1123, and that systems that want to store host names in 1381 schema node instances using the domain-name type are 1382 recommended to adhere to this stricter standard to ensure 1383 interoperability. 1385 The encoding of DNS names in the DNS protocol is limited 1386 to 255 characters. Since the encoding consists of labels 1387 prefixed by a length bytes and there is a trailing NULL 1388 byte, only 253 characters can appear in the textual dotted 1389 notation. 1391 The description clause of schema nodes using the domain-name 1392 type MUST describe when and how these names are resolved to 1393 IP addresses. Note that the resolution of a domain-name value 1394 may require to query multiple DNS records (e.g., A for IPv4 1395 and AAAA for IPv6). The order of the resolution process and 1396 which DNS record takes precedence can either be defined 1397 explicitly or may depend on the configuration of the 1398 resolver. 1400 Domain-name values use the US-ASCII encoding. Their canonical 1401 format uses lowercase US-ASCII characters. Internationalized 1402 domain names MUST be A-labels as per RFC 5890."; 1403 reference 1404 "RFC 952: DoD Internet Host Table Specification 1405 RFC 1034: Domain Names - Concepts and Facilities 1406 RFC 1123: Requirements for Internet Hosts -- Application 1407 and Support 1408 RFC 2782: A DNS RR for specifying the location of services 1409 (DNS SRV) 1410 RFC 5890: Internationalized Domain Names in Applications 1411 (IDNA): Definitions and Document Framework"; 1412 } 1414 /* 1415 * DISCUSS: 1416 * - Lada suggested to have a type that supports wildcards and 1417 * the forward slash character. 1418 */ 1420 typedef host { 1421 type union { 1422 type inet:ip-address; 1423 type inet:domain-name; 1424 } 1425 description 1426 "The host type represents either an IP address or a DNS 1427 domain name."; 1428 } 1430 /* 1431 * DISCUSS: 1432 * - Lada suggested to replace the inet:domain-name usage in 1433 * the union with a new host-name definition that follows 1434 * the NR-LDH definition in RFC 5890. 1435 */ 1437 typedef uri { 1438 type string; 1439 description 1440 "The uri type represents a Uniform Resource Identifier 1441 (URI) as defined by STD 66. 1443 Objects using the uri type MUST be in US-ASCII encoding, 1444 and MUST be normalized as described by RFC 3986 Sections 1445 6.2.1, 6.2.2.1, and 6.2.2.2. All unnecessary 1446 percent-encoding is removed, and all case-insensitive 1447 characters are set to lowercase except for hexadecimal 1448 digits, which are normalized to uppercase as described in 1449 Section 6.2.2.1. 1451 The purpose of this normalization is to help provide 1452 unique URIs. Note that this normalization is not 1453 sufficient to provide uniqueness. Two URIs that are 1454 textually distinct after this normalization may still be 1455 equivalent. 1457 Objects using the uri type may restrict the schemes that 1458 they permit. For example, 'data:' and 'urn:' schemes 1459 might not be appropriate. 1461 A zero-length URI is not a valid URI. This can be used to 1462 express 'URI absent' where required. 1464 In the value set and its semantics, this type is equivalent 1465 to the Uri SMIv2 textual convention defined in RFC 5017."; 1466 reference 1467 "RFC 3986: Uniform Resource Identifier (URI): Generic Syntax 1468 RFC 3305: Report from the Joint W3C/IETF URI Planning Interest 1469 Group: Uniform Resource Identifiers (URIs), URLs, 1470 and Uniform Resource Names (URNs): Clarifications 1471 and Recommendations 1472 RFC 5017: MIB Textual Conventions for Uniform Resource 1473 Identifiers (URIs)"; 1474 } 1476 typedef email-address { 1477 type string { 1478 // dot-atom-text "@" ... 1479 pattern '[a-zA-Z0-9!#$%&'+"'"+'*+/=?^_`{|}~-]+' 1480 + '(\.[a-zA-Z0-9!#$%&'+"'"+'*+/=?^_`{|}~-]+)*' 1481 + '@' 1482 + '[a-zA-Z0-9!#$%&'+"'"+'*+/=?^_`{|}~-]+' 1483 + '(\.[a-zA-Z0-9!#$%&'+"'"+'*+/=?^_`{|}~-]+)*'; 1484 } 1485 description 1486 "The email-address type represents an email address as 1487 defined as addr-spec in RFC 5322 section 3.4.1."; 1488 reference 1489 "RFC 5322: Internet Message Format"; 1490 } 1491 /* 1492 * DISCUSS: 1493 * - It was suggested to add email types following RFC 5322 1494 * email-address (addr-spec, per Section 3.4.1) 1495 * named-email-address (name-addr, per Section 3.4) 1496 * - This sounds useful but the devil is in the details, 1497 * in particular name-addr is a quite complex construct; 1498 * perhaps addr-spec is sufficient, this is also the 1499 * format allowed in mailto: URIs (mailto: seems to use 1500 * only a subset of addr-spec which may be good enough 1501 * here as well). 1502 * - Need to define a pattern that has a meaningful trade-off 1503 * between precision and complexity (there are very tight 1504 * pattern that are very long and complex). The current 1505 * pattern does not take care of quoted-string, obs-local-part, 1506 * domain-literal, obs-domain. 1507 */ 1508 } 1510 1512 5. IANA Considerations 1514 This document registers two URIs in the IETF XML registry [RFC3688]. 1515 Following the format in RFC 3688, the following registrations have 1516 been made. 1518 URI: urn:ietf:params:xml:ns:yang:ietf-yang-types 1519 Registrant Contact: The NETMOD WG of the IETF. 1520 XML: N/A, the requested URI is an XML namespace. 1522 URI: urn:ietf:params:xml:ns:yang:ietf-inet-types 1523 Registrant Contact: The NETMOD WG of the IETF. 1524 XML: N/A, the requested URI is an XML namespace. 1526 This document registers two YANG modules in the YANG Module Names 1527 registry [RFC6020]. 1529 name: ietf-yang-types 1530 namespace: urn:ietf:params:xml:ns:yang:ietf-yang-types 1531 prefix: yang 1532 reference: RFC XXXX 1534 name: ietf-inet-types 1535 namespace: urn:ietf:params:xml:ns:yang:ietf-inet-types 1536 prefix: inet 1537 reference: RFC XXXX 1539 6. Security Considerations 1541 This document defines common data types using the YANG data modeling 1542 language. The definitions themselves have no security impact on the 1543 Internet, but the usage of these definitions in concrete YANG modules 1544 might have. The security considerations spelled out in the YANG 1545 specification [RFC7950] apply for this document as well. 1547 7. Contributors 1549 The following people contributed significantly to the initial version 1550 of this document: 1552 - Andy Bierman (Brocade) 1553 - Martin Bjorklund (Tail-f Systems) 1554 - Balazs Lengyel (Ericsson) 1555 - David Partain (Ericsson) 1556 - Phil Shafer (Juniper Networks) 1558 8. Acknowledgments 1560 The editor wishes to thank the following individuals for providing 1561 helpful comments on various versions of this document: Andy Bierman, 1562 Martin Bjorklund, Benoit Claise, Joel M. Halpern, Ladislav Lhotka, 1563 Lars-Johan Liman, and Dan Romascanu. 1565 Juergen Schoenwaelder was partly funded by Flamingo, a Network of 1566 Excellence project (ICT-318488) supported by the European Commission 1567 under its Seventh Framework Programme. 1569 9. References 1571 9.1. Normative References 1573 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1574 Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/ 1575 RFC2119, March 1997, 1576 . 1578 [RFC3339] Klyne, G. and C. Newman, "Date and Time on the Internet: 1579 Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002, 1580 . 1582 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 1583 DOI 10.17487/RFC3688, January 2004, 1584 . 1586 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1587 Resource Identifier (URI): Generic Syntax", STD 66, 1588 RFC 3986, DOI 10.17487/RFC3986, January 2005, 1589 . 1591 [RFC4007] Deering, S., Haberman, B., Jinmei, T., Nordmark, E., and 1592 B. Zill, "IPv6 Scoped Address Architecture", RFC 4007, 1593 DOI 10.17487/RFC4007, March 2005, 1594 . 1596 [RFC4122] Leach, P., Mealling, M., and R. Salz, "A Universally 1597 Unique IDentifier (UUID) URN Namespace", RFC 4122, 1598 DOI 10.17487/RFC4122, July 2005, 1599 . 1601 [RFC4291] Hinden, R. and S. Deering, "IP Version 6 Addressing 1602 Architecture", RFC 4291, DOI 10.17487/RFC4291, 1603 February 2006, . 1605 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 1606 the Network Configuration Protocol (NETCONF)", RFC 6020, 1607 DOI 10.17487/RFC6020, October 2010, 1608 . 1610 [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types", 1611 RFC 6991, DOI 10.17487/RFC6991, July 2013, 1612 . 1614 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 1615 RFC 7950, DOI 10.17487/RFC7950, August 2016, 1616 . 1618 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1619 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1620 May 2017, . 1622 [XPATH] Clark, J. and S. DeRose, "XML Path Language (XPath) 1623 Version 1.0", World Wide Web Consortium 1624 Recommendation REC-xpath-19991116, November 1999, 1625 . 1627 9.2. Informative References 1629 [IEEE802] IEEE, "IEEE Standard for Local and Metropolitan Area 1630 Networks: Overview and Architecture", IEEE Std. 802-2001. 1632 [ISO9834-1] 1633 ISO/IEC, "Information technology -- Open Systems 1634 Interconnection -- Procedures for the operation of OSI 1635 Registration Authorities: General procedures and top arcs 1636 of the ASN.1 Object Identifier tree", ISO/IEC 9834-1:2008, 1637 2008. 1639 [RFC0768] Postel, J., "User Datagram Protocol", STD 6, RFC 768, 1640 DOI 10.17487/RFC0768, August 1980, 1641 . 1643 [RFC0791] Postel, J., "Internet Protocol", STD 5, RFC 791, 1644 DOI 10.17487/RFC0791, September 1981, 1645 . 1647 [RFC0793] Postel, J., "Transmission Control Protocol", STD 7, 1648 RFC 793, DOI 10.17487/RFC0793, September 1981, 1649 . 1651 [RFC0952] Harrenstien, K., Stahl, M., and E. Feinler, "DoD Internet 1652 host table specification", RFC 952, DOI 10.17487/RFC0952, 1653 October 1985, . 1655 [RFC1034] Mockapetris, P., "Domain names - concepts and facilities", 1656 STD 13, RFC 1034, DOI 10.17487/RFC1034, November 1987, 1657 . 1659 [RFC1123] Braden, R., Ed., "Requirements for Internet Hosts - 1660 Application and Support", STD 3, RFC 1123, DOI 10.17487/ 1661 RFC1123, October 1989, 1662 . 1664 [RFC1930] Hawkinson, J. and T. Bates, "Guidelines for creation, 1665 selection, and registration of an Autonomous System (AS)", 1666 BCP 6, RFC 1930, DOI 10.17487/RFC1930, March 1996, 1667 . 1669 [RFC2460] Deering, S. and R. Hinden, "Internet Protocol, Version 6 1670 (IPv6) Specification", RFC 2460, DOI 10.17487/RFC2460, 1671 December 1998, . 1673 [RFC2474] Nichols, K., Blake, S., Baker, F., and D. Black, 1674 "Definition of the Differentiated Services Field (DS 1675 Field) in the IPv4 and IPv6 Headers", RFC 2474, 1676 DOI 10.17487/RFC2474, December 1998, 1677 . 1679 [RFC2578] McCloghrie, K., Ed., Perkins, D., Ed., and J. 1680 Schoenwaelder, Ed., "Structure of Management Information 1681 Version 2 (SMIv2)", STD 58, RFC 2578, DOI 10.17487/ 1682 RFC2578, April 1999, 1683 . 1685 [RFC2579] McCloghrie, K., Ed., Perkins, D., Ed., and J. 1686 Schoenwaelder, Ed., "Textual Conventions for SMIv2", 1687 STD 58, RFC 2579, DOI 10.17487/RFC2579, April 1999, 1688 . 1690 [RFC2780] Bradner, S. and V. Paxson, "IANA Allocation Guidelines For 1691 Values In the Internet Protocol and Related Headers", 1692 BCP 37, RFC 2780, DOI 10.17487/RFC2780, March 2000, 1693 . 1695 [RFC2782] Gulbrandsen, A., Vixie, P., and L. Esibov, "A DNS RR for 1696 specifying the location of services (DNS SRV)", RFC 2782, 1697 DOI 10.17487/RFC2782, February 2000, 1698 . 1700 [RFC2856] Bierman, A., McCloghrie, K., and R. Presuhn, "Textual 1701 Conventions for Additional High Capacity Data Types", 1702 RFC 2856, DOI 10.17487/RFC2856, June 2000, 1703 . 1705 [RFC3289] Baker, F., Chan, K., and A. Smith, "Management Information 1706 Base for the Differentiated Services Architecture", 1707 RFC 3289, DOI 10.17487/RFC3289, May 2002, 1708 . 1710 [RFC3305] Mealling, M., Ed. and R. Denenberg, Ed., "Report from the 1711 Joint W3C/IETF URI Planning Interest Group: Uniform 1712 Resource Identifiers (URIs), URLs, and Uniform Resource 1713 Names (URNs): Clarifications and Recommendations", 1714 RFC 3305, DOI 10.17487/RFC3305, August 2002, 1715 . 1717 [RFC3595] Wijnen, B., "Textual Conventions for IPv6 Flow Label", 1718 RFC 3595, DOI 10.17487/RFC3595, September 2003, 1719 . 1721 [RFC4001] Daniele, M., Haberman, B., Routhier, S., and J. 1722 Schoenwaelder, "Textual Conventions for Internet Network 1723 Addresses", RFC 4001, DOI 10.17487/RFC4001, February 2005, 1724 . 1726 [RFC4271] Rekhter, Y., Ed., Li, T., Ed., and S. Hares, Ed., "A 1727 Border Gateway Protocol 4 (BGP-4)", RFC 4271, 1728 DOI 10.17487/RFC4271, January 2006, 1729 . 1731 [RFC4340] Kohler, E., Handley, M., and S. Floyd, "Datagram 1732 Congestion Control Protocol (DCCP)", RFC 4340, 1733 DOI 10.17487/RFC4340, March 2006, 1734 . 1736 [RFC4502] Waldbusser, S., "Remote Network Monitoring Management 1737 Information Base Version 2", RFC 4502, DOI 10.17487/ 1738 RFC4502, May 2006, 1739 . 1741 [RFC4960] Stewart, R., Ed., "Stream Control Transmission Protocol", 1742 RFC 4960, DOI 10.17487/RFC4960, September 2007, 1743 . 1745 [RFC5017] McWalter, D., Ed., "MIB Textual Conventions for Uniform 1746 Resource Identifiers (URIs)", RFC 5017, DOI 10.17487/ 1747 RFC5017, September 2007, 1748 . 1750 [RFC5322] Resnick, P., Ed., "Internet Message Format", RFC 5322, 1751 DOI 10.17487/RFC5322, October 2008, 1752 . 1754 [RFC5890] Klensin, J., "Internationalized Domain Names for 1755 Applications (IDNA): Definitions and Document Framework", 1756 RFC 5890, DOI 10.17487/RFC5890, August 2010, 1757 . 1759 [RFC5952] Kawamura, S. and M. Kawashima, "A Recommendation for IPv6 1760 Address Text Representation", RFC 5952, DOI 10.17487/ 1761 RFC5952, August 2010, 1762 . 1764 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 1765 and A. Bierman, Ed., "Network Configuration Protocol 1766 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 1767 . 1769 [RFC6793] Vohra, Q. and E. Chen, "BGP Support for Four-Octet 1770 Autonomous System (AS) Number Space", RFC 6793, 1771 DOI 10.17487/RFC6793, December 2012, 1772 . 1774 [XSD-TYPES] 1775 Malhotra, A. and P. Biron, "XML Schema Part 2: Datatypes 1776 Second Edition", World Wide Web Consortium 1777 Recommendation REC-xmlschema-2-20041028, October 2004, 1778 . 1780 Appendix A. Changes from RFC 6991 1782 This version adds new type definitions to the YANG modules. The 1783 following new data types have been added to the ietf-yang-types 1784 module: 1786 o date, time 1788 o hours, minutes, seconds 1790 o centiseconds, milliseconds, microseconds, nanoseconds 1792 o revision-identifier, node-instance-identifier 1794 The following new data types have been added to the ietf-inet-types 1795 module: 1797 o ip-address-and-prefix, ipv4-address-and-prefix, ipv6-address-and- 1798 prefix 1800 o email-address 1802 Appendix B. Changes from RFC 6021 1804 This version adds new type definitions to the YANG modules. The 1805 following new data types have been added to the ietf-yang-types 1806 module: 1808 o yang-identifier 1810 o hex-string 1812 o uuid 1814 o dotted-quad 1816 The following new data types have been added to the ietf-inet-types 1817 module: 1819 o ip-address-no-zone 1821 o ipv4-address-no-zone 1823 o ipv6-address-no-zone 1825 Author's Address 1827 Juergen Schoenwaelder (editor) 1828 Jacobs University 1830 Email: j.schoenwaelder@jacobs-university.de