Skip to main content

A YANG Grouping for Geographic Locations
draft-ietf-netmod-geo-location-10

The information below is for an old version of the document.
Document Type
This is an older version of an Internet-Draft that was ultimately published as RFC 9179.
Author Christian Hopps
Last updated 2021-06-17
Replaces draft-chopps-netmod-geo-location
RFC stream Internet Engineering Task Force (IETF)
Formats
Reviews
Additional resources Mailing list discussion
Stream WG state Submitted to IESG for Publication
Doc Shepherd Follow-up Underway
Document shepherd Kent Watsen
Shepherd write-up Show Last changed 2020-12-25
IESG IESG state Became RFC 9179 (Proposed Standard)
Consensus boilerplate Yes
Telechat date (None)
Needs a YES. Needs 4 more YES or NO OBJECTION positions to pass.
Responsible AD Robert Wilton
Send notices to Kent Watsen <kent+ietf@watsen.net>
IANA IANA review state Version Changed - Review Needed
IANA expert review state Expert Reviews OK
draft-ietf-netmod-geo-location-10
Network Working Group                                           C. Hopps
Internet-Draft                                   LabN Consulting, L.L.C.
Intended status: Standards Track                            17 June 2021
Expires: 19 December 2021

                A YANG Grouping for Geographic Locations
                   draft-ietf-netmod-geo-location-10

Abstract

   This document defines a generic geographical location YANG grouping.
   The geographical location grouping is intended to be used in YANG
   models for specifying a location on or in reference to Earth or any
   other astronomical object.

Status of This Memo

   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 19 December 2021.

Copyright Notice

   Copyright (c) 2021 IETF Trust and the persons identified as the
   document authors.  All rights reserved.

   This document is subject to BCP 78 and the IETF Trust's Legal
   Provisions Relating to IETF Documents (https://trustee.ietf.org/
   license-info) in effect on the date of publication of this document.
   Please review these documents carefully, as they describe your rights
   and restrictions with respect to this document.  Code Components
   extracted from this document must include Simplified BSD License text
   as described in Section 4.e of the Trust Legal Provisions and are
   provided without warranty as described in the Simplified BSD License.

Hopps                   Expires 19 December 2021                [Page 1]
Internet-Draft  A YANG Grouping for Geographic Locations       June 2021

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 . . . . . . . . . . . . . . . . . .  12
   5.  Usability . . . . . . . . . . . . . . . . . . . . . . . . . .  13
     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 . . . . . . . . . . . . . . . . . . . . .  17
     6.1.  Geodetic System Values Registry . . . . . . . . . . . . .  17
     6.2.  Updates to the IETF XML Registry  . . . . . . . . . . . .  18
     6.3.  Updates to the YANG Module Names Registry . . . . . . . .  18
   7.  Security Considerations . . . . . . . . . . . . . . . . . . .  19
   8.  Normative References  . . . . . . . . . . . . . . . . . . . .  19
   9.  Informative References  . . . . . . . . . . . . . . . . . . .  20
   Appendix A.  Examples . . . . . . . . . . . . . . . . . . . . . .  22
   Appendix B.  Acknowledgments  . . . . . . . . . . . . . . . . . .  24
   Author's Address  . . . . . . . . . . . . . . . . . . . . . . . .  25

1.  Introduction

   In many applications we would like to specify the location of
   something geographically.  Some examples of locations in networking
   might be the location of data center, a rack in an internet exchange
   point, a router, a firewall, a port on some device, or it could be
   the endpoints of a fiber, or perhaps the failure point along a fiber.

   Additionally, while this location is typically relative to Earth, it
   does not need to be.  Indeed, it is easy to imagine a network or
   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).

Hopps                   Expires 19 December 2021                [Page 2]
Internet-Draft  A YANG Grouping for Geographic Locations       June 2021

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

Hopps                   Expires 19 December 2021                [Page 3]
Internet-Draft  A YANG Grouping for Geographic Locations       June 2021

   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 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 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, Earth (or another astronomical body).

Hopps                   Expires 19 December 2021                [Page 4]
Internet-Draft  A YANG Grouping for Geographic Locations       June 2021

   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.

Hopps                   Expires 19 December 2021                [Page 5]
Internet-Draft  A YANG Grouping for Geographic Locations       June 2021

     module: ietf-geo-location
       grouping geo-location
         +-- geo-location
            +-- reference-frame
            |  +-- alternate-system?    string {alternate-systems}?
            |  +-- astronomical-body?   string
            |  +-- geodetic-system
            |     +-- geodetic-datum?    string
            |     +-- coord-accuracy?    decimal64
            |     +-- height-accuracy?   decimal64
            +-- (location)?
            |  +--:(ellipsoid)
            |  |  +-- latitude?    decimal64
            |  |  +-- longitude?   decimal64
            |  |  +-- height?      decimal64
            |  +--:(cartesian)
            |     +-- x?           decimal64
            |     +-- y?           decimal64
            |     +-- z?           decimal64
            +-- velocity
            |  +-- v-north?   decimal64
            |  +-- v-east?    decimal64
            |  +-- v-up?      decimal64
            +-- timestamp?         yang:date-and-time
            +-- valid-until?       yang:date-and-time

3.  YANG Module

   This model imports Common YANG Data Types [RFC6991].  It uses YANG
   version 1.1 [RFC7950]

   <CODE BEGINS> file "ietf-geo-location@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
      "WG Web:   <https://datatracker.ietf.org/wg/netmod/>
       WG List:  <mailto:netmod@ietf.org>

       Editor:   Christian Hopps

