rfc9179.original   rfc9179.txt 
Network Working Group C. Hopps Internet Engineering Task Force (IETF) C. Hopps
Internet-Draft LabN Consulting, L.L.C. Request for Comments: 9179 LabN Consulting, L.L.C.
Intended status: Standards Track 24 October 2021 Category: Standards Track February 2022
Expires: 27 April 2022 ISSN: 2070-1721
A YANG Grouping for Geographic Locations A YANG Grouping for Geographic Locations
draft-ietf-netmod-geo-location-11
Abstract Abstract
This document defines a generic geographical location YANG grouping. This document defines a generic geographical location YANG grouping.
The geographical location grouping is intended to be used in YANG The geographical location grouping is intended to be used in YANG
models for specifying a location on or in reference to Earth or any data models for specifying a location on or in reference to Earth or
other astronomical object. any other astronomical object.
Status of This Memo Status of This Memo
This Internet-Draft is submitted in full conformance with the This is an Internet Standards Track document.
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 This document is a product of the Internet Engineering Task Force
and may be updated, replaced, or obsoleted by other documents at any (IETF). It represents the consensus of the IETF community. It has
time. It is inappropriate to use Internet-Drafts as reference received public review and has been approved for publication by the
material or to cite them other than as "work in progress." Internet Engineering Steering Group (IESG). Further information on
Internet Standards is available in Section 2 of RFC 7841.
This Internet-Draft will expire on 27 April 2022. 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 Notice
Copyright (c) 2021 IETF Trust and the persons identified as the Copyright (c) 2022 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents (https://trustee.ietf.org/ Provisions Relating to IETF Documents
license-info) in effect on the date of publication of this document. (https://trustee.ietf.org/license-info) in effect on the date of
Please review these documents carefully, as they describe your rights publication of this document. Please review these documents
and restrictions with respect to this document. Code Components carefully, as they describe your rights and restrictions with respect
extracted from this document must include Simplified BSD License text to this document. Code Components extracted from this document must
as described in Section 4.e of the Trust Legal Provisions and are include Revised BSD License text as described in Section 4.e of the
provided without warranty as described in the Simplified BSD License. Trust Legal Provisions and are provided without warranty as described
in the Revised BSD License.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 1. Introduction
1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 1.1. Terminology
2. The Geo Location Object . . . . . . . . . . . . . . . . . . . 3 2. The Geolocation Object
2.1. Frame of Reference . . . . . . . . . . . . . . . . . . . 3 2.1. Frame of Reference
2.2. Location . . . . . . . . . . . . . . . . . . . . . . . . 4 2.2. Location
2.3. Motion . . . . . . . . . . . . . . . . . . . . . . . . . 4 2.3. Motion
2.4. Nested Locations . . . . . . . . . . . . . . . . . . . . 5 2.4. Nested Locations
2.5. Non-location Attributes . . . . . . . . . . . . . . . . . 5 2.5. Non-location Attributes
2.6. Tree . . . . . . . . . . . . . . . . . . . . . . . . . . 5 2.6. Tree
3. YANG Module . . . . . . . . . . . . . . . . . . . . . . . . . 6 3. YANG Module
4. ISO 6709:2008 Conformance . . . . . . . . . . . . . . . . . . 12 4. ISO 6709:2008 Conformance
5. Usability . . . . . . . . . . . . . . . . . . . . . . . . . . 13 5. Usability
5.1. Portability . . . . . . . . . . . . . . . . . . . . . . . 13 5.1. Portability
5.1.1. IETF URI Value . . . . . . . . . . . . . . . . . . . 14 5.1.1. IETF URI Value
5.1.2. W3C . . . . . . . . . . . . . . . . . . . . . . . . . 14 5.1.2. W3C
5.1.3. Geography Markup Language (GML) . . . . . . . . . . . 16 5.1.3. Geography Markup Language (GML)
5.1.4. KML . . . . . . . . . . . . . . . . . . . . . . . . . 16 5.1.4. KML
6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 17 6. IANA Considerations
6.1. Geodetic System Values Registry . . . . . . . . . . . . . 17 6.1. Geodetic System Values Registry
6.2. Updates to the IETF XML Registry . . . . . . . . . . . . 18 6.2. Updates to the IETF XML Registry
6.3. Updates to the YANG Module Names Registry . . . . . . . . 19 6.3. Updates to the YANG Module Names Registry
7. Security Considerations . . . . . . . . . . . . . . . . . . . 19 7. Security Considerations
8. Normative References . . . . . . . . . . . . . . . . . . . . 20 8. Normative References
9. Informative References . . . . . . . . . . . . . . . . . . . 21 9. Informative References
Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 22 Appendix A. Examples
Appendix B. Acknowledgments . . . . . . . . . . . . . . . . . . 25 Acknowledgments
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 26 Author's Address
1. Introduction 1. Introduction
In many applications we would like to specify the location of In many applications, we would like to specify the location of
something geographically. Some examples of locations in networking something geographically. Some examples of locations in networking
might be the location of data center, a rack in an internet exchange 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 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. the endpoints of a fiber, or perhaps the failure point along a fiber.
Additionally, while this location is typically relative to Earth, it Additionally, while this location is typically relative to Earth, it
does not need to be. Indeed, it is easy to imagine a network or 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 device located on the Moon, on Mars, on Enceladus (the moon of
Saturn) or even a comet (e.g., 67p/churyumov-gerasimenko). Saturn), or even on a comet (e.g., 67p/churyumov-gerasimenko).
Finally, one can imagine defining locations using different frames of Finally, one can imagine defining locations using different frames of
reference or even alternate systems (e.g., simulations or virtual reference or even alternate systems (e.g., simulations or virtual
realities). realities).
This document defines a "geo-location" YANG grouping that allows for This document defines a 'geo-location' YANG grouping that allows for
all the above data to be captured. all the above data to be captured.
This specification conforms to [ISO.6709.2008]. This specification conforms to [ISO.6709.2008].
The YANG data model described in this document conforms to the The YANG data model described in this document conforms to the
Network Management Datastore Architecture defined in [RFC8342]. Network Management Datastore Architecture (NMDA) defined in
[RFC8342].
1.1. Terminology 1.1. Terminology
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in "OPTIONAL" in this document are to be interpreted as described in
[RFC2119] [RFC8174] when, and only when, they appear in all capitals, BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all
as shown here. capitals, as shown here.
2. The Geo Location Object 2. The Geolocation Object
2.1. Frame of Reference 2.1. Frame of Reference
The frame of reference ("reference-frame") defines what the location The frame of reference ('reference-frame') defines what the location
values refer to and their meaning. The referred to object can be any 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 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 moon such as Enceladus, an asteroid such as Ceres, or even a comet
such as 1P/Halley. This value is specified in "astronomical-body" such as 1P/Halley. This value is specified in 'astronomical-body'
and is defined by the International Astronomical Union and is defined by the International Astronomical Union
(http://www.iau.org). The default "astronomical-body" value is <http://www.iau.org>. The default 'astronomical-body' value is
"earth". 'earth'.
In addition to identifying the astronomical body, we also need to In addition to identifying the astronomical body, we also need to
define the meaning of the coordinates (e.g., latitude and longitude) define the meaning of the coordinates (e.g., latitude and longitude)
and the definition of 0-height. This is done with a "geodetic-datum" 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 value. The default value for 'geodetic-datum' is 'wgs-84' (i.e., the
World Geodetic System, [WGS84]), which is used by the Global World Geodetic System [WGS84]), which is used by the Global
Positioning System (GPS) among many others. We define an IANA Positioning System (GPS) among many others. We define an IANA
registry for specifying standard values for the "geodetic-datum". registry for specifying standard values for the 'geodetic-datum'.
In addition to the "geodetic-datum" value, we allow overriding the In addition to the 'geodetic-datum' value, we allow overriding the
coordinate and height accuracy using "coord-accuracy" and "height- coordinate and height accuracy using 'coord-accuracy' and 'height-
accuracy" respectively. When specified, these values override the accuracy', respectively. When specified, these values override the
defaults implied by the "geodetic-datum" value. defaults implied by the 'geodetic-datum' value.
Finally, we define an optional feature which allows for changing the Finally, we define an optional feature that allows for changing the
system for which the above values are defined. This optional feature system for which the above values are defined. This optional feature
adds an "alternate-system" value to the reference frame. This value adds an 'alternate-system' value to the reference frame. This value
is normally not present which implies the natural universe is the is normally not present, which implies the natural universe is the
system. The use of this value is intended to allow for creating system. The use of this value is intended to allow for creating
virtual realities or perhaps alternate coordinate systems. The virtual realities or perhaps alternate coordinate systems. The
definition of alternate systems is outside the scope of this definition of alternate systems is outside the scope of this
document. document.
2.2. Location 2.2. Location
This is the location on, or relative to, the astronomical object. It This is the location on, or relative to, the astronomical object. It
is specified using 2 or 3 coordinates values. These values are given is specified using two or three coordinate values. These values are
either as "latitude", "longitude", and an optional "height", or as given either as 'latitude', 'longitude', and an optional 'height', or
Cartesian coordinates of "x", "y" and "z". For the standard location as Cartesian coordinates of 'x', 'y', and 'z'. For the standard
choice "latitude" and "longitude" are specified as decimal degrees, location choice, 'latitude' and 'longitude' are specified as decimal
and the "height" value is in fractions of meters. For the Cartesian degrees, and the 'height' value is in fractions of meters. For the
choice "x", "y" and "z" are in fractions of meters. In both choices Cartesian choice, 'x', 'y', and 'z' are in fractions of meters. In
the exact meanings of all the values are defined by the "geodetic- both choices, the exact meanings of all the values are defined by the
datum" value in the Section 2.1. 'geodetic-datum' value in Section 2.1.
2.3. Motion 2.3. Motion
Support is added for objects in relatively stable motion. For Support is added for objects in relatively stable motion. For
objects in relatively stable motion the grouping provides a objects in relatively stable motion, the grouping provides a three-
3-dimensional vector value. The components of the vector are dimensional vector value. The components of the vector are
"v-north", "v-east" and "v-up" which are all given in fractional '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 meters per second. The values 'v-north' and 'v-east' are relative to
true north as defined by the reference frame for the astronomical true north as defined by the reference frame for the astronomical
body, "v-up" is perpendicular to the plane defined by "v-north" and body; 'v-up' is perpendicular to the plane defined by 'v-north' and
"v-east", and is pointed away from the center of mass. 'v-east', and is pointed away from the center of mass.
To derive the 2-dimensional heading and speed one would use the To derive the two-dimensional heading and speed, one would use the
following formulas: following formulas:
,------------------------------ ,------------------------------
speed = V v_{north}^{2} + v_{east}^{2} speed = V v_{north}^{2} + v_{east}^{2}
heading = arctan(v_{east} / v_{north}) heading = arctan(v_{east} / v_{north})
For some applications that demand high accuracy, and where the data For some applications that demand high accuracy and where the data is
is infrequently updated this velocity vector can track very slow infrequently updated, this velocity vector can track very slow
movement such as continental drift. movement such as continental drift.
Tracking more complex forms of motion is outside the scope of this Tracking more complex forms of motion is outside the scope of this
work. The intent of the grouping being defined here is to identify work. The intent of the grouping being defined here is to identify
where something is located, and generally this is expected to be where something is located, and generally this is expected to be
somewhere on, or relative to, Earth (or another astronomical body). somewhere on, or relative to, Earth (or another astronomical body).
At least two options are available to YANG data models that wish to
At least two options are available to YANG models that wish to use use this grouping with objects that are changing location frequently
this grouping with objects that are changing location frequently in in non-simple ways. A data model can either add additional motion
non-simple ways. They can add additional motion data to their model data to its model directly, or if the application allows, it can
directly. Or, if the application allows, it can require more require more frequent queries to keep the location data current.
frequent queries to keep the location data current.
2.4. Nested Locations 2.4. Nested Locations
When locations are nested (e.g., a building may have a location which When locations are nested (e.g., a building may have a location that
houses routers that also have locations) the module using this houses routers that also have locations), the module using this
grouping is free to indicate in its definition that the "reference- grouping is free to indicate in its definition that the 'reference-
frame" is inherited from the containing object so that the frame' is inherited from the containing object so that the
"reference-frame" need not be repeated in every instance of location 'reference-frame' need not be repeated in every instance of location
data. data.
2.5. Non-location Attributes 2.5. Non-location Attributes
During the development of this module, the question of whether it During the development of this module, the question of whether it
would support data such as orientation arose. These types of would support data such as orientation arose. These types of
attributes are outside the scope of this grouping because they do not attributes are outside the scope of this grouping because they do not
deal with a location but rather describe something more about the deal with a location but rather describe something more about the
object that is at the location. Module authors are free to add these object that is at the location. Module authors are free to add these
non-location attributes along with their use of this location non-location attributes along with their use of this location
grouping. grouping.
2.6. Tree 2.6. Tree
The following is the YANG tree diagram [RFC8340] for the geo-location The following is the YANG tree diagram [RFC8340] for the geo-location
grouping. grouping.
module: ietf-geo-location module: ietf-geo-location
grouping geo-location grouping geo-location:
+-- geo-location +-- geo-location
+-- reference-frame +-- reference-frame
| +-- alternate-system? string {alternate-systems}? | +-- alternate-system? string {alternate-systems}?
| +-- astronomical-body? string | +-- astronomical-body? string
| +-- geodetic-system | +-- geodetic-system
| +-- geodetic-datum? string | +-- geodetic-datum? string
| +-- coord-accuracy? decimal64 | +-- coord-accuracy? decimal64
| +-- height-accuracy? decimal64 | +-- height-accuracy? decimal64
+-- (location)? +-- (location)?
| +--:(ellipsoid) | +--:(ellipsoid)
skipping to change at page 6, line 34 skipping to change at line 242
+-- velocity +-- velocity
| +-- v-north? decimal64 | +-- v-north? decimal64
| +-- v-east? decimal64 | +-- v-east? decimal64
| +-- v-up? decimal64 | +-- v-up? decimal64
+-- timestamp? yang:date-and-time +-- timestamp? yang:date-and-time
+-- valid-until? yang:date-and-time +-- valid-until? yang:date-and-time
3. YANG Module 3. YANG Module
This model imports Common YANG Data Types [RFC6991]. It uses YANG This model imports Common YANG Data Types [RFC6991]. It uses YANG
version 1.1 [RFC7950] version 1.1 [RFC7950].
<CODE BEGINS> file "ietf-geo-location@2019-02-17.yang" <CODE BEGINS> file "ietf-geo-location@2022-2-7.yang"
module ietf-geo-location { module ietf-geo-location {
yang-version 1.1; yang-version 1.1;
namespace "urn:ietf:params:xml:ns:yang:ietf-geo-location"; namespace "urn:ietf:params:xml:ns:yang:ietf-geo-location";
prefix geo; prefix geo;
import ietf-yang-types { import ietf-yang-types {
prefix yang; prefix yang;
reference "RFC 6991: Common YANG Data Types."; reference "RFC 6991: Common YANG Data Types";
} }
organization organization
"IETF NETMOD Working Group (NETMOD)"; "IETF NETMOD Working Group (NETMOD)";
contact contact
"WG Web: <https://datatracker.ietf.org/wg/netmod/> "WG Web: <https://datatracker.ietf.org/wg/netmod/>
WG List: <mailto:netmod@ietf.org> WG List: <mailto:netmod@ietf.org>
Editor: Christian Hopps Editor: Christian Hopps
<mailto:chopps@chopps.org>"; <mailto:chopps@chopps.org>";
// RFC Ed.: replace XXXX with actual RFC number or IANA reference
// and remove this note.
description description
"This module defines a grouping of a container object for "This module defines a grouping of a container object for
specifying a location on or around an astronomical object (e.g., specifying a location on or around an astronomical object (e.g.,
'earth'). 'earth').
Copyright (c) 2019 IETF Trust and the persons identified as 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. authors of the code. All rights reserved.
Redistribution and use in source and binary forms, with or Redistribution and use in source and binary forms, with or
without modification, is permitted pursuant to, and subject to without modification, is permitted pursuant to, and subject to
the license terms contained in, the Simplified BSD License set the license terms contained in, the Revised BSD License set
forth in Section 4.c of the IETF Trust's Legal Provisions forth in Section 4.e of the IETF Trust's Legal Provisions
Relating to IETF Documents Relating to IETF Documents
(https://trustee.ietf.org/license-info). (https://trustee.ietf.org/license-info).
This version of this YANG module is part of RFC XXXX This version of this YANG module is part of RFC 9179
(https://www.rfc-editor.org/info/rfcXXXX); see the RFC itself (https://www.rfc-editor.org/info/rfc9179); see the RFC itself
for full legal notices. 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 { revision 2022-2-7 {
description "Initial Revision"; description
reference "RFC XXXX: A YANG Grouping for Geographic Locations"; "Initial Revision";
reference
"RFC 9179: A YANG Grouping for Geographic Locations";
} }
feature alternate-systems { feature alternate-systems {
description description
"This feature means the device supports specifying locations "This feature means the device supports specifying locations
using alternate systems for reference frames."; using alternate systems for reference frames.";
} }
grouping geo-location { grouping geo-location {
description description
"Grouping to identify a location on an astronomical object."; "Grouping to identify a location on an astronomical object.";
container geo-location { container geo-location {
description description
"A location on an astronomical body (e.g., 'earth') "A location on an astronomical body (e.g., 'earth')
somewhere in a universe."; somewhere in a universe.";
container reference-frame { container reference-frame {
description description
"The Frame of Reference for the location values."; "The Frame of Reference for the location values.";
leaf alternate-system { leaf alternate-system {
if-feature alternate-systems; if-feature "alternate-systems";
type string; type string;
description description
"The system in which the astronomical body and "The system in which the astronomical body and
geodetic-datum is defined. Normally, this value is not geodetic-datum is defined. Normally, this value is not
present and the system is the natural universe; however, present and the system is the natural universe; however,
when present this value allows for specifying alternate when present, this value allows for specifying alternate
systems (e.g., virtual realities). An alternate-system systems (e.g., virtual realities). An alternate-system
modifies the definition (but not the type) of the other modifies the definition (but not the type) of the other
values in the reference frame."; values in the reference frame.";
} }
leaf astronomical-body { leaf astronomical-body {
type string { type string {
pattern '[ -@\[-\^_-~]*'; pattern '[ -@\[-\^_-~]*';
} }
default "earth"; default "earth";
description description
"An astronomical body as named by the International "An astronomical body as named by the International
Astronomical Union (IAU) or according to the alternate Astronomical Union (IAU) or according to the alternate
system if specified. Examples include 'sun' (our star), system if specified. Examples include 'sun' (our star),
'earth' (our planet), 'moon' (our moon), 'enceladus' (a 'earth' (our planet), 'moon' (our moon), 'enceladus' (a
moon of Saturn), 'ceres' (an asteroid), moon of Saturn), 'ceres' (an asteroid), and
'67p/churyumov-gerasimenko (a comet). The ASCII value '67p/churyumov-gerasimenko (a comet). The ASCII value
SHOULD have upper case converted to lower case and not SHOULD have uppercase converted to lowercase and not
include control characters (i.e., values 32..64, and include control characters (i.e., values 32..64, and
91..126). Any preceding 'the' in the name SHOULD NOT be 91..126). Any preceding 'the' in the name SHOULD NOT be
included."; included.";
reference "https://www.iau.org/"; reference
"https://www.iau.org/";
} }
container geodetic-system { container geodetic-system {
description description
"The geodetic system of the location data."; "The geodetic system of the location data.";
leaf geodetic-datum { leaf geodetic-datum {
type string { type string {
pattern '[ -@\[-\^_-~]*'; pattern '[ -@\[-\^_-~]*';
} }
description description
"A geodetic-datum defining the meaning of latitude, "A geodetic-datum defining the meaning of latitude,
longitude and height. The default when the longitude, and height. The default when the
astronomical body is 'earth' is 'wgs-84' which is astronomical body is 'earth' is 'wgs-84', which is
used by the Global Positioning System (GPS). The used by the Global Positioning System (GPS). The
ASCII value SHOULD have upper case converted to lower ASCII value SHOULD have uppercase converted to
case and not include control characters (i.e., values lowercase and not include control characters
32..64, and 91..126). The IANA registry further (i.e., values 32..64, and 91..126). The IANA registry
restricts the value by converting all spaces (' ') to further restricts the value by converting all spaces
dashes ('-'). (' ') to dashes ('-').
The specification for the geodetic-datum indicates The specification for the geodetic-datum indicates
how accurately it models the astronomical body in how accurately it models the astronomical body in
question, both for the 'horizontal' question, both for the 'horizontal'
latitude/longitude coordinates and for height latitude/longitude coordinates and for height
coordinates."; coordinates.";
reference reference
"IANA XXXX YANG Geographic Location Parameters, "RFC 9179: A YANG Grouping for Geographic Locations,
Geodetic System Values"; Section 6.1";
} }
leaf coord-accuracy { leaf coord-accuracy {
type decimal64 { type decimal64 {
fraction-digits 6; fraction-digits 6;
} }
description description
"The accuracy of the latitude longitude pair for "The accuracy of the latitude/longitude pair for
ellipsoidal coordinates, or the X, Y and Z components ellipsoidal coordinates, or the X, Y, and Z components
for Cartesian coordinates. When coord-accuracy is for Cartesian coordinates. When coord-accuracy is
specified, it indicates how precisely the coordinates specified, it indicates how precisely the coordinates
in the associated list of locations have been in the associated list of locations have been
determined with respect to the coordinate system determined with respect to the coordinate system
defined by the geodetic-datum. For example, there defined by the geodetic-datum. For example, there
might be uncertainty due to measurement error if an might be uncertainty due to measurement error if an
experimental measurement was made to determine each experimental measurement was made to determine each
location."; location.";
} }
leaf height-accuracy { leaf height-accuracy {
type decimal64 { type decimal64 {
fraction-digits 6; fraction-digits 6;
} }
units "meters"; units "meters";
description description
"The accuracy of height value for ellipsoidal "The accuracy of the height value for ellipsoidal
coordinates, this value is not used with Cartesian coordinates; this value is not used with Cartesian
coordinates. When height-accuracy is specified, it coordinates. When height-accuracy is specified, it
indicates how precisely the heights in the indicates how precisely the heights in the
associated list of locations have been determined associated list of locations have been determined
with respect to the coordinate system defined by the with respect to the coordinate system defined by the
geodetic-datum. For example, there might be geodetic-datum. For example, there might be
uncertainty due to measurement error if an uncertainty due to measurement error if an
experimental measurement was made to determine each experimental measurement was made to determine each
location."; location.";
} }
} }
} }
choice location { choice location {
description description
"The location data either in lat/long or Cartesian values"; "The location data either in latitude/longitude or
Cartesian values";
case ellipsoid { case ellipsoid {
leaf latitude { leaf latitude {
type decimal64 { type decimal64 {
fraction-digits 16; fraction-digits 16;
} }
units "decimal degrees"; units "decimal degrees";
description description
"The latitude value on the astronomical body. The "The latitude value on the astronomical body. The
definition and precision of this measurement is definition and precision of this measurement is
indicated by the reference-frame."; indicated by the reference-frame.";
} }
leaf longitude { leaf longitude {
type decimal64 { type decimal64 {
fraction-digits 16; fraction-digits 16;
} }
units "decimal degrees"; units "decimal degrees";
description description
"The longitude value on the astronomical body. The "The longitude value on the astronomical body. The
definition and precision of this measurement is definition and precision of this measurement is
indicated by the reference-frame."; indicated by the reference-frame.";
} }
leaf height { leaf height {
type decimal64 { type decimal64 {
fraction-digits 6; fraction-digits 6;
} }
units "meters"; units "meters";
description description
"Height from a reference 0 value. The precision and '0' "Height from a reference 0 value. The precision and
value is defined by the reference-frame."; '0' value is defined by the reference-frame.";
} }
} }
case cartesian { case cartesian {
leaf x { leaf x {
type decimal64 { type decimal64 {
fraction-digits 6; fraction-digits 6;
} }
units "meters"; units "meters";
description description
"The X value as defined by the reference-frame."; "The X value as defined by the reference-frame.";
skipping to change at page 11, line 23 skipping to change at line 470
fraction-digits 6; fraction-digits 6;
} }
units "meters"; units "meters";
description description
"The Z value as defined by the reference-frame."; "The Z value as defined by the reference-frame.";
} }
} }
} }
container velocity { container velocity {
description description
"If the object is in motion the velocity vector describes "If the object is in motion, the velocity vector describes
this motion at the the time given by the timestamp. For a this motion at the time given by the timestamp. For a
formula to convert these values to speed and heading see formula to convert these values to speed and heading, see
RFC XXXX."; RFC 9179.";
reference reference
"RFC XXXX: A YANG Grouping for Geographic Locations"; "RFC 9179: A YANG Grouping for Geographic Locations";
leaf v-north { leaf v-north {
type decimal64 { type decimal64 {
fraction-digits 12; fraction-digits 12;
} }
units "meters per second"; units "meters per second";
description description
"v-north is the rate of change (i.e., speed) towards "v-north is the rate of change (i.e., speed) towards
truth north as defined by the geodetic-system."; true north as defined by the geodetic-system.";
} }
leaf v-east { leaf v-east {
type decimal64 { type decimal64 {
fraction-digits 12; fraction-digits 12;
} }
units "meters per second"; units "meters per second";
description description
"v-east is the rate of change (i.e., speed) perpendicular "v-east is the rate of change (i.e., speed) perpendicular
to the right of true north as defined by to the right of true north as defined by
skipping to change at page 12, line 15 skipping to change at line 510
fraction-digits 12; fraction-digits 12;
} }
units "meters per second"; units "meters per second";
description description
"v-up is the rate of change (i.e., speed) away from the "v-up is the rate of change (i.e., speed) away from the
center of mass."; center of mass.";
} }
} }
leaf timestamp { leaf timestamp {
type yang:date-and-time; type yang:date-and-time;
description "Reference time when location was recorded."; description
"Reference time when location was recorded.";
} }
leaf valid-until { leaf valid-until {
type yang:date-and-time; type yang:date-and-time;
description description
"The timestamp for which this geo-location is valid until. "The timestamp for which this geo-location is valid until.
If unspecified the geo-location has no specific expiration If unspecified, the geo-location has no specific
time."; expiration time.";
} }
} }
} }
} }
<CODE ENDS> <CODE ENDS>
4. ISO 6709:2008 Conformance 4. ISO 6709:2008 Conformance
[ISO.6709.2008] provides an appendix with a set of tests for [ISO.6709.2008] provides an appendix with a set of tests for
conformance to the standard. The tests and results are given in the conformance to the standard. The tests and results are given in the
following table along with an explanation of non-applicable tests. following table along with an explanation of inapplicable tests.
+---------+----------------------+------------------+ +=========+===========================+====================+
| Test | Description | Pass Explanation | | Test | Description | Pass Explanation |
+=========+======================+==================+ +=========+===========================+====================+
| A.1.2.1 | elements reqd. for a | CRS is always | | A.1.2.1 | elements required for a | CRS is always |
| | geo. point location | indicated | | | geographic point location | indicated |
+---------+----------------------+------------------+ +---------+---------------------------+--------------------+
| A.1.2.2 | Description of a CRS | CRS register is | | A.1.2.2 | description of a CRS from | CRS register is |
| | from a register | defined | | | a register | defined |
+---------+----------------------+------------------+ +---------+---------------------------+--------------------+
| A.1.2.3 | definition of CRS | N/A - Don't | | A.1.2.3 | definition of CRS | N/A - Don't define |
| | | define CRS | | | | CRS |
+---------+----------------------+------------------+ +---------+---------------------------+--------------------+
| A.1.2.4 | representation of | lat/long values | | A.1.2.4 | representation of | latitude/longitude |
| | horizontal position | conform | | | horizontal position | values conform |
+---------+----------------------+------------------+ +---------+---------------------------+--------------------+
| A.1.2.5 | representation of | height value | | A.1.2.5 | representation of | height value |
| | vertical position | conforms | | | vertical position | conforms |
+---------+----------------------+------------------+ +---------+---------------------------+--------------------+
| A.1.2.6 | text string | N/A - No string | | A.1.2.6 | text string | N/A - No string |
| | representation | format | | | representation | format |
+---------+----------------------+------------------+ +---------+---------------------------+--------------------+
Table 1: Conformance Test Results Table 1: Conformance Test Results
For test "A.1.2.1" the YANG geo location object either includes a For test 'A.1.2.1', the YANG geo-location object either includes a
Coordinate Reference System (CRS) ("reference-frame") or has a Coordinate Reference System (CRS) ('reference-frame') or has a
default defined ([WGS84]). default defined [WGS84].
For "A.1.2.3" we do not define our own CRS, and doing so is not For 'A.1.2.3', we do not define our own CRS, and doing so is not
required for conformance. required for conformance.
For "A.1.2.6" we do not define a text string representation, which is For 'A.1.2.6', we do not define a text string representation, which
also not required for conformance. is also not required for conformance.
5. Usability 5. Usability
The geo-location object defined in this document and YANG module have 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 been designed to be usable in a very broad set of applications. This
includes the ability to locate things on astronomical bodies other includes the ability to locate things on astronomical bodies other
than Earth, and to utilize entirely different coordinate systems and than Earth, and to utilize entirely different coordinate systems and
realities. realities.
5.1. Portability 5.1. Portability
In order to verify portability while developing this module the In order to verify portability while developing this module, the
following standards and standard APIs were considered. following standards and standard APIs were considered.
5.1.1. IETF URI Value 5.1.1. IETF URI Value
[RFC5870] defines a standard URI value for geographic location data. [RFC5870] defines a standard URI value for geographic location data.
It includes the ability to specify the "geodetic-value" (it calls It includes the ability to specify the 'geodetic-value' (it calls
this "crs") with the default being "wgs-84" [WGS84]. For the this 'crs') with the default being 'wgs-84' [WGS84]. For the
location data it allows 2 to 3 coordinates defined by the "crs" location data, it allows two to three coordinates defined by the
value. For accuracy, it has a single "u" parameter for specifying 'crs' value. For accuracy, it has a single 'u' parameter for
uncertainty. The "u" value is in fractions of meters and applies to specifying uncertainty. The 'u' value is in fractions of meters and
all the location values. As the URI is a string, all values are applies to all the location values. As the URI is a string, all
specified as strings and so are capable of as much precision as values are specified as strings and so are capable of as much
required. precision as required.
URI values can be mapped to and from the YANG grouping, with the 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 caveat that some loss of precision (in the extremes) may occur due to
the YANG grouping using decimal64 values rather than strings. the YANG grouping using decimal64 values rather than strings.
5.1.2. W3C 5.1.2. W3C
W3C Defines a geo-location API in [W3CGEO]. We show a snippet of W3C defines a geolocation API in [W3CGEO]. We show a snippet of code
code below which defines the geo-location data for this API. This is below that defines the geolocation data for this API. This is used
used by many applications (e.g., Google Maps API). by many applications (e.g., Google Maps API).
interface GeolocationPosition { interface GeolocationPosition {
readonly attribute GeolocationCoordinates coords; readonly attribute GeolocationCoordinates coords;
readonly attribute DOMTimeStamp timestamp; readonly attribute DOMTimeStamp timestamp;
}; };
interface GeolocationCoordinates { interface GeolocationCoordinates {
readonly attribute double latitude; readonly attribute double latitude;
readonly attribute double longitude; readonly attribute double longitude;
readonly attribute double? altitude; readonly attribute double? altitude;
readonly attribute double accuracy; readonly attribute double accuracy;
readonly attribute double? altitudeAccuracy; readonly attribute double? altitudeAccuracy;
readonly attribute double? heading; readonly attribute double? heading;
readonly attribute double? speed; readonly attribute double? speed;
}; };
Figure 1: Snippet Showing Geo-Location Definition Figure 1: Snippet Showing Geolocation Definition
5.1.2.1. Compare with YANG Model 5.1.2.1. Comparison with YANG Data Model
+------------------+--------------+-----------------+-------------+ +==================+==============+=================+=============+
| Field | Type | YANG | Type | | Field | Type | YANG | Type |
+==================+==============+=================+=============+ +==================+==============+=================+=============+
| accuracy | double | coord-accuracy | dec64 fr 6 | | accuracy | double | coord-accuracy | dec64 fr 6 |
+------------------+--------------+-----------------+-------------+ +------------------+--------------+-----------------+-------------+
| altitude | double | height | dec64 fr 6 | | altitude | double | height | dec64 fr 6 |
+------------------+--------------+-----------------+-------------+ +------------------+--------------+-----------------+-------------+
| altitudeAccuracy | double | height-accuracy | dec64 fr 6 | | altitudeAccuracy | double | height-accuracy | dec64 fr 6 |
+------------------+--------------+-----------------+-------------+ +------------------+--------------+-----------------+-------------+
| heading | double | v-north, v-east | dec64 fr 12 | | heading | double | v-north, v-east | dec64 fr 12 |
+------------------+--------------+-----------------+-------------+ +------------------+--------------+-----------------+-------------+
skipping to change at page 15, line 19 skipping to change at line 641
+------------------+--------------+-----------------+-------------+ +------------------+--------------+-----------------+-------------+
| longitude | double | longitude | dec64 fr 16 | | longitude | double | longitude | dec64 fr 16 |
+------------------+--------------+-----------------+-------------+ +------------------+--------------+-----------------+-------------+
| speed | double | v-north, v-east | dec64 fr 12 | | speed | double | v-north, v-east | dec64 fr 12 |
+------------------+--------------+-----------------+-------------+ +------------------+--------------+-----------------+-------------+
| timestamp | DOMTimeStamp | timestamp | string | | timestamp | DOMTimeStamp | timestamp | string |
+------------------+--------------+-----------------+-------------+ +------------------+--------------+-----------------+-------------+
Table 2 Table 2
accuracy (double) Accuracy of "latitude" and "longitude" values in accuracy (double): Accuracy of 'latitude' and 'longitude' values in
meters. meters.
altitude (double) Optional height in meters above the [WGS84] altitude (double): Optional height in meters above the [WGS84]
ellipsoid. ellipsoid.
altitudeAccuracy (double) Optional accuracy of "altitude" value in altitudeAccuracy (double): Optional accuracy of 'altitude' value in
meters. meters.
heading (double) Optional Direction in decimal deg from true north heading (double): Optional direction in decimal degrees from true
increasing clock-wise. north increasing clockwise.
latitude, longitude (double) Standard lat/long values in decimal latitude, longitude (double): Standard latitude/longitude values in
degrees. decimal degrees.
speed (double) Speed along heading in meters per second. speed (double): Speed along the heading in meters per second.
timestamp (DOMTimeStamp) Specifies milliseconds since the Unix EPOCH timestamp (DOMTimeStamp): Specifies milliseconds since the UNIX
in 64 bit unsigned integer. The YANG model defines the timestamp Epoch in a 64-bit unsigned integer. The YANG data model defines
with arbitrarily large precision by using a string which the timestamp with arbitrarily large precision by using a string
encompasses all representable values of this timestamp value. that encompasses all representable values of this timestamp value.
W3C API values can be mapped to the YANG grouping, with the caveat 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 that some loss of precision (in the extremes) may occur due to the
YANG grouping using decimal64 values rather than doubles. YANG grouping using decimal64 values rather than doubles.
Conversely, only YANG values for Earth using the default "wgs-84" Conversely, only YANG values for Earth using the default 'wgs-84'
[WGS84] as the "geodetic-datum", can be directly mapped to the W3C [WGS84] as the 'geodetic-datum' can be directly mapped to the W3C
values, as W3C does not provide the extra features necessary to map values as W3C does not provide the extra features necessary to map
the broader set of values supported by the YANG grouping. the broader set of values supported by the YANG grouping.
5.1.3. Geography Markup Language (GML) 5.1.3. Geography Markup Language (GML)
ISO adopted the Geography Markup Language (GML) defined by OGC 07-036 ISO adopted the Geography Markup Language (GML) defined by OGC 07-036
as [ISO.19136.2007]. GML defines, among many other things, a [OGC] as [ISO.19136.2007]. GML defines, among many other things, a
position type "gml:pos" which is a sequence of "double" values. This position type 'gml:pos', which is a sequence of 'double' values.
sequence of values represents coordinates in a given CRS. The CRS is This sequence of values represents coordinates in a given CRS. The
either inherited from containing elements or directly specified as CRS is either inherited from containing elements or directly
attributes "srsName" and optionally "srsDimension" on the "gml:pos". specified as attributes 'srsName' and optionally 'srsDimension' on
the 'gml:pos'.
GML defines an Abstract CRS type which Concrete CRS types derive GML defines an Abstract CRS type from which Concrete CRS types are
from. This allows for many types of CRS definitions. We are derived. This allows for many types of CRS definitions. We are
concerned with the Geodetic CRS type which can have either concerned with the Geodetic CRS type, which can have either
ellipsoidal or Cartesian coordinates. We believe that other non- ellipsoidal or Cartesian coordinates. We believe that other non-
Earth based CRS as well as virtual CRS should also be representable Earth-based CRSs as well as virtual CRSs should also be representable
by the GML CRS types. by the GML CRS types.
Thus, GML "gml:pos" values can be mapped directly to the YANG Thus, GML 'gml:pos' values can be mapped directly to the YANG
grouping, with the caveat that some loss of precision (in the grouping with the caveat that some loss of precision (in the
extremes) may occur due to the YANG grouping using decimal64 values extremes) may occur due to the YANG grouping using decimal64 values
rather than doubles. rather than doubles.
Conversely, YANG grouping values can be mapped to GML as directly as Conversely, mapping YANG grouping values to GML is fully supported
the GML CRS available definitions allow with a minimum of Earth-based for Earth-based geodetic systems.
geodetic systems fully supported.
GML also defines an observation value in "gml:Observation" which GML also defines an observation value in 'gml:Observation', which
includes a timestamp value "gml:validTime" in addition to other includes a timestamp value 'gml:validTime' in addition to other
components such as "gml:using" "gml:target" and "gml:resultOf". Only components such as 'gml:using', 'gml:target', and 'gml:resultOf'.
the timestamp is mappable to and from the YANG grouping. Only the timestamp is mappable to and from the YANG grouping.
Furthermore, "gml:validTime" can either be an Instantaneous measure Furthermore, 'gml:validTime' can either be an instantaneous measure
("gml:TimeInstant") or a time period ("gml:TimePeriod"). The ('gml:TimeInstant') or a time period ('gml:TimePeriod'). The
instantaneous "gml:TimeInstant" is mappable to and from the YANG instantaneous 'gml:TimeInstant' is mappable to and from the YANG
grouping "timestamp" value, and values down to the resolution of grouping 'timestamp' value, and values down to the resolution of
seconds for "gml:TimePeriod" can be mapped using the "valid-until" seconds for 'gml:TimePeriod' can be mapped using the 'valid-until'
node of the YANG grouping. node of the YANG grouping.
5.1.4. KML 5.1.4. KML
KML 2.2 [KML22] (formerly Keyhole Markup Language) was submitted by KML 2.2 [KML22] (formerly Keyhole Markup Language) was submitted by
Google to the Open Geospatial Consortium, Google to the Open Geospatial Consortium
(https://www.opengeospatial.org/) and was adopted. The latest (https://www.opengeospatial.org/) and was adopted. The latest
version as of this writing is KML 2.3 [KML23]. This schema includes 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 geographic location data in some of its objects (e.g., 'kml:Point' or
"kml:Camera" objects). This data is provided in string format and 'kml:Camera' objects). This data is provided in string format and
corresponds to the [W3CGEO] values. The timestamp value is also corresponds to the values specified in [W3CGEO]. The timestamp value
specified as a string as in our YANG grouping. is also specified as a string as in our YANG grouping.
KML has some special handling for the height value useful for KML has some special handling for the height value that is useful for
visualization software, "kml:altitudeMode". These values for visualization software, 'kml:altitudeMode'. The values for
"kml:altitudeMode" include indicating the height is ignored 'kml:altitudeMode' include 'clampToGround', which indicates the
("clampToGround"), in relation to the location's ground level height is ignored; 'relativeToGround', which indicates the height
("relativeToGround"), or in relation to the geodetic datum value is relative to the location's ground level; or 'absolute',
("absolute"). The YANG grouping can directly map the ignored and which indicates the height value is an absolute value within the
absolute cases, but not the relative to ground case. 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 In addition to the 'kml:altitudeMode', KML also defines two seafloor
height values using "kml:seaFloorAltitudeMode". One value is to height values using 'kml:seaFloorAltitudeMode'. One value is to
ignore the height value ("clampToSeaFloor") and the other is relative ignore the height value ('clampToSeaFloor') and the other is relative
("relativeToSeaFloor"). As with the "kml:altitudeMode" value, the ('relativeToSeaFloor'). As with the 'kml:altitudeMode' value, the
YANG grouping supports the ignore case but not the relative case. 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 KML location values use a geodetic datum defined in Annex A of
the GML Coordinate Reference System (CRS) [ISO.19136.2007] with [ISO.19136.2007] with identifier 'LonLat84_5773'. The altitude value
identifier "LonLat84_5773". The altitude value for KML absolute for KML absolute height mode is measured from the vertical datum
height mode is measured from the vertical datum specified by [WGS84]. specified by [WGS84].
Thus, the YANG grouping and KML values can be directly mapped in both Thus, the YANG grouping and KML values can be directly mapped in both
directions (when using a supported altitude mode) with the caveat directions (when using a supported altitude mode) with the caveat
that some loss of precision (in the extremes) may occur due to the that some loss of precision (in the extremes) may occur due to the
YANG grouping using decimal64 values rather than strings. For the YANG grouping using decimal64 values rather than strings. For the
relative height cases, the application doing the transformation is relative height cases, the application doing the transformation is
expected to have the data available to transform the relative height expected to have the data available to transform the relative height
into an absolute height, which can then be expressed using the YANG into an absolute height, which can then be expressed using the YANG
grouping. grouping.
6. IANA Considerations 6. IANA Considerations
6.1. Geodetic System Values Registry 6.1. Geodetic System Values Registry
IANA is asked to create a new registry "Geodetic System Values" under IANA has created the "Geodetic System Values" registry under the
a new protocol category group "YANG Geographic Location Parameters". "YANG Geographic Location Parameters" registry.
This registry allocates names for standard geodetic systems. Often This registry allocates names for standard geodetic systems. Often,
these values are referred to using multiple names (e.g., full names these values are referred to using multiple names (e.g., full names
or multiple acronyms). The intent of this registry is to provide a or multiple acronyms). The intent of this registry is to provide a
single standard value for any given geodetic system. single standard value for any given geodetic system.
The values SHOULD use an acronym when available, they MUST be The values SHOULD use an acronym when available, they MUST be
converted to lower case, and spaces MUST be changed to dashes "-". converted to lowercase, and spaces MUST be changed to dashes "-".
Each entry should be sufficient to define the 2 coordinate values, Each entry should be sufficient to define the two coordinate values
and to define height if height is required. So, for example, the 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 'wgs-84' is defined as WGS-84 with the geoid updated by at least
[EGM96] for height values. Specific entries for [EGM96] and [EGM08] [EGM96] for height values. Specific entries for [EGM96] and [EGM08]
are present if a more precise definition of the data is required. are present if a more precise definition of the data is required.
It should be noted that [RFC5870] also creates a registry for It should be noted that [RFC5870] also created a registry for
Geodetic Systems (it calls CRS); however, this registry has a very geodetic systems (the "'geo' URI 'crs' Parameter Values" registry);
strict modification policy. The authors of [RFC5870] have the stated however, this registry has a very strict modification policy. The
goal of making CRS registration hard to avoid proliferation of CRS authors of [RFC5870] have the stated goal of making CRS registration
values. As our module defines alternate systems and has a broader hard to avoid proliferation of CRS values. As our module defines
(beyond Earth) scope, the registry defined below is meant to be more alternate systems and has a broader scope (i.e., beyond Earth), the
easily modified. registry defined below is meant to be more easily modified.
The allocation policy for this registry is First Come, First Served, The allocation policy for this registry is First Come First Served
[RFC8126] as the intent is simply to avoid duplicate values. [RFC8126], as the intent is simply to avoid duplicate values.
The Reference value can either be a document or a contact person as 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 in [RFC8126]. The Change Controller (i.e., Owner) is also
defined by [RFC8126]. defined by [RFC8126].
The initial values for this registry are as follows. They include The initial values for this registry are as follows. They include
the non-Earth based geodetic-datum value for the moon based on [ME]. the non-Earth-based geodetic-datum value for the Moon based on
[MEAN-EARTH].
+-----------+------------------------------+-----------+---------+ +===========+==================+===========+===================+
| Name | Description | Reference | Change | | Name | Description | Reference | Change Controller |
+-----------+------------------------------+-----------+---------+ +===========+==================+===========+===================+
| | | /Contact | Control | | me | Mean Earth/Polar | RFC 9179 | IETF |
+===========+==============================+===========+=========+ | | Axis (Moon) | | |
| me | Mean Earth/Polar Axis (Moon) | this | IESG | +-----------+------------------+-----------+-------------------+
+-----------+------------------------------+-----------+---------+ | wgs-84-96 | World Geodetic | RFC 9179 | IETF |
| wgs-84-96 | World Geodetic System 1984 | this | IESG | | | System 1984 | | |
+-----------+------------------------------+-----------+---------+ +-----------+------------------+-----------+-------------------+
| wgs-84-08 | World Geodetic System 1984 | this | IESG | | wgs-84-08 | World Geodetic | RFC 9179 | IETF |
+-----------+------------------------------+-----------+---------+ | | System 1984 | | |
| wgs-84 | World Geodetic System 1984 | this | IESG | +-----------+------------------+-----------+-------------------+
+-----------+------------------------------+-----------+---------+ | wgs-84 | World Geodetic | RFC 9179 | IETF |
| | System 1984 | | |
+-----------+------------------+-----------+-------------------+
Table 3 Table 3
6.2. Updates to the IETF XML Registry 6.2. Updates to the IETF XML Registry
This document registers a URI in the "IETF XML Registry" [RFC3688]. This document registers a URI in the "IETF XML Registry" [RFC3688].
Following the format in [RFC3688], the following registration has Following the format in [RFC3688], the following registration has
been made: been made:
URI urn:ietf:params:xml:ns:yang:ietf-geo-location URI: urn:ietf:params:xml:ns:yang:ietf-geo-location
Registrant Contact: The IESG.
Registrant Contact The IESG. XML: N/A; the requested URI is an XML namespace.
XML N/A; the requested URI is an XML namespace.
6.3. Updates to the YANG Module Names Registry 6.3. Updates to the YANG Module Names Registry
This document registers one YANG module in the "YANG Module Names" This document registers one YANG module in the "YANG Module Names"
registry [RFC6020]. Following the format in [RFC6020], the following registry [RFC6020]. Following the format in [RFC6020], the following
registration has been made: registration has been made:
name ietf-geo-location Name: ietf-geo-location
Maintained by IANA: N
namespace urn:ietf:params:xml:ns:yang:ietf-geo-location Namespace: urn:ietf:params:xml:ns:yang:ietf-geo-location
Prefix: geo
prefix geo Reference: RFC 9179
reference RFC XXXX (RFC Ed.: replace XXXX with RFC number and remove
this note.)
7. Security Considerations 7. Security Considerations
The YANG module specified in this document defines a schema for data The YANG module specified in this document defines a schema for data
that is designed to be accessed via network management protocols such that is designed to be accessed via network management protocols such
as NETCONF [RFC6241] or RESTCONF [RFC8040]. The lowest NETCONF layer as the Network Configuration Protocol (NETCONF) [RFC6241] or RESTCONF
is the secure transport layer, and the mandatory-to-implement secure [RFC8040]. The lowest NETCONF layer is the secure transport layer,
transport is Secure Shell (SSH) [RFC6242]. The lowest RESTCONF layer and the mandatory-to-implement secure transport is Secure Shell (SSH)
is HTTPS, and the mandatory-to-implement secure transport is TLS [RFC6242]. The lowest RESTCONF layer is HTTPS, and the mandatory-to-
[RFC8446]. implement secure transport is TLS [RFC8446].
The NETCONF access control model [RFC8341] provides the means to The NETCONF access control model [RFC8341] provides the means to
restrict access for particular NETCONF or RESTCONF users to a restrict access for particular NETCONF or RESTCONF users to a
preconfigured subset of all available NETCONF or RESTCONF protocol preconfigured subset of all available NETCONF or RESTCONF protocol
operations and content. operations and content.
Since the modules defined in this document only define groupings, Since the modules defined in this document only define groupings,
these considerations are primarily for the designers of other modules these considerations are primarily for the designers of other modules
that use these groupings. that use these groupings.
skipping to change at page 20, line 12 skipping to change at line 867
important to control read access (e.g., via get, get-config, or important to control read access (e.g., via get, get-config, or
notification) to these data nodes. notification) to these data nodes.
Since the grouping defined in this module identifies locations, Since the grouping defined in this module identifies locations,
authors using this grouping SHOULD consider any privacy issues that authors using this grouping SHOULD consider any privacy issues that
may arise when the data is readable (e.g., customer device locations, may arise when the data is readable (e.g., customer device locations,
etc). etc).
8. Normative References 8. Normative References
[EGM08] Pavlis, N.K., Holmes, S.A., Kenyon, S.C., and J.K. Factor, [EGM08] Pavlis, N., Holmes, S., Kenyon, S., and J. Factor, "An
"An Earth Gravitational Model to Degree 2160: EGM08.", Earth Gravitational Model to Degree 2160: EGM08.",
Presented at the 2008 General Assembly of the European Presented at the 2008 General Assembly of the European
Geosciences Union, Vienna, Arpil13-18, 2008, 2008. Geosciences Union, Vienna, April 2008.
[EGM96] Lemoine, F.G., Kenyon, S.C., Factor, J.K., Trimmer, R.G., [EGM96] Lemoine, F., Kenyon, S., Factor, J., Trimmer, R., Pavlis,
Pavlis, N.K., Chinn, D.S., Cox, C.M., Klosko, S.M., N., Chinn, D., Cox, C., Klosko, S., Luthcke, S., Torrence,
Luthcke, S.B., Torrence, M.H., Wang, Y.M., Williamson, M., Wang, Y., Williamson, R., Pavlis, E., Rapp, R., and T.
R.G., Pavlis, E.C., Rapp, R.H., and T.R. Olson, "The Olson, "The Development of the Joint NASA GSFC and the
Development of the Joint NASA GSFC and the National National Imagery and Mapping Agency (NIMA) Geopotential
Imagery and Mapping Agency (NIMA) Geopotential Model Model EGM96.", NASA/TP-1998-206861, July 1998.
EGM96.", Technical Report NASA/TP-1998-206861, NASA,
Greenbelt., 1998.
[ISO.6709.2008] [ISO.6709.2008]
International Organization for Standardization, "ISO International Organization for Standardization, "Standard
6709:2008 Standard representation of geographic point representation of geographic point location by
location by coordinates.", 2008. coordinates", ISO 6709:2008, 2008.
[ME] National Aeronautics and Space Administration, Goddard [MEAN-EARTH]
Space Flight Center., "A Standardized Lunar Coordinate NASA, "A Standardized Lunar Coordinate System for the
System for the Lunar Reconnaissance Orbiter, Version 4.", Lunar Reconnaissance Orbiter", Version 4, Goddard Space
14 May 2008. Flight Center, May 2008.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997, DOI 10.17487/RFC2119, March 1997,
<https://www.rfc-editor.org/info/rfc2119>. <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", [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types",
RFC 6991, DOI 10.17487/RFC6991, July 2013, RFC 6991, DOI 10.17487/RFC6991, July 2013,
<https://www.rfc-editor.org/info/rfc6991>. <https://www.rfc-editor.org/info/rfc6991>.
[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF
2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017,
May 2017, <https://www.rfc-editor.org/info/rfc8174>. <https://www.rfc-editor.org/info/rfc8040>.
[RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for
Writing an IANA Considerations Section in RFCs", BCP 26, Writing an IANA Considerations Section in RFCs", BCP 26,
RFC 8126, DOI 10.17487/RFC8126, June 2017, RFC 8126, DOI 10.17487/RFC8126, June 2017,
<https://www.rfc-editor.org/info/rfc8126>. <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., [RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K.,
and R. Wilton, "Network Management Datastore Architecture and R. Wilton, "Network Management Datastore Architecture
(NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018, (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018,
<https://www.rfc-editor.org/info/rfc8342>. <https://www.rfc-editor.org/info/rfc8342>.
[WGS84] National Imagery and Mapping Agency., "National Imagery [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol
and Mapping Agency Technical Report 8350.2, Third Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018,
Edition.", 3 January 2000. <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 9. Informative References
[ISO.19136.2007] [ISO.19136.2007]
International Organization for Standardization, "ISO International Organization for Standardization,
19136:2007 Geographic information -- Geography Markup "Geographic information -- Geography Markup Language
Language (GML)". (GML)", ISO 19136:2007.
[KML22] Wilson, T., Ed., "OGC KML (Version 2.2)", 14 April 2008, [KML22] Wilson, T., Ed., "OGC KML", Version 2.2, April 2008,
<http://portal.opengeospatial.org/ <https://portal.opengeospatial.org/
files/?artifact_id=27810>. files/?artifact_id=27810>.
[KML23] Burggraf, D., Ed., "OGC KML 2.3", 4 August 2015, [KML23] Burggraf, D., Ed., "OGC KML", Version 2.3, August 2015,
<http://docs.opengeospatial.org/ <https://docs.opengeospatial.org/
is/12-007r2/12-007r2.html>. 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, [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688,
DOI 10.17487/RFC3688, January 2004, DOI 10.17487/RFC3688, January 2004,
<https://www.rfc-editor.org/info/rfc3688>. <https://www.rfc-editor.org/info/rfc3688>.
[RFC5870] Mayrhofer, A. and C. Spanring, "A Uniform Resource [RFC5870] Mayrhofer, A. and C. Spanring, "A Uniform Resource
Identifier for Geographic Locations ('geo' URI)", Identifier for Geographic Locations ('geo' URI)",
RFC 5870, DOI 10.17487/RFC5870, June 2010, RFC 5870, DOI 10.17487/RFC5870, June 2010,
<https://www.rfc-editor.org/info/rfc5870>. <https://www.rfc-editor.org/info/rfc5870>.
[RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for
the Network Configuration Protocol (NETCONF)", RFC 6020, the Network Configuration Protocol (NETCONF)", RFC 6020,
DOI 10.17487/RFC6020, October 2010, DOI 10.17487/RFC6020, October 2010,
<https://www.rfc-editor.org/info/rfc6020>. <https://www.rfc-editor.org/info/rfc6020>.
[RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed.,
and A. Bierman, Ed., "Network Configuration Protocol
(NETCONF)", RFC 6241, DOI 10.17487/RFC6241, 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", [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language",
RFC 7950, DOI 10.17487/RFC7950, August 2016, RFC 7950, DOI 10.17487/RFC7950, August 2016,
<https://www.rfc-editor.org/info/rfc7950>. <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", [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams",
BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018,
<https://www.rfc-editor.org/info/rfc8340>. <https://www.rfc-editor.org/info/rfc8340>.
[RFC8341] Bierman, A. and M. Bjorklund, "Network Configuration [W3CGEO] Popescu, A., "Geolocation API Specification", 2nd Edition,
Access Control Model", STD 91, RFC 8341, November 2016, <https://www.w3.org/TR/2016/REC-
DOI 10.17487/RFC8341, March 2018, geolocation-API-20161108/>.
<https://www.rfc-editor.org/info/rfc8341>.
[RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol
Version 1.3", RFC 8446, DOI 10.17487/RFC8446, 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 Appendix A. Examples
Below is a fictitious module that uses the geo-location grouping. Below is a fictitious module that uses the geo-location grouping.
module example-uses-geo-location { module example-uses-geo-location {
namespace namespace
"urn:example:example-uses-geo-location"; "urn:example:example-uses-geo-location";
prefix ugeo; prefix ugeo;
import ietf-geo-location { prefix geo; } import ietf-geo-location { prefix geo; }
organization "Empty Org"; organization "Empty Org";
contact "Example Author <eauthor@example.com>"; contact "Example Author <eauthor@example.com>";
description "Example use of geo-location"; description
revision 2019-02-02 { reference "None"; } "Example use of geo-location";
revision 2022-2-7 { reference "None"; }
container locatable-items { container locatable-items {
description "container of locatable items"; description
"The container of locatable items";
list locatable-item { list locatable-item {
key name; key name;
description "A locatable item"; description
"A locatable item";
leaf name { leaf name {
type string; type string;
description "name of locatable item"; description
"The name of locatable item";
} }
uses geo:geo-location; uses geo:geo-location;
} }
} }
} }
Figure 2: Example YANG module using geo location. Figure 2: Example YANG Module Using Geolocation
Below is the YANG tree for the fictitious module that uses the geo- Below is the YANG tree for the fictitious module that uses the geo-
location grouping. location grouping.
module: example-uses-geo-location module: example-uses-geo-location
+--rw locatable-items +--rw locatable-items
+--rw locatable-item* [name] +--rw locatable-item* [name]
+--rw name string +--rw name string
+--rw geo-location +--rw geo-location
+--rw reference-frame +--rw reference-frame
skipping to change at page 24, line 34 skipping to change at line 1048
| +--rw x? decimal64 | +--rw x? decimal64
| +--rw y? decimal64 | +--rw y? decimal64
| +--rw z? decimal64 | +--rw z? decimal64
+--rw velocity +--rw velocity
| +--rw v-north? decimal64 | +--rw v-north? decimal64
| +--rw v-east? decimal64 | +--rw v-east? decimal64
| +--rw v-up? decimal64 | +--rw v-up? decimal64
+--rw timestamp? yang:date-and-time +--rw timestamp? yang:date-and-time
+--rw valid-until? 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 Below is some example YANG XML data for the fictitious module that
uses the geo-location grouping. uses the geo-location grouping.
<locatable-items xmlns="urn:example:example-uses-geo-location"> <locatable-items xmlns="urn:example:example-uses-geo-location">
<locatable-item> <locatable-item>
<name>Gaetana's</name> <name>Gaetana's</name>
<geo-location> <geo-location>
<latitude>40.73297</latitude> <latitude>40.73297</latitude>
<longitude>-74.007696</longitude> <longitude>-74.007696</longitude>
</geo-location> </geo-location>
skipping to change at page 25, line 41 skipping to change at line 1105
<reference-frame> <reference-frame>
<astronomical-body>moon</astronomical-body> <astronomical-body>moon</astronomical-body>
<geodetic-system> <geodetic-system>
<geodetic-datum>me</geodetic-datum> <geodetic-datum>me</geodetic-datum>
</geodetic-system> </geodetic-system>
</reference-frame> </reference-frame>
</geo-location> </geo-location>
</locatable-item> </locatable-item>
</locatable-items> </locatable-items>
Figure 3: Example XML data of geo location use. Figure 4: Example XML Data of Geolocation Use
Appendix B. Acknowledgments Acknowledgments
We would like to thank Jim Biard and Ben Koziol for their reviews and We would like to thank Jim Biard and Ben Koziol for their reviews and
suggested improvements. We would also like to thank Peter Lothberg suggested improvements. We would also like to thank Peter Lothberg
for the motivation as well as help in defining a broadly useful for the motivation as well as help in defining a broadly useful
geographic location object, and Acee Lindem and Qin Wu for their work geographic location object as well as Acee Lindem and Qin Wu for
on a geographic location object that led to this documents' creation. their work on a geographic location object that led to this
We would also like to thank the document shepherd Kent Watsen. document's creation. We would also like to thank the Document
Shepherd Kent Watsen.
Author's Address Author's Address
Christian Hopps Christian Hopps
LabN Consulting, L.L.C. LabN Consulting, L.L.C.
Email: chopps@chopps.org Email: chopps@chopps.org
 End of changes. 135 change blocks. 
395 lines changed or deleted 399 lines changed or added

This html diff was produced by rfcdiff 1.48. The latest version is available from http://tools.ietf.org/tools/rfcdiff/