diff options
Diffstat (limited to 'doc/rfc/rfc9179.txt')
| -rw-r--r-- | doc/rfc/rfc9179.txt | 1126 |
1 files changed, 1126 insertions, 0 deletions
diff --git a/doc/rfc/rfc9179.txt b/doc/rfc/rfc9179.txt new file mode 100644 index 0000000..7d7007a --- /dev/null +++ b/doc/rfc/rfc9179.txt @@ -0,0 +1,1126 @@ + + + + +Internet Engineering Task Force (IETF) C. Hopps +Request for Comments: 9179 LabN Consulting, L.L.C. +Category: Standards Track February 2022 +ISSN: 2070-1721 + + + A YANG Grouping for Geographic Locations + +Abstract + + This document defines a generic geographical location YANG grouping. + The geographical location grouping is intended to be used in YANG + data models for specifying a location on or in reference to Earth or + any other astronomical object. + +Status of This Memo + + This is an Internet Standards Track document. + + This document is a product of the Internet Engineering Task Force + (IETF). It represents the consensus of the IETF community. It has + received public review and has been approved for publication by the + Internet Engineering Steering Group (IESG). Further information on + Internet Standards is available in Section 2 of RFC 7841. + + Information about the current status of this document, any errata, + and how to provide feedback on it may be obtained at + https://www.rfc-editor.org/info/rfc9179. + +Copyright Notice + + Copyright (c) 2022 IETF Trust and the persons identified as the + document authors. All rights reserved. + + This document is subject to BCP 78 and the IETF Trust's Legal + Provisions Relating to IETF Documents + (https://trustee.ietf.org/license-info) in effect on the date of + publication of this document. Please review these documents + carefully, as they describe your rights and restrictions with respect + to this document. Code Components extracted from this document must + include Revised BSD License text as described in Section 4.e of the + Trust Legal Provisions and are provided without warranty as described + in the Revised BSD License. + +Table of Contents + + 1. Introduction + 1.1. Terminology + 2. The Geolocation Object + 2.1. Frame of Reference + 2.2. Location + 2.3. Motion + 2.4. Nested Locations + 2.5. Non-location Attributes + 2.6. Tree + 3. YANG Module + 4. ISO 6709:2008 Conformance + 5. Usability + 5.1. Portability + 5.1.1. IETF URI Value + 5.1.2. W3C + 5.1.3. Geography Markup Language (GML) + 5.1.4. KML + 6. IANA Considerations + 6.1. Geodetic System Values Registry + 6.2. Updates to the IETF XML Registry + 6.3. Updates to the YANG Module Names Registry + 7. Security Considerations + 8. Normative References + 9. Informative References + Appendix A. Examples + Acknowledgments + Author's Address + +1. Introduction + + In many applications, we would like to specify the location of + something geographically. Some examples of locations in networking + might be the location of data centers, a rack in an Internet exchange + point, a router, a firewall, a port on some device, or it could be + the endpoints of a fiber, or perhaps the failure point along a fiber. + + Additionally, while this location is typically relative to Earth, it + does not need to be. Indeed, it is easy to imagine a network or + device located on the Moon, on Mars, on Enceladus (the moon of + Saturn), or even on a comet (e.g., 67p/churyumov-gerasimenko). + + Finally, one can imagine defining locations using different frames of + reference or even alternate systems (e.g., simulations or virtual + realities). + + This document defines a 'geo-location' YANG grouping that allows for + all the above data to be captured. + + This specification conforms to [ISO.6709.2008]. + + The YANG data model described in this document conforms to the + Network Management Datastore Architecture (NMDA) defined in + [RFC8342]. + +1.1. Terminology + + The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and + "OPTIONAL" in this document are to be interpreted as described in + BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all + capitals, as shown here. + +2. The Geolocation Object + +2.1. Frame of Reference + + The frame of reference ('reference-frame') defines what the location + values refer to and their meaning. The referred-to object can be any + astronomical body. It could be a planet such as Earth or Mars, a + moon such as Enceladus, an asteroid such as Ceres, or even a comet + such as 1P/Halley. This value is specified in 'astronomical-body' + and is defined by the International Astronomical Union + <http://www.iau.org>. The default 'astronomical-body' value is + 'earth'. + + In addition to identifying the astronomical body, we also need to + define the meaning of the coordinates (e.g., latitude and longitude) + and the definition of 0-height. This is done with a 'geodetic-datum' + value. The default value for 'geodetic-datum' is 'wgs-84' (i.e., the + World Geodetic System [WGS84]), which is used by the Global + Positioning System (GPS) among many others. We define an IANA + registry for specifying standard values for the 'geodetic-datum'. + + In addition to the 'geodetic-datum' value, we allow overriding the + coordinate and height accuracy using 'coord-accuracy' and 'height- + accuracy', respectively. When specified, these values override the + defaults implied by the 'geodetic-datum' value. + + Finally, we define an optional feature that allows for changing the + system for which the above values are defined. This optional feature + adds an 'alternate-system' value to the reference frame. This value + is normally not present, which implies the natural universe is the + system. The use of this value is intended to allow for creating + virtual realities or perhaps alternate coordinate systems. The + definition of alternate systems is outside the scope of this + document. + +2.2. Location + + This is the location on, or relative to, the astronomical object. It + is specified using two or three coordinate values. These values are + given either as 'latitude', 'longitude', and an optional 'height', or + as Cartesian coordinates of 'x', 'y', and 'z'. For the standard + location choice, 'latitude' and 'longitude' are specified as decimal + degrees, and the 'height' value is in fractions of meters. For the + Cartesian choice, 'x', 'y', and 'z' are in fractions of meters. In + both choices, the exact meanings of all the values are defined by the + 'geodetic-datum' value in Section 2.1. + +2.3. Motion + + Support is added for objects in relatively stable motion. For + objects in relatively stable motion, the grouping provides a three- + dimensional vector value. The components of the vector are + 'v-north', 'v-east', and 'v-up', which are all given in fractional + meters per second. The values 'v-north' and 'v-east' are relative to + true north as defined by the reference frame for the astronomical + body; 'v-up' is perpendicular to the plane defined by 'v-north' and + 'v-east', and is pointed away from the center of mass. + + To derive the two-dimensional heading and speed, one would use the + following formulas: + + ,------------------------------ + speed = V v_{north}^{2} + v_{east}^{2} + + heading = arctan(v_{east} / v_{north}) + + For some applications that demand high accuracy and where the data is + infrequently updated, this velocity vector can track very slow + movement such as continental drift. + + Tracking more complex forms of motion is outside the scope of this + work. The intent of the grouping being defined here is to identify + where something is located, and generally this is expected to be + somewhere on, or relative to, Earth (or another astronomical body). + At least two options are available to YANG data models that wish to + use this grouping with objects that are changing location frequently + in non-simple ways. A data model can either add additional motion + data to its model directly, or if the application allows, it can + require more frequent queries to keep the location data current. + +2.4. Nested Locations + + When locations are nested (e.g., a building may have a location that + houses routers that also have locations), the module using this + grouping is free to indicate in its definition that the 'reference- + frame' is inherited from the containing object so that the + 'reference-frame' need not be repeated in every instance of location + data. + +2.5. Non-location Attributes + + During the development of this module, the question of whether it + would support data such as orientation arose. These types of + attributes are outside the scope of this grouping because they do not + deal with a location but rather describe something more about the + object that is at the location. Module authors are free to add these + non-location attributes along with their use of this location + grouping. + +2.6. Tree + + The following is the YANG tree diagram [RFC8340] for the geo-location + grouping. + + module: ietf-geo-location + grouping geo-location: + +-- geo-location + +-- reference-frame + | +-- alternate-system? string {alternate-systems}? + | +-- astronomical-body? string + | +-- geodetic-system + | +-- geodetic-datum? string + | +-- coord-accuracy? decimal64 + | +-- height-accuracy? decimal64 + +-- (location)? + | +--:(ellipsoid) + | | +-- latitude? decimal64 + | | +-- longitude? decimal64 + | | +-- height? decimal64 + | +--:(cartesian) + | +-- x? decimal64 + | +-- y? decimal64 + | +-- z? decimal64 + +-- velocity + | +-- v-north? decimal64 + | +-- v-east? decimal64 + | +-- v-up? decimal64 + +-- timestamp? yang:date-and-time + +-- valid-until? yang:date-and-time + +3. YANG Module + + This model imports Common YANG Data Types [RFC6991]. It uses YANG + version 1.1 [RFC7950]. + + <CODE BEGINS> file "ietf-geo-location@2022-02-11.yang" + module ietf-geo-location { + yang-version 1.1; + namespace "urn:ietf:params:xml:ns:yang:ietf-geo-location"; + prefix geo; + import ietf-yang-types { + prefix yang; + reference "RFC 6991: Common YANG Data Types"; + } + + organization + "IETF NETMOD Working Group (NETMOD)"; + contact + "WG Web: <https://datatracker.ietf.org/wg/netmod/> + WG List: <mailto:netmod@ietf.org> + + Editor: Christian Hopps + <mailto:chopps@chopps.org>"; + + description + "This module defines a grouping of a container object for + specifying a location on or around an astronomical object (e.g., + 'earth'). + + The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL + NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'NOT RECOMMENDED', + 'MAY', and 'OPTIONAL' in this document are to be interpreted as + described in BCP 14 (RFC 2119) (RFC 8174) when, and only when, + they appear in all capitals, as shown here. + + Copyright (c) 2022 IETF Trust and the persons identified as + authors of the code. All rights reserved. + + Redistribution and use in source and binary forms, + with or without modification, is permitted pursuant to, + and subject to the license terms contained in, the + Revised BSD License set forth in Section 4.c of the + IETF Trust's Legal Provisions Relating to IETF Documents + (https://trustee.ietf.org/license-info). + + This version of this YANG module is part of RFC 9179 + (https://www.rfc-editor.org/info/rfc9179); see the RFC itself + for full legal notices."; + + revision 2022-02-11 { + description + "Initial Revision"; + reference + "RFC 9179: A YANG Grouping for Geographic Locations"; + } + + feature alternate-systems { + description + "This feature means the device supports specifying locations + using alternate systems for reference frames."; + } + + grouping geo-location { + description + "Grouping to identify a location on an astronomical object."; + + container geo-location { + description + "A location on an astronomical body (e.g., 'earth') + somewhere in a universe."; + + container reference-frame { + description + "The Frame of Reference for the location values."; + + leaf alternate-system { + if-feature "alternate-systems"; + type string; + description + "The system in which the astronomical body and + geodetic-datum is defined. Normally, this value is not + present and the system is the natural universe; however, + when present, this value allows for specifying alternate + systems (e.g., virtual realities). An alternate-system + modifies the definition (but not the type) of the other + values in the reference frame."; + } + leaf astronomical-body { + type string { + pattern '[ -@\[-\^_-~]*'; + } + default "earth"; + description + "An astronomical body as named by the International + Astronomical Union (IAU) or according to the alternate + system if specified. Examples include 'sun' (our star), + 'earth' (our planet), 'moon' (our moon), 'enceladus' (a + moon of Saturn), 'ceres' (an asteroid), and + '67p/churyumov-gerasimenko (a comet). The ASCII value + SHOULD have uppercase converted to lowercase and not + include control characters (i.e., values 32..64, and + 91..126). Any preceding 'the' in the name SHOULD NOT be + included."; + reference + "https://www.iau.org/"; + } + container geodetic-system { + description + "The geodetic system of the location data."; + leaf geodetic-datum { + type string { + pattern '[ -@\[-\^_-~]*'; + } + description + "A geodetic-datum defining the meaning of latitude, + longitude, and height. The default when the + astronomical body is 'earth' is 'wgs-84', which is + used by the Global Positioning System (GPS). The + ASCII value SHOULD have uppercase converted to + lowercase and not include control characters + (i.e., values 32..64, and 91..126). The IANA registry + further restricts the value by converting all spaces + (' ') to dashes ('-'). + The specification for the geodetic-datum indicates + how accurately it models the astronomical body in + question, both for the 'horizontal' + latitude/longitude coordinates and for height + coordinates."; + reference + "RFC 9179: A YANG Grouping for Geographic Locations, + Section 6.1"; + } + leaf coord-accuracy { + type decimal64 { + fraction-digits 6; + } + description + "The accuracy of the latitude/longitude pair for + ellipsoidal coordinates, or the X, Y, and Z components + for Cartesian coordinates. When coord-accuracy is + specified, it indicates how precisely the coordinates + in the associated list of locations have been + determined with respect to the coordinate system + defined by the geodetic-datum. For example, there + might be uncertainty due to measurement error if an + experimental measurement was made to determine each + location."; + } + leaf height-accuracy { + type decimal64 { + fraction-digits 6; + } + units "meters"; + description + "The accuracy of the height value for ellipsoidal + coordinates; this value is not used with Cartesian + coordinates. When height-accuracy is specified, it + indicates how precisely the heights in the + associated list of locations have been determined + with respect to the coordinate system defined by the + geodetic-datum. For example, there might be + uncertainty due to measurement error if an + experimental measurement was made to determine each + location."; + } + } + } + choice location { + description + "The location data either in latitude/longitude or + Cartesian values"; + case ellipsoid { + leaf latitude { + type decimal64 { + fraction-digits 16; + } + units "decimal degrees"; + description + "The latitude value on the astronomical body. The + definition and precision of this measurement is + indicated by the reference-frame."; + } + leaf longitude { + type decimal64 { + fraction-digits 16; + } + units "decimal degrees"; + description + "The longitude value on the astronomical body. The + definition and precision of this measurement is + indicated by the reference-frame."; + } + leaf height { + type decimal64 { + fraction-digits 6; + } + units "meters"; + description + "Height from a reference 0 value. The precision and + '0' value is defined by the reference-frame."; + } + } + case cartesian { + leaf x { + type decimal64 { + fraction-digits 6; + } + units "meters"; + description + "The X value as defined by the reference-frame."; + } + leaf y { + type decimal64 { + fraction-digits 6; + } + units "meters"; + description + "The Y value as defined by the reference-frame."; + } + leaf z { + type decimal64 { + fraction-digits 6; + } + units "meters"; + description + "The Z value as defined by the reference-frame."; + } + } + } + container velocity { + description + "If the object is in motion, the velocity vector describes + this motion at the time given by the timestamp. For a + formula to convert these values to speed and heading, see + RFC 9179."; + reference + "RFC 9179: A YANG Grouping for Geographic Locations"; + + leaf v-north { + type decimal64 { + fraction-digits 12; + } + units "meters per second"; + description + "v-north is the rate of change (i.e., speed) towards + true north as defined by the geodetic-system."; + } + + leaf v-east { + type decimal64 { + fraction-digits 12; + } + units "meters per second"; + description + "v-east is the rate of change (i.e., speed) perpendicular + to the right of true north as defined by + the geodetic-system."; + } + + leaf v-up { + type decimal64 { + fraction-digits 12; + } + units "meters per second"; + description + "v-up is the rate of change (i.e., speed) away from the + center of mass."; + } + } + leaf timestamp { + type yang:date-and-time; + description + "Reference time when location was recorded."; + } + leaf valid-until { + type yang:date-and-time; + description + "The timestamp for which this geo-location is valid until. + If unspecified, the geo-location has no specific + expiration time."; + } + } + } + } + <CODE ENDS> + +4. ISO 6709:2008 Conformance + + [ISO.6709.2008] provides an appendix with a set of tests for + conformance to the standard. The tests and results are given in the + following table along with an explanation of inapplicable tests. + + +=========+===========================+====================+ + | Test | Description | Pass Explanation | + +=========+===========================+====================+ + | A.1.2.1 | elements required for a | CRS is always | + | | geographic point location | indicated | + +---------+---------------------------+--------------------+ + | A.1.2.2 | description of a CRS from | CRS register is | + | | a register | defined | + +---------+---------------------------+--------------------+ + | A.1.2.3 | definition of CRS | N/A - Don't define | + | | | CRS | + +---------+---------------------------+--------------------+ + | A.1.2.4 | representation of | latitude/longitude | + | | horizontal position | values conform | + +---------+---------------------------+--------------------+ + | A.1.2.5 | representation of | height value | + | | vertical position | conforms | + +---------+---------------------------+--------------------+ + | A.1.2.6 | text string | N/A - No string | + | | representation | format | + +---------+---------------------------+--------------------+ + + Table 1: Conformance Test Results + + For test 'A.1.2.1', the YANG geo-location object either includes a + Coordinate Reference System (CRS) ('reference-frame') or has a + default defined [WGS84]. + + For 'A.1.2.3', we do not define our own CRS, and doing so is not + required for conformance. + + For 'A.1.2.6', we do not define a text string representation, which + is also not required for conformance. + +5. Usability + + The geo-location object defined in this document and YANG module has + been designed to be usable in a very broad set of applications. This + includes the ability to locate things on astronomical bodies other + than Earth, and to utilize entirely different coordinate systems and + realities. + +5.1. Portability + + In order to verify portability while developing this module, the + following standards and standard APIs were considered. + +5.1.1. IETF URI Value + + [RFC5870] defines a standard URI value for geographic location data. + It includes the ability to specify the 'geodetic-value' (it calls + this 'crs') with the default being 'wgs-84' [WGS84]. For the + location data, it allows two to three coordinates defined by the + 'crs' value. For accuracy, it has a single 'u' parameter for + specifying uncertainty. The 'u' value is in fractions of meters and + applies to all the location values. As the URI is a string, all + values are specified as strings and so are capable of as much + precision as required. + + URI values can be mapped to and from the YANG grouping with the + caveat that some loss of precision (in the extremes) may occur due to + the YANG grouping using decimal64 values rather than strings. + +5.1.2. W3C + + W3C defines a geolocation API in [W3CGEO]. We show a snippet of code + below that defines the geolocation data for this API. This is used + by many applications (e.g., Google Maps API). + + interface GeolocationPosition { + readonly attribute GeolocationCoordinates coords; + readonly attribute DOMTimeStamp timestamp; + }; + + interface GeolocationCoordinates { + readonly attribute double latitude; + readonly attribute double longitude; + readonly attribute double? altitude; + readonly attribute double accuracy; + readonly attribute double? altitudeAccuracy; + readonly attribute double? heading; + readonly attribute double? speed; + }; + + Figure 1: Snippet Showing Geolocation Definition + +5.1.2.1. Comparison with YANG Data Model + + +==================+==============+=================+=============+ + | Field | Type | YANG | Type | + +==================+==============+=================+=============+ + | accuracy | double | coord-accuracy | dec64 fr 6 | + +------------------+--------------+-----------------+-------------+ + | altitude | double | height | dec64 fr 6 | + +------------------+--------------+-----------------+-------------+ + | altitudeAccuracy | double | height-accuracy | dec64 fr 6 | + +------------------+--------------+-----------------+-------------+ + | heading | double | v-north, v-east | dec64 fr 12 | + +------------------+--------------+-----------------+-------------+ + | latitude | double | latitude | dec64 fr 16 | + +------------------+--------------+-----------------+-------------+ + | longitude | double | longitude | dec64 fr 16 | + +------------------+--------------+-----------------+-------------+ + | speed | double | v-north, v-east | dec64 fr 12 | + +------------------+--------------+-----------------+-------------+ + | timestamp | DOMTimeStamp | timestamp | string | + +------------------+--------------+-----------------+-------------+ + + Table 2 + + accuracy (double): Accuracy of 'latitude' and 'longitude' values in + meters. + + altitude (double): Optional height in meters above the [WGS84] + ellipsoid. + + altitudeAccuracy (double): Optional accuracy of 'altitude' value in + meters. + + heading (double): Optional direction in decimal degrees from true + north increasing clockwise. + + latitude, longitude (double): Standard latitude/longitude values in + decimal degrees. + + speed (double): Speed along the heading in meters per second. + + timestamp (DOMTimeStamp): Specifies milliseconds since the UNIX + Epoch in a 64-bit unsigned integer. The YANG data model defines + the timestamp with arbitrarily large precision by using a string + that encompasses all representable values of this timestamp value. + + W3C API values can be mapped to the YANG grouping with the caveat + that some loss of precision (in the extremes) may occur due to the + YANG grouping using decimal64 values rather than doubles. + + Conversely, only YANG values for Earth using the default 'wgs-84' + [WGS84] as the 'geodetic-datum' can be directly mapped to the W3C + values as W3C does not provide the extra features necessary to map + the broader set of values supported by the YANG grouping. + +5.1.3. Geography Markup Language (GML) + + ISO adopted the Geography Markup Language (GML) defined by OGC 07-036 + [OGC] as [ISO.19136.2007]. GML defines, among many other things, a + position type 'gml:pos', which is a sequence of 'double' values. + This sequence of values represents coordinates in a given CRS. The + CRS is either inherited from containing elements or directly + specified as attributes 'srsName' and optionally 'srsDimension' on + the 'gml:pos'. + + GML defines an Abstract CRS type from which Concrete CRS types are + derived. This allows for many types of CRS definitions. We are + concerned with the Geodetic CRS type, which can have either + ellipsoidal or Cartesian coordinates. We believe that other non- + Earth-based CRSs as well as virtual CRSs should also be representable + by the GML CRS types. + + Thus, GML 'gml:pos' values can be mapped directly to the YANG + grouping with the caveat that some loss of precision (in the + extremes) may occur due to the YANG grouping using decimal64 values + rather than doubles. + + Conversely, mapping YANG grouping values to GML is fully supported + for Earth-based geodetic systems. + + GML also defines an observation value in 'gml:Observation', which + includes a timestamp value 'gml:validTime' in addition to other + components such as 'gml:using', 'gml:target', and 'gml:resultOf'. + Only the timestamp is mappable to and from the YANG grouping. + Furthermore, 'gml:validTime' can either be an instantaneous measure + ('gml:TimeInstant') or a time period ('gml:TimePeriod'). The + instantaneous 'gml:TimeInstant' is mappable to and from the YANG + grouping 'timestamp' value, and values down to the resolution of + seconds for 'gml:TimePeriod' can be mapped using the 'valid-until' + node of the YANG grouping. + +5.1.4. KML + + KML 2.2 [KML22] (formerly Keyhole Markup Language) was submitted by + Google to the Open Geospatial Consortium + (https://www.opengeospatial.org/) and was adopted. The latest + version as of this writing is KML 2.3 [KML23]. This schema includes + geographic location data in some of its objects (e.g., 'kml:Point' or + 'kml:Camera' objects). This data is provided in string format and + corresponds to the values specified in [W3CGEO]. The timestamp value + is also specified as a string as in our YANG grouping. + + KML has some special handling for the height value that is useful for + visualization software, 'kml:altitudeMode'. The values for + 'kml:altitudeMode' include 'clampToGround', which indicates the + height is ignored; 'relativeToGround', which indicates the height + value is relative to the location's ground level; or 'absolute', + which indicates the height value is an absolute value within the + geodetic datum. The YANG grouping can directly map the ignored and + absolute cases but not the relative-to-ground case. + + In addition to the 'kml:altitudeMode', KML also defines two seafloor + height values using 'kml:seaFloorAltitudeMode'. One value is to + ignore the height value ('clampToSeaFloor') and the other is relative + ('relativeToSeaFloor'). As with the 'kml:altitudeMode' value, the + YANG grouping supports the ignore case but not the relative case. + + The KML location values use a geodetic datum defined in Annex A of + [ISO.19136.2007] with identifier 'LonLat84_5773'. The altitude value + for KML absolute height mode is measured from the vertical datum + specified by [WGS84]. + + Thus, the YANG grouping and KML values can be directly mapped in both + directions (when using a supported altitude mode) with the caveat + that some loss of precision (in the extremes) may occur due to the + YANG grouping using decimal64 values rather than strings. For the + relative height cases, the application doing the transformation is + expected to have the data available to transform the relative height + into an absolute height, which can then be expressed using the YANG + grouping. + +6. IANA Considerations + +6.1. Geodetic System Values Registry + + IANA has created the "Geodetic System Values" registry under the + "YANG Geographic Location Parameters" registry. + + This registry allocates names for standard geodetic systems. Often, + these values are referred to using multiple names (e.g., full names + or multiple acronyms). The intent of this registry is to provide a + single standard value for any given geodetic system. + + The values SHOULD use an acronym when available, they MUST be + converted to lowercase, and spaces MUST be changed to dashes "-". + + Each entry should be sufficient to define the two coordinate values + and to define height if height is required. So, for example, the + 'wgs-84' is defined as WGS-84 with the geoid updated by at least + [EGM96] for height values. Specific entries for [EGM96] and [EGM08] + are present if a more precise definition of the data is required. + + It should be noted that [RFC5870] also created a registry for + geodetic systems (the "'geo' URI 'crs' Parameter Values" registry); + however, this registry has a very strict modification policy. The + authors of [RFC5870] have the stated goal of making CRS registration + hard to avoid proliferation of CRS values. As our module defines + alternate systems and has a broader scope (i.e., beyond Earth), the + registry defined below is meant to be more easily modified. + + The allocation policy for this registry is First Come First Served + [RFC8126], as the intent is simply to avoid duplicate values. + + The Reference value can either be a document or a contact person as + defined in [RFC8126]. The Change Controller (i.e., Owner) is also + defined by [RFC8126]. + + The initial values for this registry are as follows. They include + the non-Earth-based geodetic-datum value for the Moon based on + [MEAN-EARTH]. + + +===========+==================+===========+===================+ + | Name | Description | Reference | Change Controller | + +===========+==================+===========+===================+ + | me | Mean Earth/Polar | RFC 9179 | IETF | + | | Axis (Moon) | | | + +-----------+------------------+-----------+-------------------+ + | wgs-84-96 | World Geodetic | RFC 9179 | IETF | + | | System 1984 | | | + +-----------+------------------+-----------+-------------------+ + | wgs-84-08 | World Geodetic | RFC 9179 | IETF | + | | System 1984 | | | + +-----------+------------------+-----------+-------------------+ + | wgs-84 | World Geodetic | RFC 9179 | IETF | + | | System 1984 | | | + +-----------+------------------+-----------+-------------------+ + + Table 3 + +6.2. Updates to the IETF XML Registry + + This document registers a URI in the "IETF XML Registry" [RFC3688]. + Following the format in [RFC3688], the following registration has + been made: + + URI: urn:ietf:params:xml:ns:yang:ietf-geo-location + Registrant Contact: The IESG. + XML: N/A; the requested URI is an XML namespace. + +6.3. Updates to the YANG Module Names Registry + + This document registers one YANG module in the "YANG Module Names" + registry [RFC6020]. Following the format in [RFC6020], the following + registration has been made: + + Name: ietf-geo-location + Maintained by IANA: N + Namespace: urn:ietf:params:xml:ns:yang:ietf-geo-location + Prefix: geo + Reference: RFC 9179 + +7. Security Considerations + + The YANG module specified in this document defines a schema for data + that is designed to be accessed via network management protocols such + as the Network Configuration Protocol (NETCONF) [RFC6241] or RESTCONF + [RFC8040]. The lowest NETCONF layer is the secure transport layer, + and the mandatory-to-implement secure transport is Secure Shell (SSH) + [RFC6242]. The lowest RESTCONF layer is HTTPS, and the mandatory-to- + implement secure transport is TLS [RFC8446]. + + The NETCONF access control model [RFC8341] provides the means to + restrict access for particular NETCONF or RESTCONF users to a + preconfigured subset of all available NETCONF or RESTCONF protocol + operations and content. + + Since the modules defined in this document only define groupings, + these considerations are primarily for the designers of other modules + that use these groupings. + + All the data nodes defined in this YANG module are + writable/creatable/deletable (i.e., "config true", which is the + default). + + None of the writable/creatable/deletable data nodes in the YANG + module defined in this document are by themselves considered more + sensitive or vulnerable than standard configuration. + + Some of the readable data nodes in this YANG module may be considered + sensitive or vulnerable in some network environments. It is thus + important to control read access (e.g., via get, get-config, or + notification) to these data nodes. + + Since the grouping defined in this module identifies locations, + authors using this grouping SHOULD consider any privacy issues that + may arise when the data is readable (e.g., customer device locations, + etc). + +8. Normative References + + [EGM08] Pavlis, N., Holmes, S., Kenyon, S., and J. Factor, "An + Earth Gravitational Model to Degree 2160: EGM08.", + Presented at the 2008 General Assembly of the European + Geosciences Union, Vienna, April 2008. + + [EGM96] Lemoine, F., Kenyon, S., Factor, J., Trimmer, R., Pavlis, + N., Chinn, D., Cox, C., Klosko, S., Luthcke, S., Torrence, + M., Wang, Y., Williamson, R., Pavlis, E., Rapp, R., and T. + Olson, "The Development of the Joint NASA GSFC and the + National Imagery and Mapping Agency (NIMA) Geopotential + Model EGM96.", NASA/TP-1998-206861, July 1998. + + [ISO.6709.2008] + International Organization for Standardization, "Standard + representation of geographic point location by + coordinates", ISO 6709:2008, 2008. + + [MEAN-EARTH] + NASA, "A Standardized Lunar Coordinate System for the + Lunar Reconnaissance Orbiter", Version 4, Goddard Space + Flight Center, May 2008. + + [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, + DOI 10.17487/RFC2119, March 1997, + <https://www.rfc-editor.org/info/rfc2119>. + + [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., + and A. Bierman, Ed., "Network Configuration Protocol + (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, + <https://www.rfc-editor.org/info/rfc6241>. + + [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure + Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011, + <https://www.rfc-editor.org/info/rfc6242>. + + [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types", + RFC 6991, DOI 10.17487/RFC6991, July 2013, + <https://www.rfc-editor.org/info/rfc6991>. + + [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF + Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, + <https://www.rfc-editor.org/info/rfc8040>. + + [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for + Writing an IANA Considerations Section in RFCs", BCP 26, + RFC 8126, DOI 10.17487/RFC8126, June 2017, + <https://www.rfc-editor.org/info/rfc8126>. + + [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC + 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, + May 2017, <https://www.rfc-editor.org/info/rfc8174>. + + [RFC8341] Bierman, A. and M. Bjorklund, "Network Configuration + Access Control Model", STD 91, RFC 8341, + DOI 10.17487/RFC8341, March 2018, + <https://www.rfc-editor.org/info/rfc8341>. + + [RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., + and R. Wilton, "Network Management Datastore Architecture + (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018, + <https://www.rfc-editor.org/info/rfc8342>. + + [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol + Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, + <https://www.rfc-editor.org/info/rfc8446>. + + [WGS84] National Imagery and Mapping Agency, "Department of + Defense World Geodetic System 1984", NIMA TR8350.2, Third + Edition, January 2000. + +9. Informative References + + [ISO.19136.2007] + International Organization for Standardization, + "Geographic information -- Geography Markup Language + (GML)", ISO 19136:2007. + + [KML22] Wilson, T., Ed., "OGC KML", Version 2.2, April 2008, + <https://portal.opengeospatial.org/ + files/?artifact_id=27810>. + + [KML23] Burggraf, D., Ed., "OGC KML", Version 2.3, August 2015, + <https://docs.opengeospatial.org/ + is/12-007r2/12-007r2.html>. + + [OGC] OpenGIS, "OpenGIS Geography Markup Language (GML) Encoding + Standard", Version: 3.2.1, OGC 07-036, August 2007, + <https://portal.ogc.org/files/?artifact_id=20509>. + + [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, + DOI 10.17487/RFC3688, January 2004, + <https://www.rfc-editor.org/info/rfc3688>. + + [RFC5870] Mayrhofer, A. and C. Spanring, "A Uniform Resource + Identifier for Geographic Locations ('geo' URI)", + RFC 5870, DOI 10.17487/RFC5870, June 2010, + <https://www.rfc-editor.org/info/rfc5870>. + + [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for + the Network Configuration Protocol (NETCONF)", RFC 6020, + DOI 10.17487/RFC6020, October 2010, + <https://www.rfc-editor.org/info/rfc6020>. + + [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", + RFC 7950, DOI 10.17487/RFC7950, August 2016, + <https://www.rfc-editor.org/info/rfc7950>. + + [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", + BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, + <https://www.rfc-editor.org/info/rfc8340>. + + [W3CGEO] Popescu, A., "Geolocation API Specification", 2nd Edition, + November 2016, <https://www.w3.org/TR/2016/REC- + geolocation-API-20161108/>. + +Appendix A. Examples + + Below is a fictitious module that uses the geo-location grouping. + + module example-uses-geo-location { + namespace + "urn:example:example-uses-geo-location"; + prefix ugeo; + import ietf-geo-location { prefix geo; } + organization "Empty Org"; + contact "Example Author <eauthor@example.com>"; + description + "Example use of geo-location"; + revision 2022-02-11 { reference "None"; } + container locatable-items { + description + "The container of locatable items"; + list locatable-item { + key name; + description + "A locatable item"; + leaf name { + type string; + description + "The name of locatable item"; + } + uses geo:geo-location; + } + } + } + + Figure 2: Example YANG Module Using Geolocation + + Below is the YANG tree for the fictitious module that uses the geo- + location grouping. + + module: example-uses-geo-location + +--rw locatable-items + +--rw locatable-item* [name] + +--rw name string + +--rw geo-location + +--rw reference-frame + | +--rw alternate-system? string + | | {alternate-systems}? + | +--rw astronomical-body? string + | +--rw geodetic-system + | +--rw geodetic-datum? string + | +--rw coord-accuracy? decimal64 + | +--rw height-accuracy? decimal64 + +--rw (location)? + | +--:(ellipsoid) + | | +--rw latitude? decimal64 + | | +--rw longitude? decimal64 + | | +--rw height? decimal64 + | +--:(cartesian) + | +--rw x? decimal64 + | +--rw y? decimal64 + | +--rw z? decimal64 + +--rw velocity + | +--rw v-north? decimal64 + | +--rw v-east? decimal64 + | +--rw v-up? decimal64 + +--rw timestamp? yang:date-and-time + +--rw valid-until? yang:date-and-time + + Figure 3: Example YANG Tree Using Geolocation + + Below is some example YANG XML data for the fictitious module that + uses the geo-location grouping. + + <locatable-items xmlns="urn:example:example-uses-geo-location"> + <locatable-item> + <name>Gaetana's</name> + <geo-location> + <latitude>40.73297</latitude> + <longitude>-74.007696</longitude> + </geo-location> + </locatable-item> + <locatable-item> + <name>Pont des Arts</name> + <geo-location> + <timestamp>2012-03-31T16:00:00Z</timestamp> + <latitude>48.8583424</latitude> + <longitude>2.3375084</longitude> + <height>35</height> + </geo-location> + </locatable-item> + <locatable-item> + <name>Saint Louis Cathedral</name> + <geo-location> + <timestamp>2013-10-12T15:00:00-06:00</timestamp> + <latitude>29.9579735</latitude> + <longitude>-90.0637281</longitude> + </geo-location> + </locatable-item> + <locatable-item> + <name>Apollo 11 Landing Site</name> + <geo-location> + <timestamp>1969-07-21T02:56:15Z</timestamp> + <reference-frame> + <astronomical-body>moon</astronomical-body> + <geodetic-system> + <geodetic-datum>me</geodetic-datum> + </geodetic-system> + </reference-frame> + <latitude>0.67409</latitude> + <longitude>23.47298</longitude> + </geo-location> + </locatable-item> + <locatable-item> + <name>Reference Frame Only</name> + <geo-location> + <reference-frame> + <astronomical-body>moon</astronomical-body> + <geodetic-system> + <geodetic-datum>me</geodetic-datum> + </geodetic-system> + </reference-frame> + </geo-location> + </locatable-item> + </locatable-items> + + Figure 4: Example XML Data of Geolocation Use + +Acknowledgments + + We would like to thank Jim Biard and Ben Koziol for their reviews and + suggested improvements. We would also like to thank Peter Lothberg + for the motivation as well as help in defining a broadly useful + geographic location object as well as Acee Lindem and Qin Wu for + their work on a geographic location object that led to this + document's creation. We would also like to thank the Document + Shepherd Kent Watsen. + +Author's Address + + Christian Hopps + LabN Consulting, L.L.C. + + Email: chopps@chopps.org |