draft-ietf-netmod-geo-location-03.txt   draft-ietf-netmod-geo-location-04.txt 
Network Working Group C. Hopps Network Working Group C. Hopps
Internet-Draft LabN Consulting, L.L.C. Internet-Draft LabN Consulting, L.L.C.
Intended status: Standards Track 13 February 2020 Intended status: Standards Track 1 March 2020
Expires: 16 August 2020 Expires: 2 September 2020
YANG Geo Location A YANG Grouping for Geographic Locations
draft-ietf-netmod-geo-location-03 draft-ietf-netmod-geo-location-04
Abstract Abstract
This document defines a generic geographical location object YANG This document defines a generic geographical location object YANG
grouping. The geographical location grouping is intended to be used grouping. The geographical location grouping is intended to be used
in YANG models for specifying a location on or in reference to the in YANG models for specifying a location on or in reference to the
Earth or any other astronomical object. Earth or any other astronomical object.
Status of This Memo Status of This Memo
skipping to change at page 1, line 33 skipping to change at page 1, line 33
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at https://datatracker.ietf.org/drafts/current/. Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on 16 August 2020. This Internet-Draft will expire on 2 September 2020.
Copyright Notice Copyright Notice
Copyright (c) 2020 IETF Trust and the persons identified as the Copyright (c) 2020 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 (https://trustee.ietf.org/
license-info) in effect on the date of publication of this document. license-info) in effect on the date of publication of this document.
Please review these documents carefully, as they describe your rights Please review these documents carefully, as they describe your rights
skipping to change at page 3, line 28 skipping to change at page 3, line 28
2. The Geo Location Object 2. The Geo Location 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 The Earth or Mars, a astronomical body. It could be a planet such as The Earth or Mars, a
moon such as Enceladus, an asteroid such as Ceres, or even a comet 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".
skipping to change at page 13, line 28 skipping to change at page 13, line 28
all the location values. As the URI is a string, all values are all the location values. As the URI is a string, all values are
specifies as strings and so are capable of as much precision as specifies as strings and so are capable of as much precision as
required. 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
See https://w3c.github.io/geolocation-api/#dom-geolocationposition.
W3C Defines a geo-location API in [W3CGEO]. We show a snippet of W3C Defines a geo-location API in [W3CGEO]. We show a snippet of
code below which defines the geo-location data for this API. This is code below which defines the geo-location data for this API. This is
used by many application (e.g., Google Maps API). used by many application (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? speed; readonly attribute double? speed;
}; };
Figure 1: Snippet Showing Geo-Location Definition Figure 1: Snippet Showing Geo-Location Definition
5.1.2.1. Compare with YANG Model 5.1.2.1. Compare with YANG Model
+------------------+--------------+-----------------+-------------+ +------------------+--------------+-----------------+-------------+
| Field | Type | YANG | Type | | Field | Type | YANG | Type |
+==================+==============+=================+=============+ +==================+==============+=================+=============+
| accuracy | double | coord-accuracy | dec64 fr 6 | | accuracy | double | coord-accuracy | dec64 fr 6 |
+------------------+--------------+-----------------+-------------+ +------------------+--------------+-----------------+-------------+
skipping to change at page 16, line 8 skipping to change at page 16, line 8
"gml:validTime" can either be an Instantaneous measure "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 using the seconds for "gml:TimePeriod" can be mapped using the using the
"valid-for" node of the YANG grouping. "valid-for" 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 Open Geospatial Consortium (OGC) Google to the Open Geospatial Consortium,
https://www.opengeospatial.org/ and was adopted. The latest version (https://www.opengeospatial.org/) and was adopted. The latest
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 [W3CGEO] values. The timestamp value is also
specified as a string as in our YANG grouping. 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 useful for
visualization software, "kml:altitudeMode". These values for visualization software, "kml:altitudeMode". These values for
"kml:altitudeMode" include indicating the height is ignored "kml:altitudeMode" include indicating the height is ignored
("clampToGround"), in relation to the location's ground level ("clampToGround"), in relation to the location's ground level
("relativeToGround"), or in relation to the geodetic datum ("relativeToGround"), or in relation to the geodetic datum
skipping to change at page 18, line 34 skipping to change at page 18, line 34
[ISO.6709.2008] [ISO.6709.2008]
International Organization for Standardization, "ISO International Organization for Standardization, "ISO
6709:2008 Standard representation of geographic point 6709:2008 Standard representation of geographic point
location by coordinates.", 2008. location by coordinates.", 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>.
[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
May 2017, <https://www.rfc-editor.org/info/rfc8174>.
[RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for [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>.
[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 [WGS84] National Imagery and Mapping Agency., "National Imagery
and Mapping Agency Technical Report 8350.2, Third and Mapping Agency Technical Report 8350.2, Third
Edition.", 3 January 2000, <http://earth- Edition.", 3 January 2000,
info.nga.mil/GandG/publications/tr8350.2/wgs84fin.pdf>. <http://earth-info.nga.mil/GandG/publications/tr8350.2/
wgs84fin.pdf>.
9. Informative References 9. Informative References
[ISO.19136.2007] [ISO.19136.2007]
International Organization for Standardization, "ISO International Organization for Standardization, "ISO
19136:2007 Geographic information -- Geography Markup 19136:2007 Geographic information -- Geography Markup
Language (GML)". Language (GML)", March 2020.
[KML22] Wilson, T., Ed., "OGC KML (Version 2.2)", 14 April 2008, [KML22] Wilson, T., Ed., "OGC KML (Version 2.2)", 14 April 2008,
<http://portal.opengeospatial.org/ <http://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 2.3", 4 August 2015,
<http://docs.opengeospatial.org/ <http://docs.opengeospatial.org/
is/12-007r2/12-007r2.html>. is/12-007r2/12-007r2.html>.
[RFC5870] Mayrhofer, A. and C. Spanring, "A Uniform Resource [RFC5870] Mayrhofer, A. and C. Spanring, "A Uniform Resource
skipping to change at page 19, line 34 skipping to change at page 19, line 34
[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>.
[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>.
[W3CGEO] Popescu, A., "Geolocation API Specification", 8 November [W3CGEO] Popescu, A., "Geolocation API Specification", 8 November
2016, <https://www.w3.org/TR/2016/REC-geolocation-API- 2016, <https://www.w3.org/TR/2016/
20161108/>. 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 "Example use of geo-location";
revision 2019-02-02 { reference "None"; } revision 2019-02-02 { reference "None"; }
container locatable-items { container locatable-items {
description "container of locatable items"; description "container of locatable items";
list locatable-item { list locatable-item {
key name; key name;
description "A of locatable item"; description "A of locatable item";
leaf name { leaf name {
type string; type string;
description "name of locatable item"; description "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 geo location.
Below is a the YANG tree for the fictitious module that uses the geo- Below is a 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
skipping to change at page 21, line 36 skipping to change at page 21, line 36
+--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? types:date-and-time +--rw timestamp? types:date-and-time
+--rw valid-until? types:date-and-time +--rw valid-until? types:date-and-time
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>
</locatable-item> </locatable-item>
<locatable-item> <locatable-item>
<name>Pont des Arts</name> <name>Pont des Arts</name>
<geo-location> <geo-location>
<timestamp>2012-03-31T16:00:00Z</timestamp> <timestamp>2012-03-31T16:00:00Z</timestamp>
<latitude>48.8583424</latitude> <latitude>48.8583424</latitude>
<longitude>2.3375084</longitude> <longitude>2.3375084</longitude>
<height>35</height> <height>35</height>
</geo-location> </geo-location>
</locatable-item> </locatable-item>
<locatable-item> <locatable-item>
<name>Saint Louis Cathedral</name> <name>Saint Louis Cathedral</name>
<geo-location> <geo-location>
<timestamp>2013-10-12T15:00:00-06:00</timestamp> <timestamp>2013-10-12T15:00:00-06:00</timestamp>
<latitude>29.9579735</latitude> <latitude>29.9579735</latitude>
<longitude>-90.0637281</longitude> <longitude>-90.0637281</longitude>
</geo-location> </geo-location>
</locatable-item> </locatable-item>
<locatable-item> <locatable-item>
<name>Apollo 11 Landing Site</name> <name>Apollo 11 Landing Site</name>
<geo-location> <geo-location>
<timestamp>1969-07-21T02:56:15Z</timestamp> <timestamp>1969-07-21T02:56:15Z</timestamp>
<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>
<latitude>0.67409</latitude> <latitude>0.67409</latitude>
<longitude>23.47298</longitude> <longitude>23.47298</longitude>
</geo-location> </geo-location>
</locatable-item> </locatable-item>
<locatable-item> <locatable-item>
<name>Reference Frame Only</name> <name>Reference Frame Only</name>
<geo-location> <geo-location>
<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 3: Example XML data of geo location use.
Appendix B. Acknowledgements Appendix B. Acknowledgements
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, and Acee Lindem and Qin Wu for their work
on a geographic location object that led to this documents creation. on a geographic location object that led to this documents creation.
 End of changes. 16 change blocks. 
105 lines changed or deleted 104 lines changed or added

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