Internet Engineering Task Force (IETF) C. Hopps

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 "[email protected]"
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:[email protected]>

Editor: Christian Hopps
<mailto:[email protected]>";

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 <[email protected]>";
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: [email protected]