idnits 2.17.1 draft-ietf-netmod-geo-location-03.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 -- The document date (13 February 2020) is 1524 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 (~~), 1 warning (==), 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 13 February 2020 5 Expires: 16 August 2020 7 YANG Geo Location 8 draft-ietf-netmod-geo-location-03 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 16 August 2020. 34 Copyright Notice 36 Copyright (c) 2020 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 . . . . . . . . . . . . . . . . . . 11 61 5. Usability . . . . . . . . . . . . . . . . . . . . . . . . . . 12 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 . . . . . . . . . . . . . . . . . . . . . 16 68 6.1. Geodetic System Value Registry . . . . . . . . . . . . . 16 69 7. Security Considerations . . . . . . . . . . . . . . . . . . . 17 70 8. Normative References . . . . . . . . . . . . . . . . . . . . 18 71 9. Informative References . . . . . . . . . . . . . . . . . . . 19 72 Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 19 73 Appendix B. Acknowledgements . . . . . . . . . . . . . . . . . . 22 74 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 22 76 1. Introduction 78 In many applications we would like to specify the location of 79 something geographically. Some examples of locations in networking 80 might be the location of data center, a rack in an internet exchange 81 point, a router, a firewall, a port on some device, or it could be 82 the endpoints of a fiber, or perhaps the failure point along a fiber. 84 Additionally, while this location is typically relative to The Earth, 85 it does not need to be. Indeed it is easy to imagine a network or 86 device located on The Moon, on Mars, on Enceladus (the moon of 87 Saturn) or even a comet (e.g., 67p/churyumov-gerasimenko). 89 Finally, one can imagine defining locations using different frames of 90 reference or even alternate systems (e.g., simulations or virtual 91 realities). 93 This document defines a "geo-location" YANG grouping that allows for 94 all of the above data to be captured. 96 This specification conforms to [ISO.6709.2008]. 98 The YANG data model described in this document conforms to the 99 Network Management Datastore Architecture defined in [RFC8342]. 101 1.1. Terminology 103 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 104 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 105 "OPTIONAL" in this document are to be interpreted as described in 106 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, 107 as shown here. 109 2. The Geo Location Object 111 2.1. Frame of Reference 113 The frame of reference ("reference-frame") defines what the location 114 values refer to and their meaning. The referred to object can be any 115 astronomical body. It could be a planet such as The Earth or Mars, a 116 moon such as Enceladus, an asteroid such as Ceres, or even a comet 117 such as 1P/Halley. This value is specified in "astronomical-body" 118 and is defined by the International Astronomical Union 119 (http://www.iau.org), The default "astronomical-body" value is 120 "earth". 122 In addition to identifying the astronomical body we also need to 123 define the meaning of the coordinates (e.g., latitude and longitude) 124 and the definition of 0-height. This is done with a "geodetic-datum" 125 value. The default value for "geodetic-datum" is "wgs-84" (i.e., the 126 World Geodetic System, [WGS84]), which is used by the Global 127 Positioning System (GPS) among many others. We define an IANA 128 registry for specifying standard values for the "geodetic-datum". 130 In addition to the "geodetic-datum" value we allow refining the 131 coordinate and height accuracy using "coord-accuracy" and "height- 132 accuracy" respectively. When specified these values override the 133 defaults implied by the "geodetic-datum" value. 135 Finally, we define an optional feature which allows for changing the 136 system for which the above values are defined. This optional feature 137 adds an "alternate-system" value to the reference frame. This value 138 is normally not present which implies the natural universe is the 139 system. The use of this value is intended to allow for creating 140 virtual realities or perhaps alternate coordinate systems. The 141 definition of alternate systems is outside the scope of this 142 document. 144 2.2. Location 146 This is the location on or relative to the astronomical object. It 147 is specified using 2 or 3 coordinates values. These values are given 148 either as "latitude", "longitude", and an optional "height", or as 149 Cartesian coordinates of "x", "y" and "z". For the standard location 150 choice "latitude" and "longitude" are specified as fractions of 151 decimal degrees, and the "height" value is in fractions of meters. 152 For the Cartesian choice "x", "y" and "z" are in fractions of meters. 153 In both choices the exact meanings of all of the values are defined 154 by the "geodetic-datum" value in the Section 2.1. 156 2.3. Motion 158 Support is added for objects in relatively stable motion. For 159 objects in relatively stable motion the grouping provides a 160 3-dimensional vector value. The components of the vector are 161 "v-north", "v-east" and "v-up" which are all given in fractional 162 meters per second. The values "v-north" and "v-east" are relative to 163 true-north as defined by the reference frame for the astronomical 164 body, "v-up" is perpendicular to the plane defined by "v-north" and 165 "v-east", and is pointed away from the center of mass. 167 To derive the 2-dimensional heading and speed one would use the 168 following formulas: 170 ,------------------------------ 171 speed = V v_{north}^{2} + v_{east}^{2} 173 heading = arctan(v_{east} / v_{north}) 175 For some applications that demand high accuracy, and where the data 176 is infrequently updated this velocity vector can track very slow 177 movement such as continental drift. 179 Tracking more complex forms of motion is outside the scope of this 180 work. The intent of the grouping being defined here is to identify 181 where something is located, and generally this is expected to be 182 somewhere on or relative to the Earth (or another astronomical body). 183 At least two options are available to YANG models that wish to use 184 this grouping with objects that are changing location frequently in 185 non-simple ways, they can add additional motion data to their model 186 directly, or if the application allows it can require more frequent 187 queries to keep the location data current. 189 2.4. Nested Locations 191 When locations are nested (e.g., a building may have a location which 192 houses routers that also have locations) the module using this 193 grouping is free to indicate in its definition that the "reference- 194 frame" is inherited from the containing object so that the 195 "reference-frame" need not be repeated in every instance of location 196 data. 198 2.5. Non-location Attributes 200 During the development of this module, the question of whether it 201 would support data such as orientation arose. These types of 202 attributes are outside the scope of this grouping because they do not 203 deal with a location but rather describe something more about the 204 object that is at the location. Module authors are free to add these 205 non-location attributes along with their use of this location 206 grouping. 208 2.6. Tree 210 The following is the YANG tree diagram [RFC8340] for the geo-location 211 grouping. 213 module: ietf-geo-location 214 grouping geo-location 215 +-- geo-location 216 +-- reference-frame 217 | +-- alternate-system? string {alternate-systems}? 218 | +-- astronomical-body? string 219 | +-- geodetic-system 220 | +-- geodetic-datum? string 221 | +-- coord-accuracy? decimal64 222 | +-- height-accuracy? decimal64 223 +-- (location)? 224 | +--:(ellipsoid) 225 | | +-- latitude? decimal64 226 | | +-- longitude? decimal64 227 | | +-- height? decimal64 228 | +--:(cartesian) 229 | +-- x? decimal64 230 | +-- y? decimal64 231 | +-- z? decimal64 232 +-- velocity 233 | +-- v-north? decimal64 234 | +-- v-east? decimal64 235 | +-- v-up? decimal64 236 +-- timestamp? types:date-and-time 237 +-- valid-until? types:date-and-time 239 3. YANG Module 241 file "ietf-geo-location@2019-02-17.yang" 242 module ietf-geo-location { 243 namespace "urn:ietf:params:xml:ns:yang:ietf-geo-location"; 244 prefix geo; 245 import ietf-yang-types { prefix types; } 247 organization 248 "IETF NETMOD Working Group (NETMOD)"; 249 contact 250 "Christian Hopps "; 252 // RFC Ed.: replace XXXX with actual RFC number and 253 // remove this note. 255 description 256 "This module defines a grouping of a container object for 257 specifying a location on or around an astronomical object (e.g., 258 The Earth). 260 Copyright (c) 2019 IETF Trust and the persons identified as 261 authors of the code. All rights reserved. 263 Redistribution and use in source and binary forms, with or 264 without modification, is permitted pursuant to, and subject to 265 the license terms contained in, the Simplified BSD License set 266 forth in Section 4.c of the IETF Trust's Legal Provisions 267 Relating to IETF Documents 268 (https://trustee.ietf.org/license-info). 270 This version of this YANG module is part of RFC XXXX 271 (https://www.rfc-editor.org/info/rfcXXXX); see the RFC itself 272 for full legal notices. 274 // RFC Ed.: replace XXXX with actual RFC number and 275 // remove this note. 277 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL 278 NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'NOT RECOMMENDED', 279 'MAY', and 'OPTIONAL' in this document are to be interpreted as 280 described in BCP 14 (RFC 2119) (RFC 8174) when, and only when, 281 they appear in all capitals, as shown here."; 283 revision 2019-02-17 { 284 description "Initial Revision"; 285 reference "RFC XXXX: YANG Geo Location"; 286 } 288 feature alternate-systems { 289 description 290 "This feature means the device supports specifying locations 291 using alternate systems for reference frames."; 292 } 294 grouping geo-location { 295 description 296 "Grouping to identify a location on an astronomical object."; 298 container geo-location { 299 description 300 "A location on an astronomical body (e.g., The Earth) 301 somewhere in a universe."; 303 container reference-frame { 304 description 305 "The Frame of Reference for the location values."; 307 leaf alternate-system { 308 if-feature alternate-systems; 309 type string; 310 description 311 "The system in which the astronomical body and 312 geodetic-datum is defined. Normally, this value is not 313 present and the system is the natural universe; however, 314 when present this value allows for specifying alternate 315 systems (e.g., virtual realities). An alternate-system 316 modifies the definition (but not the type) of the other 317 values in the reference frame."; 318 } 319 leaf astronomical-body { 320 type string { 321 pattern '[ -@\[-\^_-~]*'; 322 } 323 default "earth"; 324 description 325 "An astronomical body as named by the International 326 Astronomical Union (IAU) or according to the alternate 327 system if specified. Examples include 'sun' (our star), 328 'earth' (our planet), 'moon' (our moon), 'enceladus' (a 329 moon of Saturn), 'ceres' (an asteroid), 330 '67p/churyumov-gerasimenko (a comet). The value should 331 be comprised of all lower case ASCII characters not 332 including control characters (i.e., values 32..64, and 333 91..126). Any preceding 'the' in the name should not be 334 included."; 335 } 336 container geodetic-system { 337 description 338 "The geodetic system of the location data."; 339 leaf geodetic-datum { 340 type string { 341 pattern '[ -@\[-\^_-~]*'; 342 } 343 default "wgs-84"; 344 description 345 "A geodetic-datum defining the meaning of latitude, 346 longitude and height. The default is 'wgs-84' which is 347 used by the Global Positioning System (GPS). The value 348 SHOULD be comprised of all lower case ASCII characters 349 not including control characters (i.e., values 32..64, 350 and 91..126). The IANA registry further restricts the 351 value by converting all spaces (' ') to dashes ('-')"; 352 } 353 leaf coord-accuracy { 354 type decimal64 { 355 fraction-digits 6; 356 } 357 description 358 "The accuracy of the latitude longitude pair for 359 ellipsoidal coordinates, or the X, Y and Z components 360 for Cartesian coordinates. When coord-accuracy is 361 specified it overrides the geodetic-datum implied 362 accuracy."; 363 } 364 leaf height-accuracy { 365 type decimal64 { 366 fraction-digits 6; 367 } 368 units "meters"; 369 description 370 "The accuracy of height value for ellipsoidal 371 coordinates, this value is not used with Cartesian 372 coordinates. When specified it overrides the 373 geodetic-datum implied default."; 374 } 375 } 376 } 377 choice location { 378 description 379 "The location data either in lat/long or Cartesian values"; 380 case ellipsoid { 381 leaf latitude { 382 type decimal64 { 383 fraction-digits 16; 384 } 385 units "decimal degrees"; 386 description 387 "The latitude value on the astronomical body. The 388 definition and precision of this measurement is 389 indicated by the reference-frame value."; 390 } 391 leaf longitude { 392 type decimal64 { 393 fraction-digits 16; 394 } 395 units "decimal degrees"; 396 description 397 "The longitude value on the astronomical body. The 398 definition and precision of this measurement is 399 indicated by the reference-frame."; 400 } 401 leaf height { 402 type decimal64 { 403 fraction-digits 6; 404 } 405 units "meters"; 406 description 407 "Height from a reference 0 value. The precision and '0' 408 value is defined by the reference-frame."; 409 } 410 } 411 case cartesian { 412 leaf x { 413 type decimal64 { 414 fraction-digits 6; 415 } 416 units "meters"; 417 description 418 "The X value as defined by the reference-frame."; 419 } 420 leaf y { 421 type decimal64 { 422 fraction-digits 6; 423 } 424 units "meters"; 425 description 426 "The Y value as defined by the reference-frame."; 427 } 428 leaf z { 429 type decimal64 { 430 fraction-digits 6; 431 } 432 units "meters"; 433 description 434 "The Z value as defined by the reference-frame."; 435 } 436 } 437 } 438 container velocity { 439 description 440 "If the object is in motion the velocity vector describes 441 this motion at the the time given by the timestamp"; 443 leaf v-north { 444 type decimal64 { 445 fraction-digits 12; 446 } 447 units "meters per second"; 448 description 449 "v-north is the rate of change (i.e., speed) towards 450 truth north as defined by the ~geodetic-system~."; 451 } 452 leaf v-east { 453 type decimal64 { 454 fraction-digits 12; 455 } 456 units "meters per second"; 457 description 458 "v-east is the rate of change (i.e., speed) perpendicular 459 to truth-north as defined by the ~geodetic-system~."; 460 } 462 leaf v-up { 463 type decimal64 { 464 fraction-digits 12; 465 } 466 units "meters per second"; 467 description 468 "v-up is the rate of change (i.e., speed) away from the 469 center of mass."; 470 } 471 } 472 leaf timestamp { 473 type types:date-and-time; 474 description "Reference time when location was recorded."; 475 } 476 leaf valid-until { 477 type types:date-and-time; 478 description 479 "The timestamp for which this geo-location is valid until. 480 If unspecified the geo-location has no specific expiration 481 time."; 482 } 483 } 484 } 485 } 486 488 4. ISO 6709:2008 Conformance 490 [ISO.6709.2008] provides an appendix with a set of tests for 491 conformance to the standard. The tests and results are given in the 492 following table along with an explanation of non-applicable tests. 494 +---------+----------------------+------------------+ 495 | Test | Description | Pass Explanation | 496 +=========+======================+==================+ 497 | A.1.2.1 | elements reqd. for a | CRS is always | 498 | | geo. point location | indicated | 499 +---------+----------------------+------------------+ 500 | A.1.2.2 | Description of a CRS | CRS register is | 501 | | from a register | defined | 502 +---------+----------------------+------------------+ 503 | A.1.2.3 | definition of CRS | N/A - Don't | 504 | | | define CRS | 505 +---------+----------------------+------------------+ 506 | A.1.2.4 | representation of | lat/long values | 507 | | horizontal position | conform | 508 +---------+----------------------+------------------+ 509 | A.1.2.5 | representation of | height value | 510 | | vertical position | conforms | 511 +---------+----------------------+------------------+ 512 | A.1.2.6 | text string | N/A - No string | 513 | | representation | format | 514 +---------+----------------------+------------------+ 516 Table 1: Conformance Test Results 518 For test "A.1.2.1" the YANG geo location object either includes a CRS 519 ("reference-frame") or has a default defined ([WGS84]). 521 For "A.1.2.3" we do not define our own CRS, and doing so is not 522 required for conformance. 524 For "A.1.2.6" we do not define a text string representation, which is 525 also not required for conformance. 527 5. Usability 529 The geo-location object defined in this document and YANG module have 530 been designed to be usable in a very broad set of applications. This 531 includes the ability to locate things on astronomical bodies other 532 than The Earth, and to utilize entirely different coordinate systems 533 and realities. 535 Many systems make use of geo-location data, and so it's important to 536 be able describe this data using this geo-location object defined in 537 this document. 539 5.1. Portability 541 In order to verify portability while developing this module the 542 following standards and standard APIs and were considered. 544 5.1.1. IETF URI Value 546 [RFC5870] defines a standard URI value for geographic location data. 547 It includes the ability to specify the "geodetic-value" (it calls 548 this "crs") with the default being "wgs-84" [WGS84]. For the 549 location data it allows 2 to 3 coordinates defined by the "crs" 550 value. For accuracy it has a single "u" parameter for specifying 551 uncertainty. The "u" value is in fractions of meters and applies to 552 all the location values. As the URI is a string, all values are 553 specifies as strings and so are capable of as much precision as 554 required. 556 URI values can be mapped to and from the YANG grouping, with the 557 caveat that some loss of precision (in the extremes) may occur due to 558 the YANG grouping using decimal64 values rather than strings. 560 5.1.2. W3C 562 See https://w3c.github.io/geolocation-api/#dom-geolocationposition. 564 W3C Defines a geo-location API in [W3CGEO]. We show a snippet of 565 code below which defines the geo-location data for this API. This is 566 used by many application (e.g., Google Maps API). 568 interface GeolocationPosition { 569 readonly attribute GeolocationCoordinates coords; 570 readonly attribute DOMTimeStamp timestamp; 571 }; 573 interface GeolocationCoordinates { 574 readonly attribute double latitude; 575 readonly attribute double longitude; 576 readonly attribute double? altitude; 577 readonly attribute double accuracy; 578 readonly attribute double? altitudeAccuracy; 580 readonly attribute double? speed; 581 }; 583 Figure 1: Snippet Showing Geo-Location Definition 585 5.1.2.1. Compare with YANG Model 587 +------------------+--------------+-----------------+-------------+ 588 | Field | Type | YANG | Type | 589 +==================+==============+=================+=============+ 590 | accuracy | double | coord-accuracy | dec64 fr 6 | 591 +------------------+--------------+-----------------+-------------+ 592 | altitude | double | height | dec64 fr 6 | 593 +------------------+--------------+-----------------+-------------+ 594 | altitudeAccuracy | double | height-accuracy | dec64 fr 6 | 595 +------------------+--------------+-----------------+-------------+ 596 | heading | double | v-north, v-east | dec64 fr 12 | 597 +------------------+--------------+-----------------+-------------+ 598 | latitude | double | latitude | dec64 fr 16 | 599 +------------------+--------------+-----------------+-------------+ 600 | longitude | double | longitude | dec64 fr 16 | 601 +------------------+--------------+-----------------+-------------+ 602 | speed | double | v-north, v-east | dec64 fr 12 | 603 +------------------+--------------+-----------------+-------------+ 604 | timestamp | DOMTimeStamp | timestamp | string | 605 +------------------+--------------+-----------------+-------------+ 607 Table 2 609 accuracy (double) Accuracy of "latitude" and "longitude" values in 610 meters. 612 altitude (double) Optional height in meters above the [WGS84] 613 ellipsoid. 615 altitudeAccuracy (double) Optional accuracy of "altitude" value in 616 meters. 618 heading (double) Optional Direction in decimal deg from true north 619 increasing clock-wise. 621 latitude, longitude (double) Standard lat/long values in decimal 622 degrees. 624 speed (double) Speed along heading in meters per second. 626 timestamp (DOMTimeStamp) Specifies milliseconds since the Unix EPOCH 627 in 64 bit unsigned integer. The YANG model defines the timestamp 628 with arbitrarily large precision by using a string which 629 encompasses all representable values of this timestamp value. 631 W3C API values can be mapped to the YANG grouping, with the caveat 632 that some loss of precision (in the extremes) may occur due to the 633 YANG grouping using decimal64 values rather than doubles. 635 Conversely, only YANG values for The Earth using the default "wgs-84" 636 [WGS84] as the "geodetic-datum", can be directly mapped to the W3C 637 values, as W3C does not provide the extra features necessary to map 638 the broader set of values supported by the YANG grouping. 640 5.1.3. Geography Markup Language (GML) 642 ISO adopted the Geography Markup Language (GML) defined by OGC 07-036 643 as [ISO.19136.2007]. GML defines, among many other things, a 644 position type "gml:pos" which is a sequence of "double" values. This 645 sequence of values represent coordinates in a given CRS. The CRS is 646 either inherited from containing elements or directly specified as 647 attributes "srsName" and optionally "srsDimension" on the "gml:pos". 649 GML defines an Abstract CRS type which Concrete CRS types derive 650 from. This allows for many types of CRS definitions. We are 651 concerned with the Geodetic CRS type which can have either 652 ellipsoidal or Cartesian coordinates. We believe that other non- 653 Earth based CRS as well as virtual CRS should also be representable 654 by the GML CRS types as well. 656 Thus GML "gml:pos" values can be mapped directly to the YANG 657 grouping, with the caveat that some loss of precision (in the 658 extremes) may occur due to the YANG grouping using decimal64 values 659 rather than doubles. 661 Conversely, YANG grouping values can be mapped to GML as directly as 662 the GML CRS available definitions allow with a minimum of Earth-based 663 geodetic systems fully supported. 665 GML also defines an observation value in "gml:Observation" which 666 includes a timestamp value "gml:validTime" in addition to other 667 components such as "gml:using" "gml:target" and "gml:resultOf". Only 668 the timestamp is mappable to and from the YANG grouping. Furthermore 669 "gml:validTime" can either be an Instantaneous measure 670 ("gml:TimeInstant") or a time period ("gml:TimePeriod"). The 671 instantaneous "gml:TimeInstant" is mappable to and from the YANG 672 grouping "timestamp" value, and values down to the resolution of 673 seconds for "gml:TimePeriod" can be mapped using the using the 674 "valid-for" node of the YANG grouping. 676 5.1.4. KML 678 KML 2.2 [KML22] (formerly Keyhole Markup Language) was submitted by 679 Google to Open Geospatial Consortium (OGC) 680 https://www.opengeospatial.org/ and was adopted. The latest version 681 as of this writing is KML 2.3 [KML23]. This schema includes 682 geographic location data in some of its objects (e.g., "kml:Point" or 683 "kml:Camera" objects). This data is provided in string format and 684 corresponds to the [W3CGEO] values. The timestamp value is also 685 specified as a string as in our YANG grouping. 687 KML has some special handling for the height value useful for 688 visualization software, "kml:altitudeMode". These values for 689 "kml:altitudeMode" include indicating the height is ignored 690 ("clampToGround"), in relation to the location's ground level 691 ("relativeToGround"), or in relation to the geodetic datum 692 ("absolute"). The YANG grouping can directly map the ignored and 693 absolute cases, but not the relative to ground case. 695 In addition to the "kml:altitudeMode" KML also defines two seafloor 696 height values using "kml:seaFloorAltitudeMode". One value is to 697 ignore the height value ("clampToSeaFloor") and the other is relative 698 ("relativeToSeaFloor"). As with the "kml:altitudeMode" value, the 699 YANG grouping supports the ignore case but not the relative case. 701 The KML location values use a geodetic datum defined in Annex A by 702 the GML Coordinate Reference System (CRS) [ISO.19136.2007] with 703 identifier "LonLat84_5773". The altitude value for KML absolute 704 height mode is measured from the vertical datum specified by [WGS84]. 706 Thus the YANG grouping and KML values can be directly mapped in both 707 directions (when using a supported altitude mode) with the caveat 708 that some loss of precision (in the extremes) may occur due to the 709 YANG grouping using decimal64 values rather than strings. For the 710 relative height cases the application doing the transformation is 711 expected to have the data available to transform the relative height 712 into an absolute height which can then be expressed using the YANG 713 grouping. 715 6. IANA Considerations 717 6.1. Geodetic System Value Registry 719 This registry allocates names for standard geodetic systems. Often 720 these values are referred to using multiple names (e.g., full names 721 or multiple acronyms values). The intent of this registry is to 722 provide a single standard value for any given geodetic system. 724 The values SHOULD use an acronym when available, they MUST be 725 converted to lower case, and spaces MUST be changed to dashes "-". 727 Each entry should be sufficient to define the 3 coordinate values (2 728 if height is not required). So for example the "wgs-84" is defined 729 as WGS-84 with the geoid updated by at least [EGM96] for height 730 values. Specific entries for [EGM96] and [EGM08] are present if a 731 more precise definition of the data is required. 733 It should be noted that [RFC5870] also creates a registry for 734 Geodetic Systems (it calls CRS); however, this registry has a very 735 strict modification policy. The authors of [RFC5870] have the stated 736 goal of making CRS registration hard to avoid proliferation of CRS 737 values. As our module defines alternate systems and has a broader 738 (beyond earth) scope, the registry defined below is meant to be more 739 easily modified. 741 The allocation policy for this registry is First Come First Served, 742 [RFC8126] as the intent is simply to avoid duplicate values. 744 The initial values for this registry are as follows. 746 +------------+------------------------------------------------------+ 747 | Name | Description | 748 +============+======================================================+ 749 | me | Mean Earth/Polar Axis (Moon) | 750 +------------+------------------------------------------------------+ 751 | mola-vik-1 | MOLA Height, IAU Viking-1 PM (Mars) | 752 +------------+------------------------------------------------------+ 753 | wgs-84-96 | World Geodetic System 1984 [WGS84] w/ EGM96 | 754 +------------+------------------------------------------------------+ 755 | wgs-84-08 | World Geodetic System 1984 [WGS84] w/ [EGM08] | 756 +------------+------------------------------------------------------+ 757 | wgs-84 | World Geodetic System 1984 [WGS84] (EGM96 or | 758 | | better) | 759 +------------+------------------------------------------------------+ 761 Table 3 763 7. Security Considerations 765 This document defines a common geo location grouping using the YANG 766 data modeling language. The grouping itself has no security or 767 privacy impact on the Internet, but the usage of the grouping in 768 concrete YANG modules might have. The security considerations 769 spelled out in the YANG 1.1 specification [RFC7950] apply for this 770 document as well. 772 8. Normative References 774 [EGM08] Pavlis, N.K., Holmes, S.A., Kenyon, S.C., and J.K. Factor, 775 "An Earth Gravitational Model to Degree 2160: EGM08.", 776 Presented at the 2008 General Assembly of the European 777 Geosciences Union, Vienna, Arpil13-18, 2008, 2008, 778 . 781 [EGM96] Lemoine, F.G., Kenyon, S.C., Factor, J.K., Trimmer, R.G., 782 Pavlis, N.K., Chinn, D.S., Cox, C.M., Klosko, S.M., 783 Luthcke, S.B., Torrence, M.H., Wang, Y.M., Williamson, 784 R.G., Pavlis, E.C., Rapp, R.H., and T.R. Olson, "The 785 Development of the Joint NASA GSFC and the National 786 Imagery and Mapping Agency (NIMA) Geopotential Model 787 EGM96.", Technical Report NASA/TP-1998-206861, NASA, 788 Greenbelt., 1998, 789 . 791 [ISO.6709.2008] 792 International Organization for Standardization, "ISO 793 6709:2008 Standard representation of geographic point 794 location by coordinates.", 2008. 796 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 797 Requirement Levels", BCP 14, RFC 2119, 798 DOI 10.17487/RFC2119, March 1997, 799 . 801 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 802 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 803 May 2017, . 805 [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for 806 Writing an IANA Considerations Section in RFCs", BCP 26, 807 RFC 8126, DOI 10.17487/RFC8126, June 2017, 808 . 810 [RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 811 and R. Wilton, "Network Management Datastore Architecture 812 (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018, 813 . 815 [WGS84] National Imagery and Mapping Agency., "National Imagery 816 and Mapping Agency Technical Report 8350.2, Third 817 Edition.", 3 January 2000, . 820 9. Informative References 822 [ISO.19136.2007] 823 International Organization for Standardization, "ISO 824 19136:2007 Geographic information -- Geography Markup 825 Language (GML)". 827 [KML22] Wilson, T., Ed., "OGC KML (Version 2.2)", 14 April 2008, 828 . 831 [KML23] Burggraf, D., Ed., "OGC KML 2.3", 4 August 2015, 832 . 835 [RFC5870] Mayrhofer, A. and C. Spanring, "A Uniform Resource 836 Identifier for Geographic Locations ('geo' URI)", 837 RFC 5870, DOI 10.17487/RFC5870, June 2010, 838 . 840 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 841 RFC 7950, DOI 10.17487/RFC7950, August 2016, 842 . 844 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 845 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 846 . 848 [W3CGEO] Popescu, A., "Geolocation API Specification", 8 November 849 2016, . 852 Appendix A. Examples 854 Below is a fictitious module that uses the geo-location grouping. 856 module example-uses-geo-location { 857 namespace 858 "urn:example:example-uses-geo-location"; 859 prefix ugeo; 860 import ietf-geo-location { prefix geo; } 861 organization "Empty Org"; 862 contact "Example Author "; 863 description "Example use of geo-location"; 864 revision 2019-02-02 { reference "None"; } 865 container locatable-items { 866 description "container of locatable items"; 867 list locatable-item { 868 key name; 869 description "A of locatable item"; 870 leaf name { 871 type string; 872 description "name of locatable item"; 873 } 874 uses geo:geo-location; 875 } 876 } 877 } 879 Figure 2: Example YANG module using geo location. 881 Below is a the YANG tree for the fictitious module that uses the geo- 882 location grouping. 884 module: example-uses-geo-location 885 +--rw locatable-items 886 +--rw locatable-item* [name] 887 +--rw name string 888 +--rw geo-location 889 +--rw reference-frame 890 | +--rw alternate-system? string {alternate-systems}? 891 | +--rw astronomical-body? string 892 | +--rw geodetic-system 893 | +--rw geodetic-datum? string 894 | +--rw coord-accuracy? decimal64 895 | +--rw height-accuracy? decimal64 896 +--rw (location)? 897 | +--:(ellipsoid) 898 | | +--rw latitude? decimal64 899 | | +--rw longitude? decimal64 900 | | +--rw height? decimal64 901 | +--:(cartesian) 902 | +--rw x? decimal64 903 | +--rw y? decimal64 904 | +--rw z? decimal64 905 +--rw velocity 906 | +--rw v-north? decimal64 907 | +--rw v-east? decimal64 908 | +--rw v-up? decimal64 909 +--rw timestamp? types:date-and-time 910 +--rw valid-until? types:date-and-time 912 Below is some example YANG XML data for the fictitious module that 913 uses the geo-location grouping. 915 916 917 Gaetana's 918 919 40.73297 920 -74.007696 921 922 923 924 Pont des Arts 925 926 2012-03-31T16:00:00Z 927 48.8583424 928 2.3375084 929 35 930 931 932 933 Saint Louis Cathedral 934 935 2013-10-12T15:00:00-06:00 936 29.9579735 937 -90.0637281 938 939 940 941 Apollo 11 Landing Site 942 943 1969-07-21T02:56:15Z 944 945 moon 946 947 me 948 949 950 0.67409 951 23.47298 952 953 954 955 Reference Frame Only 956 957 958 moon 959 960 me 961 962 963 964 965 967 Figure 3: Example XML data of geo location use. 969 Appendix B. Acknowledgements 971 We would like to thank Jim Biard and Ben Koziol for their reviews and 972 suggested improvements. We would also like to thank Peter Lothberg 973 for the motivation as well as help in defining a broadly useful 974 geographic location object, and Acee Lindem and Qin Wu for their work 975 on a geographic location object that led to this documents creation. 977 Author's Address 978 Christian Hopps 979 LabN Consulting, L.L.C. 981 Email: chopps@chopps.org