idnits 2.17.1 draft-ietf-netmod-geo-location-08.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 is 1 instance of too long lines in the document, the longest one being 1 character in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 804 has weird spacing: '... name ietf-...' == Line 806 has weird spacing: '...mespace urn:i...' == Line 808 has weird spacing: '... prefix geo...' -- The document date (16 April 2021) is 1105 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. 'EGM08' -- Possible downref: Non-RFC (?) normative reference: ref. 'EGM96' -- Possible downref: Non-RFC (?) normative reference: ref. 'WGS84' Summary: 1 error (**), 0 flaws (~~), 4 warnings (==), 4 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group C. Hopps 3 Internet-Draft LabN Consulting, L.L.C. 4 Intended status: Standards Track 16 April 2021 5 Expires: 18 October 2021 7 A YANG Grouping for Geographic Locations 8 draft-ietf-netmod-geo-location-08 10 Abstract 12 This document defines a generic geographical location object YANG 13 grouping. The geographical location grouping is intended to be used 14 in YANG models for specifying a location on or in reference to Earth 15 or any other astronomical object. 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 https://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 18 October 2021. 34 Copyright Notice 36 Copyright (c) 2021 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 (https://trustee.ietf.org/ 41 license-info) in effect on the date of publication of this document. 42 Please review these documents carefully, as they describe your rights 43 and restrictions with respect to this document. Code Components 44 extracted from this document must include Simplified BSD License text 45 as described in Section 4.e of the Trust Legal Provisions and are 46 provided without warranty as described in the Simplified BSD License. 48 Table of Contents 50 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 51 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 52 2. The Geo Location Object . . . . . . . . . . . . . . . . . . . 3 53 2.1. Frame of Reference . . . . . . . . . . . . . . . . . . . 3 54 2.2. Location . . . . . . . . . . . . . . . . . . . . . . . . 4 55 2.3. Motion . . . . . . . . . . . . . . . . . . . . . . . . . 4 56 2.4. Nested Locations . . . . . . . . . . . . . . . . . . . . 5 57 2.5. Non-location Attributes . . . . . . . . . . . . . . . . . 5 58 2.6. Tree . . . . . . . . . . . . . . . . . . . . . . . . . . 5 59 3. YANG Module . . . . . . . . . . . . . . . . . . . . . . . . . 6 60 4. ISO 6709:2008 Conformance . . . . . . . . . . . . . . . . . . 12 61 5. Usability . . . . . . . . . . . . . . . . . . . . . . . . . . 13 62 5.1. Portability . . . . . . . . . . . . . . . . . . . . . . . 13 63 5.1.1. IETF URI Value . . . . . . . . . . . . . . . . . . . 13 64 5.1.2. W3C . . . . . . . . . . . . . . . . . . . . . . . . . 13 65 5.1.3. Geography Markup Language (GML) . . . . . . . . . . . 15 66 5.1.4. KML . . . . . . . . . . . . . . . . . . . . . . . . . 16 67 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 17 68 6.1. Geodetic System Values Registry . . . . . . . . . . . . . 17 69 6.2. Updates to the IETF XML Registry . . . . . . . . . . . . 18 70 6.3. Updates to the YANG Module Names Registry . . . . . . . . 18 71 7. Security Considerations . . . . . . . . . . . . . . . . . . . 19 72 8. Normative References . . . . . . . . . . . . . . . . . . . . 19 73 9. Informative References . . . . . . . . . . . . . . . . . . . 21 74 Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 22 75 Appendix B. Acknowledgments . . . . . . . . . . . . . . . . . . 25 76 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 25 78 1. Introduction 80 In many applications we would like to specify the location of 81 something geographically. Some examples of locations in networking 82 might be the location of data center, a rack in an internet exchange 83 point, a router, a firewall, a port on some device, or it could be 84 the endpoints of a fiber, or perhaps the failure point along a fiber. 86 Additionally, while this location is typically relative to Earth, it 87 does not need to be. Indeed, it is easy to imagine a network or 88 device located on The Moon, on Mars, on Enceladus (the moon of 89 Saturn) or even a comet (e.g., 67p/churyumov-gerasimenko). 91 Finally, one can imagine defining locations using different frames of 92 reference or even alternate systems (e.g., simulations or virtual 93 realities). 95 This document defines a "geo-location" YANG grouping that allows for 96 all the above data to be captured. 98 This specification conforms to [ISO.6709.2008]. 100 The YANG data model described in this document conforms to the 101 Network Management Datastore Architecture defined in [RFC8342]. 103 1.1. Terminology 105 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 106 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 107 "OPTIONAL" in this document are to be interpreted as described in 108 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, 109 as shown here. 111 2. The Geo Location Object 113 2.1. Frame of Reference 115 The frame of reference ("reference-frame") defines what the location 116 values refer to and their meaning. The referred to object can be any 117 astronomical body. It could be a planet such as Earth or Mars, a 118 moon such as Enceladus, an asteroid such as Ceres, or even a comet 119 such as 1P/Halley. This value is specified in "astronomical-body" 120 and is defined by the International Astronomical Union 121 (http://www.iau.org). The default "astronomical-body" value is 122 "earth". 124 In addition to identifying the astronomical body, we also need to 125 define the meaning of the coordinates (e.g., latitude and longitude) 126 and the definition of 0-height. This is done with a "geodetic-datum" 127 value. The default value for "geodetic-datum" is "wgs-84" (i.e., the 128 World Geodetic System, [WGS84]), which is used by the Global 129 Positioning System (GPS) among many others. We define an IANA 130 registry for specifying standard values for the "geodetic-datum". 132 In addition to the "geodetic-datum" value, we allow refining the 133 coordinate and height accuracy using "coord-accuracy" and "height- 134 accuracy" respectively. When specified, these values override the 135 defaults implied by the "geodetic-datum" value. 137 Finally, we define an optional feature which allows for changing the 138 system for which the above values are defined. This optional feature 139 adds an "alternate-system" value to the reference frame. This value 140 is normally not present which implies the natural universe is the 141 system. The use of this value is intended to allow for creating 142 virtual realities or perhaps alternate coordinate systems. The 143 definition of alternate systems is outside the scope of this 144 document. 146 2.2. Location 148 This is the location on, or relative to, the astronomical object. It 149 is specified using 2 or 3 coordinates values. These values are given 150 either as "latitude", "longitude", and an optional "height", or as 151 Cartesian coordinates of "x", "y" and "z". For the standard location 152 choice "latitude" and "longitude" are specified as fractions of 153 decimal degrees, and the "height" value is in fractions of meters. 154 For the Cartesian choice "x", "y" and "z" are in fractions of meters. 155 In both choices the exact meanings of all the values are defined by 156 the "geodetic-datum" value in the Section 2.1. 158 2.3. Motion 160 Support is added for objects in relatively stable motion. For 161 objects in relatively stable motion the grouping provides a 162 3-dimensional vector value. The components of the vector are 163 "v-north", "v-east" and "v-up" which are all given in fractional 164 meters per second. The values "v-north" and "v-east" are relative to 165 true north as defined by the reference frame for the astronomical 166 body, "v-up" is perpendicular to the plane defined by "v-north" and 167 "v-east", and is pointed away from the center of mass. 169 To derive the 2-dimensional heading and speed one would use the 170 following formulas: 172 ,------------------------------ 173 speed = V v_{north}^{2} + v_{east}^{2} 175 heading = arctan(v_{east} / v_{north}) 177 For some applications that demand high accuracy, and where the data 178 is infrequently updated this velocity vector can track very slow 179 movement such as continental drift. 181 Tracking more complex forms of motion is outside the scope of this 182 work. The intent of the grouping being defined here is to identify 183 where something is located, and generally this is expected to be 184 somewhere on, or relative to, Earth (or another astronomical body). 186 At least two options are available to YANG models that wish to use 187 this grouping with objects that are changing location frequently in 188 non-simple ways. They can add additional motion data to their model 189 directly. Or, if the application allows, it can require more 190 frequent queries to keep the location data current. 192 2.4. Nested Locations 194 When locations are nested (e.g., a building may have a location which 195 houses routers that also have locations) the module using this 196 grouping is free to indicate in its definition that the "reference- 197 frame" is inherited from the containing object so that the 198 "reference-frame" need not be repeated in every instance of location 199 data. 201 2.5. Non-location Attributes 203 During the development of this module, the question of whether it 204 would support data such as orientation arose. These types of 205 attributes are outside the scope of this grouping because they do not 206 deal with a location but rather describe something more about the 207 object that is at the location. Module authors are free to add these 208 non-location attributes along with their use of this location 209 grouping. 211 2.6. Tree 213 The following is the YANG tree diagram [RFC8340] for the geo-location 214 grouping. 216 module: ietf-geo-location 217 grouping geo-location 218 +-- geo-location 219 +-- reference-frame 220 | +-- alternate-system? string {alternate-systems}? 221 | +-- astronomical-body? string 222 | +-- geodetic-system 223 | +-- geodetic-datum? string 224 | +-- coord-accuracy? decimal64 225 | +-- height-accuracy? decimal64 226 +-- (location)? 227 | +--:(ellipsoid) 228 | | +-- latitude? decimal64 229 | | +-- longitude? decimal64 230 | | +-- height? decimal64 231 | +--:(cartesian) 232 | +-- x? decimal64 233 | +-- y? decimal64 234 | +-- z? decimal64 235 +-- velocity 236 | +-- v-north? decimal64 237 | +-- v-east? decimal64 238 | +-- v-up? decimal64 239 +-- timestamp? yang:date-and-time 240 +-- valid-until? yang:date-and-time 242 3. YANG Module 244 This model imports Common YANG Data Types [RFC6991]. It uses YANG 245 version 1.1 [RFC7950] 247 file "ietf-geo-location@2019-02-17.yang" 248 module ietf-geo-location { 249 yang-version 1.1; 250 namespace "urn:ietf:params:xml:ns:yang:ietf-geo-location"; 251 prefix geo; 252 import ietf-yang-types { 253 prefix yang; 254 reference "RFC 6991: Common YANG Data Types."; 255 } 257 organization 258 "IETF NETMOD Working Group (NETMOD)"; 259 contact 260 "WG Web: 261 WG List: 263 Editor: Christian Hopps 264 "; 266 // RFC Ed.: replace XXXX with actual RFC number or IANA reference 267 // and remove this note. 269 description 270 "This module defines a grouping of a container object for 271 specifying a location on or around an astronomical object (e.g., 272 'earth'). 274 Copyright (c) 2019 IETF Trust and the persons identified as 275 authors of the code. All rights reserved. 277 Redistribution and use in source and binary forms, with or 278 without modification, is permitted pursuant to, and subject to 279 the license terms contained in, the Simplified BSD License set 280 forth in Section 4.c of the IETF Trust's Legal Provisions 281 Relating to IETF Documents 282 (https://trustee.ietf.org/license-info). 284 This version of this YANG module is part of RFC XXXX 285 (https://www.rfc-editor.org/info/rfcXXXX); see the RFC itself 286 for full legal notices. 288 // RFC Ed.: replace XXXX with the actual RFC number or IANA 289 // reference and remove this note. 291 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL 292 NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'NOT RECOMMENDED', 293 'MAY', and 'OPTIONAL' in this document are to be interpreted as 294 described in BCP 14 (RFC 2119) (RFC 8174) when, and only when, 295 they appear in all capitals, as shown here."; 297 revision 2019-02-17 { 298 description "Initial Revision"; 299 reference "RFC XXXX: A YANG Grouping for Geographic Locations"; 300 } 302 feature alternate-systems { 303 description 304 "This feature means the device supports specifying locations 305 using alternate systems for reference frames."; 306 } 308 grouping geo-location { 309 description 310 "Grouping to identify a location on an astronomical object."; 312 container geo-location { 313 description 314 "A location on an astronomical body (e.g., 'earth') 315 somewhere in a universe."; 317 container reference-frame { 318 description 319 "The Frame of Reference for the location values."; 321 leaf alternate-system { 322 if-feature alternate-systems; 323 type string; 324 description 325 "The system in which the astronomical body and 326 geodetic-datum is defined. Normally, this value is not 327 present and the system is the natural universe; however, 328 when present this value allows for specifying alternate 329 systems (e.g., virtual realities). An alternate-system 330 modifies the definition (but not the type) of the other 331 values in the reference frame."; 332 } 333 leaf astronomical-body { 334 type string { 335 pattern '[ -@\[-\^_-~]*'; 336 } 337 default "earth"; 338 description 339 "An astronomical body as named by the International 340 Astronomical Union (IAU) or according to the alternate 341 system if specified. Examples include 'sun' (our star), 342 'earth' (our planet), 'moon' (our moon), 'enceladus' (a 343 moon of Saturn), 'ceres' (an asteroid), 344 '67p/churyumov-gerasimenko (a comet). The value should 345 be comprised of all lower case ASCII characters not 346 including control characters (i.e., values 32..64, and 347 91..126). Any preceding 'the' in the name should not be 348 included."; 349 reference "https://www.iau.org/"; 350 } 351 container geodetic-system { 352 description 353 "The geodetic system of the location data."; 354 leaf geodetic-datum { 355 type string { 356 pattern '[ -@\[-\^_-~]*'; 357 } 358 default "wgs-84"; 359 description 360 "A geodetic-datum defining the meaning of latitude, 361 longitude and height. The default is 'wgs-84' which is 362 used by the Global Positioning System (GPS). The value 363 SHOULD be comprised of all lower case ASCII characters 364 not including control characters (i.e., values 32..64, 365 and 91..126). The IANA registry further restricts the 366 value by converting all spaces (' ') to dashes ('-')"; 367 reference 368 "IANA XXXX YANG Geographic Location Parameters, 369 Geodetic System Values"; 370 } 371 leaf coord-accuracy { 372 type decimal64 { 373 fraction-digits 6; 374 } 375 description 376 "The accuracy of the latitude longitude pair for 377 ellipsoidal coordinates, or the X, Y and Z components 378 for Cartesian coordinates. When coord-accuracy is 379 specified, it overrides the geodetic-datum implied 380 accuracy."; 381 } 382 leaf height-accuracy { 383 type decimal64 { 384 fraction-digits 6; 385 } 386 units "meters"; 387 description 388 "The accuracy of height value for ellipsoidal 389 coordinates, this value is not used with Cartesian 390 coordinates. When specified, it overrides the 391 geodetic-datum implied default."; 392 } 393 } 394 } 395 choice location { 396 description 397 "The location data either in lat/long or Cartesian values"; 398 case ellipsoid { 399 leaf latitude { 400 type decimal64 { 401 fraction-digits 16; 402 } 403 units "decimal degrees"; 404 description 405 "The latitude value on the astronomical body. The 406 definition and precision of this measurement is 407 indicated by the reference-frame."; 409 } 410 leaf longitude { 411 type decimal64 { 412 fraction-digits 16; 413 } 414 units "decimal degrees"; 415 description 416 "The longitude value on the astronomical body. The 417 definition and precision of this measurement is 418 indicated by the reference-frame."; 419 } 420 leaf height { 421 type decimal64 { 422 fraction-digits 6; 423 } 424 units "meters"; 425 description 426 "Height from a reference 0 value. The precision and '0' 427 value is defined by the reference-frame."; 428 } 429 } 430 case cartesian { 431 leaf x { 432 type decimal64 { 433 fraction-digits 6; 434 } 435 units "meters"; 436 description 437 "The X value as defined by the reference-frame."; 438 } 439 leaf y { 440 type decimal64 { 441 fraction-digits 6; 442 } 443 units "meters"; 444 description 445 "The Y value as defined by the reference-frame."; 446 } 447 leaf z { 448 type decimal64 { 449 fraction-digits 6; 450 } 451 units "meters"; 452 description 453 "The Z value as defined by the reference-frame."; 454 } 455 } 456 } 457 container velocity { 458 description 459 "If the object is in motion the velocity vector describes 460 this motion at the the time given by the timestamp. For a 461 formula to convert these values to speed and heading see 462 RFC XXXX."; 463 reference 464 "RFC XXXX: A YANG Grouping for Geographic Locations"; 466 leaf v-north { 467 type decimal64 { 468 fraction-digits 12; 469 } 470 units "meters per second"; 471 description 472 "v-north is the rate of change (i.e., speed) towards 473 truth north as defined by the geodetic-system."; 474 } 476 leaf v-east { 477 type decimal64 { 478 fraction-digits 12; 479 } 480 units "meters per second"; 481 description 482 "v-east is the rate of change (i.e., speed) perpendicular 483 to the right of true north as defined by 484 the geodetic-system."; 485 } 487 leaf v-up { 488 type decimal64 { 489 fraction-digits 12; 490 } 491 units "meters per second"; 492 description 493 "v-up is the rate of change (i.e., speed) away from the 494 center of mass."; 495 } 496 } 497 leaf timestamp { 498 type yang:date-and-time; 499 description "Reference time when location was recorded."; 500 } 501 leaf valid-until { 502 type yang:date-and-time; 503 description 504 "The timestamp for which this geo-location is valid until. 506 If unspecified the geo-location has no specific expiration 507 time."; 508 } 509 } 510 } 511 } 512 514 4. ISO 6709:2008 Conformance 516 [ISO.6709.2008] provides an appendix with a set of tests for 517 conformance to the standard. The tests and results are given in the 518 following table along with an explanation of non-applicable tests. 520 +---------+----------------------+------------------+ 521 | Test | Description | Pass Explanation | 522 +=========+======================+==================+ 523 | A.1.2.1 | elements reqd. for a | CRS is always | 524 | | geo. point location | indicated | 525 +---------+----------------------+------------------+ 526 | A.1.2.2 | Description of a CRS | CRS register is | 527 | | from a register | defined | 528 +---------+----------------------+------------------+ 529 | A.1.2.3 | definition of CRS | N/A - Don't | 530 | | | define CRS | 531 +---------+----------------------+------------------+ 532 | A.1.2.4 | representation of | lat/long values | 533 | | horizontal position | conform | 534 +---------+----------------------+------------------+ 535 | A.1.2.5 | representation of | height value | 536 | | vertical position | conforms | 537 +---------+----------------------+------------------+ 538 | A.1.2.6 | text string | N/A - No string | 539 | | representation | format | 540 +---------+----------------------+------------------+ 542 Table 1: Conformance Test Results 544 For test "A.1.2.1" the YANG geo location object either includes a CRS 545 ("reference-frame") or has a default defined ([WGS84]). 547 For "A.1.2.3" we do not define our own CRS, and doing so is not 548 required for conformance. 550 For "A.1.2.6" we do not define a text string representation, which is 551 also not required for conformance. 553 5. Usability 555 The geo-location object defined in this document and YANG module have 556 been designed to be usable in a very broad set of applications. This 557 includes the ability to locate things on astronomical bodies other 558 than Earth, and to utilize entirely different coordinate systems and 559 realities. 561 5.1. Portability 563 In order to verify portability while developing this module the 564 following standards and standard APIs and were considered. 566 5.1.1. IETF URI Value 568 [RFC5870] defines a standard URI value for geographic location data. 569 It includes the ability to specify the "geodetic-value" (it calls 570 this "crs") with the default being "wgs-84" [WGS84]. For the 571 location data it allows 2 to 3 coordinates defined by the "crs" 572 value. For accuracy, it has a single "u" parameter for specifying 573 uncertainty. The "u" value is in fractions of meters and applies to 574 all the location values. As the URI is a string, all values are 575 specifies as strings and so are capable of as much precision as 576 required. 578 URI values can be mapped to and from the YANG grouping, with the 579 caveat that some loss of precision (in the extremes) may occur due to 580 the YANG grouping using decimal64 values rather than strings. 582 5.1.2. W3C 584 W3C Defines a geo-location API in [W3CGEO]. We show a snippet of 585 code below which defines the geo-location data for this API. This is 586 used by many applications (e.g., Google Maps API). 588 interface GeolocationPosition { 589 readonly attribute GeolocationCoordinates coords; 590 readonly attribute DOMTimeStamp timestamp; 591 }; 593 interface GeolocationCoordinates { 594 readonly attribute double latitude; 595 readonly attribute double longitude; 596 readonly attribute double? altitude; 597 readonly attribute double accuracy; 598 readonly attribute double? altitudeAccuracy; 600 readonly attribute double? speed; 601 }; 603 Figure 1: Snippet Showing Geo-Location Definition 605 5.1.2.1. Compare with YANG Model 607 +------------------+--------------+-----------------+-------------+ 608 | Field | Type | YANG | Type | 609 +==================+==============+=================+=============+ 610 | accuracy | double | coord-accuracy | dec64 fr 6 | 611 +------------------+--------------+-----------------+-------------+ 612 | altitude | double | height | dec64 fr 6 | 613 +------------------+--------------+-----------------+-------------+ 614 | altitudeAccuracy | double | height-accuracy | dec64 fr 6 | 615 +------------------+--------------+-----------------+-------------+ 616 | heading | double | v-north, v-east | dec64 fr 12 | 617 +------------------+--------------+-----------------+-------------+ 618 | latitude | double | latitude | dec64 fr 16 | 619 +------------------+--------------+-----------------+-------------+ 620 | longitude | double | longitude | dec64 fr 16 | 621 +------------------+--------------+-----------------+-------------+ 622 | speed | double | v-north, v-east | dec64 fr 12 | 623 +------------------+--------------+-----------------+-------------+ 624 | timestamp | DOMTimeStamp | timestamp | string | 625 +------------------+--------------+-----------------+-------------+ 627 Table 2 629 accuracy (double) Accuracy of "latitude" and "longitude" values in 630 meters. 632 altitude (double) Optional height in meters above the [WGS84] 633 ellipsoid. 635 altitudeAccuracy (double) Optional accuracy of "altitude" value in 636 meters. 638 heading (double) Optional Direction in decimal deg from true north 639 increasing clock-wise. 641 latitude, longitude (double) Standard lat/long values in decimal 642 degrees. 644 speed (double) Speed along heading in meters per second. 646 timestamp (DOMTimeStamp) Specifies milliseconds since the Unix EPOCH 647 in 64 bit unsigned integer. The YANG model defines the timestamp 648 with arbitrarily large precision by using a string which 649 encompasses all representable values of this timestamp value. 651 W3C API values can be mapped to the YANG grouping, with the caveat 652 that some loss of precision (in the extremes) may occur due to the 653 YANG grouping using decimal64 values rather than doubles. 655 Conversely, only YANG values for Earth using the default "wgs-84" 656 [WGS84] as the "geodetic-datum", can be directly mapped to the W3C 657 values, as W3C does not provide the extra features necessary to map 658 the broader set of values supported by the YANG grouping. 660 5.1.3. Geography Markup Language (GML) 662 ISO adopted the Geography Markup Language (GML) defined by OGC 07-036 663 as [ISO.19136.2007]. GML defines, among many other things, a 664 position type "gml:pos" which is a sequence of "double" values. This 665 sequence of values represent coordinates in a given CRS. The CRS is 666 either inherited from containing elements or directly specified as 667 attributes "srsName" and optionally "srsDimension" on the "gml:pos". 669 GML defines an Abstract CRS type which Concrete CRS types derive 670 from. This allows for many types of CRS definitions. We are 671 concerned with the Geodetic CRS type which can have either 672 ellipsoidal or Cartesian coordinates. We believe that other non- 673 Earth based CRS as well as virtual CRS should also be representable 674 by the GML CRS types as well. 676 Thus, GML "gml:pos" values can be mapped directly to the YANG 677 grouping, with the caveat that some loss of precision (in the 678 extremes) may occur due to the YANG grouping using decimal64 values 679 rather than doubles. 681 Conversely, YANG grouping values can be mapped to GML as directly as 682 the GML CRS available definitions allow with a minimum of Earth-based 683 geodetic systems fully supported. 685 GML also defines an observation value in "gml:Observation" which 686 includes a timestamp value "gml:validTime" in addition to other 687 components such as "gml:using" "gml:target" and "gml:resultOf". Only 688 the timestamp is mappable to and from the YANG grouping. 689 Furthermore, "gml:validTime" can either be an Instantaneous measure 690 ("gml:TimeInstant") or a time period ("gml:TimePeriod"). The 691 instantaneous "gml:TimeInstant" is mappable to and from the YANG 692 grouping "timestamp" value, and values down to the resolution of 693 seconds for "gml:TimePeriod" can be mapped using the "valid-until" 694 node of the YANG grouping. 696 5.1.4. KML 698 KML 2.2 [KML22] (formerly Keyhole Markup Language) was submitted by 699 Google to the Open Geospatial Consortium, 700 (https://www.opengeospatial.org/) and was adopted. The latest 701 version as of this writing is KML 2.3 [KML23]. This schema includes 702 geographic location data in some of its objects (e.g., "kml:Point" or 703 "kml:Camera" objects). This data is provided in string format and 704 corresponds to the [W3CGEO] values. The timestamp value is also 705 specified as a string as in our YANG grouping. 707 KML has some special handling for the height value useful for 708 visualization software, "kml:altitudeMode". These values for 709 "kml:altitudeMode" include indicating the height is ignored 710 ("clampToGround"), in relation to the location's ground level 711 ("relativeToGround"), or in relation to the geodetic datum 712 ("absolute"). The YANG grouping can directly map the ignored and 713 absolute cases, but not the relative to ground case. 715 In addition to the "kml:altitudeMode" KML also defines two seafloor 716 height values using "kml:seaFloorAltitudeMode". One value is to 717 ignore the height value ("clampToSeaFloor") and the other is relative 718 ("relativeToSeaFloor"). As with the "kml:altitudeMode" value, the 719 YANG grouping supports the ignore case but not the relative case. 721 The KML location values use a geodetic datum defined in Annex A by 722 the GML Coordinate Reference System (CRS) [ISO.19136.2007] with 723 identifier "LonLat84_5773". The altitude value for KML absolute 724 height mode is measured from the vertical datum specified by [WGS84]. 726 Thus, the YANG grouping and KML values can be directly mapped in both 727 directions (when using a supported altitude mode) with the caveat 728 that some loss of precision (in the extremes) may occur due to the 729 YANG grouping using decimal64 values rather than strings. For the 730 relative height cases, the application doing the transformation is 731 expected to have the data available to transform the relative height 732 into an absolute height, which can then be expressed using the YANG 733 grouping. 735 6. IANA Considerations 737 6.1. Geodetic System Values Registry 739 IANA is asked to create a new registry "Geodetic System Values" under 740 a new protocol category group "YANG Geographic Location Parameters". 742 This registry allocates names for standard geodetic systems. Often 743 these values are referred to using multiple names (e.g., full names 744 or multiple acronyms values). The intent of this registry is to 745 provide a single standard value for any given geodetic system. 747 The values SHOULD use an acronym when available, they MUST be 748 converted to lower case, and spaces MUST be changed to dashes "-". 750 Each entry should be sufficient to define the 3 coordinate values (2 751 if height is not required). So for example the "wgs-84" is defined 752 as WGS-84 with the geoid updated by at least [EGM96] for height 753 values. Specific entries for [EGM96] and [EGM08] are present if a 754 more precise definition of the data is required. 756 It should be noted that [RFC5870] also creates a registry for 757 Geodetic Systems (it calls CRS); however, this registry has a very 758 strict modification policy. The authors of [RFC5870] have the stated 759 goal of making CRS registration hard to avoid proliferation of CRS 760 values. As our module defines alternate systems and has a broader 761 (beyond Earth) scope, the registry defined below is meant to be more 762 easily modified. 764 The allocation policy for this registry is First Come, First Served, 765 [RFC8126] as the intent is simply to avoid duplicate values. 767 The initial values for this registry are as follows. 769 +------------+------------------------------------------------------+ 770 | Name | Description | 771 +============+======================================================+ 772 | me | Mean Earth/Polar Axis (Moon) | 773 +------------+------------------------------------------------------+ 774 | mola-vik-1 | MOLA Height, IAU Viking-1 PM (Mars) | 775 +------------+------------------------------------------------------+ 776 | wgs-84-96 | World Geodetic System 1984 [WGS84] w/ EGM96 | 777 +------------+------------------------------------------------------+ 778 | wgs-84-08 | World Geodetic System 1984 [WGS84] w/ [EGM08] | 779 +------------+------------------------------------------------------+ 780 | wgs-84 | World Geodetic System 1984 [WGS84] (EGM96 or | 781 | | better) | 782 +------------+------------------------------------------------------+ 784 Table 3 786 6.2. Updates to the IETF XML Registry 788 This document registers a URI in the "IETF XML Registry" [RFC3688]. 789 Following the format in [RFC3688], the following registration has 790 been made: 792 URI urn:ietf:params:xml:ns:yang:ietf-geo-location 794 Registrant Contact The IESG. 796 XML N/A; the requested URI is an XML namespace. 798 6.3. Updates to the YANG Module Names Registry 800 This document registers one YANG module in the "YANG Module Names" 801 registry [RFC6020]. Following the format in [RFC6020], the following 802 registration has been made: 804 name ietf-geo-location 806 namespace urn:ietf:params:xml:ns:yang:ietf-geo-location 808 prefix geo 810 reference RFC XXXX (RFC Ed.: replace XXXX with RFC number and remove 811 this note.) 813 7. Security Considerations 815 The YANG module specified in this document defines a schema for data 816 that is designed to be accessed via network management protocols such 817 as NETCONF [RFC6241] or RESTCONF [RFC8040]. The lowest NETCONF layer 818 is the secure transport layer, and the mandatory-to-implement secure 819 transport is Secure Shell (SSH) [RFC6242]. The lowest RESTCONF layer 820 is HTTPS, and the mandatory-to-implement secure transport is TLS 821 [RFC8446]. 823 The NETCONF access control model [RFC8341] provides the means to 824 restrict access for particular NETCONF or RESTCONF users to a 825 preconfigured subset of all available NETCONF or RESTCONF protocol 826 operations and content. 828 Since the modules defined in this document only define groupings, 829 these considerations are primarily for the designers of other modules 830 that use these groupings. 832 All the data nodes defined in this YANG module are 833 writable/creatable/deletable (i.e., "config true", which is the 834 default). These data nodes may be considered sensitive or vulnerable 835 in some network environments. Write operations (e.g., edit-config) 836 to these data nodes without proper protection can have a negative 837 effect on network operations. These are the subtrees and data nodes 838 and their sensitivity/vulnerability: 840 None of the writable/creatable/deletable data nodes in the YANG 841 module defined in this document are by themselves considered more 842 sensitive or vulnerable than standard configuration. 844 Some of the readable data nodes in this YANG module may be considered 845 sensitive or vulnerable in some network environments. It is thus 846 important to control read access (e.g., via get, get-config, or 847 notification) to these data nodes. These are the subtrees and data 848 nodes and their sensitivity/vulnerability: 850 Since the grouping defined in this module identifies locations, 851 authors using this grouping SHOULD consider any privacy issues that 852 may arise when the data is readable (e.g., customer device locations, 853 etc). 855 This document does not define any RPC actions and hence this section 856 does not consider the security of RPCs. 858 8. Normative References 860 [EGM08] Pavlis, N.K., Holmes, S.A., Kenyon, S.C., and J.K. Factor, 861 "An Earth Gravitational Model to Degree 2160: EGM08.", 862 Presented at the 2008 General Assembly of the European 863 Geosciences Union, Vienna, Arpil13-18, 2008, 2008, 864 . 867 [EGM96] Lemoine, F.G., Kenyon, S.C., Factor, J.K., Trimmer, R.G., 868 Pavlis, N.K., Chinn, D.S., Cox, C.M., Klosko, S.M., 869 Luthcke, S.B., Torrence, M.H., Wang, Y.M., Williamson, 870 R.G., Pavlis, E.C., Rapp, R.H., and T.R. Olson, "The 871 Development of the Joint NASA GSFC and the National 872 Imagery and Mapping Agency (NIMA) Geopotential Model 873 EGM96.", Technical Report NASA/TP-1998-206861, NASA, 874 Greenbelt., 1998, 875 . 877 [ISO.6709.2008] 878 International Organization for Standardization, "ISO 879 6709:2008 Standard representation of geographic point 880 location by coordinates.", 2008. 882 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 883 Requirement Levels", BCP 14, RFC 2119, 884 DOI 10.17487/RFC2119, March 1997, 885 . 887 [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types", 888 RFC 6991, DOI 10.17487/RFC6991, July 2013, 889 . 891 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 892 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 893 May 2017, . 895 [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for 896 Writing an IANA Considerations Section in RFCs", BCP 26, 897 RFC 8126, DOI 10.17487/RFC8126, June 2017, 898 . 900 [RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 901 and R. Wilton, "Network Management Datastore Architecture 902 (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018, 903 . 905 [WGS84] National Imagery and Mapping Agency., "National Imagery 906 and Mapping Agency Technical Report 8350.2, Third 907 Edition.", 3 January 2000, . 910 9. Informative References 912 [ISO.19136.2007] 913 International Organization for Standardization, "ISO 914 19136:2007 Geographic information -- Geography Markup 915 Language (GML)". 917 [KML22] Wilson, T., Ed., "OGC KML (Version 2.2)", 14 April 2008, 918 . 921 [KML23] Burggraf, D., Ed., "OGC KML 2.3", 4 August 2015, 922 . 925 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 926 DOI 10.17487/RFC3688, January 2004, 927 . 929 [RFC5870] Mayrhofer, A. and C. Spanring, "A Uniform Resource 930 Identifier for Geographic Locations ('geo' URI)", 931 RFC 5870, DOI 10.17487/RFC5870, June 2010, 932 . 934 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 935 the Network Configuration Protocol (NETCONF)", RFC 6020, 936 DOI 10.17487/RFC6020, October 2010, 937 . 939 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 940 and A. Bierman, Ed., "Network Configuration Protocol 941 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 942 . 944 [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure 945 Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011, 946 . 948 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 949 RFC 7950, DOI 10.17487/RFC7950, August 2016, 950 . 952 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 953 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 954 . 956 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 957 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 958 . 960 [RFC8341] Bierman, A. and M. Bjorklund, "Network Configuration 961 Access Control Model", STD 91, RFC 8341, 962 DOI 10.17487/RFC8341, March 2018, 963 . 965 [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol 966 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, 967 . 969 [W3CGEO] Popescu, A., "Geolocation API Specification", 8 November 970 2016, . 973 Appendix A. Examples 975 Below is a fictitious module that uses the geo-location grouping. 977 module example-uses-geo-location { 978 namespace 979 "urn:example:example-uses-geo-location"; 980 prefix ugeo; 981 import ietf-geo-location { prefix geo; } 982 organization "Empty Org"; 983 contact "Example Author "; 984 description "Example use of geo-location"; 985 revision 2019-02-02 { reference "None"; } 986 container locatable-items { 987 description "container of locatable items"; 988 list locatable-item { 989 key name; 990 description "A of locatable item"; 991 leaf name { 992 type string; 993 description "name of locatable item"; 994 } 995 uses geo:geo-location; 996 } 997 } 998 } 999 Figure 2: Example YANG module using geo location. 1001 Below is the YANG tree for the fictitious module that uses the geo- 1002 location grouping. 1004 module: example-uses-geo-location 1005 +--rw locatable-items 1006 +--rw locatable-item* [name] 1007 +--rw name string 1008 +--rw geo-location 1009 +--rw reference-frame 1010 | +--rw alternate-system? string {alternate-systems}? 1011 | +--rw astronomical-body? string 1012 | +--rw geodetic-system 1013 | +--rw geodetic-datum? string 1014 | +--rw coord-accuracy? decimal64 1015 | +--rw height-accuracy? decimal64 1016 +--rw (location)? 1017 | +--:(ellipsoid) 1018 | | +--rw latitude? decimal64 1019 | | +--rw longitude? decimal64 1020 | | +--rw height? decimal64 1021 | +--:(cartesian) 1022 | +--rw x? decimal64 1023 | +--rw y? decimal64 1024 | +--rw z? decimal64 1025 +--rw velocity 1026 | +--rw v-north? decimal64 1027 | +--rw v-east? decimal64 1028 | +--rw v-up? decimal64 1029 +--rw timestamp? yang:date-and-time 1030 +--rw valid-until? yang:date-and-time 1032 Below is some example YANG XML data for the fictitious module that 1033 uses the geo-location grouping. 1035 1036 1037 Gaetana's 1038 1039 40.73297 1040 -74.007696 1041 1042 1043 1044 Pont des Arts 1045 1046 2012-03-31T16:00:00Z 1047 48.8583424 1048 2.3375084 1049 35 1050 1051 1052 1053 Saint Louis Cathedral 1054 1055 2013-10-12T15:00:00-06:00 1056 29.9579735 1057 -90.0637281 1058 1059 1060 1061 Apollo 11 Landing Site 1062 1063 1969-07-21T02:56:15Z 1064 1065 moon 1066 1067 me 1068 1069 1070 0.67409 1071 23.47298 1072 1073 1074 1075 Reference Frame Only 1076 1077 1078 moon 1079 1080 me 1081 1082 1083 1084 1085 1087 Figure 3: Example XML data of geo location use. 1089 Appendix B. Acknowledgments 1091 We would like to thank Jim Biard and Ben Koziol for their reviews and 1092 suggested improvements. We would also like to thank Peter Lothberg 1093 for the motivation as well as help in defining a broadly useful 1094 geographic location object, and Acee Lindem and Qin Wu for their work 1095 on a geographic location object that led to this documents' creation. 1097 Author's Address 1099 Christian Hopps 1100 LabN Consulting, L.L.C. 1102 Email: chopps@chopps.org