Internet-Draft A YANG Grouping for Geographic Locations July 2020
Hopps Expires 30 January 2021 [Page]
Workgroup:
Network Working Group
Published:
Intended Status:
Standards Track
Expires:
Author:
C. Hopps
LabN Consulting, L.L.C.

A YANG Grouping for Geographic Locations

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 30 January 2021.

Table of Contents

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.

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. 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.

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.

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.

  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].

<CODE BEGINS> file "ietf-geo-location@2019-02-17.yang"
module ietf-geo-location {
  yang-version 1.1;
  namespace "urn:ietf:params:xml:ns:yang:ietf-geo-location";
  prefix geo;
  import ietf-yang-types {
    prefix yang;
    reference "RFC 6991: Common YANG Data Types.";
  }

  organization
    "IETF NETMOD Working Group (NETMOD)";
  contact
    "Christian Hopps <chopps@chopps.org>";

  // RFC Ed.: replace XXXX with actual RFC number or IANA reference
  // 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
     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 or IANA reference
     // 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: 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., 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;
          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.";
          reference "https://www.iau.org/";
        }
        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 ('-')";
            reference
              "IANA XXXX YANG Geographic Location Parameters,
               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
               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;
            }
            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. For a
           formula to convert these values to speed and heading see
           this modules defining document 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~.";
        }

        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 non-applicable tests.

Table 1: Conformance Test Results
Test Description Pass Explanation
A.1.2.1 elements reqd. for a geo. point location CRS is always indicated
A.1.2.2 Description of a CRS from a register CRS register is defined
A.1.2.3 definition of CRS N/A - Don't define CRS
A.1.2.4 representation of horizontal position lat/long values conform
A.1.2.5 representation of vertical position height value conforms
A.1.2.6 text string representation N/A - No string format

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.

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
5.1.2.1. Compare with YANG Model
Table 2
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
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 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 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, 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 Values Registry

IANA is asked to create a new registry "Geodetic System Values" grouped under a new category named "YANG Geographic Location Parameters".

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.

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.

Table 3
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)

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

namespace

urn:ietf:params:xml:ns:yang:ietf-geo-location

prefix

geo

reference

RFC XXXX (RFC Ed.: replace XXX with actual RFC number and remove this note.)

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 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 of 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.

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.

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, , <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., , <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.", .
[RFC2119]
Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, , <https://www.rfc-editor.org/info/rfc2119>.
[RFC6991]
Schoenwaelder, J., Ed., "Common YANG Data Types", RFC 6991, DOI 10.17487/RFC6991, , <https://www.rfc-editor.org/info/rfc6991>.
[RFC8174]
Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, , <https://www.rfc-editor.org/info/rfc8174>.
[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, , <https://www.rfc-editor.org/info/rfc8126>.
[RFC8342]
Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., and R. Wilton, "Network Management Datastore Architecture (NMDA)", RFC 8342, DOI 10.17487/RFC8342, , <https://www.rfc-editor.org/info/rfc8342>.
[WGS84]
National Imagery and Mapping Agency., "National Imagery and Mapping Agency Technical Report 8350.2, Third Edition.", , <http://earth-info.nga.mil/GandG/publications/tr8350.2/wgs84fin.pdf>.

9. Informative References

[ISO.19136.2007]
International Organization for Standardization, "ISO 19136:2007 Geographic information -- Geography Markup Language (GML)", .
[KML22]
Wilson, T., Ed., "OGC KML (Version 2.2)", , <http://portal.opengeospatial.org/files/?artifact_id=27810>.
[KML23]
Burggraf, D., Ed., "OGC KML 2.3", , <http://docs.opengeospatial.org/is/12-007r2/12-007r2.html>.
[RFC3688]
Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, DOI 10.17487/RFC3688, , <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, , <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, , <https://www.rfc-editor.org/info/rfc6020>.
[RFC6241]
Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., and A. Bierman, Ed., "Network Configuration Protocol (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, , <https://www.rfc-editor.org/info/rfc6241>.
[RFC6242]
Wasserman, M., "Using the NETCONF Protocol over Secure Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, , <https://www.rfc-editor.org/info/rfc6242>.
[RFC7950]
Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", RFC 7950, DOI 10.17487/RFC7950, , <https://www.rfc-editor.org/info/rfc7950>.
[RFC8040]
Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF Protocol", RFC 8040, DOI 10.17487/RFC8040, , <https://www.rfc-editor.org/info/rfc8040>.
[RFC8340]
Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", BCP 215, RFC 8340, DOI 10.17487/RFC8340, , <https://www.rfc-editor.org/info/rfc8340>.
[RFC8341]
Bierman, A. and M. Bjorklund, "Network Configuration Access Control Model", STD 91, RFC 8341, DOI 10.17487/RFC8341, , <https://www.rfc-editor.org/info/rfc8341>.
[RFC8446]
Rescorla, E., "The Transport Layer Security (TLS) Protocol Version 1.3", RFC 8446, DOI 10.17487/RFC8446, , <https://www.rfc-editor.org/info/rfc8446>.
[W3CGEO]
Popescu, A., "Geolocation API Specification", , <https://www.w3.org/TR/2016/REC-geolocation-API-20161108/>.

Appendix A. Examples

Below is a fictitious module that uses the geo-location grouping.

module example-uses-geo-location {
  namespace
    "urn:example:example-uses-geo-location";
  prefix ugeo;
  import ietf-geo-location { prefix geo; }
  organization "Empty Org";
  contact "Example Author <eauthor@example.com>";
  description "Example use of geo-location";
  revision 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.

  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

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 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.

Author's Address

Christian Hopps
LabN Consulting, L.L.C.