idnits 2.17.1 draft-ietf-netmod-geo-location-11.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 824 has weird spacing: '... name ietf-...' == Line 826 has weird spacing: '...mespace urn:i...' == Line 828 has weird spacing: '... prefix geo...' -- The document date (24 October 2021) is 916 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. 'ME' -- Possible downref: Non-RFC (?) normative reference: ref. 'WGS84' Summary: 0 errors (**), 0 flaws (~~), 4 warnings (==), 5 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 24 October 2021 5 Expires: 27 April 2022 7 A YANG Grouping for Geographic Locations 8 draft-ietf-netmod-geo-location-11 10 Abstract 12 This document defines a generic geographical location YANG grouping. 13 The geographical location grouping is intended to be used in YANG 14 models for specifying a location on or in reference to Earth or any 15 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 27 April 2022. 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 . . . . . . . . . . . . . . . . . . . 14 64 5.1.2. W3C . . . . . . . . . . . . . . . . . . . . . . . . . 14 65 5.1.3. Geography Markup Language (GML) . . . . . . . . . . . 16 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 . . . . . . . . 19 71 7. Security Considerations . . . . . . . . . . . . . . . . . . . 19 72 8. Normative References . . . . . . . . . . . . . . . . . . . . 20 73 9. Informative References . . . . . . . . . . . . . . . . . . . 21 74 Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 22 75 Appendix B. Acknowledgments . . . . . . . . . . . . . . . . . . 25 76 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 26 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 overriding 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 decimal degrees, 153 and the "height" value is in fractions of meters. For the Cartesian 154 choice "x", "y" and "z" are in fractions of meters. In both choices 155 the exact meanings of all the values are defined by the "geodetic- 156 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 ASCII value 345 SHOULD have upper case converted to lower case and not 346 include 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 description 359 "A geodetic-datum defining the meaning of latitude, 360 longitude and height. The default when the 361 astronomical body is 'earth' is 'wgs-84' which is 362 used by the Global Positioning System (GPS). The 363 ASCII value SHOULD have upper case converted to lower 364 case and not include control characters (i.e., values 365 32..64, and 91..126). The IANA registry further 366 restricts the value by converting all spaces (' ') to 367 dashes ('-'). 368 The specification for the geodetic-datum indicates 369 how accurately it models the astronomical body in 370 question, both for the 'horizontal' 371 latitude/longitude coordinates and for height 372 coordinates."; 373 reference 374 "IANA XXXX YANG Geographic Location Parameters, 375 Geodetic System Values"; 376 } 377 leaf coord-accuracy { 378 type decimal64 { 379 fraction-digits 6; 380 } 381 description 382 "The accuracy of the latitude longitude pair for 383 ellipsoidal coordinates, or the X, Y and Z components 384 for Cartesian coordinates. When coord-accuracy is 385 specified, it indicates how precisely the coordinates 386 in the associated list of locations have been 387 determined with respect to the coordinate system 388 defined by the geodetic-datum. For example, there 389 might be uncertainty due to measurement error if an 390 experimental measurement was made to determine each 391 location."; 392 } 393 leaf height-accuracy { 394 type decimal64 { 395 fraction-digits 6; 396 } 397 units "meters"; 398 description 399 "The accuracy of height value for ellipsoidal 400 coordinates, this value is not used with Cartesian 401 coordinates. When height-accuracy is specified, it 402 indicates how precisely the heights in the 403 associated list of locations have been determined 404 with respect to the coordinate system defined by the 405 geodetic-datum. For example, there might be 406 uncertainty due to measurement error if an 407 experimental measurement was made to determine each 408 location."; 409 } 410 } 411 } 412 choice location { 413 description 414 "The location data either in lat/long or Cartesian values"; 415 case ellipsoid { 416 leaf latitude { 417 type decimal64 { 418 fraction-digits 16; 419 } 420 units "decimal degrees"; 421 description 422 "The latitude value on the astronomical body. The 423 definition and precision of this measurement is 424 indicated by the reference-frame."; 425 } 426 leaf longitude { 427 type decimal64 { 428 fraction-digits 16; 429 } 430 units "decimal degrees"; 431 description 432 "The longitude value on the astronomical body. The 433 definition and precision of this measurement is 434 indicated by the reference-frame."; 435 } 436 leaf height { 437 type decimal64 { 438 fraction-digits 6; 439 } 440 units "meters"; 441 description 442 "Height from a reference 0 value. The precision and '0' 443 value is defined by the reference-frame."; 444 } 445 } 446 case cartesian { 447 leaf x { 448 type decimal64 { 449 fraction-digits 6; 450 } 451 units "meters"; 452 description 453 "The X value as defined by the reference-frame."; 454 } 455 leaf y { 456 type decimal64 { 457 fraction-digits 6; 458 } 459 units "meters"; 460 description 461 "The Y value as defined by the reference-frame."; 462 } 463 leaf z { 464 type decimal64 { 465 fraction-digits 6; 466 } 467 units "meters"; 468 description 469 "The Z value as defined by the reference-frame."; 470 } 471 } 472 } 473 container velocity { 474 description 475 "If the object is in motion the velocity vector describes 476 this motion at the the time given by the timestamp. For a 477 formula to convert these values to speed and heading see 478 RFC XXXX."; 479 reference 480 "RFC XXXX: A YANG Grouping for Geographic Locations"; 482 leaf v-north { 483 type decimal64 { 484 fraction-digits 12; 485 } 486 units "meters per second"; 487 description 488 "v-north is the rate of change (i.e., speed) towards 489 truth north as defined by the geodetic-system."; 490 } 492 leaf v-east { 493 type decimal64 { 494 fraction-digits 12; 495 } 496 units "meters per second"; 497 description 498 "v-east is the rate of change (i.e., speed) perpendicular 499 to the right of true north as defined by 500 the geodetic-system."; 501 } 503 leaf v-up { 504 type decimal64 { 505 fraction-digits 12; 506 } 507 units "meters per second"; 508 description 509 "v-up is the rate of change (i.e., speed) away from the 510 center of mass."; 511 } 512 } 513 leaf timestamp { 514 type yang:date-and-time; 515 description "Reference time when location was recorded."; 516 } 517 leaf valid-until { 518 type yang:date-and-time; 519 description 520 "The timestamp for which this geo-location is valid until. 521 If unspecified the geo-location has no specific expiration 522 time."; 523 } 524 } 525 } 526 } 527 529 4. ISO 6709:2008 Conformance 531 [ISO.6709.2008] provides an appendix with a set of tests for 532 conformance to the standard. The tests and results are given in the 533 following table along with an explanation of non-applicable tests. 535 +---------+----------------------+------------------+ 536 | Test | Description | Pass Explanation | 537 +=========+======================+==================+ 538 | A.1.2.1 | elements reqd. for a | CRS is always | 539 | | geo. point location | indicated | 540 +---------+----------------------+------------------+ 541 | A.1.2.2 | Description of a CRS | CRS register is | 542 | | from a register | defined | 543 +---------+----------------------+------------------+ 544 | A.1.2.3 | definition of CRS | N/A - Don't | 545 | | | define CRS | 546 +---------+----------------------+------------------+ 547 | A.1.2.4 | representation of | lat/long values | 548 | | horizontal position | conform | 549 +---------+----------------------+------------------+ 550 | A.1.2.5 | representation of | height value | 551 | | vertical position | conforms | 552 +---------+----------------------+------------------+ 553 | A.1.2.6 | text string | N/A - No string | 554 | | representation | format | 555 +---------+----------------------+------------------+ 557 Table 1: Conformance Test Results 559 For test "A.1.2.1" the YANG geo location object either includes a 560 Coordinate Reference System (CRS) ("reference-frame") or has a 561 default defined ([WGS84]). 563 For "A.1.2.3" we do not define our own CRS, and doing so is not 564 required for conformance. 566 For "A.1.2.6" we do not define a text string representation, which is 567 also not required for conformance. 569 5. Usability 571 The geo-location object defined in this document and YANG module have 572 been designed to be usable in a very broad set of applications. This 573 includes the ability to locate things on astronomical bodies other 574 than Earth, and to utilize entirely different coordinate systems and 575 realities. 577 5.1. Portability 579 In order to verify portability while developing this module the 580 following standards and standard APIs were considered. 582 5.1.1. IETF URI Value 584 [RFC5870] defines a standard URI value for geographic location data. 585 It includes the ability to specify the "geodetic-value" (it calls 586 this "crs") with the default being "wgs-84" [WGS84]. For the 587 location data it allows 2 to 3 coordinates defined by the "crs" 588 value. For accuracy, it has a single "u" parameter for specifying 589 uncertainty. The "u" value is in fractions of meters and applies to 590 all the location values. As the URI is a string, all values are 591 specified as strings and so are capable of as much precision as 592 required. 594 URI values can be mapped to and from the YANG grouping, with the 595 caveat that some loss of precision (in the extremes) may occur due to 596 the YANG grouping using decimal64 values rather than strings. 598 5.1.2. W3C 600 W3C Defines a geo-location API in [W3CGEO]. We show a snippet of 601 code below which defines the geo-location data for this API. This is 602 used by many applications (e.g., Google Maps API). 604 interface GeolocationPosition { 605 readonly attribute GeolocationCoordinates coords; 606 readonly attribute DOMTimeStamp timestamp; 607 }; 609 interface GeolocationCoordinates { 610 readonly attribute double latitude; 611 readonly attribute double longitude; 612 readonly attribute double? altitude; 613 readonly attribute double accuracy; 614 readonly attribute double? altitudeAccuracy; 615 readonly attribute double? heading; 616 readonly attribute double? speed; 617 }; 619 Figure 1: Snippet Showing Geo-Location Definition 621 5.1.2.1. Compare with YANG Model 623 +------------------+--------------+-----------------+-------------+ 624 | Field | Type | YANG | Type | 625 +==================+==============+=================+=============+ 626 | accuracy | double | coord-accuracy | dec64 fr 6 | 627 +------------------+--------------+-----------------+-------------+ 628 | altitude | double | height | dec64 fr 6 | 629 +------------------+--------------+-----------------+-------------+ 630 | altitudeAccuracy | double | height-accuracy | dec64 fr 6 | 631 +------------------+--------------+-----------------+-------------+ 632 | heading | double | v-north, v-east | dec64 fr 12 | 633 +------------------+--------------+-----------------+-------------+ 634 | latitude | double | latitude | dec64 fr 16 | 635 +------------------+--------------+-----------------+-------------+ 636 | longitude | double | longitude | dec64 fr 16 | 637 +------------------+--------------+-----------------+-------------+ 638 | speed | double | v-north, v-east | dec64 fr 12 | 639 +------------------+--------------+-----------------+-------------+ 640 | timestamp | DOMTimeStamp | timestamp | string | 641 +------------------+--------------+-----------------+-------------+ 643 Table 2 645 accuracy (double) Accuracy of "latitude" and "longitude" values in 646 meters. 648 altitude (double) Optional height in meters above the [WGS84] 649 ellipsoid. 651 altitudeAccuracy (double) Optional accuracy of "altitude" value in 652 meters. 654 heading (double) Optional Direction in decimal deg from true north 655 increasing clock-wise. 657 latitude, longitude (double) Standard lat/long values in decimal 658 degrees. 660 speed (double) Speed along heading in meters per second. 662 timestamp (DOMTimeStamp) Specifies milliseconds since the Unix EPOCH 663 in 64 bit unsigned integer. The YANG model defines the timestamp 664 with arbitrarily large precision by using a string which 665 encompasses all representable values of this timestamp value. 667 W3C API values can be mapped to the YANG grouping, with the caveat 668 that some loss of precision (in the extremes) may occur due to the 669 YANG grouping using decimal64 values rather than doubles. 671 Conversely, only YANG values for Earth using the default "wgs-84" 672 [WGS84] as the "geodetic-datum", can be directly mapped to the W3C 673 values, as W3C does not provide the extra features necessary to map 674 the broader set of values supported by the YANG grouping. 676 5.1.3. Geography Markup Language (GML) 678 ISO adopted the Geography Markup Language (GML) defined by OGC 07-036 679 as [ISO.19136.2007]. GML defines, among many other things, a 680 position type "gml:pos" which is a sequence of "double" values. This 681 sequence of values represents coordinates in a given CRS. The CRS is 682 either inherited from containing elements or directly specified as 683 attributes "srsName" and optionally "srsDimension" on the "gml:pos". 685 GML defines an Abstract CRS type which Concrete CRS types derive 686 from. This allows for many types of CRS definitions. We are 687 concerned with the Geodetic CRS type which can have either 688 ellipsoidal or Cartesian coordinates. We believe that other non- 689 Earth based CRS as well as virtual CRS should also be representable 690 by the GML CRS types. 692 Thus, GML "gml:pos" values can be mapped directly to the YANG 693 grouping, with the caveat that some loss of precision (in the 694 extremes) may occur due to the YANG grouping using decimal64 values 695 rather than doubles. 697 Conversely, YANG grouping values can be mapped to GML as directly as 698 the GML CRS available definitions allow with a minimum of Earth-based 699 geodetic systems fully supported. 701 GML also defines an observation value in "gml:Observation" which 702 includes a timestamp value "gml:validTime" in addition to other 703 components such as "gml:using" "gml:target" and "gml:resultOf". Only 704 the timestamp is mappable to and from the YANG grouping. 705 Furthermore, "gml:validTime" can either be an Instantaneous measure 706 ("gml:TimeInstant") or a time period ("gml:TimePeriod"). The 707 instantaneous "gml:TimeInstant" is mappable to and from the YANG 708 grouping "timestamp" value, and values down to the resolution of 709 seconds for "gml:TimePeriod" can be mapped using the "valid-until" 710 node of the YANG grouping. 712 5.1.4. KML 714 KML 2.2 [KML22] (formerly Keyhole Markup Language) was submitted by 715 Google to the Open Geospatial Consortium, 716 (https://www.opengeospatial.org/) and was adopted. The latest 717 version as of this writing is KML 2.3 [KML23]. This schema includes 718 geographic location data in some of its objects (e.g., "kml:Point" or 719 "kml:Camera" objects). This data is provided in string format and 720 corresponds to the [W3CGEO] values. The timestamp value is also 721 specified as a string as in our YANG grouping. 723 KML has some special handling for the height value useful for 724 visualization software, "kml:altitudeMode". These values for 725 "kml:altitudeMode" include indicating the height is ignored 726 ("clampToGround"), in relation to the location's ground level 727 ("relativeToGround"), or in relation to the geodetic datum 728 ("absolute"). The YANG grouping can directly map the ignored and 729 absolute cases, but not the relative to ground case. 731 In addition to the "kml:altitudeMode" KML also defines two seafloor 732 height values using "kml:seaFloorAltitudeMode". One value is to 733 ignore the height value ("clampToSeaFloor") and the other is relative 734 ("relativeToSeaFloor"). As with the "kml:altitudeMode" value, the 735 YANG grouping supports the ignore case but not the relative case. 737 The KML location values use a geodetic datum defined in Annex A by 738 the GML Coordinate Reference System (CRS) [ISO.19136.2007] with 739 identifier "LonLat84_5773". The altitude value for KML absolute 740 height mode is measured from the vertical datum specified by [WGS84]. 742 Thus, the YANG grouping and KML values can be directly mapped in both 743 directions (when using a supported altitude mode) with the caveat 744 that some loss of precision (in the extremes) may occur due to the 745 YANG grouping using decimal64 values rather than strings. For the 746 relative height cases, the application doing the transformation is 747 expected to have the data available to transform the relative height 748 into an absolute height, which can then be expressed using the YANG 749 grouping. 751 6. IANA Considerations 753 6.1. Geodetic System Values Registry 755 IANA is asked to create a new registry "Geodetic System Values" under 756 a new protocol category group "YANG Geographic Location Parameters". 758 This registry allocates names for standard geodetic systems. Often 759 these values are referred to using multiple names (e.g., full names 760 or multiple acronyms). The intent of this registry is to provide a 761 single standard value for any given geodetic system. 763 The values SHOULD use an acronym when available, they MUST be 764 converted to lower case, and spaces MUST be changed to dashes "-". 766 Each entry should be sufficient to define the 2 coordinate values, 767 and to define height if height is required. So, for example, the 768 "wgs-84" is defined as WGS-84 with the geoid updated by at least 769 [EGM96] for height values. Specific entries for [EGM96] and [EGM08] 770 are present if a more precise definition of the data is required. 772 It should be noted that [RFC5870] also creates a registry for 773 Geodetic Systems (it calls CRS); however, this registry has a very 774 strict modification policy. The authors of [RFC5870] have the stated 775 goal of making CRS registration hard to avoid proliferation of CRS 776 values. As our module defines alternate systems and has a broader 777 (beyond Earth) scope, the registry defined below is meant to be more 778 easily modified. 780 The allocation policy for this registry is First Come, First Served, 781 [RFC8126] as the intent is simply to avoid duplicate values. 783 The Reference value can either be a document or a contact person as 784 defined in [RFC8126]. The Change Control (i.e., Owner) is also 785 defined by [RFC8126]. 787 The initial values for this registry are as follows. They include 788 the non-Earth based geodetic-datum value for the moon based on [ME]. 790 +-----------+------------------------------+-----------+---------+ 791 | Name | Description | Reference | Change | 792 +-----------+------------------------------+-----------+---------+ 793 | | | /Contact | Control | 794 +===========+==============================+===========+=========+ 795 | me | Mean Earth/Polar Axis (Moon) | this | IESG | 796 +-----------+------------------------------+-----------+---------+ 797 | wgs-84-96 | World Geodetic System 1984 | this | IESG | 798 +-----------+------------------------------+-----------+---------+ 799 | wgs-84-08 | World Geodetic System 1984 | this | IESG | 800 +-----------+------------------------------+-----------+---------+ 801 | wgs-84 | World Geodetic System 1984 | this | IESG | 802 +-----------+------------------------------+-----------+---------+ 804 Table 3 806 6.2. Updates to the IETF XML Registry 808 This document registers a URI in the "IETF XML Registry" [RFC3688]. 809 Following the format in [RFC3688], the following registration has 810 been made: 812 URI urn:ietf:params:xml:ns:yang:ietf-geo-location 814 Registrant Contact The IESG. 816 XML N/A; the requested URI is an XML namespace. 818 6.3. Updates to the YANG Module Names Registry 820 This document registers one YANG module in the "YANG Module Names" 821 registry [RFC6020]. Following the format in [RFC6020], the following 822 registration has been made: 824 name ietf-geo-location 826 namespace urn:ietf:params:xml:ns:yang:ietf-geo-location 828 prefix geo 830 reference RFC XXXX (RFC Ed.: replace XXXX with RFC number and remove 831 this note.) 833 7. Security Considerations 835 The YANG module specified in this document defines a schema for data 836 that is designed to be accessed via network management protocols such 837 as NETCONF [RFC6241] or RESTCONF [RFC8040]. The lowest NETCONF layer 838 is the secure transport layer, and the mandatory-to-implement secure 839 transport is Secure Shell (SSH) [RFC6242]. The lowest RESTCONF layer 840 is HTTPS, and the mandatory-to-implement secure transport is TLS 841 [RFC8446]. 843 The NETCONF access control model [RFC8341] provides the means to 844 restrict access for particular NETCONF or RESTCONF users to a 845 preconfigured subset of all available NETCONF or RESTCONF protocol 846 operations and content. 848 Since the modules defined in this document only define groupings, 849 these considerations are primarily for the designers of other modules 850 that use these groupings. 852 All the data nodes defined in this YANG module are 853 writable/creatable/deletable (i.e., "config true", which is the 854 default). 856 None of the writable/creatable/deletable data nodes in the YANG 857 module defined in this document are by themselves considered more 858 sensitive or vulnerable than standard configuration. 860 Some of the readable data nodes in this YANG module may be considered 861 sensitive or vulnerable in some network environments. It is thus 862 important to control read access (e.g., via get, get-config, or 863 notification) to these data nodes. 865 Since the grouping defined in this module identifies locations, 866 authors using this grouping SHOULD consider any privacy issues that 867 may arise when the data is readable (e.g., customer device locations, 868 etc). 870 8. Normative References 872 [EGM08] Pavlis, N.K., Holmes, S.A., Kenyon, S.C., and J.K. Factor, 873 "An Earth Gravitational Model to Degree 2160: EGM08.", 874 Presented at the 2008 General Assembly of the European 875 Geosciences Union, Vienna, Arpil13-18, 2008, 2008. 877 [EGM96] Lemoine, F.G., Kenyon, S.C., Factor, J.K., Trimmer, R.G., 878 Pavlis, N.K., Chinn, D.S., Cox, C.M., Klosko, S.M., 879 Luthcke, S.B., Torrence, M.H., Wang, Y.M., Williamson, 880 R.G., Pavlis, E.C., Rapp, R.H., and T.R. Olson, "The 881 Development of the Joint NASA GSFC and the National 882 Imagery and Mapping Agency (NIMA) Geopotential Model 883 EGM96.", Technical Report NASA/TP-1998-206861, NASA, 884 Greenbelt., 1998. 886 [ISO.6709.2008] 887 International Organization for Standardization, "ISO 888 6709:2008 Standard representation of geographic point 889 location by coordinates.", 2008. 891 [ME] National Aeronautics and Space Administration, Goddard 892 Space Flight Center., "A Standardized Lunar Coordinate 893 System for the Lunar Reconnaissance Orbiter, Version 4.", 894 14 May 2008. 896 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 897 Requirement Levels", BCP 14, RFC 2119, 898 DOI 10.17487/RFC2119, March 1997, 899 . 901 [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types", 902 RFC 6991, DOI 10.17487/RFC6991, July 2013, 903 . 905 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 906 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 907 May 2017, . 909 [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for 910 Writing an IANA Considerations Section in RFCs", BCP 26, 911 RFC 8126, DOI 10.17487/RFC8126, June 2017, 912 . 914 [RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 915 and R. Wilton, "Network Management Datastore Architecture 916 (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018, 917 . 919 [WGS84] National Imagery and Mapping Agency., "National Imagery 920 and Mapping Agency Technical Report 8350.2, Third 921 Edition.", 3 January 2000. 923 9. Informative References 925 [ISO.19136.2007] 926 International Organization for Standardization, "ISO 927 19136:2007 Geographic information -- Geography Markup 928 Language (GML)". 930 [KML22] Wilson, T., Ed., "OGC KML (Version 2.2)", 14 April 2008, 931 . 934 [KML23] Burggraf, D., Ed., "OGC KML 2.3", 4 August 2015, 935 . 938 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 939 DOI 10.17487/RFC3688, January 2004, 940 . 942 [RFC5870] Mayrhofer, A. and C. Spanring, "A Uniform Resource 943 Identifier for Geographic Locations ('geo' URI)", 944 RFC 5870, DOI 10.17487/RFC5870, June 2010, 945 . 947 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 948 the Network Configuration Protocol (NETCONF)", RFC 6020, 949 DOI 10.17487/RFC6020, October 2010, 950 . 952 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 953 and A. Bierman, Ed., "Network Configuration Protocol 954 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 955 . 957 [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure 958 Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011, 959 . 961 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 962 RFC 7950, DOI 10.17487/RFC7950, August 2016, 963 . 965 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 966 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 967 . 969 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 970 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 971 . 973 [RFC8341] Bierman, A. and M. Bjorklund, "Network Configuration 974 Access Control Model", STD 91, RFC 8341, 975 DOI 10.17487/RFC8341, March 2018, 976 . 978 [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol 979 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, 980 . 982 [W3CGEO] Popescu, A., "Geolocation API Specification", 8 November 983 2016, . 986 Appendix A. Examples 988 Below is a fictitious module that uses the geo-location grouping. 990 module example-uses-geo-location { 991 namespace 992 "urn:example:example-uses-geo-location"; 993 prefix ugeo; 994 import ietf-geo-location { prefix geo; } 995 organization "Empty Org"; 996 contact "Example Author "; 997 description "Example use of geo-location"; 998 revision 2019-02-02 { reference "None"; } 999 container locatable-items { 1000 description "container of locatable items"; 1001 list locatable-item { 1002 key name; 1003 description "A locatable item"; 1004 leaf name { 1005 type string; 1006 description "name of locatable item"; 1007 } 1008 uses geo:geo-location; 1009 } 1010 } 1011 } 1013 Figure 2: Example YANG module using geo location. 1015 Below is the YANG tree for the fictitious module that uses the geo- 1016 location grouping. 1018 module: example-uses-geo-location 1019 +--rw locatable-items 1020 +--rw locatable-item* [name] 1021 +--rw name string 1022 +--rw geo-location 1023 +--rw reference-frame 1024 | +--rw alternate-system? string 1025 | | {alternate-systems}? 1026 | +--rw astronomical-body? string 1027 | +--rw geodetic-system 1028 | +--rw geodetic-datum? string 1029 | +--rw coord-accuracy? decimal64 1030 | +--rw height-accuracy? decimal64 1031 +--rw (location)? 1032 | +--:(ellipsoid) 1033 | | +--rw latitude? decimal64 1034 | | +--rw longitude? decimal64 1035 | | +--rw height? decimal64 1036 | +--:(cartesian) 1037 | +--rw x? decimal64 1038 | +--rw y? decimal64 1039 | +--rw z? decimal64 1040 +--rw velocity 1041 | +--rw v-north? decimal64 1042 | +--rw v-east? decimal64 1043 | +--rw v-up? decimal64 1044 +--rw timestamp? yang:date-and-time 1045 +--rw valid-until? yang:date-and-time 1047 Below is some example YANG XML data for the fictitious module that 1048 uses the geo-location grouping. 1050 1051 1052 Gaetana's 1053 1054 40.73297 1055 -74.007696 1056 1057 1058 1059 Pont des Arts 1060 1061 2012-03-31T16:00:00Z 1062 48.8583424 1063 2.3375084 1064 35 1065 1067 1068 1069 Saint Louis Cathedral 1070 1071 2013-10-12T15:00:00-06:00 1072 29.9579735 1073 -90.0637281 1074 1075 1076 1077 Apollo 11 Landing Site 1078 1079 1969-07-21T02:56:15Z 1080 1081 moon 1082 1083 me 1084 1085 1086 0.67409 1087 23.47298 1088 1089 1090 1091 Reference Frame Only 1092 1093 1094 moon 1095 1096 me 1097 1098 1099 1100 1101 1103 Figure 3: Example XML data of geo location use. 1105 Appendix B. Acknowledgments 1107 We would like to thank Jim Biard and Ben Koziol for their reviews and 1108 suggested improvements. We would also like to thank Peter Lothberg 1109 for the motivation as well as help in defining a broadly useful 1110 geographic location object, and Acee Lindem and Qin Wu for their work 1111 on a geographic location object that led to this documents' creation. 1112 We would also like to thank the document shepherd Kent Watsen. 1114 Author's Address 1116 Christian Hopps 1117 LabN Consulting, L.L.C. 1119 Email: chopps@chopps.org