idnits 2.17.1 draft-ietf-netmod-geo-location-07.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 805 has weird spacing: '... name ietf-...' == Line 807 has weird spacing: '...mespace urn:i...' == Line 809 has weird spacing: '... prefix geo...' -- The document date (3 December 2020) is 1233 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 3 December 2020 5 Expires: 6 June 2021 7 A YANG Grouping for Geographic Locations 8 draft-ietf-netmod-geo-location-07 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 6 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 . . . . . . . . . . . . . . . . . . . . . . . . . . 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 . . . . . . . . . . . . . . . . . . . 21 74 Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 22 75 Appendix B. Acknowledgments . . . . . . . . . . . . . . . . . . 25 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 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 "WG Web: 260 WG List: 262 Editor: Christian Hopps 263 "; 265 // RFC Ed.: replace XXXX with actual RFC number or IANA reference 266 // and remove this note. 268 description 269 "This module defines a grouping of a container object for 270 specifying a location on or around an astronomical object (e.g., 271 'earth'). 273 Copyright (c) 2019 IETF Trust and the persons identified as 274 authors of the code. All rights reserved. 276 Redistribution and use in source and binary forms, with or 277 without modification, is permitted pursuant to, and subject to 278 the license terms contained in, the Simplified BSD License set 279 forth in Section 4.c of the IETF Trust's Legal Provisions 280 Relating to IETF Documents 281 (https://trustee.ietf.org/license-info). 283 This version of this YANG module is part of RFC XXXX 284 (https://www.rfc-editor.org/info/rfcXXXX); see the RFC itself 285 for full legal notices. 287 // RFC Ed.: replace XXXX with the actual RFC number or IANA 288 // reference and remove this note. 290 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL 291 NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'NOT RECOMMENDED', 292 'MAY', and 'OPTIONAL' in this document are to be interpreted as 293 described in BCP 14 (RFC 2119) (RFC 8174) when, and only when, 294 they appear in all capitals, as shown here."; 296 revision 2019-02-17 { 297 description "Initial Revision"; 298 reference "RFC XXXX: A YANG Grouping for Geographic Locations"; 299 } 301 feature alternate-systems { 302 description 303 "This feature means the device supports specifying locations 304 using alternate systems for reference frames."; 305 } 307 grouping geo-location { 308 description 309 "Grouping to identify a location on an astronomical object."; 311 container geo-location { 312 description 313 "A location on an astronomical body (e.g., 'earth') 314 somewhere in a universe."; 316 container reference-frame { 317 description 318 "The Frame of Reference for the location values."; 320 leaf alternate-system { 321 if-feature alternate-systems; 322 type string; 323 description 324 "The system in which the astronomical body and 325 geodetic-datum is defined. Normally, this value is not 326 present and the system is the natural universe; however, 327 when present this value allows for specifying alternate 328 systems (e.g., virtual realities). An alternate-system 329 modifies the definition (but not the type) of the other 330 values in the reference frame."; 331 } 332 leaf astronomical-body { 333 type string { 334 pattern '[ -@\[-\^_-~]*'; 335 } 336 default "earth"; 337 description 338 "An astronomical body as named by the International 339 Astronomical Union (IAU) or according to the alternate 340 system if specified. Examples include 'sun' (our star), 341 'earth' (our planet), 'moon' (our moon), 'enceladus' (a 342 moon of Saturn), 'ceres' (an asteroid), 343 '67p/churyumov-gerasimenko (a comet). The value should 344 be comprised of all lower case ASCII characters not 345 including control characters (i.e., values 32..64, and 346 91..126). Any preceding 'the' in the name should not be 347 included."; 348 reference "https://www.iau.org/"; 349 } 350 container geodetic-system { 351 description 352 "The geodetic system of the location data."; 353 leaf geodetic-datum { 354 type string { 355 pattern '[ -@\[-\^_-~]*'; 356 } 357 default "wgs-84"; 358 description 359 "A geodetic-datum defining the meaning of latitude, 360 longitude and height. The default is 'wgs-84' which is 361 used by the Global Positioning System (GPS). The value 362 SHOULD be comprised of all lower case ASCII characters 363 not including control characters (i.e., values 32..64, 364 and 91..126). The IANA registry further restricts the 365 value by converting all spaces (' ') to dashes ('-')"; 366 reference 367 "IANA XXXX YANG Geographic Location Parameters, 368 Geodetic System Values"; 369 } 370 leaf coord-accuracy { 371 type decimal64 { 372 fraction-digits 6; 373 } 374 description 375 "The accuracy of the latitude longitude pair for 376 ellipsoidal coordinates, or the X, Y and Z components 377 for Cartesian coordinates. When coord-accuracy is 378 specified it overrides the geodetic-datum implied 379 accuracy."; 380 } 381 leaf height-accuracy { 382 type decimal64 { 383 fraction-digits 6; 384 } 385 units "meters"; 386 description 387 "The accuracy of height value for ellipsoidal 388 coordinates, this value is not used with Cartesian 389 coordinates. When specified it overrides the 390 geodetic-datum implied default."; 391 } 392 } 393 } 394 choice location { 395 description 396 "The location data either in lat/long or Cartesian values"; 397 case ellipsoid { 398 leaf latitude { 399 type decimal64 { 400 fraction-digits 16; 401 } 402 units "decimal degrees"; 403 description 404 "The latitude value on the astronomical body. The 405 definition and precision of this measurement is 406 indicated by the reference-frame value."; 408 } 409 leaf longitude { 410 type decimal64 { 411 fraction-digits 16; 412 } 413 units "decimal degrees"; 414 description 415 "The longitude value on the astronomical body. The 416 definition and precision of this measurement is 417 indicated by the reference-frame."; 418 } 419 leaf height { 420 type decimal64 { 421 fraction-digits 6; 422 } 423 units "meters"; 424 description 425 "Height from a reference 0 value. The precision and '0' 426 value is defined by the reference-frame."; 427 } 428 } 429 case cartesian { 430 leaf x { 431 type decimal64 { 432 fraction-digits 6; 433 } 434 units "meters"; 435 description 436 "The X value as defined by the reference-frame."; 437 } 438 leaf y { 439 type decimal64 { 440 fraction-digits 6; 441 } 442 units "meters"; 443 description 444 "The Y value as defined by the reference-frame."; 445 } 446 leaf z { 447 type decimal64 { 448 fraction-digits 6; 449 } 450 units "meters"; 451 description 452 "The Z value as defined by the reference-frame."; 453 } 454 } 455 } 456 container velocity { 457 description 458 "If the object is in motion the velocity vector describes 459 this motion at the the time given by the timestamp. For a 460 formula to convert these values to speed and heading see 461 this modules defining document RFC XXXX."; 462 reference 463 "RFC XXXX: A YANG Grouping for Geographic Locations"; 465 leaf v-north { 466 type decimal64 { 467 fraction-digits 12; 468 } 469 units "meters per second"; 470 description 471 "v-north is the rate of change (i.e., speed) towards 472 truth north as defined by the geodetic-system."; 473 } 475 leaf v-east { 476 type decimal64 { 477 fraction-digits 12; 478 } 479 units "meters per second"; 480 description 481 "v-east is the rate of change (i.e., speed) perpendicular 482 to truth-north as defined by the geodetic-system."; 483 } 485 leaf v-up { 486 type decimal64 { 487 fraction-digits 12; 488 } 489 units "meters per second"; 490 description 491 "v-up is the rate of change (i.e., speed) away from the 492 center of mass."; 493 } 494 } 495 leaf timestamp { 496 type yang:date-and-time; 497 description "Reference time when location was recorded."; 498 } 499 leaf valid-until { 500 type yang:date-and-time; 501 description 502 "The timestamp for which this geo-location is valid until. 503 If unspecified the geo-location has no specific expiration 504 time."; 505 } 506 } 507 } 508 } 509 511 4. ISO 6709:2008 Conformance 513 [ISO.6709.2008] provides an appendix with a set of tests for 514 conformance to the standard. The tests and results are given in the 515 following table along with an explanation of non-applicable tests. 517 +---------+----------------------+------------------+ 518 | Test | Description | Pass Explanation | 519 +=========+======================+==================+ 520 | A.1.2.1 | elements reqd. for a | CRS is always | 521 | | geo. point location | indicated | 522 +---------+----------------------+------------------+ 523 | A.1.2.2 | Description of a CRS | CRS register is | 524 | | from a register | defined | 525 +---------+----------------------+------------------+ 526 | A.1.2.3 | definition of CRS | N/A - Don't | 527 | | | define CRS | 528 +---------+----------------------+------------------+ 529 | A.1.2.4 | representation of | lat/long values | 530 | | horizontal position | conform | 531 +---------+----------------------+------------------+ 532 | A.1.2.5 | representation of | height value | 533 | | vertical position | conforms | 534 +---------+----------------------+------------------+ 535 | A.1.2.6 | text string | N/A - No string | 536 | | representation | format | 537 +---------+----------------------+------------------+ 539 Table 1: Conformance Test Results 541 For test "A.1.2.1" the YANG geo location object either includes a CRS 542 ("reference-frame") or has a default defined ([WGS84]). 544 For "A.1.2.3" we do not define our own CRS, and doing so is not 545 required for conformance. 547 For "A.1.2.6" we do not define a text string representation, which is 548 also not required for conformance. 550 5. Usability 552 The geo-location object defined in this document and YANG module have 553 been designed to be usable in a very broad set of applications. This 554 includes the ability to locate things on astronomical bodies other 555 than Earth, and to utilize entirely different coordinate systems and 556 realities. 558 Many systems make use of geo-location data, and so it's important to 559 be able describe this data using this geo-location object defined in 560 this document. 562 5.1. Portability 564 In order to verify portability while developing this module the 565 following standards and standard APIs and 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 specifies 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 application (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; 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 represent 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 as well. 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. Furthermore 690 "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 values). The intent of this registry is to 746 provide a 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 3 coordinate values (2 752 if height is not required). So for example the "wgs-84" is defined 753 as WGS-84 with the geoid updated by at least [EGM96] for height 754 values. Specific entries for [EGM96] and [EGM08] are present if a 755 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) | 774 +------------+------------------------------------------------------+ 775 | mola-vik-1 | MOLA Height, IAU Viking-1 PM (Mars) | 776 +------------+------------------------------------------------------+ 777 | wgs-84-96 | World Geodetic System 1984 [WGS84] w/ EGM96 | 778 +------------+------------------------------------------------------+ 779 | wgs-84-08 | World Geodetic System 1984 [WGS84] w/ [EGM08] | 780 +------------+------------------------------------------------------+ 781 | wgs-84 | World Geodetic System 1984 [WGS84] (EGM96 or | 782 | | better) | 783 +------------+------------------------------------------------------+ 785 Table 3 787 6.2. Updates to the IETF XML Registry 789 This document registers a URI in the "IETF XML Registry" [RFC3688]. 790 Following the format in [RFC3688], the following registration has 791 been made: 793 URI urn:ietf:params:xml:ns:yang:ietf-geo-location 795 Registrant Contact The IESG. 797 XML N/A; the requested URI is an XML namespace. 799 6.3. Updates to the YANG Module Names Registry 801 This document registers one YANG module in the "YANG Module Names" 802 registry [RFC6020]. Following the format in [RFC6020], the following 803 registration has been made: 805 name ietf-geo-location 807 namespace urn:ietf:params:xml:ns:yang:ietf-geo-location 809 prefix geo 811 reference RFC XXXX (RFC Ed.: replace XXXX with RFC number and remove 812 this note.) 814 7. Security Considerations 816 The YANG module specified in this document defines a schema for data 817 that is designed to be accessed via network management protocols such 818 as NETCONF [RFC6241] or RESTCONF [RFC8040]. The lowest NETCONF layer 819 is the secure transport layer, and the mandatory-to-implement secure 820 transport is Secure Shell (SSH) [RFC6242]. The lowest RESTCONF layer 821 is HTTPS, and the mandatory-to-implement secure transport is TLS 822 [RFC8446]. 824 The NETCONF access control model [RFC8341] provides the means to 825 restrict access for particular NETCONF or RESTCONF users to a 826 preconfigured subset of all available NETCONF or RESTCONF protocol 827 operations and content. 829 Since the modules defined in this document only define groupings, 830 these considerations are primarily for the designers of other modules 831 that use these groupings. 833 All of the data nodes defined in this YANG module are 834 writable/creatable/deletable (i.e., "config true", which is the 835 default). These data nodes may be considered sensitive or vulnerable 836 in some network environments. Write operations (e.g., edit-config) 837 to these data nodes without proper protection can have a negative 838 effect on network operations. These are the subtrees and data nodes 839 and their sensitivity/vulnerability: 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 then 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. These are the subtrees and data 849 nodes and their sensitivity/vulnerability: 851 Since the grouping defined in this module identifies locations, 852 authors using this grouping SHOULD consider any privacy issues that 853 may arise when the data is readable. 855 This document does not define any RPC actions and hence this section 856 does not consider the security of RPCs. 858 8. Normative References 860 [EGM08] Pavlis, N.K., Holmes, S.A., Kenyon, S.C., and J.K. Factor, 861 "An Earth Gravitational Model to Degree 2160: EGM08.", 862 Presented at the 2008 General Assembly of the European 863 Geosciences Union, Vienna, Arpil13-18, 2008, 2008, 864 . 867 [EGM96] Lemoine, F.G., Kenyon, S.C., Factor, J.K., Trimmer, R.G., 868 Pavlis, N.K., Chinn, D.S., Cox, C.M., Klosko, S.M., 869 Luthcke, S.B., Torrence, M.H., Wang, Y.M., Williamson, 870 R.G., Pavlis, E.C., Rapp, R.H., and T.R. Olson, "The 871 Development of the Joint NASA GSFC and the National 872 Imagery and Mapping Agency (NIMA) Geopotential Model 873 EGM96.", Technical Report NASA/TP-1998-206861, NASA, 874 Greenbelt., 1998, 875 . 877 [ISO.6709.2008] 878 International Organization for Standardization, "ISO 879 6709:2008 Standard representation of geographic point 880 location by coordinates.", 2008. 882 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 883 Requirement Levels", BCP 14, RFC 2119, 884 DOI 10.17487/RFC2119, March 1997, 885 . 887 [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types", 888 RFC 6991, DOI 10.17487/RFC6991, July 2013, 889 . 891 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 892 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 893 May 2017, . 895 [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for 896 Writing an IANA Considerations Section in RFCs", BCP 26, 897 RFC 8126, DOI 10.17487/RFC8126, June 2017, 898 . 900 [RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 901 and R. Wilton, "Network Management Datastore Architecture 902 (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018, 903 . 905 [WGS84] National Imagery and Mapping Agency., "National Imagery 906 and Mapping Agency Technical Report 8350.2, Third 907 Edition.", 3 January 2000, . 910 9. Informative References 912 [ISO.19136.2007] 913 International Organization for Standardization, "ISO 914 19136:2007 Geographic information -- Geography Markup 915 Language (GML)". 917 [KML22] Wilson, T., Ed., "OGC KML (Version 2.2)", 14 April 2008, 918 . 921 [KML23] Burggraf, D., Ed., "OGC KML 2.3", 4 August 2015, 922 . 925 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 926 DOI 10.17487/RFC3688, January 2004, 927 . 929 [RFC5870] Mayrhofer, A. and C. Spanring, "A Uniform Resource 930 Identifier for Geographic Locations ('geo' URI)", 931 RFC 5870, DOI 10.17487/RFC5870, June 2010, 932 . 934 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 935 the Network Configuration Protocol (NETCONF)", RFC 6020, 936 DOI 10.17487/RFC6020, October 2010, 937 . 939 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 940 and A. Bierman, Ed., "Network Configuration Protocol 941 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 942 . 944 [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure 945 Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011, 946 . 948 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 949 RFC 7950, DOI 10.17487/RFC7950, August 2016, 950 . 952 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 953 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 954 . 956 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 957 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 958 . 960 [RFC8341] Bierman, A. and M. Bjorklund, "Network Configuration 961 Access Control Model", STD 91, RFC 8341, 962 DOI 10.17487/RFC8341, March 2018, 963 . 965 [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol 966 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, 967 . 969 [W3CGEO] Popescu, A., "Geolocation API Specification", 8 November 970 2016, . 973 Appendix A. Examples 975 Below is a fictitious module that uses the geo-location grouping. 977 module example-uses-geo-location { 978 namespace 979 "urn:example:example-uses-geo-location"; 980 prefix ugeo; 981 import ietf-geo-location { prefix geo; } 982 organization "Empty Org"; 983 contact "Example Author "; 984 description "Example use of geo-location"; 985 revision 2019-02-02 { reference "None"; } 986 container locatable-items { 987 description "container of locatable items"; 988 list locatable-item { 989 key name; 990 description "A of locatable item"; 991 leaf name { 992 type string; 993 description "name of locatable item"; 994 } 995 uses geo:geo-location; 996 } 997 } 998 } 999 Figure 2: Example YANG module using geo location. 1001 Below is a the YANG tree for the fictitious module that uses the geo- 1002 location grouping. 1004 module: example-uses-geo-location 1005 +--rw locatable-items 1006 +--rw locatable-item* [name] 1007 +--rw name string 1008 +--rw geo-location 1009 +--rw reference-frame 1010 | +--rw alternate-system? string {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 1051 1052 1053 Saint Louis Cathedral 1054 1055 2013-10-12T15:00:00-06:00 1056 29.9579735 1057 -90.0637281 1058 1059 1060 1061 Apollo 11 Landing Site 1062 1063 1969-07-21T02:56:15Z 1064 1065 moon 1066 1067 me 1068 1069 1070 0.67409 1071 23.47298 1072 1073 1074 1075 Reference Frame Only 1076 1077 1078 moon 1079 1080 me 1081 1082 1083 1084 1085 1087 Figure 3: Example XML data of geo location use. 1089 Appendix B. Acknowledgments 1091 We would like to thank Jim Biard and Ben Koziol for their reviews and 1092 suggested improvements. We would also like to thank Peter Lothberg 1093 for the motivation as well as help in defining a broadly useful 1094 geographic location object, and Acee Lindem and Qin Wu for their work 1095 on a geographic location object that led to this documents creation. 1097 Author's Address 1099 Christian Hopps 1100 LabN Consulting, L.L.C. 1102 Email: chopps@chopps.org