doc: Add RFC documents

1 files changed, 1126 insertions, 0 deletions

diff --git a/doc/rfc/rfc9179.txt b/doc/rfc/rfc9179.txt
new file mode 100644
index 0000000..7d7007a
--- /dev/null
+++ b/doc/rfc/rfc9179.txt
@@ -0,0 +1,1126 @@
+
+
+
+
+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 "ietf-geo-location@2022-02-11.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
+                 <mailto:chopps@chopps.org>";
+
+     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 <eauthor@example.com>";
+     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: chopps@chopps.org