A YANG Grouping for Geographic Locations
draft-ietf-netmod-geo-location-04
| The information below is for an old version of the document |
| Document |
Type |
|
Active Internet-Draft (netmod WG)
|
|
Author |
|
Christian Hopps
|
|
Last updated |
|
2020-06-08
(latest revision 2020-03-02)
|
|
Replaces |
|
draft-chopps-netmod-geo-location
|
|
Stream |
|
Internet Engineering Task Force (IETF)
|
|
Formats |
|
pdf
htmlized (tools)
htmlized
bibtex
|
|
Reviews |
|
|
| Stream |
WG state
|
|
In WG Last Call
Revised I-D Needed - Issue raised by WGLC
|
|
Document shepherd |
|
Kent Watsen
|
| IESG |
IESG state |
|
I-D Exists
|
|
Consensus Boilerplate |
|
Yes
|
|
Telechat date |
|
|
|
Responsible AD |
|
(None)
|
|
Send notices to |
|
Kent Watsen <kent+ietf@watsen.net>
|
Network Working Group C. Hopps
Internet-Draft LabN Consulting, L.L.C.
Intended status: Standards Track 1 March 2020
Expires: 2 September 2020
A YANG Grouping for Geographic Locations
draft-ietf-netmod-geo-location-04
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 the
Earth or any other astronomical object.
Status of This Memo
This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79.
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 2 September 2020.
Copyright Notice
Copyright (c) 2020 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.
Hopps Expires 2 September 2020 [Page 1]
Internet-Draft A YANG Grouping for Geographic Locations March 2020
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3
2. The Geo Location Object . . . . . . . . . . . . . . . . . . . 3
2.1. Frame of Reference . . . . . . . . . . . . . . . . . . . 3
2.2. Location . . . . . . . . . . . . . . . . . . . . . . . . 4
2.3. Motion . . . . . . . . . . . . . . . . . . . . . . . . . 4
2.4. Nested Locations . . . . . . . . . . . . . . . . . . . . 5
2.5. Non-location Attributes . . . . . . . . . . . . . . . . . 5
2.6. Tree . . . . . . . . . . . . . . . . . . . . . . . . . . 5
3. YANG Module . . . . . . . . . . . . . . . . . . . . . . . . . 6
4. ISO 6709:2008 Conformance . . . . . . . . . . . . . . . . . . 11
5. Usability . . . . . . . . . . . . . . . . . . . . . . . . . . 12
5.1. Portability . . . . . . . . . . . . . . . . . . . . . . . 13
5.1.1. IETF URI Value . . . . . . . . . . . . . . . . . . . 13
5.1.2. W3C . . . . . . . . . . . . . . . . . . . . . . . . . 13
5.1.3. Geography Markup Language (GML) . . . . . . . . . . . 15
5.1.4. KML . . . . . . . . . . . . . . . . . . . . . . . . . 16
6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 16
6.1. Geodetic System Value Registry . . . . . . . . . . . . . 16
7. Security Considerations . . . . . . . . . . . . . . . . . . . 17
8. Normative References . . . . . . . . . . . . . . . . . . . . 18
9. Informative References . . . . . . . . . . . . . . . . . . . 19
Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 19
Appendix B. Acknowledgements . . . . . . . . . . . . . . . . . . 22
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 22
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 The 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 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.
Hopps Expires 2 September 2020 [Page 2]
Internet-Draft A YANG Grouping for Geographic Locations March 2020
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
"OPTIONAL" in this document are to be interpreted as described in
[RFC2119] [RFC8174] when, and only when, they appear in all capitals,
as shown here.
2. The Geo Location 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 The 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 refining 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 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.
Hopps Expires 2 September 2020 [Page 3]
Internet-Draft A YANG Grouping for Geographic Locations March 2020
2.2. Location
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.
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
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 the 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.
Hopps Expires 2 September 2020 [Page 4]
Internet-Draft A YANG Grouping for Geographic Locations March 2020
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.
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.
Hopps Expires 2 September 2020 [Page 5]
Internet-Draft A YANG Grouping for Geographic Locations March 2020
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? types:date-and-time
+-- valid-until? types:date-and-time
3. YANG Module
<CODE BEGINS> file "ietf-geo-location@2019-02-17.yang"
module ietf-geo-location {
namespace "urn:ietf:params:xml:ns:yang:ietf-geo-location";
prefix geo;
import ietf-yang-types { prefix types; }
organization
"IETF NETMOD Working Group (NETMOD)";
contact
"Christian Hopps <chopps@chopps.org>";
// RFC Ed.: replace XXXX with actual RFC number and
// remove this note.
description
"This module defines a grouping of a container object for
specifying a location on or around an astronomical object (e.g.,
The Earth).
Copyright (c) 2019 IETF Trust and the persons identified as
Hopps Expires 2 September 2020 [Page 6]
Internet-Draft A YANG Grouping for Geographic Locations March 2020
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 Simplified 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 XXXX
(https://www.rfc-editor.org/info/rfcXXXX); see the RFC itself
for full legal notices.
// RFC Ed.: replace XXXX with actual RFC number and
// remove this note.
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.";
revision 2019-02-17 {
description "Initial Revision";
reference "RFC XXXX: YANG Geo Location";
}
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., The Earth)
somewhere in a universe.";
container reference-frame {
description
"The Frame of Reference for the location values.";
leaf alternate-system {
if-feature alternate-systems;
Hopps Expires 2 September 2020 [Page 7]
Internet-Draft A YANG Grouping for Geographic Locations March 2020
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),
'67p/churyumov-gerasimenko (a comet). The value should
be comprised of all lower case ASCII characters not
including control characters (i.e., values 32..64, and
91..126). Any preceding 'the' in the name should not be
included.";
}
container geodetic-system {
description
"The geodetic system of the location data.";
leaf geodetic-datum {
type string {
pattern '[ -@\[-\^_-~]*';
}
default "wgs-84";
description
"A geodetic-datum defining the meaning of latitude,
longitude and height. The default is 'wgs-84' which is
used by the Global Positioning System (GPS). The value
SHOULD be comprised of all lower case ASCII characters
not including control characters (i.e., values 32..64,
and 91..126). The IANA registry further restricts the
value by converting all spaces (' ') to dashes ('-')";
}
leaf coord-accuracy {
type decimal64 {
fraction-digits 6;
}
Hopps Expires 2 September 2020 [Page 8]
Internet-Draft A YANG Grouping for Geographic Locations March 2020
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
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
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.";
}
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;
}
Hopps Expires 2 September 2020 [Page 9]
Internet-Draft A YANG Grouping for Geographic Locations March 2020
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 the time given by the timestamp";
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~.";
}
Hopps Expires 2 September 2020 [Page 10]
Internet-Draft A YANG Grouping for Geographic Locations March 2020
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~.";
}
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 types:date-and-time;
description "Reference time when location was recorded.";
}
leaf valid-until {
type types: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 non-applicable tests.
Hopps Expires 2 September 2020 [Page 11]
Internet-Draft A YANG Grouping for Geographic Locations March 2020
+---------+----------------------+------------------+
| Test | Description | Pass Explanation |
+=========+======================+==================+
| A.1.2.1 | elements reqd. for a | CRS is always |
| | geo. point location | indicated |
+---------+----------------------+------------------+
| A.1.2.2 | Description of a CRS | CRS register is |
| | from a register | defined |
+---------+----------------------+------------------+
| A.1.2.3 | definition of CRS | N/A - Don't |
| | | define CRS |
+---------+----------------------+------------------+
| A.1.2.4 | representation of | lat/long values |
| | horizontal position | 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 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 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 The 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.
Hopps Expires 2 September 2020 [Page 12]
Internet-Draft A YANG Grouping for Geographic Locations March 2020
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
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).
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? speed;
};
Figure 1: Snippet Showing Geo-Location Definition
Hopps Expires 2 September 2020 [Page 13]
Internet-Draft A YANG Grouping for Geographic Locations March 2020
5.1.2.1. Compare with YANG 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 deg from true north
increasing clock-wise.
latitude, longitude (double) Standard lat/long values in decimal
degrees.
speed (double) Speed along heading in meters per second.
timestamp (DOMTimeStamp) Specifies milliseconds since the Unix EPOCH
in 64 bit unsigned integer. The YANG model defines the timestamp
with arbitrarily large precision by using a string which
encompasses all representable values of this timestamp value.
W3C API values can be mapped to the YANG grouping, with the caveat
Hopps Expires 2 September 2020 [Page 14]
Internet-Draft A YANG Grouping for Geographic Locations March 2020
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 The 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
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 represent 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 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
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
("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 using the
"valid-for" node of the YANG grouping.
Hopps Expires 2 September 2020 [Page 15]
Internet-Draft A YANG Grouping for Geographic Locations March 2020
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 [W3CGEO] values. The timestamp value is also
specified as a string as in our YANG grouping.
KML has some special handling for the height value useful for
visualization software, "kml:altitudeMode". These values for
"kml:altitudeMode" include indicating the height is ignored
("clampToGround"), in relation to the location's ground level
("relativeToGround"), or in relation to the geodetic datum
("absolute"). 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 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
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 Value 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 values). The intent of this registry is to
provide a single standard value for any given geodetic system.
Hopps Expires 2 September 2020 [Page 16]
Internet-Draft A YANG Grouping for Geographic Locations March 2020
The values SHOULD use an acronym when available, they MUST be
converted to lower case, and spaces MUST be changed to dashes "-".
Each entry should be sufficient to define the 3 coordinate values (2
if height is not 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 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,
[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) |
+------------+------------------------------------------------------+
| wgs-84-96 | World Geodetic System 1984 [WGS84] w/ EGM96 |
+------------+------------------------------------------------------+
| wgs-84-08 | World Geodetic System 1984 [WGS84] w/ [EGM08] |
+------------+------------------------------------------------------+
| wgs-84 | World Geodetic System 1984 [WGS84] (EGM96 or |
| | better) |
+------------+------------------------------------------------------+
Table 3
7. Security Considerations
This document defines a common geo location grouping using the YANG
data modeling language. The grouping itself has no security or
privacy impact on the Internet, but the usage of the grouping in
concrete YANG modules might have. The security considerations
spelled out in the YANG 1.1 specification [RFC7950] apply for this
document as well.
Hopps Expires 2 September 2020 [Page 17]
Internet-Draft A YANG Grouping for Geographic Locations March 2020
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,
<http://earth-info.nga.mil/GandG/wgs84/gravitymod/egm2008/
egm08_wgs84.html>.
[EGM96] Lemoine, F.G., Kenyon, S.C., Factor, J.K., Trimmer, R.G.,
Pavlis, N.K., Chinn, D.S., Cox, C.M., Klosko, S.M.,
Luthcke, S.B., Torrence, M.H., Wang, Y.M., Williamson,
R.G., Pavlis, E.C., Rapp, R.H., and T.R. Olson, "The
Development of the Joint NASA GSFC and the National
Imagery and Mapping Agency (NIMA) Geopotential Model
EGM96.", Technical Report NASA/TP-1998-206861, NASA,
Greenbelt., 1998,
<https://cddis.nasa.gov/926/egm96/egm96.html>.
[ISO.6709.2008]
International Organization for Standardization, "ISO
6709:2008 Standard representation of geographic point
location by coordinates.", 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>.
[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>.
[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>.
[WGS84] National Imagery and Mapping Agency., "National Imagery
and Mapping Agency Technical Report 8350.2, Third
Edition.", 3 January 2000,
<http://earth-info.nga.mil/GandG/publications/tr8350.2/
wgs84fin.pdf>.
Hopps Expires 2 September 2020 [Page 18]
Internet-Draft A YANG Grouping for Geographic Locations March 2020
9. Informative References
[ISO.19136.2007]
International Organization for Standardization, "ISO
19136:2007 Geographic information -- Geography Markup
Language (GML)", March 2020.
[KML22] Wilson, T., Ed., "OGC KML (Version 2.2)", 14 April 2008,
<http://portal.opengeospatial.org/
files/?artifact_id=27810>.
[KML23] Burggraf, D., Ed., "OGC KML 2.3", 4 August 2015,
<http://docs.opengeospatial.org/
is/12-007r2/12-007r2.html>.
[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>.
[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", 8 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.
Hopps Expires 2 September 2020 [Page 19]
Internet-Draft A YANG Grouping for Geographic Locations March 2020
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 2019-02-02 { reference "None"; }
container locatable-items {
description "container of locatable items";
list locatable-item {
key name;
description "A of locatable item";
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-
location grouping.
Hopps Expires 2 September 2020 [Page 20]
Internet-Draft A YANG Grouping for Geographic Locations March 2020
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? types:date-and-time
+--rw valid-until? types:date-and-time
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>
Hopps Expires 2 September 2020 [Page 21]
Internet-Draft A YANG Grouping for Geographic Locations March 2020
<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 3: Example XML data of geo location use.
Appendix B. Acknowledgements
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.
Author's Address
Hopps Expires 2 September 2020 [Page 22]
Internet-Draft A YANG Grouping for Geographic Locations March 2020
Christian Hopps
LabN Consulting, L.L.C.
Email: chopps@chopps.org
Hopps Expires 2 September 2020 [Page 23]