idnits 2.17.1 draft-ietf-netmod-geo-location-10.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 809 has weird spacing: '... name ietf-...' == Line 811 has weird spacing: '...mespace urn:i...' == Line 813 has weird spacing: '... prefix geo...' -- The document date (17 June 2021) is 1044 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 17 June 2021 5 Expires: 19 December 2021 7 A YANG Grouping for Geographic Locations 8 draft-ietf-netmod-geo-location-10 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 19 December 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 Reference value can either be a document or a contact person as 769 defined in [RFC8126]. The Change Control (i.e., Owner) is also 770 defined by [RFC8126]. 772 The initial values for this registry are as follows. They include 773 the non-Earth based geodetic-datum value for the moon based on [ME]. 775 +-----------+------------------------------+-----------+---------+ 776 | Name | Description | Reference | Change | 777 +-----------+------------------------------+-----------+---------+ 778 | | | /Contact | Control | 779 +===========+==============================+===========+=========+ 780 | me | Mean Earth/Polar Axis (Moon) | this | IESG | 781 +-----------+------------------------------+-----------+---------+ 782 | wgs-84-96 | World Geodetic System 1984 | this | IESG | 783 +-----------+------------------------------+-----------+---------+ 784 | wgs-84-08 | World Geodetic System 1984 | this | IESG | 785 +-----------+------------------------------+-----------+---------+ 786 | wgs-84 | World Geodetic System 1984 | this | IESG | 787 +-----------+------------------------------+-----------+---------+ 789 Table 3 791 6.2. Updates to the IETF XML Registry 793 This document registers a URI in the "IETF XML Registry" [RFC3688]. 794 Following the format in [RFC3688], the following registration has 795 been made: 797 URI urn:ietf:params:xml:ns:yang:ietf-geo-location 799 Registrant Contact The IESG. 801 XML N/A; the requested URI is an XML namespace. 803 6.3. Updates to the YANG Module Names Registry 805 This document registers one YANG module in the "YANG Module Names" 806 registry [RFC6020]. Following the format in [RFC6020], the following 807 registration has been made: 809 name ietf-geo-location 811 namespace urn:ietf:params:xml:ns:yang:ietf-geo-location 813 prefix geo 815 reference RFC XXXX (RFC Ed.: replace XXXX with RFC number and remove 816 this note.) 818 7. Security Considerations 820 The YANG module specified in this document defines a schema for data 821 that is designed to be accessed via network management protocols such 822 as NETCONF [RFC6241] or RESTCONF [RFC8040]. The lowest NETCONF layer 823 is the secure transport layer, and the mandatory-to-implement secure 824 transport is Secure Shell (SSH) [RFC6242]. The lowest RESTCONF layer 825 is HTTPS, and the mandatory-to-implement secure transport is TLS 826 [RFC8446]. 828 The NETCONF access control model [RFC8341] provides the means to 829 restrict access for particular NETCONF or RESTCONF users to a 830 preconfigured subset of all available NETCONF or RESTCONF protocol 831 operations and content. 833 Since the modules defined in this document only define groupings, 834 these considerations are primarily for the designers of other modules 835 that use these groupings. 837 All the data nodes defined in this YANG module are 838 writable/creatable/deletable (i.e., "config true", which is the 839 default). 841 None of the writable/creatable/deletable data nodes in the YANG 842 module defined in this document are by themselves considered more 843 sensitive or vulnerable than standard configuration. 845 Some of the readable data nodes in this YANG module may be considered 846 sensitive or vulnerable in some network environments. It is thus 847 important to control read access (e.g., via get, get-config, or 848 notification) to these data nodes. 850 Since the grouping defined in this module identifies locations, 851 authors using this grouping SHOULD consider any privacy issues that 852 may arise when the data is readable (e.g., customer device locations, 853 etc). 855 8. Normative References 857 [EGM08] Pavlis, N.K., Holmes, S.A., Kenyon, S.C., and J.K. Factor, 858 "An Earth Gravitational Model to Degree 2160: EGM08.", 859 Presented at the 2008 General Assembly of the European 860 Geosciences Union, Vienna, Arpil13-18, 2008, 2008. 862 [EGM96] Lemoine, F.G., Kenyon, S.C., Factor, J.K., Trimmer, R.G., 863 Pavlis, N.K., Chinn, D.S., Cox, C.M., Klosko, S.M., 864 Luthcke, S.B., Torrence, M.H., Wang, Y.M., Williamson, 865 R.G., Pavlis, E.C., Rapp, R.H., and T.R. Olson, "The 866 Development of the Joint NASA GSFC and the National 867 Imagery and Mapping Agency (NIMA) Geopotential Model 868 EGM96.", Technical Report NASA/TP-1998-206861, NASA, 869 Greenbelt., 1998. 871 [ISO.6709.2008] 872 International Organization for Standardization, "ISO 873 6709:2008 Standard representation of geographic point 874 location by coordinates.", 2008. 876 [ME] National Aeronautics and Space Administration, Goddard 877 Space Flight Center., "A Standardized Lunar Coordinate 878 System for the Lunar Reconnaissance Orbiter, Version 4.", 879 14 May 2008. 881 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 882 Requirement Levels", BCP 14, RFC 2119, 883 DOI 10.17487/RFC2119, March 1997, 884 . 886 [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types", 887 RFC 6991, DOI 10.17487/RFC6991, July 2013, 888 . 890 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 891 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 892 May 2017, . 894 [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for 895 Writing an IANA Considerations Section in RFCs", BCP 26, 896 RFC 8126, DOI 10.17487/RFC8126, June 2017, 897 . 899 [RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 900 and R. Wilton, "Network Management Datastore Architecture 901 (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018, 902 . 904 [WGS84] National Imagery and Mapping Agency., "National Imagery 905 and Mapping Agency Technical Report 8350.2, Third 906 Edition.", 3 January 2000. 908 9. Informative References 910 [ISO.19136.2007] 911 International Organization for Standardization, "ISO 912 19136:2007 Geographic information -- Geography Markup 913 Language (GML)". 915 [KML22] Wilson, T., Ed., "OGC KML (Version 2.2)", 14 April 2008, 916 . 919 [KML23] Burggraf, D., Ed., "OGC KML 2.3", 4 August 2015, 920 . 923 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 924 DOI 10.17487/RFC3688, January 2004, 925 . 927 [RFC5870] Mayrhofer, A. and C. Spanring, "A Uniform Resource 928 Identifier for Geographic Locations ('geo' URI)", 929 RFC 5870, DOI 10.17487/RFC5870, June 2010, 930 . 932 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 933 the Network Configuration Protocol (NETCONF)", RFC 6020, 934 DOI 10.17487/RFC6020, October 2010, 935 . 937 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 938 and A. Bierman, Ed., "Network Configuration Protocol 939 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 940 . 942 [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure 943 Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011, 944 . 946 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 947 RFC 7950, DOI 10.17487/RFC7950, August 2016, 948 . 950 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 951 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 952 . 954 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 955 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 956 . 958 [RFC8341] Bierman, A. and M. Bjorklund, "Network Configuration 959 Access Control Model", STD 91, RFC 8341, 960 DOI 10.17487/RFC8341, March 2018, 961 . 963 [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol 964 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, 965 . 967 [W3CGEO] Popescu, A., "Geolocation API Specification", 8 November 968 2016, . 971 Appendix A. Examples 973 Below is a fictitious module that uses the geo-location grouping. 975 module example-uses-geo-location { 976 namespace 977 "urn:example:example-uses-geo-location"; 978 prefix ugeo; 979 import ietf-geo-location { prefix geo; } 980 organization "Empty Org"; 981 contact "Example Author "; 982 description "Example use of geo-location"; 983 revision 2019-02-02 { reference "None"; } 984 container locatable-items { 985 description "container of locatable items"; 986 list locatable-item { 987 key name; 988 description "A locatable item"; 989 leaf name { 990 type string; 991 description "name of locatable item"; 992 } 993 uses geo:geo-location; 994 } 995 } 996 } 998 Figure 2: Example YANG module using geo location. 1000 Below is the YANG tree for the fictitious module that uses the geo- 1001 location grouping. 1003 module: example-uses-geo-location 1004 +--rw locatable-items 1005 +--rw locatable-item* [name] 1006 +--rw name string 1007 +--rw geo-location 1008 +--rw reference-frame 1009 | +--rw alternate-system? string 1010 | | {alternate-systems}? 1011 | +--rw astronomical-body? string 1012 | +--rw geodetic-system 1013 | +--rw geodetic-datum? string 1014 | +--rw coord-accuracy? decimal64 1015 | +--rw height-accuracy? decimal64 1016 +--rw (location)? 1017 | +--:(ellipsoid) 1018 | | +--rw latitude? decimal64 1019 | | +--rw longitude? decimal64 1020 | | +--rw height? decimal64 1021 | +--:(cartesian) 1022 | +--rw x? decimal64 1023 | +--rw y? decimal64 1024 | +--rw z? decimal64 1025 +--rw velocity 1026 | +--rw v-north? decimal64 1027 | +--rw v-east? decimal64 1028 | +--rw v-up? decimal64 1029 +--rw timestamp? yang:date-and-time 1030 +--rw valid-until? yang:date-and-time 1032 Below is some example YANG XML data for the fictitious module that 1033 uses the geo-location grouping. 1035 1036 1037 Gaetana's 1038 1039 40.73297 1040 -74.007696 1041 1042 1043 1044 Pont des Arts 1045 1046 2012-03-31T16:00:00Z 1047 48.8583424 1048 2.3375084 1049 35 1050 1052 1053 1054 Saint Louis Cathedral 1055 1056 2013-10-12T15:00:00-06:00 1057 29.9579735 1058 -90.0637281 1059 1060 1061 1062 Apollo 11 Landing Site 1063 1064 1969-07-21T02:56:15Z 1065 1066 moon 1067 1068 me 1069 1070 1071 0.67409 1072 23.47298 1073 1074 1075 1076 Reference Frame Only 1077 1078 1079 moon 1080 1081 me 1082 1083 1084 1085 1086 1088 Figure 3: Example XML data of geo location use. 1090 Appendix B. Acknowledgments 1092 We would like to thank Jim Biard and Ben Koziol for their reviews and 1093 suggested improvements. We would also like to thank Peter Lothberg 1094 for the motivation as well as help in defining a broadly useful 1095 geographic location object, and Acee Lindem and Qin Wu for their work 1096 on a geographic location object that led to this documents' creation. 1097 We would also like to thank the document shepherd Kent Watsen. 1099 Author's Address 1101 Christian Hopps 1102 LabN Consulting, L.L.C. 1104 Email: chopps@chopps.org