Hopps                   Expires 19 December 2021                [Page 6]
Internet-Draft  A YANG Grouping for Geographic Locations       June 2021

                 <mailto: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.,
        '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 the 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.";

Hopps                   Expires 19 December 2021                [Page 7]
Internet-Draft  A YANG Grouping for Geographic Locations       June 2021

       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),
                '67p/churyumov-gerasimenko (a comet). The ASCII value
                SHOULD have upper case converted to lower case 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,

Hopps                   Expires 19 December 2021                [Page 8]
Internet-Draft  A YANG Grouping for Geographic Locations       June 2021

                  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 upper case converted to lower
                  case 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 ('-')";
               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 height-accuracy is 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

Hopps                   Expires 19 December 2021                [Page 9]
Internet-Draft  A YANG Grouping for Geographic Locations       June 2021

                  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.";
             }
           }

Hopps                   Expires 19 December 2021               [Page 10]
Internet-Draft  A YANG Grouping for Geographic Locations       June 2021

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

Hopps                   Expires 19 December 2021               [Page 11]
Internet-Draft  A YANG Grouping for Geographic Locations       June 2021

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

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

Hopps                   Expires 19 December 2021               [Page 12]
Internet-Draft  A YANG Grouping for Geographic Locations       June 2021

5.  Usability

   The geo-location object defined in this document and YANG module have
   been designed to be usable in a very broad set of applications.  This
   includes the ability to locate things on astronomical bodies other
   than Earth, and to utilize entirely different coordinate systems and
   realities.

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 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
   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 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 applications (e.g., Google Maps API).

Hopps                   Expires 19 December 2021               [Page 13]
Internet-Draft  A YANG Grouping for Geographic Locations       June 2021

   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 Geo-Location Definition

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.

Hopps                   Expires 19 December 2021               [Page 14]
Internet-Draft  A YANG Grouping for Geographic Locations       June 2021

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

   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.

Hopps                   Expires 19 December 2021               [Page 15]
Internet-Draft  A YANG Grouping for Geographic Locations       June 2021

   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,
   (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

Hopps                   Expires 19 December 2021               [Page 16]
Internet-Draft  A YANG Grouping for Geographic Locations       June 2021

   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" under
   a new protocol category group "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).  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 2 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 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 Reference value can either be a document or a contact person as
   defined in [RFC8126].  The Change Control (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 [ME].

Hopps                   Expires 19 December 2021               [Page 17]
Internet-Draft  A YANG Grouping for Geographic Locations       June 2021

    +-----------+------------------------------+-----------+---------+
    | Name      | Description                  | Reference | Change  |
    +-----------+------------------------------+-----------+---------+
    |           |                              | /Contact  | Control |
    +===========+==============================+===========+=========+
    | me        | Mean Earth/Polar Axis (Moon) | this      | IESG    |
    +-----------+------------------------------+-----------+---------+
    | wgs-84-96 | World Geodetic System 1984   | this      | IESG    |
    +-----------+------------------------------+-----------+---------+
    | wgs-84-08 | World Geodetic System 1984   | this      | IESG    |
    +-----------+------------------------------+-----------+---------+
    | wgs-84    | World Geodetic System 1984   | this      | IESG    |
    +-----------+------------------------------+-----------+---------+

                                 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

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

   prefix  geo

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

Hopps                   Expires 19 December 2021               [Page 18]
Internet-Draft  A YANG Grouping for Geographic Locations       June 2021

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

   [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

Hopps                   Expires 19 December 2021               [Page 19]
Internet-Draft  A YANG Grouping for Geographic Locations       June 2021

              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.

   [ISO.6709.2008]
              International Organization for Standardization, "ISO
              6709:2008 Standard representation of geographic point
              location by coordinates.", 2008.

   [ME]       National Aeronautics and Space Administration, Goddard
              Space Flight Center., "A Standardized Lunar Coordinate
              System for the Lunar Reconnaissance Orbiter, Version 4.",
              14 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>.

   [RFC6991]  Schoenwaelder, J., Ed., "Common YANG Data Types",
              RFC 6991, DOI 10.17487/RFC6991, July 2013,
              <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,
              May 2017, <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, June 2017,
              <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, 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.

9.  Informative References

   [ISO.19136.2007]
              International Organization for Standardization, "ISO
              19136:2007 Geographic information -- Geography Markup
              Language (GML)".

Hopps                   Expires 19 December 2021               [Page 20]
Internet-Draft  A YANG Grouping for Geographic Locations       June 2021

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

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

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

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

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

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

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

Hopps                   Expires 19 December 2021               [Page 21]
Internet-Draft  A YANG Grouping for Geographic Locations       June 2021

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

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

   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 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 the YANG tree for the fictitious module that uses the geo-
   location grouping.

Hopps                   Expires 19 December 2021               [Page 22]
Internet-Draft  A YANG Grouping for Geographic Locations       June 2021

     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>

Hopps                   Expires 19 December 2021               [Page 23]
Internet-Draft  A YANG Grouping for Geographic Locations       June 2021

     </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.
   We would also like to thank the document shepherd Kent Watsen.

Hopps                   Expires 19 December 2021               [Page 24]
Internet-Draft  A YANG Grouping for Geographic Locations       June 2021

Author's Address

   Christian Hopps
   LabN Consulting, L.L.C.

   Email: chopps@chopps.org

Hopps                   Expires 19 December 2021               [Page 25]