RFC 9179
A YANG Grouping for Geographic Locations
RFC 9179: A YANG Grouping for Geographic Locations 🗺️💖
Okay bestie, this is RFC 9179, "A YANG Grouping for Geographic Locations" 🌍✨. It was written by C. Hopps from LabN Consulting, L.L.C., and it's dated February 2022 🎀. It's a Standards Track doc, so it's an official Internet spec, not just an opinion piece 👑. The ISSN is 2070-1721 🧚. The title block doesn't list anything it obsoletes or updates, so it isn't replacing or patching any other RFC 💅.
Abstract ✨
This doc defines a generic geographical location YANG grouping 🗺️. The grouping is meant for YANG data models that need to specify a location on or in reference to Earth, or to any other astronomical object 🌌.
Status of This Memo 📜
This is an Internet Standards Track document 🔥.
It's a product of the Internet Engineering Task Force (IETF) 💖. It represents the consensus of the IETF community 🫶. It went through public review and got approved for publication by the Internet Engineering Steering Group (IESG) 🎉. If you want more info on Internet Standards, check Section 2 of RFC 7841 📚.
Info about the current status of this document, any errata, and how to give feedback on it is 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) as they're in effect on the date of publication 📑. Please actually read these, because they spell out your rights and restrictions for this document 🙈. Code Components pulled out of this document must include Revised BSD License text as described in Section 4.e of the Trust Legal Provisions, and they come 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 Address1. Introduction 🦋
Okay so, a LOT of apps want to say where something is geographically 📍. In networking, that could be a data center, a rack at an Internet exchange point, a router, a firewall, a port on some device, the endpoints of a fiber, or even the spot where a fiber broke 💀.
Also, the location is usually relative to Earth, but it doesn't have to be 🌙. It's totally easy to imagine a network or device on the Moon, on Mars, on Enceladus (the moon of Saturn) 🪐, or even on a comet like 67p/churyumov-gerasimenko ☄️. Iconic behavior 😭.
And finally, you can imagine locations using different frames of reference, or even totally alternate systems like simulations or virtual realities 🧚✨.
This doc defines a 'geo-location' YANG grouping that can capture all of the above 💖.
This spec conforms to [ISO.6709.2008] 📐.
The YANG data model in this doc 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 🔥. So if you see them in all caps, that's the official meaning, and lowercase is just normal English 🙈.
To be continued in part 2 🌈💜
3. YANG Module ✨
okay so this is the actual YANG model, bestie 💅 It imports Common YANG Data Types [RFC6991] so we don't have to reinvent dates and numbers, and it's written in YANG version 1.1 [RFC7950] 🎀
the code is the star of this section, so read it slowly 💖
<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 🧚
okay so [ISO.6709.2008] comes with an appendix full of conformance tests, and we actually ran through them 💅 The results are in the table below, along with a note on the tests that just don't apply to us.
+=========+===========================+====================+
| 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 don't define our own CRS, and doing so isn't required for conformance. 🙈
for A.1.2.6, we don't define a text string representation, which also isn't required for conformance. 💅
5. Usability 🌍
the geo-location object in this document and YANG module was designed to be super usable across a huge range of apps 🦋 That includes locating things on astronomical bodies other than Earth, and using totally different coordinate systems and realities. it's giving main character energy, fr fr 🌌
5.1. Portability 💖
to check portability while we were building this module, we looked at the following standards and standard APIs. 🎀
5.1.1. IETF URI Value
[RFC5870] defines a standard URI value for geographic location data. 🔗 It lets you specify the geodetic value (it calls this crs), with the default being wgs-84 [WGS84]. For the location data, it allows two or three coordinates, defined by the crs value. For accuracy, there's a single u parameter for uncertainty. The u value is in fractions of meters and applies to all the location values. Since the URI is a string, every value is written as a string, so it can be as precise as you need ✨
URI values can be mapped to and from the YANG grouping, with the caveat that some loss of precision (at the extremes) may happen, because the YANG grouping uses decimal64 values instead of strings. 🥺
5.1.2. W3C
[W3CGEO] is the W3C's geolocation API, and it's used by lots of apps (Google Maps API, for example) 🗺️ Here's a snippet of code showing how it defines the geolocation data:
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 📊
here's the side-by-side. the YANG column is where each W3C field lands in our 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
here's what each W3C field means:
accuracy(double): accuracy of thelatitudeandlongitudevalues, in meters. 📏altitude(double): optional height in meters above the [WGS84] ellipsoid. ⛰️altitudeAccuracy(double): optional accuracy of thealtitudevalue, 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): 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 covers every representable value of this timestamp. ⏰
W3C API values can be mapped to the YANG grouping, with the caveat that some loss of precision (at the extremes) may happen, because the YANG grouping uses decimal64 values instead of doubles. 🫶
the other direction is more limited 🙈 YANG values for Earth that use the default wgs-84 [WGS84] as the geodetic-datum can be mapped directly to the W3C values. W3C doesn't provide the extra features needed to map the broader set of values the YANG grouping supports, so those can't be mapped that way.
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 a lot of things, including a position type gml:pos, which is a sequence of double values. That sequence represents coordinates in a given CRS. The CRS is either inherited from containing elements or set directly with the attributes srsName and, optionally, srsDimension on the gml:pos.
GML defines an Abstract CRS type, and Concrete CRS types are derived from it. This allows for many kinds of CRS definitions. We're focused on the Geodetic CRS type, which can use either ellipsoidal or Cartesian coordinates. We believe other non-Earth-based CRSs, as well as virtual CRSs, should also be representable with the GML CRS types. 🪐
So GML gml:pos values can be mapped directly to the YANG grouping, with the caveat that some loss of precision (at the extremes) may happen, because the YANG grouping uses decimal64 values instead of doubles. ✨
Mapping YANG grouping values to GML is fully supported for Earth-based geodetic systems. 🌎
GML also defines an observation value in gml:Observation. It includes a timestamp value, gml:validTime, along with other parts such as gml:using, gml:target, and gml:resultOf. Only the timestamp can be mapped to and from the YANG grouping. Also, gml:validTime can be either an instantaneous measure (gml:TimeInstant) or a time period (gml:TimePeriod). The instantaneous gml:TimeInstant maps 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]. The schema includes geographic location data in some of its objects (for example, kml:Point or kml:Camera objects). This data is provided in string format and matches the values in [W3CGEO]. The timestamp is also a string, just like in our YANG grouping. 💕
KML has some special handling for height that's useful for visualization software, called kml:altitudeMode. Its values include clampToGround, which means the height is ignored; relativeToGround, which means the height is relative to the location's ground level; and absolute, which means the height 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. 🙃
On top of kml:altitudeMode, KML also defines two seafloor height values using kml:seaFloorAltitudeMode. One is to ignore the height value (clampToSeaFloor), and the other is relative (relativeToSeaFloor). Just like with kml:altitudeMode, 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 the identifier LonLat84_5773. The altitude value for KML absolute height mode is measured from the vertical datum specified by [WGS84]. 📐
So the YANG grouping and KML values can be mapped directly in both directions (when using a supported altitude mode), with the caveat that some loss of precision (at the extremes) may happen, because the YANG grouping uses decimal64 values instead of strings. For relative height cases, the application doing the transformation is expected to have the data it needs to turn 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 ✨
okay so IANA made a new registry called "Geodetic System Values" 🌍, and it lives under the "YANG Geographic Location Parameters" registry 💖.
This one hands out names for standard geodetic systems. People call the same system a bunch of different things (full names, multiple acronyms, the works 🙈), so the whole point is to give each system ONE standard value. one name to rule them all 👑
The values SHOULD use an acronym when one is available 💅, they MUST be converted to lowercase 🍓, and spaces MUST be changed to dashes "-" ✨.
Each entry should be enough to define the two coordinate values, and also height if height is needed. Like, wgs-84 is WGS-84 with the geoid updated by at least [EGM96] for height values 🌸. There are also specific entries for [EGM96] and [EGM08] if you need a more precise definition of the data 🎀.
It should be noted that [RFC5870] also made 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] wanted CRS registration to be hard on purpose, so CRS values wouldn't multiply everywhere 🚫. Our module defines alternate systems and has a broader scope (beyond Earth too 🌙), so the registry below is meant to be easier to modify.
The allocation policy for this registry is First Come First Served [RFC8126], since the intent is simply to avoid duplicate values 💜.
The Reference value can be either 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 below. 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 36.2. Updates to the IETF XML Registry 📜
This document registers a URI in the "IETF XML Registry" [RFC3688]. Following the format in [RFC3688], here's the registration that got 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 registration is:
Name: ietf-geo-location
Maintained by IANA: N
Namespace: urn:ietf:params:xml:ns:yang:ietf-geo-location
Prefix: geo
Reference: RFC 91797. Security Considerations 🛡️
Okay, bestie, this section is SERIOUS. Read it like your location data depends on it, because it kinda does 😭
The YANG module in this document is a schema for data that's meant to be accessed through network management protocols like 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] gives you the tools to restrict particular NETCONF or RESTCONF users to a preconfigured subset of all the available protocol operations and content 🚦.
Since the modules in this document only define groupings, these considerations are mainly 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 considered more sensitive or vulnerable than standard configuration by themselves 🙌.
Some of the readable data nodes in this YANG module may be considered sensitive or vulnerable in some network environments 👀. It is 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). 💀 This is the big one, bestie. Location data is personal.
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 🧚
Okay bestie, this is the fun part where we get to see the geo-location grouping in action 💅 Here's a totally made-up module (don't @ anyone, it's fictitious ✨) that uses it:
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 🎀
Next up, the YANG tree for that same fictitious module. It's giving structure, and I'm obsessed 🦋
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-timeFigure 3: Example YANG Tree Using Geolocation ⭐
And finally, some example YANG XML data for that same fictitious module that uses the geo-location grouping. This is where the locations actually come alive 🌸 (Gaetana's, the Pont des Arts, the Saint Louis Cathedral, the Apollo 11 Landing Site, and a lonely one with only a reference frame 🌈)
<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 🫶
Huge thanks to Jim Biard and Ben Koziol for their reviews and suggested improvements, you two are literal angels 😭 We also owe a big hug to Peter Lothberg, who provided the motivation and helped define a broadly useful geographic location object 🍓 Acee Lindem and Qin Wu also deserve a shoutout for their work on a geographic location object that led to this document's creation 👑 And last but not least, we'd like to thank Document Shepherd Kent Watsen 💜
Author's Address 🦋
Christian Hopps LabN Consulting, L.L.C.
Email: chopps@chopps.org
📦 where this page comes from
- ietf: rfc9179 2022-02
- 💖 girlified by claude-haiku-5-5 on : a language model's rewrite of the original, under its terms