draft-ietf-netmod-geo-location-05.txt   draft-ietf-netmod-geo-location-06.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 29 July 2020 Intended status: Standards Track 2 December 2020
Expires: 30 January 2021 Expires: 5 June 2021
A YANG Grouping for Geographic Locations A YANG Grouping for Geographic Locations
draft-ietf-netmod-geo-location-05 draft-ietf-netmod-geo-location-06
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 Earth
Earth or any other astronomical object. or any other astronomical object.
Status of This Memo Status of This Memo
This Internet-Draft is submitted in full conformance with the This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79. provisions of BCP 78 and BCP 79.
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 30 January 2021. This Internet-Draft will expire on 5 June 2021.
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 2, line 43 skipping to change at page 2, line 43
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 24 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 24
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 center, 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 The Earth, Additionally, while this location is typically relative to Earth, it
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 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 of the above data to be captured. all of the above data to be captured.
skipping to change at page 3, line 27 skipping to change at page 3, line 27
"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, [RFC2119] [RFC8174] when, and only when, they appear in all capitals,
as shown here. as shown here.
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 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
skipping to change at page 4, line 52 skipping to change at page 4, line 52
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 infrequently updated this velocity vector can track very slow is 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 the Earth (or another astronomical body). somewhere on or relative to Earth (or another astronomical body). At
least two options are available to YANG models that wish to use this
At least two options are available to YANG models that wish to use grouping with objects that are changing location frequently in non-
this grouping with objects that are changing location frequently in simple ways, they can add additional motion data to their model
non-simple ways, they can add additional motion data to their model
directly, or if the application allows it can require more frequent directly, or if the application allows it can require more frequent
queries to keep the location data current. 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 which
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
skipping to change at page 6, line 33 skipping to change at page 6, line 33
| +-- z? decimal64 | +-- z? decimal64
+-- 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]. This model imports Common YANG Data Types [RFC6991]. It uses YANG
version 1.1 [RFC7950]
<CODE BEGINS> file "ietf-geo-location@2019-02-17.yang" <CODE BEGINS> file "ietf-geo-location@2019-02-17.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.";
} }
skipping to change at page 7, line 8 skipping to change at page 7, line 8
"IETF NETMOD Working Group (NETMOD)"; "IETF NETMOD Working Group (NETMOD)";
contact contact
"Christian Hopps <chopps@chopps.org>"; "Christian Hopps <chopps@chopps.org>";
// RFC Ed.: replace XXXX with actual RFC number or IANA reference // RFC Ed.: replace XXXX with actual RFC number or IANA reference
// and remove this note. // 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.,
The Earth). 'earth').
Copyright (c) 2019 IETF Trust and the persons identified as Copyright (c) 2019 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 Simplified BSD License set
forth in Section 4.c of the IETF Trust's Legal Provisions forth in Section 4.c 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 XXXX
(https://www.rfc-editor.org/info/rfcXXXX); see the RFC itself (https://www.rfc-editor.org/info/rfcXXXX); see the RFC itself
for full legal notices. for full legal notices.
// RFC Ed.: replace XXXX with actual RFC number or IANA reference // RFC Ed.: replace XXXX with the actual RFC number or IANA
// and remove this note. // reference and remove this note.
The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL
NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'NOT RECOMMENDED', NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'NOT RECOMMENDED',
'MAY', and 'OPTIONAL' in this document are to be interpreted as 'MAY', and 'OPTIONAL' in this document are to be interpreted as
described in BCP 14 (RFC 2119) (RFC 8174) when, and only when, described in BCP 14 (RFC 2119) (RFC 8174) when, and only when,
they appear in all capitals, as shown here."; they appear in all capitals, as shown here.";
revision 2019-02-17 { revision 2019-02-17 {
description "Initial Revision"; description "Initial Revision";
reference "RFC XXXX: A YANG Grouping for Geographic Locations"; reference "RFC XXXX: A YANG Grouping for Geographic Locations";
skipping to change at page 7, line 50 skipping to change at page 7, line 50
"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., the 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
skipping to change at page 11, line 15 skipping to change at page 11, line 15
reference reference
"RFC XXXX: A YANG Grouping for Geographic Locations"; "RFC XXXX: 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~."; truth 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 truth-north as defined by the ~geodetic-system~."; to truth-north as defined by the geodetic-system.";
} }
leaf v-up { leaf v-up {
type decimal64 { type decimal64 {
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.";
skipping to change at page 12, line 50 skipping to change at page 12, line 50
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 is
also not required for conformance. 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 have
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 The Earth, and to utilize entirely different coordinate systems than Earth, and to utilize entirely different coordinate systems and
and realities. realities.
Many systems make use of geo-location data, and so it's important to Many systems make use of geo-location data, and so it's important to
be able describe this data using this geo-location object defined in be able describe this data using this geo-location object defined in
this document. this document.
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 and were considered. following standards and standard APIs and were considered.
skipping to change at page 15, line 9 skipping to change at page 15, line 9
timestamp (DOMTimeStamp) Specifies milliseconds since the Unix EPOCH timestamp (DOMTimeStamp) Specifies milliseconds since the Unix EPOCH
in 64 bit unsigned integer. The YANG model defines the timestamp in 64 bit unsigned integer. The YANG model defines the timestamp
with arbitrarily large precision by using a string which with arbitrarily large precision by using a string which
encompasses all representable values of this timestamp value. 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 The 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 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. This
sequence of values represent coordinates in a given CRS. The CRS is sequence of values represent coordinates in a given CRS. The CRS is
skipping to change at page 16, line 48 skipping to change at page 16, line 48
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" IANA is asked to create a new registry "Geodetic System Values" under
grouped under a new category named "YANG Geographic Location a new protocol category group "YANG Geographic Location Parameters".
Parameters".
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 values). The intent of this registry is to or multiple acronyms values). The intent of this registry is to
provide a single standard value for any given geodetic system. provide a 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 lower case, and spaces MUST be changed to dashes "-".
Each entry should be sufficient to define the 3 coordinate values (2 Each entry should be sufficient to define the 3 coordinate values (2
if height is not required). So for example the "wgs-84" is defined if height is not required). So for example the "wgs-84" is defined
as WGS-84 with the geoid updated by at least [EGM96] for height as WGS-84 with the geoid updated by at least [EGM96] for height
values. Specific entries for [EGM96] and [EGM08] are present if a values. Specific entries for [EGM96] and [EGM08] are present if a
more precise definition of the data is required. 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 creates a registry for
Geodetic Systems (it calls CRS); however, this registry has a very Geodetic Systems (it calls CRS); however, this registry has a very
strict modification policy. The authors of [RFC5870] have the stated strict modification policy. The authors of [RFC5870] have the stated
goal of making CRS registration hard to avoid proliferation of CRS goal of making CRS registration hard to avoid proliferation of CRS
values. As our module defines alternate systems and has a broader values. As our module defines alternate systems and has a broader
(beyond earth) scope, the registry defined below is meant to be more (beyond Earth) scope, the registry defined below is meant to be more
easily modified. 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 initial values for this registry are as follows. The initial values for this registry are as follows.
+------------+------------------------------------------------------+ +------------+------------------------------------------------------+
| Name | Description | | Name | Description |
+============+======================================================+ +============+======================================================+
skipping to change at page 18, line 29 skipping to change at page 18, line 29
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
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 XXXX (RFC Ed.: replace XXX with actual RFC number and reference RFC XXXX (RFC Ed.: replace XXXX with RFC number and remove
remove this note.) 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 NETCONF [RFC6241] or RESTCONF [RFC8040]. The lowest NETCONF layer
is the secure transport layer, and the mandatory-to-implement secure is the secure transport layer, and the mandatory-to-implement secure
transport is Secure Shell (SSH) [RFC6242]. The lowest RESTCONF layer transport is Secure Shell (SSH) [RFC6242]. The lowest RESTCONF layer
is HTTPS, and the mandatory-to-implement secure transport is TLS is HTTPS, and the mandatory-to-implement secure transport is TLS
[RFC8446]. [RFC8446].
 End of changes. 18 change blocks. 
30 lines changed or deleted 29 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/