--- 1/draft-ietf-netmod-geo-location-07.txt 2021-04-16 15:13:16.348471060 -0700 +++ 2/draft-ietf-netmod-geo-location-08.txt 2021-04-16 15:13:16.400472367 -0700 @@ -1,18 +1,18 @@ Network Working Group C. Hopps Internet-Draft LabN Consulting, L.L.C. -Intended status: Standards Track 3 December 2020 -Expires: 6 June 2021 +Intended status: Standards Track 16 April 2021 +Expires: 18 October 2021 A YANG Grouping for Geographic Locations - draft-ietf-netmod-geo-location-07 + draft-ietf-netmod-geo-location-08 Abstract This document defines a generic geographical location object YANG grouping. The geographical location grouping is intended to be used in YANG models for specifying a location on or in reference to Earth or any other astronomical object. Status of This Memo @@ -22,25 +22,25 @@ Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at https://datatracker.ietf.org/drafts/current/. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." - This Internet-Draft will expire on 6 June 2021. + This Internet-Draft will expire on 18 October 2021. Copyright Notice - Copyright (c) 2020 IETF Trust and the persons identified as the + Copyright (c) 2021 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 Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. @@ -77,30 +77,30 @@ 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 center, 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 + 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 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 of the above data to be captured. + 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 defined in [RFC8342]. 1.1. Terminology The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and @@ -114,86 +114,87 @@ 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 + 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 refining the + In addition to the "geodetic-datum" value, we allow refining the coordinate and height accuracy using "coord-accuracy" and "height- - accuracy" respectively. When specified these values override the + accuracy" respectively. When specified, these values override the defaults implied by the "geodetic-datum" value. Finally, we define an optional feature which 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 + This is the location on, or relative to, the astronomical object. It is specified using 2 or 3 coordinates 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 fractions of 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 of the values are defined - by the "geodetic-datum" value in the Section 2.1. + In both choices the exact meanings of all the values are defined by + the "geodetic-datum" value in the 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 3-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 + 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 2-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 models that wish to use this - grouping with objects that are changing location frequently in non- - simple ways, they can add additional motion data to their model - directly, or if the application allows it can require more frequent - queries to keep the location data current. + somewhere on, or relative to, Earth (or another astronomical body). + + At least two options are available to YANG models that wish to use + this grouping with objects that are changing location frequently in + non-simple ways. They can add additional motion data to their 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 which 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. @@ -368,49 +369,49 @@ Geodetic System Values"; } 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 overrides the geodetic-datum implied + specified, it overrides the geodetic-datum implied accuracy."; } leaf height-accuracy { type decimal64 { fraction-digits 6; } units "meters"; description "The accuracy of height value for ellipsoidal coordinates, this value is not used with Cartesian - coordinates. When specified it overrides the + coordinates. When specified, it overrides the geodetic-datum implied default."; } } } choice location { description "The location data either in lat/long 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 value."; + 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 @@ -451,42 +452,43 @@ 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 the time given by the timestamp. For a formula to convert these values to speed and heading see - this modules defining document RFC XXXX."; + RFC XXXX."; reference "RFC XXXX: 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 truth 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 truth-north as defined by the geodetic-system."; + 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."; @@ -548,50 +551,46 @@ also not required for conformance. 5. Usability The geo-location object defined in this document and YANG module have 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. - Many systems make use of geo-location data, and so it's important to - be able describe this data using this geo-location object defined in - this document. - 5.1. Portability In order to verify portability while developing this module the following standards and standard APIs and 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 2 to 3 coordinates defined by the "crs" - value. For accuracy it has a single "u" parameter for specifying + 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 specifies 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 geo-location API in [W3CGEO]. We show a snippet of code below which defines the geo-location data for this API. This is - used by many application (e.g., Google Maps API). + 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; @@ -667,34 +666,34 @@ either inherited from containing elements or directly specified as attributes "srsName" and optionally "srsDimension" on the "gml:pos". GML defines an Abstract CRS type which Concrete CRS types derive from. 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 CRS as well as virtual CRS should also be representable by the GML CRS types as well. - Thus GML "gml:pos" values can be mapped directly to the YANG + 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, YANG grouping values can be mapped to GML as directly as the GML CRS available definitions allow with a minimum of Earth-based geodetic systems fully supported. 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 + 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, @@ -717,27 +716,27 @@ 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 by the GML Coordinate Reference System (CRS) [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 + 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 + 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 + into an absolute height, which can then be expressed using the YANG grouping. 6. IANA Considerations 6.1. Geodetic System Values Registry IANA is asked to create a new registry "Geodetic System Values" under a new protocol category group "YANG Geographic Location Parameters". This registry allocates names for standard geodetic systems. Often @@ -755,21 +754,21 @@ more precise definition of the data is required. It should be noted that [RFC5870] also creates a registry for Geodetic Systems (it calls CRS); 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 (beyond Earth) scope, the registry defined below is meant to be more easily modified. - The allocation policy for this registry is First Come First Served, + The allocation policy for this registry is First Come, First Served, [RFC8126] as the intent is simply to avoid duplicate values. The initial values for this registry are as follows. +------------+------------------------------------------------------+ | Name | Description | +============+======================================================+ | me | Mean Earth/Polar Axis (Moon) | +------------+------------------------------------------------------+ | mola-vik-1 | MOLA Height, IAU Viking-1 PM (Mars) | @@ -823,41 +822,42 @@ 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 of the data nodes defined in this YANG module are + All the data nodes defined in this YANG module are writable/creatable/deletable (i.e., "config true", which is the default). These data nodes may be considered sensitive or vulnerable in some network environments. Write operations (e.g., edit-config) to these data nodes without proper protection can have a negative effect on network operations. These are the subtrees and data nodes and their sensitivity/vulnerability: None of the writable/creatable/deletable data nodes in the YANG module defined in this document are by themselves considered more - sensitive or vulnerable then standard configuration. + 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. These are the subtrees and data nodes and their sensitivity/vulnerability: 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. + may arise when the data is readable (e.g., customer device locations, + etc). This document does not define any RPC actions and hence this section does not consider the security of RPCs. 8. Normative References [EGM08] Pavlis, N.K., Holmes, S.A., Kenyon, S.C., and J.K. Factor, "An Earth Gravitational Model to Degree 2160: EGM08.", Presented at the 2008 General Assembly of the European Geosciences Union, Vienna, Arpil13-18, 2008, 2008, @@ -991,21 +991,21 @@ leaf name { type string; description "name of locatable item"; } uses geo:geo-location; } } } Figure 2: Example YANG module using geo location. - Below is a the YANG tree for the fictitious module that uses the geo- + 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 @@ -1085,18 +1085,18 @@ Figure 3: Example XML data of geo location use. Appendix B. 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, and Acee Lindem and Qin Wu for their work - on a geographic location object that led to this documents creation. + on a geographic location object that led to this documents' creation. Author's Address Christian Hopps LabN Consulting, L.L.C. Email: chopps@chopps.org