idnits 2.17.1 draft-ietf-netmod-geo-location-00.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 228 has weird spacing: '...ngitude deg...' == Line 915 has weird spacing: '...ngitude deg...' -- The document date (April 20, 2019) is 1826 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: 0 errors (**), 0 flaws (~~), 3 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 April 20, 2019 5 Expires: October 22, 2019 7 YANG Geo Location 8 draft-ietf-netmod-geo-location-00 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 the 15 Earth 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 October 22, 2019. 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 (https://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 Table of Contents 51 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 52 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 53 2. The Geo Location Object . . . . . . . . . . . . . . . . . . . 3 54 2.1. Frame of Reference . . . . . . . . . . . . . . . . . . . 3 55 2.2. Location . . . . . . . . . . . . . . . . . . . . . . . . 4 56 2.3. Motion . . . . . . . . . . . . . . . . . . . . . . . . . 4 57 2.4. Nested Locations . . . . . . . . . . . . . . . . . . . . 5 58 2.5. Non-location Attributes . . . . . . . . . . . . . . . . . 5 59 2.6. Tree . . . . . . . . . . . . . . . . . . . . . . . . . . 5 60 3. YANG Module . . . . . . . . . . . . . . . . . . . . . . . . . 6 61 4. ISO 6709:2008 Conformance . . . . . . . . . . . . . . . . . . 11 62 5. Usability . . . . . . . . . . . . . . . . . . . . . . . . . . 12 63 5.1. Portability . . . . . . . . . . . . . . . . . . . . . . . 13 64 5.1.1. IETF URI Value . . . . . . . . . . . . . . . . . . . 13 65 5.1.2. W3C . . . . . . . . . . . . . . . . . . . . . . . . . 13 66 5.1.3. Geography Markup Language (GML) . . . . . . . . . . . 15 67 5.1.4. KML . . . . . . . . . . . . . . . . . . . . . . . . . 15 68 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 16 69 6.1. Geodetic System Value Registry . . . . . . . . . . . . . 16 70 7. Security Considerations . . . . . . . . . . . . . . . . . . . 17 71 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 18 72 8.1. Normative References . . . . . . . . . . . . . . . . . . 18 73 8.2. Informative References . . . . . . . . . . . . . . . . . 19 74 Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 19 75 Appendix B. Acknowledgements . . . . . . . . . . . . . . . . . . 23 76 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 23 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 The Earth, 87 it 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 of 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 The 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 (), 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 an optional "z". For the 152 standard location choice "latitude" and "longitude" are specified as 153 fractions of decimal degrees, and the "height" value is in fractions 154 of meters. For the Cartesian choice "x", "y" and "z" are in 155 fractions of meters. In both choices the exact meanings of all of 156 the values are defined by the "geodetic-datum" value in the 157 Section 2.1. 159 2.3. Motion 161 Support is added for objects in relatively stable motion. For 162 objects in relatively stable motion the grouping provides a 163 3-dimensional vector value. The components of the vector are 164 "v-north", "v-east" and "v-up" which are all given in fractional 165 meters per second. The values "v-north" and "v-east" are relative to 166 true-north as defined by the reference frame for the astronomical 167 body, "v-up" is perpendicular to the plane defined by "v-north" and 168 "v-east", and is pointed away from the center of mass. 170 To derive the 2-dimensional heading and speed one would use the 171 following formulas: 173 ,------------------------------ 174 speed = V v_{north}^{2} + v_{east}^{2} 176 heading = arctan(v_{east} / v_{north}) 178 For some applications that demand high accuracy, and where the data 179 is infrequently updated this velocity vector can track very slow 180 movement such as continental drift. 182 Tracking more complex forms of motion is outside the scope of this 183 work. The intent of the grouping being defined here is to identify 184 where something is located, and generally this is expected to be 185 somewhere on or relative to the 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 frequent 190 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: geo-location 217 +-- geo-location 218 +-- reference-frame 219 | +-- alternate-system? string {alternate-systems}? 220 | +-- astronomical-body? string 221 | +-- geodetic-system 222 | +-- geodetic-datum? string 223 | +-- coord-accuracy? decimal64 224 | +-- height-accuracy? decimal64 225 +-- (location) 226 | +--:(ellipsoid) 227 | | +-- latitude degrees 228 | | +-- longitude degrees 229 | | +-- height? decimal64 230 | +--:(cartesian) 231 | +-- x decimal64 232 | +-- y decimal64 233 | +-- z? decimal64 234 +-- velocity 235 | +-- v-north? decimal64 236 | +-- v-east? decimal64 237 | +-- v-up? decimal64 238 +-- timestamp? types:date-and-time 240 Figure 1: Geo Location YANG tree diagram. 242 3. YANG Module 244 file "ietf-geo-location@2019-02-17.yang" 245 module ietf-geo-location { 246 namespace "urn:ietf:params:xml:ns:yang:ietf-geo-location"; 247 prefix geo; 248 import ietf-yang-types { prefix types; } 250 organization 251 "IETF NETMOD Working Group (NETMOD)"; 252 contact 253 "Christian Hopps "; 255 // RFC Ed.: replace XXXX with actual RFC number and 256 // remove this note. 258 description 259 "This module defines a grouping of a container object for 260 specifying a location on or around an astronomical object (e.g., 261 The Earth). 263 Copyright (c) 2018 IETF Trust and the persons identified as 264 authors of the code. All rights reserved. 266 Redistribution and use in source and binary forms, with or 267 without modification, is permitted pursuant to, and subject to 268 the license terms contained in, the Simplified BSD License set 269 forth in Section 4.c of the IETF Trust's Legal Provisions 270 Relating to IETF Documents 271 (https://trustee.ietf.org/license-info). 273 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL 274 NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'NOT RECOMMENDED', 275 'MAY', and 'OPTIONAL' in this document are to be interpreted as 276 described in BCP 14 [RFC2119] [RFC8174] when, and only when, 277 they appear in all capitals, as shown here. 279 This version of this YANG module is part of RFC XXXX 280 (https://tools.ietf.org/html/rfcXXXX); see the RFC itself for 281 full legal notices."; 283 // RFC Ed.: replace XXXX with actual RFC number and 284 // remove this note. 286 revision 2019-02-17 { 287 description "Initial Revision"; 288 reference "RFC XXXX: YANG Geo Location"; 289 } 291 typedef degrees { 292 type decimal64 { 293 fraction-digits 16; 294 } 295 units "decimal degrees"; 296 description "Coordinate value."; 297 } 299 feature alternate-systems { 300 description 301 "This feature means the device supports specifying locations 302 using alternate systems for reference frames."; 303 } 305 grouping geo-location { 306 description 307 "Grouping to identify a location on an astronomical object."; 309 container geo-location { 310 description 311 "A location on an astronomical body (e.g., The Earth) 312 somewhere in a universe."; 314 container reference-frame { 315 description 316 "The Frame of Reference for the location values."; 318 leaf alternate-system { 319 if-feature alternate-systems; 320 type string; 321 description 322 "The system in which the astronomical body and 323 geodetic-datum is defined. Normally, this value is not 324 present and the system is the natural universe; however, 325 when present this value allows for specifying alternate 326 systems (e.g., virtual realities). An alternate-system 327 modifies the definition (but not the type) of the other 328 values in the reference frame."; 329 } 330 leaf astronomical-body { 331 type string { 332 pattern 333 '[-0-9a-z #x22#x23#x5B#x5D' + 334 '!$%&()*+,\./:;<=>?@\\^_`{|}~]+'; 335 } 336 default "earth"; 337 description 338 "An astronomical body as named by the International 339 Astronomical Union (IAU) or according to the alternate 340 system if specified. Examples include 'sun' (our star), 341 'earth' (our planet), 'moon' (our moon), 'enceladus' (a 342 moon of Saturn), 'ceres' (an asteroid), 343 '67p/churyumov-gerasimenko (a comet). The value should 344 be comprised of all lower case ASCII characters not 345 including control characters (i.e., values 32..64, and 346 91..126)"; 347 } 348 container geodetic-system { 349 description 350 "The geodetic system of the location data."; 351 leaf geodetic-datum { 352 type string { 353 pattern 354 '[-0-9a-z#x22#x23#x5B#x5D' + 355 '!$%&()*+,\./:;<=>?@\\^_`{|}~]+'; 356 } 357 default "wgs-84"; 358 description 359 "A geodetic-datum defining the meaning of latitude, 360 longitude and height. The default is 'wgs-84' which is 361 used by the Global Positioning System (GPS)"; 362 } 363 leaf coord-accuracy { 364 type decimal64 { 365 fraction-digits 6; 366 } 367 description 368 "The accuracy of the latitude longitude pair. When 369 coord-accuracy is specified it overrides the 370 geodetic-datum implied accuracy. If Cartesian 371 coordinates are in use this accuracy corresponds to 372 the X and Y components"; 373 } 374 leaf height-accuracy { 375 type decimal64 { 376 fraction-digits 6; 377 } 378 units "meters"; 379 description 380 "The accuracy of height value. When specified it 381 overrides the geodetic-datum implied default. If 382 Cartesian coordinates ar in use this accuracy 383 corresponds to the Z component."; 384 } 385 // May wish to allow for height to be relative. 386 // If so need to decide if we have a boolean (to ground) 387 // or an enumeration (e.g., local ground, sea-floor, 388 // ground floor, containing object, ...) or even allow 389 // for a string for most generic but least portable 390 // comparable 391 // leaf height-relative { 392 // } 393 } 394 } 395 choice location { 396 mandatory true; 397 description 398 "The location data either in lat/long or Cartesian values"; 399 case ellipsoid { 400 leaf latitude { 401 type degrees; 402 mandatory true; 403 description 404 "The latitude value on the astronomical body. The 405 definition and precision of this measurement is 406 indicated by the reference-frame value."; 407 } 408 leaf longitude { 409 type degrees; 410 mandatory true; 411 description 412 "The longitude value on the astronomical body. The 413 definition and precision of this measurement is 414 indicated by the reference-frame."; 415 } 416 leaf height { 417 type decimal64 { 418 fraction-digits 6; 419 } 420 units "meters"; 421 description 422 "Height from a reference 0 value. The precision and '0' 423 value is defined by the reference-frame."; 424 } 425 } 426 case cartesian { 427 leaf x { 428 type decimal64 { 429 fraction-digits 6; 430 } 431 mandatory true; 432 description 433 "The X value as defined by the reference-frame."; 434 } 435 leaf y { 436 type decimal64 { 437 fraction-digits 6; 438 } 439 mandatory true; 440 description 441 "The Y value as defined by the reference-frame."; 442 } 443 leaf z { 444 type decimal64 { 445 fraction-digits 6; 446 } 447 units "meters"; 448 description 449 "The Z value as defined by the reference-frame."; 450 } 451 } 452 } 453 container velocity { 454 description 455 "If the object is in motion the velocity vector describes 456 this motion at the the time given by the timestamp."; 458 leaf v-north { 459 type decimal64 { 460 fraction-digits 12; 461 } 462 units "meters per second"; 463 description 464 "v-north is the rate of change (i.e., speed) towards 465 truth north as defined by the ~geodetic-system~."; 466 } 468 leaf v-east { 469 type decimal64 { 470 fraction-digits 12; 471 } 472 units "meters per second"; 473 description 474 "v-east is the rate of change (i.e., speed) perpendicular 475 to truth-north as defined by the ~geodetic-system~."; 476 } 478 leaf v-up { 479 type decimal64 { 480 fraction-digits 12; 481 } 482 units "meters per second"; 483 description 484 "v-up is the rate of change (i.e., speed) away from the 485 center of mass."; 486 } 487 } 488 leaf timestamp { 489 type types:date-and-time; 490 description "Reference time when location was recorded."; 491 } 492 } 493 } 494 } 495 497 4. ISO 6709:2008 Conformance 499 [ISO.6709.2008] provides an appendix with a set of tests for 500 conformance to the standard. The tests and results are given in the 501 following table along with an explanation of non-applicable tests. 503 +---------+-----------------------------------+---------------------+ 504 | Test | Description | Pass Explanation | 505 +---------+-----------------------------------+---------------------+ 506 | A.1.2.1 | elements reqd. for a geo. point | CRS is always | 507 | | location | indicated | 508 | | | | 509 | A.1.2.2 | Description of a CRS from a | CRS register is | 510 | | register | defined | 511 | | | | 512 | A.1.2.3 | definition of CRS | N/A - Don't define | 513 | | | CRS | 514 | | | | 515 | A.1.2.4 | representation of horizontal | lat/long values | 516 | | position | conform | 517 | | | | 518 | A.1.2.5 | representation of vertical | height value | 519 | | position | conforms | 520 | | | | 521 | A.1.2.6 | text string representation | N/A - No string | 522 | | | format | 523 +---------+-----------------------------------+---------------------+ 525 Conformance Test Results 527 For test "A.1.2.1" the YANG geo location object either includes a CRS 528 ("reference-frame") or has a default defined ([WGS84]). 530 For "A.1.2.3" we do not define our own CRS, and doing so is not 531 required for conformance. 533 For "A.1.2.6" we do not define a text string representation, which is 534 also not required for conformance. 536 5. Usability 538 The geo-location object defined in this document and YANG module have 539 been designed to be usable in a very broad set of applications. This 540 includes the ability to locate things on astronomical bodies other 541 than The Earth, and to utilize entirely different coordinate systems 542 and realities. 544 Many systems make use of geo-location data, and so it's important to 545 be able describe this data using this geo-location object defined in 546 this document. 548 5.1. Portability 550 In order to verify portability while developing this module the 551 following standards and standard APIs and were considered. 553 5.1.1. IETF URI Value 555 [RFC5870] defines a standard URI value for geographic location data. 556 It includes the ability to specify the "geodetic-value" (it calls 557 this "crs") with the default being "wgs-84" [WGS84]. For the 558 location data it allows 2 to 3 coordinates defined by the "crs" 559 value. For accuracy it has a single "u" parameter for specifying 560 uncertainty. The "u" value is in fractions of meters and applies to 561 all the location values. As the URI is a string, all values are 562 specifies as strings and so are capable of as much precision as 563 required. 565 URI values can be mapped to and from the YANG grouping, with the 566 caveat that some loss of precision (in the extremes) may occur due to 567 the YANG grouping using decimal64 values rather than strings. 569 5.1.2. W3C 571 See . 573 W3C Defines a geo-location API in [W3CGEO]. We show a snippet of 574 code below which defines the geo-location data for this API. This is 575 used by many application (e.g., Google Maps API). 577 interface GeolocationPosition { 578 readonly attribute GeolocationCoordinates coords; 579 readonly attribute DOMTimeStamp timestamp; 580 }; 582 interface GeolocationCoordinates { 583 readonly attribute double latitude; 584 readonly attribute double longitude; 585 readonly attribute double? altitude; 586 readonly attribute double accuracy; 587 readonly attribute double? altitudeAccuracy; 589 readonly attribute double? speed; 590 }; 592 Figure 2: Snippet Showing Geo-Location Definition 594 5.1.2.1. Compare with YANG Model 596 +------------------+--------------+-----------------+-------------+ 597 | Field | Type | YANG | Type | 598 +------------------+--------------+-----------------+-------------+ 599 | accuracy | double | coord-accuracy | dec64 fr 6 | 600 | | | | | 601 | altitude | double | height | dec64 fr 6 | 602 | | | | | 603 | altitudeAccuracy | double | height-accuracy | dec64 fr 6 | 604 | | | | | 605 | heading | double | heading | dec64 fr 16 | 606 | | | | | 607 | latitude | double | latitude | dec64 fr 16 | 608 | | | | | 609 | longitude | double | longitude | dec64 fr 16 | 610 | | | | | 611 | speed | double | speed | dec64 fr 12 | 612 | | | | | 613 | timestamp | DOMTimeStamp | timestamp | string | 614 +------------------+--------------+-----------------+-------------+ 616 accuracy (double): 617 Accuracy of "latitude" and "longitude" values in meters. 619 altitude (double): 620 Optional height in meters above the [WGS84] ellipsoid. 622 altitudeAccuracy (double): 623 Optional accuracy of "altitude" value in meters. 625 heading (double): 626 Optional Direction in decimal deg from true north increasing 627 clock-wise. 629 latitude, longitude (double): 630 Standard lat/long values in decimal degrees. 632 speed (double): 633 Speed along heading in meters per second. 635 timestamp (DOMTimeStamp): 636 Specifies milliseconds since the Unix EPOCH in 64 bit unsigned 637 integer. The YANG model defines the timestamp with arbitrarily 638 large precision by using a string which encompasses all 639 representable values of this timestamp value. 641 W3C API values can be mapped to the YANG grouping, with the caveat 642 that some loss of precision (in the extremes) may occur due to the 643 YANG grouping using decimal64 values rather than doubles. 645 Conversely, only YANG values for The Earth using the default "wgs-84" 646 [WGS84] as the "geodetic-datum", can be directly mapped to the W3C 647 values, as W3C does not provide the extra features necessary to map 648 the broader set of values supported by the YANG grouping. 650 5.1.3. Geography Markup Language (GML) 652 ISO adopted the Geography Markup Language (GML) defined by OGC 07-036 653 as [ISO.19136.2007]. GML defines, among many other things, a 654 position type "gml:pos" which is a sequence of "double" values. This 655 sequence of values represent coordinates in a given CRS. The CRS is 656 either inherited from containing elements or directly specified as 657 attributes "srsName" and optionally "srsDimension" on the "gml:pos". 659 GML defines an Abstract CRS type which Concrete CRS types derive 660 from. This allows for many types of CRS definitions. We are 661 concerned with the Geodetic CRS type which can have either 662 ellipsoidal or Cartesian coordinates. We believe that other non- 663 Earth based CRS as well as virtual CRS should also be representable 664 by the GML CRS types as well. 666 Thus GML "gml:pos" values can be mapped directly to the YANG 667 grouping, with the caveat that some loss of precision (in the 668 extremes) may occur due to the YANG grouping using decimal64 values 669 rather than doubles. 671 Conversely, YANG grouping values can be mapped to GML as directly as 672 the GML CRS available definitions allow with a minimum of Earth-based 673 geodetic systems fully supported. 675 GML also defines an observation value in "gml:Observation" which 676 includes a timestamp value "gml:validTime" in addition to other 677 components such as "gml:using" "gml:target" and "gml:resultOf". Only 678 the timestamp is mappable to and from the YANG grouping. Furthermore 679 "gml:validTime" can either be an Instantaneous measure 680 ("gml:TimeInstant") or a time period ("gml:TimePeriod"). Only the 681 instantaneous "gml:TimeInstant" is mappable to and from the YANG 682 grouping. 684 5.1.4. KML 686 KML 2.2 [KML22] (formerly Keyhole Markup Language) was submitted by 687 Google to Open Geospatial Consortium (OGC) 688 and was adopted. The latest 689 version as of this writing is KML 2.3 [KML23]. This schema includes 690 geographic location data in some of it's objects (e.g., objects). This data is provided in string format and 692 corresponds to the [W3CGEO] values. The timestamp value is also 693 specified as a string as in our YANG grouping. 695 KML has some special handling for the height value useful for 696 visualization software, "kml:altitudeMode". These values for 697 "kml:altitudeMode" include indicating the height is ignored 698 ("clampToGround"), in relation to the locations ground level 699 ("relativeToGround"), or in relation to the geodetic datum 700 ("absolute"). The YANG grouping can directly map the ignored and 701 absolute cases, but not the relative to ground case. 703 In addition to the "kml:altitudeMode" KML also defines two seafloor 704 height values using "kml:seaFloorAltitudeMode". One value is to 705 ignore the height value ("clampToSeaFloor") and the other is relative 706 ("relativeToSeaFloor"). As with the "kml:altitudeMode" value, the 707 YANG grouping supports the ignore case but not the relative case. 709 The KML location values use a geodetic datum defined in Annex A by 710 the GML Coordinate Reference System (CRS) [ISO.19136.2007] with 711 identifier "LonLat84_5773". The altitude value for KML absolute 712 height mode is measured from the vertical datum specified by [WGS84]. 714 Thus the YANG grouping and KML values can be directly mapped in both 715 directions (when using a supported altitude mode) with the caveat 716 that some loss of precision (in the extremes) may occur due to the 717 YANG grouping using decimal64 values rather than strings. For the 718 relative height cases the application doing the transformation is 719 expected to have the data available to transform the relative height 720 into an absolute height which can then be expressed using the YANG 721 grouping. 723 6. IANA Considerations 725 6.1. Geodetic System Value Registry 727 This registry allocates names for standard geodetic systems. Often 728 these values are referred to using multiple names (e.g., full names 729 or multiple acronyms values). The intent of this registry is to 730 provide a single standard value for any given geodetic system. 732 The values SHOULD use an acronym when available, they MUST be 733 converted to lower case, and spaces MUST be changed to dashes "-". 735 Each entry should be sufficient to define the 3 coordinate values (2 736 if height is not required). So for example the "wgs-84" is defined 737 as WGS-84 with the geoid updated by at least [EGM96] for height 738 values. Specific entries for [EGM96] and [EGM08] are present if a 739 more precise definition of the data is required. 741 It should be noted that [RFC5870] also creates a registry for 742 Geodetic Systems (it calls CRS); however, this registry has a very 743 strict modification policy. The authors of [RFC5870] have the stated 744 goal of making CRS registration hard to avoid proliferation of CRS 745 values. As our module defines alternate systems and has a broader 746 (beyond earth) scope, the registry defined below is meant to be more 747 easily modified. 749 TODO: Open question, should we create a new registry here or attempt 750 to modify the one created by [RFC5870]. It's worth noting that we 751 include the ability to specify any geodetic system including ones 752 designed for astronomical bodies other than the earth, as well as 753 ones based on alternate systems. These requirements may be too broad 754 for adapting the existing [RFC5870] registry. 756 TODO: Open question, is FCFS too easy, perhaps expert review would 757 strike a good balance. If expert review is acceptable, would it also 758 be acceptable to update the policy on [RFC5870] and use it instead? 760 The allocation policy for this registry is First Come First Served, 761 [RFC8126] as the intent is simply to avoid duplicate values. 763 The initial values for this registry are as follows. 765 +------------+------------------------------------------------------+ 766 | Name | Description | 767 +------------+------------------------------------------------------+ 768 | me | Mean Earth/Polar Axis (Moon) | 769 | | | 770 | mola-vik-1 | MOLA Height, IAU Viking-1 PM (Mars) | 771 | | | 772 | wgs-84-96 | World Geodetic System 1984 [WGS84] w/ EGM96 | 773 | | | 774 | wgs-84-08 | World Geodetic System 1984 [WGS84] w/ [EGM08] | 775 | | | 776 | wgs-84 | World Geodetic System 1984 [WGS84] (EGM96 or better) | 777 +------------+------------------------------------------------------+ 779 7. Security Considerations 781 This document defines a common geo location grouping using the YANG 782 data modeling language. The grouping itself has no security or 783 privacy impact on the Internet, but the usage of the grouping in 784 concrete YANG modules might have. The security considerations 785 spelled out in the YANG 1.1 specification [RFC7950] apply for this 786 document as well. 788 8. References 790 8.1. Normative References 792 [EGM08] Pavlis, N., Holmes, S., Kenyon, S., and J. Factor, "An 793 Earth Gravitational Model to Degree 2160: EGM08.", 2008, 794 . 797 [EGM96] Lemoine, F., Kenyon, S., Factor, J., Trimmer, R., Pavlis, 798 N., Chinn, D., Cox, C., Klosko, S., Luthcke, S., Torrence, 799 M., Wang, Y., Williamson, R., Pavlis, E., Rapp, R., and T. 800 Olson, "The Development of the Joint NASA GSFC and the 801 National Imagery and Mapping Agency (NIMA) Geopotential 802 Model EGM96.", 1998, 803 . 805 [ISO.6709.2008] 806 International Organization for Standardization, "ISO 807 6709:2008 Standard representation of geographic point 808 location by coordinates.", 2008. 810 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 811 Requirement Levels", BCP 14, RFC 2119, 812 DOI 10.17487/RFC2119, March 1997, 813 . 815 [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for 816 Writing an IANA Considerations Section in RFCs", BCP 26, 817 RFC 8126, DOI 10.17487/RFC8126, June 2017, 818 . 820 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 821 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 822 May 2017, . 824 [RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 825 and R. Wilton, "Network Management Datastore Architecture 826 (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018, 827 . 829 [WGS84] National Imagery and Mapping Agency., "National Imagery 830 and Mapping Agency Technical Report 8350.2, Third 831 Edition.", 1 2000, . 834 8.2. Informative References 836 [ISO.19136.2007] 837 International Organization for Standardization, "ISO 838 19136:2007 Geographic information -- Geography Markup 839 Language (GML)". 841 [KML22] Wilson, T., Ed., "OGC KML (Version 2.2)", 4 2008, 842 . 845 [KML23] Burggraf, D., Ed., "OGC KML 2.3", 8 2015, 846 . 849 [RFC5870] Mayrhofer, A. and C. Spanring, "A Uniform Resource 850 Identifier for Geographic Locations ('geo' URI)", 851 RFC 5870, DOI 10.17487/RFC5870, June 2010, 852 . 854 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 855 RFC 7950, DOI 10.17487/RFC7950, August 2016, 856 . 858 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 859 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 860 . 862 [W3CGEO] Popescu, A., "Geolocation API Specification", 11 2016, 863 . 866 Appendix A. Examples 868 Below is a fictitious module that uses the geo-location grouping. 870 file "ietf-uses-geo-location@2019-02-02.yang" 871 module ietf-uses-geo-location { 872 namespace 873 "urn:ietf:params:xml:ns:yang:ietf-uses-geo-location"; 874 prefix ugeo; 875 import geo-location { prefix geo; } 876 organization "Empty Org"; 877 contact "Example Author "; 878 description "Example use of geo-location"; 879 revision 2019-02-02 { reference "None"; } 880 container locatable-items { 881 description "container of locatable items"; 882 list locatable-item { 883 key name; 884 description "A of locatable item"; 885 leaf name { 886 type string; 887 description "name of locatable item"; 888 } 889 uses geo:geo-location; 890 } 891 } 892 } 893 895 Figure 3: Example YANG module using geo location. 897 Below is a the YANG tree for the fictitious module that uses the geo- 898 location grouping. 900 module: ietf-uses-geo-location 901 +--rw locatable-items 902 +--rw locatable-item* [name] 903 +--rw name string 904 +--rw geo-location 905 +--rw reference-frame 906 | +--rw alternate-system? string {alternate-systems}? 907 | +--rw astronomical-body? string 908 | +--rw geodetic-system 909 | +--rw geodetic-datum? string 910 | +--rw coord-accuracy? decimal64 911 | +--rw height-accuracy? decimal64 912 +--rw (location) 913 | +--:(ellipsoid) 914 | | +--rw latitude degrees 915 | | +--rw longitude degrees 916 | | +--rw height? decimal64 917 | +--:(cartesian) 918 | +--rw x decimal64 919 | +--rw y decimal64 920 | +--rw z? decimal64 921 +--rw velocity 922 | +--rw v-north? decimal64 923 | +--rw v-east? decimal64 924 | +--rw v-up? decimal64 925 +--rw timestamp? types:date-and-time 927 Below is some example YANG XML data for the fictitious module that 928 uses the geo-location grouping. 930 931 933 934 Gaetana's 935 936 40.73297 937 -74.007696 938 939 940 941 Pont des Arts 942 943 2012-03-31T16:00:00Z 944 48.8583424 945 2.3375084 946 35 947 948 949 950 Saint Louis Cathedral 951 952 2013-10-12T15:00:00-06:00 953 29.9579735 954 -90.0637281 955 956 957 958 Apollo 11 Landing Site 959 960 1969-07-21T02:56:15Z 961 962 moon 963 964 me 965 966 967 0.67409 968 23.47298 969 970 971 972 974 Figure 4: Example XML data of geo location use. 976 Appendix B. Acknowledgements 978 We would like to thank Peter Lothberg for the motivation as well as 979 help in defining a more broadly useful geographic location object. 981 We would also like to thank Acee Lindem and Qin Wu for their work on 982 a geographic location object that led to this documents creation. 984 Author's Address 986 Christian Hopps 987 LabN Consulting, L.L.C. 989 Email: chopps@chopps.org