idnits 2.17.1 draft-chopps-netmod-geo-location-01.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- 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 905 has weird spacing: '...ngitude deg...' -- The document date (March 2, 2019) is 1875 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 March 2, 2019 5 Expires: September 3, 2019 7 YANG Geo Location 8 draft-chopps-netmod-geo-location-01 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 September 3, 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 . . . . . . . . . . . . . . . . . . . . . . . 12 64 5.1.1. IETF URI Value . . . . . . . . . . . . . . . . . . . 12 65 5.1.2. W3C . . . . . . . . . . . . . . . . . . . . . . . . . 12 66 5.1.3. Geography Markup Language (GML) . . . . . . . . . . . 14 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 . . . . . . . . . . . . . . . . . . . . . . . . . 17 72 8.1. Normative References . . . . . . . . . . . . . . . . . . 17 73 8.2. Informative References . . . . . . . . . . . . . . . . . 18 74 Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 19 75 Appendix B. Acknowledgements . . . . . . . . . . . . . . . . . . 22 76 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 22 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 3. YANG Module 242 file "ietf-geo-location@2019-02-17.yang" 243 module ietf-geo-location { 244 namespace "urn:ietf:params:xml:ns:yang:ietf-geo-location"; 245 prefix geo; 246 import ietf-yang-types { prefix types; } 248 organization 249 "IETF NETMOD Working Group (NETMOD)"; 250 contact 251 "Christian Hopps "; 253 // RFC Ed.: replace XXXX with actual RFC number and 254 // remove this note. 256 description 257 "This module defines a grouping of a container object for 258 specifying a location on or around an astronomical object (e.g., 259 The Earth). 261 Copyright (c) 2018 IETF Trust and the persons identified as 262 authors of the code. All rights reserved. 264 Redistribution and use in source and binary forms, with or 265 without modification, is permitted pursuant to, and subject to 266 the license terms contained in, the Simplified BSD License set 267 forth in Section 4.c of the IETF Trust's Legal Provisions 268 Relating to IETF Documents 269 (https://trustee.ietf.org/license-info). 271 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL 272 NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'NOT RECOMMENDED', 273 'MAY', and 'OPTIONAL' in this document are to be interpreted as 274 described in BCP 14 [RFC2119] [RFC8174] when, and only when, 275 they appear in all capitals, as shown here. 277 This version of this YANG module is part of RFC XXXX 278 (https://tools.ietf.org/html/rfcXXXX); see the RFC itself for 279 full legal notices."; 281 // RFC Ed.: replace XXXX with actual RFC number and 282 // remove this note. 284 revision 2019-02-17 { 285 description "Initial Revision"; 286 reference "RFC XXXX: YANG Geo Location"; 287 } 288 typedef degrees { 289 type decimal64 { 290 fraction-digits 16; 291 } 292 units "decimal degrees"; 293 description "Coordinate value."; 294 } 296 feature alternate-systems { 297 description 298 "This feature means the device supports specifying locations 299 using alternate systems for reference frames."; 300 } 302 grouping geo-location { 303 description 304 "Grouping to identify a location on an astronomical object."; 306 container geo-location { 307 description 308 "A location on an astronomical body (e.g., The Earth) 309 somewhere in a universe."; 311 container reference-frame { 312 description 313 "The Frame of Reference for the location values."; 315 leaf alternate-system { 316 if-feature alternate-systems; 317 type string; 318 description 319 "The system in which the astronomical body and 320 geodetic-datum is defined. Normally, this value is not 321 present and the system is the natural universe; however, 322 when present this value allows for specifying alternate 323 systems (e.g., virtual realities). An alternate-system 324 modifies the definition (but not the type) of the other 325 values in the reference frame."; 326 } 327 leaf astronomical-body { 328 type string { 329 pattern 330 '[-0-9a-z #x22#x23#x5B#x5D' + 331 '!$%&()*+,\./:;<=>?@\\^_`{|}~]+'; 332 } 333 default "earth"; 334 description 335 "An astronomical body as named by the International 336 Astronomical Union (IAU) or according to the alternate 337 system if specified. Examples include 'sun' (our star), 338 'earth' (our planet), 'moon' (our moon), 'enceladus' (a 339 moon of Saturn), 'ceres' (an asteroid), 340 '67p/churyumov-gerasimenko (a comet). The value should 341 be comprised of all lower case ASCII characters not 342 including control characters (i.e., values 32..64, and 343 91..126)"; 344 } 345 container geodetic-system { 346 description 347 "The geodetic system of the location data."; 348 leaf geodetic-datum { 349 type string { 350 pattern 351 '[-0-9a-z#x22#x23#x5B#x5D' + 352 '!$%&()*+,\./:;<=>?@\\^_`{|}~]+'; 353 } 354 default "wgs-84"; 355 description 356 "A geodetic-datum defining the meaning of latitude, 357 longitude and height. The default is 'wgs-84' which is 358 used by the Global Positioning System (GPS)"; 359 } 360 leaf coord-accuracy { 361 type decimal64 { 362 fraction-digits 6; 363 } 364 description 365 "The accuracy of the latitude longitude pair. When 366 coord-accuracy is specified it overrides the 367 geodetic-datum implied accuracy. If Cartesian 368 coordinates are in use this accuracy corresponds to 369 the X and Y components"; 370 } 371 leaf height-accuracy { 372 type decimal64 { 373 fraction-digits 6; 374 } 375 units "meters"; 376 description 377 "The accuracy of height value. When specified it 378 overrides the geodetic-datum implied default. If 379 Cartesian coordinates ar in use this accuracy 380 corresponds to the Z component."; 381 } 382 // May wish to allow for height to be relative. 383 // If so need to decide if we have a boolean (to ground) 384 // or an enumeration (e.g., local ground, sea-floor, 385 // ground floor, containing object, ...) or even allow 386 // for a string for most generic but least portable 387 // comparable 388 // leaf height-relative { 389 // } 390 } 391 } 392 choice location { 393 mandatory true; 394 description 395 "The location data either in lat/long or Cartesian values"; 396 case ellipsoid { 397 leaf latitude { 398 type degrees; 399 mandatory true; 400 description 401 "The latitude value on the astronomical body. The 402 definition and precision of this measurement is 403 indicated by the reference-frame value."; 404 } 405 leaf longitude { 406 type degrees; 407 mandatory true; 408 description 409 "The longitude value on the astronomical body. The 410 definition and precision of this measurement is 411 indicated by the reference-frame."; 412 } 413 leaf height { 414 type decimal64 { 415 fraction-digits 6; 416 } 417 units "meters"; 418 description 419 "Height from a reference 0 value. The precision and '0' 420 value is defined by the reference-frame."; 421 } 422 } 423 case cartesian { 424 leaf x { 425 type decimal64 { 426 fraction-digits 6; 427 } 428 mandatory true; 429 description 430 "The X value as defined by the reference-frame."; 431 } 432 leaf y { 433 type decimal64 { 434 fraction-digits 6; 435 } 436 mandatory true; 437 description 438 "The Y value as defined by the reference-frame."; 439 } 440 leaf z { 441 type decimal64 { 442 fraction-digits 6; 443 } 444 units "meters"; 445 description 446 "The Z value as defined by the reference-frame."; 447 } 448 } 449 } 450 container velocity { 451 description 452 "If the object is in motion the velocity vector describes 453 this motion at the the time given by the timestamp."; 455 leaf v-north { 456 type decimal64 { 457 fraction-digits 12; 458 } 459 units "meters per second"; 460 description 461 "v-north is the rate of change (i.e., speed) towards 462 truth north as defined by the ~geodetic-system~."; 463 } 465 leaf v-east { 466 type decimal64 { 467 fraction-digits 12; 468 } 469 units "meters per second"; 470 description 471 "v-east is the rate of change (i.e., speed) perpendicular 472 to truth-north as defined by the ~geodetic-system~."; 473 } 475 leaf v-up { 476 type decimal64 { 477 fraction-digits 12; 478 } 479 units "meters per second"; 480 description 481 "v-up is the rate of change (i.e., speed) away from the 482 center of mass."; 483 } 484 } 485 leaf timestamp { 486 type types:date-and-time; 487 description "Reference time when location was recorded."; 488 } 489 } 490 } 491 } 492 494 4. ISO 6709:2008 Conformance 496 [ISO.6709.2008] provides an appendix with a set of tests for 497 conformance to the standard. The tests and results are given in the 498 following table along with an explanation of non-applicable tests. 500 +---------+-----------------------------------+---------------------+ 501 | Test | Description | Pass Explanation | 502 +---------+-----------------------------------+---------------------+ 503 | A.1.2.1 | elements reqd. for a geo. point | CRS is always | 504 | | location | indicated | 505 | | | | 506 | A.1.2.2 | Description of a CRS from a | CRS register is | 507 | | register | defined | 508 | | | | 509 | A.1.2.3 | definition of CRS | N/A - Don't define | 510 | | | CRS | 511 | | | | 512 | A.1.2.4 | representation of horizontal | lat/long values | 513 | | position | conform | 514 | | | | 515 | A.1.2.5 | representation of vertical | height value | 516 | | position | conforms | 517 | | | | 518 | A.1.2.6 | text string representation | N/A - No string | 519 | | | format | 520 +---------+-----------------------------------+---------------------+ 522 Conformance Test Results 524 For test "A.1.2.1" the YANG geo location object either includes a CRS 525 ("reference-frame") or has a default defined ([WGS84]). 527 For "A.1.2.3" we do not define our own CRS, and doing so is not 528 required for conformance. 530 For "A.1.2.6" we do not define a text string representation, which is 531 also not required for conformance. 533 5. Usability 535 The geo-location object defined in this document and YANG module have 536 been designed to be usable in a very broad set of applications. This 537 includes the ability to locate things on astronomical bodies other 538 than The Earth, and to utilize entirely different coordinate systems 539 and realities. 541 Many systems make use of geo-location data, and so it's important to 542 be able describe this data using this geo-location object defined in 543 this document. 545 5.1. Portability 547 In order to verify portability while developing this module the 548 following standards and standard APIs and were considered. 550 5.1.1. IETF URI Value 552 [RFC5870] defines a standard URI value for geographic location data. 553 It includes the ability to specify the "geodetic-value" (it calls 554 this "crs") with the default being "wgs-84" [WGS84]. For the 555 location data it allows 2 to 3 coordinates defined by the "crs" 556 value. For accuracy it has a single "u" parameter for specifying 557 uncertainty. The "u" value is in fractions of meters and applies to 558 all the location values. As the URI is a string, all values are 559 specifies as strings and so are capable of as much precision as 560 required. 562 URI values can be mapped to and from the YANG grouping, with the 563 caveat that some loss of precision (in the extremes) may occur due to 564 the YANG grouping using decimal64 values rather than strings. 566 5.1.2. W3C 568 See . 570 W3C Defines a geo-location API in [W3CGEO]. We show a snippet of 571 code below which defines the geo-location data for this API. This is 572 used by many application (e.g., Google Maps API). 574 interface GeolocationPosition { 575 readonly attribute GeolocationCoordinates coords; 576 readonly attribute DOMTimeStamp timestamp; 577 }; 579 interface GeolocationCoordinates { 580 readonly attribute double latitude; 581 readonly attribute double longitude; 582 readonly attribute double? altitude; 583 readonly attribute double accuracy; 584 readonly attribute double? altitudeAccuracy; 586 readonly attribute double? speed; 587 }; 589 5.1.2.1. Compare with YANG Model 591 +------------------+--------------+-----------------+-------------+ 592 | Field | Type | YANG | Type | 593 +------------------+--------------+-----------------+-------------+ 594 | accuracy | double | coord-accuracy | dec64 fr 6 | 595 | | | | | 596 | altitude | double | height | dec64 fr 6 | 597 | | | | | 598 | altitudeAccuracy | double | height-accuracy | dec64 fr 6 | 599 | | | | | 600 | heading | double | heading | dec64 fr 16 | 601 | | | | | 602 | latitude | double | latitude | dec64 fr 16 | 603 | | | | | 604 | longitude | double | longitude | dec64 fr 16 | 605 | | | | | 606 | speed | double | speed | dec64 fr 12 | 607 | | | | | 608 | timestamp | DOMTimeStamp | timestamp | string | 609 +------------------+--------------+-----------------+-------------+ 611 accuracy (double): Accuracy of "latitude" and "longitude" values in 612 meters. 614 altitude (double): Optional height in meters above the [WGS84] 615 ellipsoid. 617 altitudeAccuracy (double): Optional accuracy of "altitude" value in 618 meters. 620 heading (double): Optional Direction in decimal deg from true north 621 increasing clock-wise. 623 latitude, longitude (double): Standard lat/long values in decimal 624 degrees. 626 speed (double): Speed along heading in meters per second. 628 timestamp (DOMTimeStamp): Specifies milliseconds since the Unix 629 EPOCH in 64 bit unsigned integer. The YANG model defines the 630 timestamp with arbitrarily large precision by using a string which 631 encompasses all representable values of this timestamp value. 633 W3C API values can be mapped to the YANG grouping, with the caveat 634 that some loss of precision (in the extremes) may occur due to the 635 YANG grouping using decimal64 values rather than doubles. 637 Conversely, only YANG values for The Earth using the default "wgs-84" 638 [WGS84] as the "geodetic-datum", can be directly mapped to the W3C 639 values, as W3C does not provide the extra features necessary to map 640 the broader set of values supported by the YANG grouping. 642 5.1.3. Geography Markup Language (GML) 644 ISO adopted the Geography Markup Language (GML) defined by OGC 07-036 645 as [ISO.19136.2007]. GML defines, among many other things, a 646 position type "gml:pos" which is a sequence of "double" values. This 647 sequence of values represent coordinates in a given CRS. The CRS is 648 either inherited from containing elements or directly specified as 649 attributes "srsName" and optionally "srsDimension" on the "gml:pos". 651 GML defines an Abstract CRS type which Concrete CRS types derive 652 from. This allows for many types of CRS definitions. We are 653 concerned with the Geodetic CRS type which can have either 654 ellipsoidal or Cartesian coordinates. We believe that other non- 655 Earth based CRS as well as virtual CRS should also be representable 656 by the GML CRS types as well. 658 Thus GML "gml:pos" values can be mapped directly to the YANG 659 grouping, with the caveat that some loss of precision (in the 660 extremes) may occur due to the YANG grouping using decimal64 values 661 rather than doubles. 663 Conversely, YANG grouping values can be mapped to GML as directly as 664 the GML CRS available definitions allow with a minimum of Earth-based 665 geodetic systems fully supported. 667 GML also defines an observation value in "gml:Observation" which 668 includes a timestamp value "gml:validTime" in addition to other 669 components such as "gml:using" "gml:target" and "gml:resultOf". Only 670 the timestamp is mappable to and from the YANG grouping. Furthermore 671 "gml:validTime" can either be an Instantaneous measure 672 ("gml:TimeInstant") or a time period ("gml:TimePeriod"). Only the 673 instantaneous "gml:TimeInstant" is mappable to and from the YANG 674 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 and was adopted. The latest 681 version as of this writing is KML 2.3 [KML23]. This schema includes 682 geographic location data in some of it's objects (e.g., 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 locations 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 TODO: Open question, should we create a new registry here or attempt 742 to modify the one created by [RFC5870]. It's worth noting that we 743 include the ability to specify any geodetic system including ones 744 designed for astronomical bodies other than the earth, as well as 745 ones based on alternate systems. These requirements may be too broad 746 for adapting the existing [RFC5870] registry. 748 TODO: Open question, is FCFS too easy, perhaps expert review would 749 strike a good balance. If expert review is acceptable, would it also 750 be acceptable to update the policy on [RFC5870] and use it instead? 752 The allocation policy for this registry is First Come First Served, 753 [RFC8126] as the intent is simply to avoid duplicate values. 755 The initial values for this registry are as follows. 757 +------------+------------------------------------------------------+ 758 | Name | Description | 759 +------------+------------------------------------------------------+ 760 | me | Mean Earth/Polar Axis (Moon) | 761 | | | 762 | mola-vik-1 | MOLA Height, IAU Viking-1 PM (Mars) | 763 | | | 764 | wgs-84-96 | World Geodetic System 1984 [WGS84] w/ EGM96 | 765 | | | 766 | wgs-84-08 | World Geodetic System 1984 [WGS84] w/ [EGM08] | 767 | | | 768 | wgs-84 | World Geodetic System 1984 [WGS84] (EGM96 or better) | 769 +------------+------------------------------------------------------+ 771 7. Security Considerations 773 This document defines a common geo location grouping using the YANG 774 data modeling language. The grouping itself has no security or 775 privacy impact on the Internet, but the usage of the grouping in 776 concrete YANG modules might have. The security considerations 777 spelled out in the YANG 1.1 specification [RFC7950] apply for this 778 document as well. 780 8. References 782 8.1. Normative References 784 [EGM08] Pavlis, N., Holmes, S., Kenyon, S., and J. Factor, "An 785 Earth Gravitational Model to Degree 2160: EGM08.", 2008, 786 . 789 [EGM96] Lemoine, F., Kenyon, S., Factor, J., Trimmer, R., Pavlis, 790 N., Chinn, D., Cox, C., Klosko, S., Luthcke, S., Torrence, 791 M., Wang, Y., Williamson, R., Pavlis, E., Rapp, R., and T. 792 Olson, "The Development of the Joint NASA GSFC and the 793 National Imagery and Mapping Agency (NIMA) Geopotential 794 Model EGM96.", 1998, 795 . 797 [ISO.6709.2008] 798 International Organization for Standardization, "ISO 799 6709:2008 Standard representation of geographic point 800 location by coordinates.", 2008. 802 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 803 Requirement Levels", BCP 14, RFC 2119, 804 DOI 10.17487/RFC2119, March 1997, 805 . 807 [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for 808 Writing an IANA Considerations Section in RFCs", BCP 26, 809 RFC 8126, DOI 10.17487/RFC8126, June 2017, 810 . 812 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 813 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 814 May 2017, . 816 [RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 817 and R. Wilton, "Network Management Datastore Architecture 818 (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018, 819 . 821 [WGS84] National Imagery and Mapping Agency., "National Imagery 822 and Mapping Agency Technical Report 8350.2, Third 823 Edition.", 1 2000, . 826 8.2. Informative References 828 [ISO.19136.2007] 829 International Organization for Standardization, "ISO 830 19136:2007 Geographic information -- Geography Markup 831 Language (GML)". 833 [KML22] Wilson, T., Ed., "OGC KML (Version 2.2)", 4 2008, 834 . 837 [KML23] Burggraf, D., Ed., "OGC KML 2.3", 8 2015, 838 . 841 [RFC5870] Mayrhofer, A. and C. Spanring, "A Uniform Resource 842 Identifier for Geographic Locations ('geo' URI)", 843 RFC 5870, DOI 10.17487/RFC5870, June 2010, 844 . 846 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 847 RFC 7950, DOI 10.17487/RFC7950, August 2016, 848 . 850 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 851 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 852 . 854 [W3CGEO] Popescu, A., "Geolocation API Specification", 11 2016, 855 . 858 Appendix A. Examples 860 Below is a fictitious module that uses the geo-location grouping. 862 file "ietf-uses-geo-location@2019-02-02.yang" 863 module ietf-uses-geo-location { 864 namespace 865 "urn:ietf:params:xml:ns:yang:ietf-uses-geo-location"; 866 prefix ugeo; 867 import geo-location { prefix geo; } 868 organization "Empty Org"; 869 contact "Example Author "; 870 description "Example use of geo-location"; 871 revision 2019-02-02 { reference "None"; } 872 container locatable-items { 873 description "container of locatable items"; 874 list locatable-item { 875 key name; 876 description "A of locatable item"; 877 leaf name { 878 type string; 879 description "name of locatable item"; 880 } 881 uses geo:geo-location; 882 } 883 } 884 } 885 887 Below is a the YANG tree for the fictitious module that uses the geo- 888 location grouping. 890 module: ietf-uses-geo-location 891 +--rw locatable-items 892 +--rw locatable-item* [name] 893 +--rw name string 894 +--rw geo-location 895 +--rw reference-frame 896 | +--rw alternate-system? string {alternate-systems}? 897 | +--rw astronomical-body? string 898 | +--rw geodetic-system 899 | +--rw geodetic-datum? string 900 | +--rw coord-accuracy? decimal64 901 | +--rw height-accuracy? decimal64 902 +--rw (location) 903 | +--:(ellipsoid) 904 | | +--rw latitude degrees 905 | | +--rw longitude degrees 906 | | +--rw height? decimal64 907 | +--:(cartesian) 908 | +--rw x decimal64 909 | +--rw y decimal64 910 | +--rw z? decimal64 911 +--rw velocity 912 | +--rw v-north? decimal64 913 | +--rw v-east? decimal64 914 | +--rw v-up? decimal64 915 +--rw timestamp? types:date-and-time 917 Below is some example YANG XML data for the fictitious module that 918 uses the geo-location grouping. 920 921 923 924 Gaetana's 925 926 40.73297 927 -74.007696 928 929 930 931 Pont des Arts 932 933 2012-03-31T16:00:00Z 934 48.8583424 935 2.3375084 936 35 937 938 939 940 Saint Louis Cathedral 941 942 2013-10-12T15:00:00-06:00 943 29.9579735 944 -90.0637281 945 946 947 948 Apollo 11 Landing Site 949 950 1969-07-21T02:56:15Z 951 952 moon 953 954 me 955 956 957 0.67409 958 23.47298 959 960 961 962 964 Appendix B. Acknowledgements 966 We would like to thank Peter Lothberg for the motivation as well as 967 help in defining a more broadly useful geographic location object. 969 We would also like to thank Acee Lindem and Qin Wu for their work on 970 a geographic location object that led to this documents creation. 972 Author's Address 974 Christian Hopps 975 LabN Consulting, L.L.C. 977 Email: chopps@chopps.org