idnits 2.17.1 draft-ietf-netmod-geo-location-06.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** There is 1 instance of too long lines in the document, the longest one being 1 character in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 800 has weird spacing: '... name ietf-...' == Line 802 has weird spacing: '...mespace urn:i...' == Line 804 has weird spacing: '... prefix geo...' -- The document date (2 December 2020) is 1240 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Possible downref: Non-RFC (?) normative reference: ref. 'EGM08' -- Possible downref: Non-RFC (?) normative reference: ref. 'EGM96' -- Possible downref: Non-RFC (?) normative reference: ref. 'WGS84' Summary: 1 error (**), 0 flaws (~~), 4 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 2 December 2020 5 Expires: 5 June 2021 7 A YANG Grouping for Geographic Locations 8 draft-ietf-netmod-geo-location-06 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 Earth 15 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 5 June 2021. 34 Copyright Notice 36 Copyright (c) 2020 IETF Trust and the persons identified as the 37 document authors. All rights reserved. 39 This document is subject to BCP 78 and the IETF Trust's Legal 40 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 41 license-info) in effect on the date of publication of this document. 42 Please review these documents carefully, as they describe your rights 43 and restrictions with respect to this document. Code Components 44 extracted from this document must include Simplified BSD License text 45 as described in Section 4.e of the Trust Legal Provisions and are 46 provided without warranty as described in the Simplified BSD License. 48 Table of Contents 50 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 51 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 52 2. The Geo Location Object . . . . . . . . . . . . . . . . . . . 3 53 2.1. Frame of Reference . . . . . . . . . . . . . . . . . . . 3 54 2.2. Location . . . . . . . . . . . . . . . . . . . . . . . . 4 55 2.3. Motion . . . . . . . . . . . . . . . . . . . . . . . . . 4 56 2.4. Nested Locations . . . . . . . . . . . . . . . . . . . . 5 57 2.5. Non-location Attributes . . . . . . . . . . . . . . . . . 5 58 2.6. Tree . . . . . . . . . . . . . . . . . . . . . . . . . . 5 59 3. YANG Module . . . . . . . . . . . . . . . . . . . . . . . . . 6 60 4. ISO 6709:2008 Conformance . . . . . . . . . . . . . . . . . . 12 61 5. Usability . . . . . . . . . . . . . . . . . . . . . . . . . . 12 62 5.1. Portability . . . . . . . . . . . . . . . . . . . . . . . 13 63 5.1.1. IETF URI Value . . . . . . . . . . . . . . . . . . . 13 64 5.1.2. W3C . . . . . . . . . . . . . . . . . . . . . . . . . 13 65 5.1.3. Geography Markup Language (GML) . . . . . . . . . . . 15 66 5.1.4. KML . . . . . . . . . . . . . . . . . . . . . . . . . 16 67 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 16 68 6.1. Geodetic System Values Registry . . . . . . . . . . . . . 16 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 . . . . . . . . . . . . . . . . . . . 18 72 8. Normative References . . . . . . . . . . . . . . . . . . . . 19 73 9. Informative References . . . . . . . . . . . . . . . . . . . 20 74 Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 21 75 Appendix B. Acknowledgments . . . . . . . . . . . . . . . . . . 24 76 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 24 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 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 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 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 "z". For the standard location 152 choice "latitude" and "longitude" are specified as fractions of 153 decimal degrees, and the "height" value is in fractions of meters. 154 For the Cartesian choice "x", "y" and "z" are in fractions of meters. 155 In both choices the exact meanings of all of the values are defined 156 by the "geodetic-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). At 185 least two options are available to YANG models that wish to use this 186 grouping with objects that are changing location frequently in non- 187 simple ways, they can add additional motion data to their model 188 directly, or if the application allows it can require more frequent 189 queries to keep the location data current. 191 2.4. Nested Locations 193 When locations are nested (e.g., a building may have a location which 194 houses routers that also have locations) the module using this 195 grouping is free to indicate in its definition that the "reference- 196 frame" is inherited from the containing object so that the 197 "reference-frame" need not be repeated in every instance of location 198 data. 200 2.5. Non-location Attributes 202 During the development of this module, the question of whether it 203 would support data such as orientation arose. These types of 204 attributes are outside the scope of this grouping because they do not 205 deal with a location but rather describe something more about the 206 object that is at the location. Module authors are free to add these 207 non-location attributes along with their use of this location 208 grouping. 210 2.6. Tree 212 The following is the YANG tree diagram [RFC8340] for the geo-location 213 grouping. 215 module: ietf-geo-location 216 grouping 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? decimal64 228 | | +-- longitude? decimal64 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? yang:date-and-time 239 +-- valid-until? yang:date-and-time 241 3. YANG Module 243 This model imports Common YANG Data Types [RFC6991]. It uses YANG 244 version 1.1 [RFC7950] 246 file "ietf-geo-location@2019-02-17.yang" 247 module ietf-geo-location { 248 yang-version 1.1; 249 namespace "urn:ietf:params:xml:ns:yang:ietf-geo-location"; 250 prefix geo; 251 import ietf-yang-types { 252 prefix yang; 253 reference "RFC 6991: Common YANG Data Types."; 254 } 256 organization 257 "IETF NETMOD Working Group (NETMOD)"; 258 contact 259 "Christian Hopps "; 261 // RFC Ed.: replace XXXX with actual RFC number or IANA reference 262 // and remove this note. 264 description 265 "This module defines a grouping of a container object for 266 specifying a location on or around an astronomical object (e.g., 267 'earth'). 269 Copyright (c) 2019 IETF Trust and the persons identified as 270 authors of the code. All rights reserved. 272 Redistribution and use in source and binary forms, with or 273 without modification, is permitted pursuant to, and subject to 274 the license terms contained in, the Simplified BSD License set 275 forth in Section 4.c of the IETF Trust's Legal Provisions 276 Relating to IETF Documents 277 (https://trustee.ietf.org/license-info). 279 This version of this YANG module is part of RFC XXXX 280 (https://www.rfc-editor.org/info/rfcXXXX); see the RFC itself 281 for full legal notices. 283 // RFC Ed.: replace XXXX with the actual RFC number or IANA 284 // reference and remove this note. 286 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL 287 NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'NOT RECOMMENDED', 288 'MAY', and 'OPTIONAL' in this document are to be interpreted as 289 described in BCP 14 (RFC 2119) (RFC 8174) when, and only when, 290 they appear in all capitals, as shown here."; 292 revision 2019-02-17 { 293 description "Initial Revision"; 294 reference "RFC XXXX: A YANG Grouping for Geographic Locations"; 295 } 297 feature alternate-systems { 298 description 299 "This feature means the device supports specifying locations 300 using alternate systems for reference frames."; 301 } 303 grouping geo-location { 304 description 305 "Grouping to identify a location on an astronomical object."; 307 container geo-location { 308 description 309 "A location on an astronomical body (e.g., 'earth') 310 somewhere in a universe."; 312 container reference-frame { 313 description 314 "The Frame of Reference for the location values."; 316 leaf alternate-system { 317 if-feature alternate-systems; 318 type string; 319 description 320 "The system in which the astronomical body and 321 geodetic-datum is defined. Normally, this value is not 322 present and the system is the natural universe; however, 323 when present this value allows for specifying alternate 324 systems (e.g., virtual realities). An alternate-system 325 modifies the definition (but not the type) of the other 326 values in the reference frame."; 327 } 328 leaf astronomical-body { 329 type string { 330 pattern '[ -@\[-\^_-~]*'; 331 } 332 default "earth"; 333 description 334 "An astronomical body as named by the International 335 Astronomical Union (IAU) or according to the alternate 336 system if specified. Examples include 'sun' (our star), 337 'earth' (our planet), 'moon' (our moon), 'enceladus' (a 338 moon of Saturn), 'ceres' (an asteroid), 339 '67p/churyumov-gerasimenko (a comet). The value should 340 be comprised of all lower case ASCII characters not 341 including control characters (i.e., values 32..64, and 342 91..126). Any preceding 'the' in the name should not be 343 included."; 344 reference "https://www.iau.org/"; 345 } 346 container geodetic-system { 347 description 348 "The geodetic system of the location data."; 349 leaf geodetic-datum { 350 type string { 351 pattern '[ -@\[-\^_-~]*'; 352 } 353 default "wgs-84"; 354 description 355 "A geodetic-datum defining the meaning of latitude, 356 longitude and height. The default is 'wgs-84' which is 357 used by the Global Positioning System (GPS). The value 358 SHOULD be comprised of all lower case ASCII characters 359 not including control characters (i.e., values 32..64, 360 and 91..126). The IANA registry further restricts the 361 value by converting all spaces (' ') to dashes ('-')"; 362 reference 363 "IANA XXXX YANG Geographic Location Parameters, 364 Geodetic System Values"; 365 } 366 leaf coord-accuracy { 367 type decimal64 { 368 fraction-digits 6; 369 } 370 description 371 "The accuracy of the latitude longitude pair for 372 ellipsoidal coordinates, or the X, Y and Z components 373 for Cartesian coordinates. When coord-accuracy is 374 specified it overrides the geodetic-datum implied 375 accuracy."; 376 } 377 leaf height-accuracy { 378 type decimal64 { 379 fraction-digits 6; 380 } 381 units "meters"; 382 description 383 "The accuracy of height value for ellipsoidal 384 coordinates, this value is not used with Cartesian 385 coordinates. When specified it overrides the 386 geodetic-datum implied default."; 387 } 388 } 389 } 390 choice location { 391 description 392 "The location data either in lat/long or Cartesian values"; 393 case ellipsoid { 394 leaf latitude { 395 type decimal64 { 396 fraction-digits 16; 397 } 398 units "decimal degrees"; 399 description 400 "The latitude value on the astronomical body. The 401 definition and precision of this measurement is 402 indicated by the reference-frame value."; 403 } 404 leaf longitude { 405 type decimal64 { 406 fraction-digits 16; 407 } 408 units "decimal degrees"; 409 description 410 "The longitude value on the astronomical body. The 411 definition and precision of this measurement is 412 indicated by the reference-frame."; 413 } 414 leaf height { 415 type decimal64 { 416 fraction-digits 6; 417 } 418 units "meters"; 419 description 420 "Height from a reference 0 value. The precision and '0' 421 value is defined by the reference-frame."; 422 } 423 } 424 case cartesian { 425 leaf x { 426 type decimal64 { 427 fraction-digits 6; 428 } 429 units "meters"; 430 description 431 "The X value as defined by the reference-frame."; 432 } 433 leaf y { 434 type decimal64 { 435 fraction-digits 6; 436 } 437 units "meters"; 438 description 439 "The Y value as defined by the reference-frame."; 440 } 441 leaf z { 442 type decimal64 { 443 fraction-digits 6; 444 } 445 units "meters"; 446 description 447 "The Z value as defined by the reference-frame."; 448 } 449 } 450 } 451 container velocity { 452 description 453 "If the object is in motion the velocity vector describes 454 this motion at the the time given by the timestamp. For a 455 formula to convert these values to speed and heading see 456 this modules defining document RFC XXXX."; 457 reference 458 "RFC XXXX: A YANG Grouping for Geographic Locations"; 460 leaf v-north { 461 type decimal64 { 462 fraction-digits 12; 463 } 464 units "meters per second"; 465 description 466 "v-north is the rate of change (i.e., speed) towards 467 truth north as defined by the geodetic-system."; 468 } 470 leaf v-east { 471 type decimal64 { 472 fraction-digits 12; 473 } 474 units "meters per second"; 475 description 476 "v-east is the rate of change (i.e., speed) perpendicular 477 to truth-north as defined by the geodetic-system."; 478 } 480 leaf v-up { 481 type decimal64 { 482 fraction-digits 12; 483 } 484 units "meters per second"; 485 description 486 "v-up is the rate of change (i.e., speed) away from the 487 center of mass."; 488 } 489 } 490 leaf timestamp { 491 type yang:date-and-time; 492 description "Reference time when location was recorded."; 493 } 494 leaf valid-until { 495 type yang:date-and-time; 496 description 497 "The timestamp for which this geo-location is valid until. 498 If unspecified the geo-location has no specific expiration 499 time."; 500 } 501 } 502 } 503 } 504 506 4. ISO 6709:2008 Conformance 508 [ISO.6709.2008] provides an appendix with a set of tests for 509 conformance to the standard. The tests and results are given in the 510 following table along with an explanation of non-applicable tests. 512 +---------+----------------------+------------------+ 513 | Test | Description | Pass Explanation | 514 +=========+======================+==================+ 515 | A.1.2.1 | elements reqd. for a | CRS is always | 516 | | geo. point location | indicated | 517 +---------+----------------------+------------------+ 518 | A.1.2.2 | Description of a CRS | CRS register is | 519 | | from a register | defined | 520 +---------+----------------------+------------------+ 521 | A.1.2.3 | definition of CRS | N/A - Don't | 522 | | | define CRS | 523 +---------+----------------------+------------------+ 524 | A.1.2.4 | representation of | lat/long values | 525 | | horizontal position | conform | 526 +---------+----------------------+------------------+ 527 | A.1.2.5 | representation of | height value | 528 | | vertical position | conforms | 529 +---------+----------------------+------------------+ 530 | A.1.2.6 | text string | N/A - No string | 531 | | representation | format | 532 +---------+----------------------+------------------+ 534 Table 1: Conformance Test Results 536 For test "A.1.2.1" the YANG geo location object either includes a CRS 537 ("reference-frame") or has a default defined ([WGS84]). 539 For "A.1.2.3" we do not define our own CRS, and doing so is not 540 required for conformance. 542 For "A.1.2.6" we do not define a text string representation, which is 543 also not required for conformance. 545 5. Usability 547 The geo-location object defined in this document and YANG module have 548 been designed to be usable in a very broad set of applications. This 549 includes the ability to locate things on astronomical bodies other 550 than Earth, and to utilize entirely different coordinate systems and 551 realities. 553 Many systems make use of geo-location data, and so it's important to 554 be able describe this data using this geo-location object defined in 555 this document. 557 5.1. Portability 559 In order to verify portability while developing this module the 560 following standards and standard APIs and were considered. 562 5.1.1. IETF URI Value 564 [RFC5870] defines a standard URI value for geographic location data. 565 It includes the ability to specify the "geodetic-value" (it calls 566 this "crs") with the default being "wgs-84" [WGS84]. For the 567 location data it allows 2 to 3 coordinates defined by the "crs" 568 value. For accuracy it has a single "u" parameter for specifying 569 uncertainty. The "u" value is in fractions of meters and applies to 570 all the location values. As the URI is a string, all values are 571 specifies as strings and so are capable of as much precision as 572 required. 574 URI values can be mapped to and from the YANG grouping, with the 575 caveat that some loss of precision (in the extremes) may occur due to 576 the YANG grouping using decimal64 values rather than strings. 578 5.1.2. W3C 580 W3C Defines a geo-location API in [W3CGEO]. We show a snippet of 581 code below which defines the geo-location data for this API. This is 582 used by many application (e.g., Google Maps API). 584 interface GeolocationPosition { 585 readonly attribute GeolocationCoordinates coords; 586 readonly attribute DOMTimeStamp timestamp; 587 }; 589 interface GeolocationCoordinates { 590 readonly attribute double latitude; 591 readonly attribute double longitude; 592 readonly attribute double? altitude; 593 readonly attribute double accuracy; 594 readonly attribute double? altitudeAccuracy; 596 readonly attribute double? speed; 597 }; 599 Figure 1: Snippet Showing Geo-Location Definition 601 5.1.2.1. Compare with YANG Model 603 +------------------+--------------+-----------------+-------------+ 604 | Field | Type | YANG | Type | 605 +==================+==============+=================+=============+ 606 | accuracy | double | coord-accuracy | dec64 fr 6 | 607 +------------------+--------------+-----------------+-------------+ 608 | altitude | double | height | dec64 fr 6 | 609 +------------------+--------------+-----------------+-------------+ 610 | altitudeAccuracy | double | height-accuracy | dec64 fr 6 | 611 +------------------+--------------+-----------------+-------------+ 612 | heading | double | v-north, v-east | dec64 fr 12 | 613 +------------------+--------------+-----------------+-------------+ 614 | latitude | double | latitude | dec64 fr 16 | 615 +------------------+--------------+-----------------+-------------+ 616 | longitude | double | longitude | dec64 fr 16 | 617 +------------------+--------------+-----------------+-------------+ 618 | speed | double | v-north, v-east | dec64 fr 12 | 619 +------------------+--------------+-----------------+-------------+ 620 | timestamp | DOMTimeStamp | timestamp | string | 621 +------------------+--------------+-----------------+-------------+ 623 Table 2 625 accuracy (double) Accuracy of "latitude" and "longitude" values in 626 meters. 628 altitude (double) Optional height in meters above the [WGS84] 629 ellipsoid. 631 altitudeAccuracy (double) Optional accuracy of "altitude" value in 632 meters. 634 heading (double) Optional Direction in decimal deg from true north 635 increasing clock-wise. 637 latitude, longitude (double) Standard lat/long values in decimal 638 degrees. 640 speed (double) Speed along heading in meters per second. 642 timestamp (DOMTimeStamp) Specifies milliseconds since the Unix EPOCH 643 in 64 bit unsigned integer. The YANG model defines the timestamp 644 with arbitrarily large precision by using a string which 645 encompasses all representable values of this timestamp value. 647 W3C API values can be mapped to the YANG grouping, with the caveat 648 that some loss of precision (in the extremes) may occur due to the 649 YANG grouping using decimal64 values rather than doubles. 651 Conversely, only YANG values for Earth using the default "wgs-84" 652 [WGS84] as the "geodetic-datum", can be directly mapped to the W3C 653 values, as W3C does not provide the extra features necessary to map 654 the broader set of values supported by the YANG grouping. 656 5.1.3. Geography Markup Language (GML) 658 ISO adopted the Geography Markup Language (GML) defined by OGC 07-036 659 as [ISO.19136.2007]. GML defines, among many other things, a 660 position type "gml:pos" which is a sequence of "double" values. This 661 sequence of values represent coordinates in a given CRS. The CRS is 662 either inherited from containing elements or directly specified as 663 attributes "srsName" and optionally "srsDimension" on the "gml:pos". 665 GML defines an Abstract CRS type which Concrete CRS types derive 666 from. This allows for many types of CRS definitions. We are 667 concerned with the Geodetic CRS type which can have either 668 ellipsoidal or Cartesian coordinates. We believe that other non- 669 Earth based CRS as well as virtual CRS should also be representable 670 by the GML CRS types as well. 672 Thus GML "gml:pos" values can be mapped directly to the YANG 673 grouping, with the caveat that some loss of precision (in the 674 extremes) may occur due to the YANG grouping using decimal64 values 675 rather than doubles. 677 Conversely, YANG grouping values can be mapped to GML as directly as 678 the GML CRS available definitions allow with a minimum of Earth-based 679 geodetic systems fully supported. 681 GML also defines an observation value in "gml:Observation" which 682 includes a timestamp value "gml:validTime" in addition to other 683 components such as "gml:using" "gml:target" and "gml:resultOf". Only 684 the timestamp is mappable to and from the YANG grouping. Furthermore 685 "gml:validTime" can either be an Instantaneous measure 686 ("gml:TimeInstant") or a time period ("gml:TimePeriod"). The 687 instantaneous "gml:TimeInstant" is mappable to and from the YANG 688 grouping "timestamp" value, and values down to the resolution of 689 seconds for "gml:TimePeriod" can be mapped using the "valid-until" 690 node of the YANG grouping. 692 5.1.4. KML 694 KML 2.2 [KML22] (formerly Keyhole Markup Language) was submitted by 695 Google to the Open Geospatial Consortium, 696 (https://www.opengeospatial.org/) and was adopted. The latest 697 version as of this writing is KML 2.3 [KML23]. This schema includes 698 geographic location data in some of its objects (e.g., "kml:Point" or 699 "kml:Camera" objects). This data is provided in string format and 700 corresponds to the [W3CGEO] values. The timestamp value is also 701 specified as a string as in our YANG grouping. 703 KML has some special handling for the height value useful for 704 visualization software, "kml:altitudeMode". These values for 705 "kml:altitudeMode" include indicating the height is ignored 706 ("clampToGround"), in relation to the location's ground level 707 ("relativeToGround"), or in relation to the geodetic datum 708 ("absolute"). The YANG grouping can directly map the ignored and 709 absolute cases, but not the relative to ground case. 711 In addition to the "kml:altitudeMode" KML also defines two seafloor 712 height values using "kml:seaFloorAltitudeMode". One value is to 713 ignore the height value ("clampToSeaFloor") and the other is relative 714 ("relativeToSeaFloor"). As with the "kml:altitudeMode" value, the 715 YANG grouping supports the ignore case but not the relative case. 717 The KML location values use a geodetic datum defined in Annex A by 718 the GML Coordinate Reference System (CRS) [ISO.19136.2007] with 719 identifier "LonLat84_5773". The altitude value for KML absolute 720 height mode is measured from the vertical datum specified by [WGS84]. 722 Thus the YANG grouping and KML values can be directly mapped in both 723 directions (when using a supported altitude mode) with the caveat 724 that some loss of precision (in the extremes) may occur due to the 725 YANG grouping using decimal64 values rather than strings. For the 726 relative height cases the application doing the transformation is 727 expected to have the data available to transform the relative height 728 into an absolute height which can then be expressed using the YANG 729 grouping. 731 6. IANA Considerations 733 6.1. Geodetic System Values Registry 735 IANA is asked to create a new registry "Geodetic System Values" under 736 a new protocol category group "YANG Geographic Location Parameters". 738 This registry allocates names for standard geodetic systems. Often 739 these values are referred to using multiple names (e.g., full names 740 or multiple acronyms values). The intent of this registry is to 741 provide a single standard value for any given geodetic system. 743 The values SHOULD use an acronym when available, they MUST be 744 converted to lower case, and spaces MUST be changed to dashes "-". 746 Each entry should be sufficient to define the 3 coordinate values (2 747 if height is not required). So for example the "wgs-84" is defined 748 as WGS-84 with the geoid updated by at least [EGM96] for height 749 values. Specific entries for [EGM96] and [EGM08] are present if a 750 more precise definition of the data is required. 752 It should be noted that [RFC5870] also creates a registry for 753 Geodetic Systems (it calls CRS); however, this registry has a very 754 strict modification policy. The authors of [RFC5870] have the stated 755 goal of making CRS registration hard to avoid proliferation of CRS 756 values. As our module defines alternate systems and has a broader 757 (beyond Earth) scope, the registry defined below is meant to be more 758 easily modified. 760 The allocation policy for this registry is First Come First Served, 761 [RFC8126] as the intent is simply to avoid duplicate values. 763 The initial values for this registry are as follows. 765 +------------+------------------------------------------------------+ 766 | Name | Description | 767 +============+======================================================+ 768 | me | Mean Earth/Polar Axis (Moon) | 769 +------------+------------------------------------------------------+ 770 | mola-vik-1 | MOLA Height, IAU Viking-1 PM (Mars) | 771 +------------+------------------------------------------------------+ 772 | wgs-84-96 | World Geodetic System 1984 [WGS84] w/ EGM96 | 773 +------------+------------------------------------------------------+ 774 | wgs-84-08 | World Geodetic System 1984 [WGS84] w/ [EGM08] | 775 +------------+------------------------------------------------------+ 776 | wgs-84 | World Geodetic System 1984 [WGS84] (EGM96 or | 777 | | better) | 778 +------------+------------------------------------------------------+ 780 Table 3 782 6.2. Updates to the IETF XML Registry 784 This document registers a URI in the "IETF XML Registry" [RFC3688]. 785 Following the format in [RFC3688], the following registration has 786 been made: 788 URI urn:ietf:params:xml:ns:yang:ietf-geo-location 790 Registrant Contact The IESG. 792 XML N/A; the requested URI is an XML namespace. 794 6.3. Updates to the YANG Module Names Registry 796 This document registers one YANG module in the "YANG Module Names" 797 registry [RFC6020]. Following the format in [RFC6020], the following 798 registration has been made: 800 name ietf-geo-location 802 namespace urn:ietf:params:xml:ns:yang:ietf-geo-location 804 prefix geo 806 reference RFC XXXX (RFC Ed.: replace XXXX with RFC number and remove 807 this note.) 809 7. Security Considerations 811 The YANG module specified in this document defines a schema for data 812 that is designed to be accessed via network management protocols such 813 as NETCONF [RFC6241] or RESTCONF [RFC8040]. The lowest NETCONF layer 814 is the secure transport layer, and the mandatory-to-implement secure 815 transport is Secure Shell (SSH) [RFC6242]. The lowest RESTCONF layer 816 is HTTPS, and the mandatory-to-implement secure transport is TLS 817 [RFC8446]. 819 The NETCONF access control model [RFC8341] provides the means to 820 restrict access for particular NETCONF or RESTCONF users to a 821 preconfigured subset of all available NETCONF or RESTCONF protocol 822 operations and content. 824 Since the modules defined in this document only define groupings, 825 these considerations are primarily for the designers of other modules 826 that use these groupings. 828 All of the data nodes defined in this YANG module are 829 writable/creatable/deletable (i.e., "config true", which is the 830 default). These data nodes may be considered sensitive or vulnerable 831 in some network environments. Write operations (e.g., edit-config) 832 to these data nodes without proper protection can have a negative 833 effect on network operations. These are the subtrees and data nodes 834 and their sensitivity/vulnerability: 836 None of the writable/creatable/deletable data nodes in the YANG 837 module defined in this document are by themselves considered more 838 sensitive or vulnerable then standard configuration. 840 Some of the readable data nodes in this YANG module may be considered 841 sensitive or vulnerable in some network environments. It is thus 842 important to control read access (e.g., via get, get-config, or 843 notification) to these data nodes. These are the subtrees and data 844 nodes and their sensitivity/vulnerability: 846 Since the grouping defined in this module identifies locations, 847 authors using this grouping SHOULD consider any privacy issues that 848 may arise when the data is readable. 850 This document does not define any RPC actions and hence this section 851 does not consider the security of RPCs. 853 8. Normative References 855 [EGM08] Pavlis, N.K., Holmes, S.A., Kenyon, S.C., and J.K. Factor, 856 "An Earth Gravitational Model to Degree 2160: EGM08.", 857 Presented at the 2008 General Assembly of the European 858 Geosciences Union, Vienna, Arpil13-18, 2008, 2008, 859 . 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, 870 . 872 [ISO.6709.2008] 873 International Organization for Standardization, "ISO 874 6709:2008 Standard representation of geographic point 875 location by coordinates.", 2008. 877 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 878 Requirement Levels", BCP 14, RFC 2119, 879 DOI 10.17487/RFC2119, March 1997, 880 . 882 [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types", 883 RFC 6991, DOI 10.17487/RFC6991, July 2013, 884 . 886 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 887 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 888 May 2017, . 890 [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for 891 Writing an IANA Considerations Section in RFCs", BCP 26, 892 RFC 8126, DOI 10.17487/RFC8126, June 2017, 893 . 895 [RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 896 and R. Wilton, "Network Management Datastore Architecture 897 (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018, 898 . 900 [WGS84] National Imagery and Mapping Agency., "National Imagery 901 and Mapping Agency Technical Report 8350.2, Third 902 Edition.", 3 January 2000, . 905 9. Informative References 907 [ISO.19136.2007] 908 International Organization for Standardization, "ISO 909 19136:2007 Geographic information -- Geography Markup 910 Language (GML)". 912 [KML22] Wilson, T., Ed., "OGC KML (Version 2.2)", 14 April 2008, 913 . 916 [KML23] Burggraf, D., Ed., "OGC KML 2.3", 4 August 2015, 917 . 920 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 921 DOI 10.17487/RFC3688, January 2004, 922 . 924 [RFC5870] Mayrhofer, A. and C. Spanring, "A Uniform Resource 925 Identifier for Geographic Locations ('geo' URI)", 926 RFC 5870, DOI 10.17487/RFC5870, June 2010, 927 . 929 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 930 the Network Configuration Protocol (NETCONF)", RFC 6020, 931 DOI 10.17487/RFC6020, October 2010, 932 . 934 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 935 and A. Bierman, Ed., "Network Configuration Protocol 936 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 937 . 939 [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure 940 Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011, 941 . 943 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 944 RFC 7950, DOI 10.17487/RFC7950, August 2016, 945 . 947 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 948 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 949 . 951 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 952 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 953 . 955 [RFC8341] Bierman, A. and M. Bjorklund, "Network Configuration 956 Access Control Model", STD 91, RFC 8341, 957 DOI 10.17487/RFC8341, March 2018, 958 . 960 [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol 961 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, 962 . 964 [W3CGEO] Popescu, A., "Geolocation API Specification", 8 November 965 2016, . 968 Appendix A. Examples 970 Below is a fictitious module that uses the geo-location grouping. 972 module example-uses-geo-location { 973 namespace 974 "urn:example:example-uses-geo-location"; 975 prefix ugeo; 976 import ietf-geo-location { prefix geo; } 977 organization "Empty Org"; 978 contact "Example Author "; 979 description "Example use of geo-location"; 980 revision 2019-02-02 { reference "None"; } 981 container locatable-items { 982 description "container of locatable items"; 983 list locatable-item { 984 key name; 985 description "A of locatable item"; 986 leaf name { 987 type string; 988 description "name of locatable item"; 989 } 990 uses geo:geo-location; 991 } 992 } 993 } 995 Figure 2: Example YANG module using geo location. 997 Below is a the YANG tree for the fictitious module that uses the geo- 998 location grouping. 1000 module: example-uses-geo-location 1001 +--rw locatable-items 1002 +--rw locatable-item* [name] 1003 +--rw name string 1004 +--rw geo-location 1005 +--rw reference-frame 1006 | +--rw alternate-system? string {alternate-systems}? 1007 | +--rw astronomical-body? string 1008 | +--rw geodetic-system 1009 | +--rw geodetic-datum? string 1010 | +--rw coord-accuracy? decimal64 1011 | +--rw height-accuracy? decimal64 1012 +--rw (location)? 1013 | +--:(ellipsoid) 1014 | | +--rw latitude? decimal64 1015 | | +--rw longitude? decimal64 1016 | | +--rw height? decimal64 1017 | +--:(cartesian) 1018 | +--rw x? decimal64 1019 | +--rw y? decimal64 1020 | +--rw z? decimal64 1021 +--rw velocity 1022 | +--rw v-north? decimal64 1023 | +--rw v-east? decimal64 1024 | +--rw v-up? decimal64 1025 +--rw timestamp? yang:date-and-time 1026 +--rw valid-until? yang:date-and-time 1028 Below is some example YANG XML data for the fictitious module that 1029 uses the geo-location grouping. 1031 1032 1033 Gaetana's 1034 1035 40.73297 1036 -74.007696 1037 1038 1039 1040 Pont des Arts 1041 1042 2012-03-31T16:00:00Z 1043 48.8583424 1044 2.3375084 1045 35 1046 1047 1048 1049 Saint Louis Cathedral 1050 1051 2013-10-12T15:00:00-06:00 1052 29.9579735 1053 -90.0637281 1054 1055 1056 1057 Apollo 11 Landing Site 1058 1059 1969-07-21T02:56:15Z 1060 1061 moon 1062 1063 me 1064 1065 1066 0.67409 1067 23.47298 1068 1069 1070 1071 Reference Frame Only 1072 1073 1074 moon 1075 1076 me 1077 1078 1079 1080 1081 1083 Figure 3: Example XML data of geo location use. 1085 Appendix B. Acknowledgments 1087 We would like to thank Jim Biard and Ben Koziol for their reviews and 1088 suggested improvements. We would also like to thank Peter Lothberg 1089 for the motivation as well as help in defining a broadly useful 1090 geographic location object, and Acee Lindem and Qin Wu for their work 1091 on a geographic location object that led to this documents creation. 1093 Author's Address 1094 Christian Hopps 1095 LabN Consulting, L.L.C. 1097 Email: chopps@chopps.org