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