LabN Consulting, L.L.C.

chopps@chopps.org

This document defines a generic geographical location object YANG grouping. The geographical location grouping is intended to be used in YANG models for specifying a location on or in reference to the Earth or any other astronomical object.

In many applications we would like to specify the location of something geographically. Some examples of locations in networking might be the location of data center, a rack in an internet exchange point, a router, a firewall, a port on some device, or it could be the endpoints of a fiber, or perhaps the failure point along a fiber. Additionally, while this location is typically relative to The Earth, it does not need to be. Indeed it is easy to imagine a network or device located on The Moon, on Mars, on Enceladus (the moon of Saturn) or even a comet (e.g., 67p/churyumov-gerasimenko). Finally, one can imagine defining locations using a different frames of reference or even alternate systems (e.g., a simulations or virtual realities). This document defines a geo-location YANG grouping that allows for all of the above data to be captured. This specification conforms to . The YANG data model described in this document conforms to the Network Management Datastore Architecture defined in .

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 when, and only when, they appear in all capitals, as shown here.

The frame of reference (reference-frame) defines what the location values refer to and their meaning. The referred to object can be any astronomical body. It could be a planet such as The Earth or Mars, a moon such as Enceladus, an asteroid such as Ceres, or even a comet such as 1P/Halley. This value is specified in astronomical-body and is defined by the International Astronomical Union (), The default astronomical-body value is earth. In addition to identifying the astronomical body we also need to define the meaning of the coordinates (e.g., latitude and longitude) and the definition of 0-height. This is done with a geodetic-datum value. The default value for geodetic-datum is wgs-84 (i.e., the World Geodetic System, ), which is used by the Global Positioning System (GPS) among many others. We define an IANA registry for specifying standard values for the geodetic-datum. In addition to the geodetic-datum value we allow refining the coordinate and height accuracy using coord-accuracy and height-accuracy respectively. When specified these values override the defaults implied by the geodetic-datum value. Finally, we define an optional feature which allows for changing the system for which the above values are defined. This optional feature adds an alternate-system value to the reference frame. This value is normally not present which implies the natural universe is the system. The use of this value is intended to allow for creating virtual realities or perhaps alternate coordinate systems. The definition of alternate systems is outside the scope of this document.

This is the location on or relative to the astronomical object. It is specified using 2 or 3 coordinates values. These values are given either as latitude, longitude, and an optional height, or as Cartesian coordinates of x, y and an optional z. For the standard location choice latitude and longitude are specified as fractions of decimal degrees, and the height value is in fractions of meters. For the Cartesian choice x, y and z are in fractions of meters. In both choices the exact meanings of all of the values are defined by the geodetic-datum value in the .

Support is added for objects in relatively stable motion. For objects in relatively stable motion there are an additional 2 values to describe their velocity; these are heading and speed. The heading value is relative to true-north as defined by the reference-frame for the astronomical body. The speed value is in fractional meters per second. For some applications that demand high accuracy, and where the data is infrequently updated this value can track very slow movement such as continental drift.

The following is the YANG tree diagram for the geo-location grouping.

Geo Location YANG tree diagram.

"; // RFC Ed.: replace XXXX with actual RFC number and // remove this note. description "This module defines a grouping of a container object for specifying a location on or around an astronomical object (e.g., The Earth). Copyright (c) 2018 IETF Trust and the persons identified as authors of the code. All rights reserved. Redistribution and use in source and binary forms, with or without modification, is permitted pursuant to, and subject to the license terms contained in, the Simplified BSD License set forth in Section 4.c of the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info). The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here. This version of this YANG module is part of RFC XXXX (https://tools.ietf.org/html/rfcXXXX); see the RFC itself for full legal notices."; // RFC Ed.: replace XXXX with actual RFC number and // remove this note. revision 2019-02-17 { description "Initial Revision"; reference "RFC XXXX: YANG Geo Location"; } typedef degrees { type decimal64 { fraction-digits 16; } units "decimal degrees"; description "Coordinate value."; } feature alternate-systems { description "This feature means the device supports specifying locations using alternate systems for reference frames."; } grouping geo-location { description "Grouping to identify a location on an astronomical object."; container geo-location { description "A location on an astronomical body (e.g., The Earth) somewhere in a universe."; container reference-frame { description "The Frame of Reference for the location values."; leaf alternate-system { if-feature alternate-systems; type string; description "The system in which the astronomical body and geodetic-datum is defined. Normally, this value is not present and the system is the natural universe; however, when present this value allows for specifying alternate systems (e.g., virtual realities). An alternate-system modifies the definition (but not the type) of the other values in the reference frame."; } leaf astronomical-body { type string { pattern '[-0-9a-z #x22#x23#x5B#x5D' + '!$%&()*+,\./:;<=>?@\\^_`{|}~]+'; } default "earth"; description "An astronomical body as named by the International Astronomical Union (IAU) or according to the alternate system if specified. Examples include 'sun' (our star), 'earth' (our planet), 'moon' (our moon), 'enceladus' (a moon of Saturn), 'ceres' (an asteroid), '67p/churyumov-gerasimenko (a comet). The value should be comprised of all lower case ASCII characters not including control characters (i.e., values 32..64, and 91..126)"; } container geodetic-system { description "The geodetic system of the location data."; leaf geodetic-datum { type string { pattern '[-0-9a-z#x22#x23#x5B#x5D' + '!$%&()*+,\./:;<=>?@\\^_`{|}~]+'; } default "wgs-84"; description "A geodetic-datum defining the meaning of latitude, longitude and height. The default is 'wgs-84' which is used by the Global Positioning System (GPS)"; } leaf coord-accuracy { type decimal64 { fraction-digits 6; } description "The accuracy of the latitude longitude pair. When coord-accuracy is specified it overrides the geodetic-datum implied accuracy. If Cartesian coordinates are in use this accuracy corresponds to the X and Y components"; } leaf height-accuracy { type decimal64 { fraction-digits 6; } units "meters"; description "The accuracy of height value. When specified it overrides the geodetic-datum implied default. If Cartesian coordinates ar in use this accuracy corresponds to the Z component."; } } } choice location { mandatory true; description "The location data either in lat/long or Cartesian values"; case ellipsoid { leaf latitude { type degrees; mandatory true; description "The latitude value on the astronomical body. The definition and precision of this measurement is indicated by the reference-frame value."; } leaf longitude { type degrees; mandatory true; description "The longitude value on the astronomical body. The definition and precision of this measurement is indicated by the reference-frame."; } leaf height { type decimal64 { fraction-digits 6; } units "meters"; description "Height from a reference 0 value. The precision and '0' value is defined by the reference-frame."; } } case cartesian { leaf x { type decimal64 { fraction-digits 6; } mandatory true; description "The X value as defined by the reference-frame."; } leaf y { type decimal64 { fraction-digits 6; } mandatory true; description "The Y value as defined by the reference-frame."; } leaf z { type decimal64 { fraction-digits 6; } units "meters"; description "The Z value as defined by the reference-frame."; } } } container velocity { description "If the object is in motion the velocity describes this motion at the the time given by the timestamp."; leaf heading { type degrees; description "If the object is in motion then the heading will indicate the direction in which the object is currently moving. It is specified in fractions of degrees from true north of the astronomical object"; } leaf speed { type decimal64 { fraction-digits 12; } units "meters per second"; description "If the object is in motion then the speed will indicate the rate at which the object is currently traveling along it's heading."; } } leaf timestamp { type types:date-and-time; description "Reference time when location was recorded."; } } } } ]]>

provides an appendix with a set of tests for conformance to the standard. The tests and results are given in the following table along with an explanation of non-applicable tests. Conformance Test Results

Test	Description	Pass Explanation
A.1.2.1	elements reqd. for a geo. point location	CRS is always indicated
A.1.2.2	Description of a CRS from a register	CRS register is defined
A.1.2.3	definition of CRS	N/A - Don't define CRS
A.1.2.4	representation of horizontal position	lat/long values conform
A.1.2.5	representation of vertical position	height value conforms
A.1.2.6	text string representation	N/A - No string format

For test A.1.2.1 the YANG geo location object either includes a CRS (reference-frame) or has a default defined (). For A.1.2.3 we do not define our own CRS, and doing so is not required for conformance. For A.1.2.6 we do not define a text string representation, which is also not required for conformance.

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 includes the ability to locate things on astronomical bodies other than The Earth, and to utilize entirely different coordinate systems and realities. 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 this document.

In order to verify portability while developing this module the following standards and standard APIs and were considered.

defines a standard URI value for geographic location data. It includes the ability to specify the geodetic-value (it calls this crs) with the default being wgs-84 . For the location data it allows 2 to 3 coordinates defined by the crs value. For accuracy it has a single u parameter for specifying uncertainty. The u value is in fractions of meters and applies to all the location values. As the URI is a string, all values are specifies as strings and so are capable of as much precision as required. URI values can be mapped to and from the YANG grouping, with the caveat that some loss of precision (in the extremes) may occur due to the YANG grouping using decimal64 values rather than strings.

See . W3C Defines a geo-location API in . We show a snippet of code below which defines the geo-location data for this API. This is used by many application (e.g., Google Maps API).

Snippet Showing Geo-Location Definition

Field	Type	YANG	Type
accuracy	double	coord-accuracy	dec64 fr 6
altitude	double	height	dec64 fr 6
altitudeAccuracy	double	height-accuracy	dec64 fr 6
heading	double	heading	dec64 fr 16
latitude	double	latitude	dec64 fr 16
longitude	double	longitude	dec64 fr 16
speed	double	speed	dec64 fr 12
timestamp	DOMTimeStamp	timestamp	string

accuracy (double)

Accuracy of latitude and longitude values in meters.

altitude (double)

Optional height in meters above the ellipsoid.

altitudeAccuracy (double)

Optional accuracy of altitude value in meters.

heading (double)

Optional Direction in decimal deg from true north increasing clock-wise.

latitude, longitude (double)

Standard lat/long values in decimal degrees.

speed (double)

Speed along heading in meters per second.

timestamp (DOMTimeStamp)

Specifies milliseconds since the Unix EPOCH in 64 bit unsigned integer. The YANG model defines the timestamp with arbitrarily large precision by using a string which encompasses all representable values of this timestamp value.

W3C API values can be mapped to the YANG grouping, with the caveat that some loss of precision (in the extremes) may occur due to the YANG grouping using decimal64 values rather than doubles. Conversely, only YANG values for The Earth using the default wgs-84 as the geodetic-datum, can be directly mapped to the W3C values, as W3C does not provide the extra features necessary to map the broader set of values supported by the YANG grouping.

ISO adopted the Geography Markup Language (GML) defined by OGC 07-036 as . GML defines, among many other things, a position type gml:pos which is a sequence of double values. This sequence of values represent coordinates in a given CRS. The CRS is either inherited from containing elements or directly specified as attributes srsName and optionally srsDimension on the gml:pos. GML defines an Abstract CRS type which Concrete CRS types derive from. This allows for many types of CRS definitions. We are concerned with the Geodetic CRS type which can have either ellipsoidal or Cartesian coordinates. We believe that other non-Earth based CRS as well as virtual CRS should also be representable by the GML CRS types as well. Thus GML gml:pos values can be mapped directly to the YANG grouping, with the caveat that some loss of precision (in the extremes) may occur due to the YANG grouping using decimal64 values rather than doubles. Conversely, YANG grouping values can be mapped to GML as directly as the GML CRS available definitions allow with a minimum of Earth-based geodetic systems fully supported. GML also defines an observation value in gml:Observation which includes a timestamp value gml:validTime in addition to other components such as gml:using gml:target and gml:resultOf. Only the timestamp is mappable to and from the YANG grouping. Furthermore gml:validTime can either be an Instantaneous measure (gml:TimeInstant) or a time period (gml:TimePeriod). Only the instantaneous gml:TimeInstant is mappable to and from the YANG grouping.

KML 2.2 (formerly Keyhole Markup Language) was submitted by Google to Open Geospatial Consortium (OGC) and was adopted. The latest version as of this writing is KML 2.3 . This schema includes geographic location data in some of it's objects (e.g., <kml:Point or <kml:Camera> objects). This data is provided in string format and corresponds to the values. The timestamp value is also specified as a string as in our YANG grouping. KML has some special handling for the height value useful for visualization software, kml:altitudeMode. These values for kml:altitudeMode include indicating the height is ignored (clampToGround), in relation to the locations ground level (relativeToGround), or in relation to the geodetic datum (absolute). The YANG grouping can directly map the ignored and absolute cases, but not the relative to ground case. In addition to the kml:altitudeMode KML also defines two seafloor height values using kml:seaFloorAltitudeMode. One value is to ignore the height value (clampToSeaFloor) and the other is relative (relativeToSeaFloor). As with the kml:altitudeMode value, the YANG grouping supports the ignore case but not the relative case. The KML location values use a geodetic datum defined in Annex A by the GML Coordinate Reference System (CRS) with identifier LonLat84_5773. The altitude value for KML absolute height mode is measured from the vertical datum specified by . Thus the YANG grouping and KML values can be directly mapped in both directions (when using a supported altitude mode) with the caveat that some loss of precision (in the extremes) may occur due to the YANG grouping using decimal64 values rather than strings. For the relative height cases the application doing the transformation is expected to have the data available to transform the relative height into an absolute height which can then be expressed using the YANG grouping.

This registry allocates names for standard geodetic systems. Often these values are referred to using multiple names (e.g., full names or multiple acronyms values). The intent of this registry is to provide a single standard value for any given geodetic system. The values SHOULD use an acronym when available, they MUST be converted to lower case, and spaces MUST be changed to dashes "-". 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 as WGS-84 with the geoid updated by at least for height values. Specific entries for and are present if a more precise definition of the data is required. It should be noted that also creates a registry for Geodetic Systems (it calls CRS); however, this registry has a very strict modification policy. The authors of have the stated goal of making CRS registration hard to avoid proliferation of CRS values. As our module defines alternate systems and has a broader (beyond earth) scope, the registry defined below is meant to be more easily modified. TODO: Open question, should we create a new registry here or attempt to modify the one created by . It's worth noting that we include the ability to specify any geodetic system including ones designed for astronomical bodies other than the earth, as well as ones based on alternate systems. These requirements may be too broad for adapting the existing registry. TODO: Open question, is FCFS too easy, perhaps expert review would strike a good balance. If expert review is acceptable, would it also be acceptable to update the policy on and use it instead? The allocation policy for this registry is First Come First Served, as the intent is simply to avoid duplicate values. The initial values for this registry are as follows.

Name	Description
me	Mean Earth/Polar Axis (Moon)
mola-vik-1	MOLA Height, IAU Viking-1 PM (Mars)
wgs-84-96	World Geodetic System 1984 w/ EGM96
wgs-84-08	World Geodetic System 1984 w/
wgs-84	World Geodetic System 1984 (EGM96 or better)

This document defines a common geo location grouping using the YANG data modeling language. The grouping itself has no security or privacy impact on the Internet, but the usage of the grouping in concrete YANG modules might have. The security considerations spelled out in the YANG 1.1 specification apply for this document as well.

Presented at the 2008 General Assembly of the European Geosciences Union, Vienna, Arpil13-18, 2008 Technical Report NASA/TP-1998-206861, NASA, Greenbelt. International Organization for Standardization In many standards track documents several words are used to signify the requirements in the specification. These words are often capitalized. This document defines these words as they should be interpreted in IETF documents. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements. RFC 2119 specifies common key words that may be used in protocol specifications. This document aims to reduce the ambiguity by clarifying that only UPPERCASE usage of the key words have the defined special meanings. Many protocols make use of points of extensibility that use constants to identify various protocol parameters. To ensure that the values in these fields do not have conflicting uses and to promote interoperability, their allocations are often coordinated by a central record keeper. For IETF protocols, that role is filled by the Internet Assigned Numbers Authority (IANA).To make assignments in a given registry prudently, guidance describing the conditions under which new values should be assigned, as well as when and how modifications to existing values can be made, is needed. This document defines a framework for the documentation of these guidelines by specification authors, in order to assure that the provided guidance for the IANA Considerations is clear and addresses the various issues that are likely in the operation of a registry.This is the third edition of this document; it obsoletes RFC 5226. Datastores are a fundamental concept binding the data models written in the YANG data modeling language to network management protocols such as the Network Configuration Protocol (NETCONF) and RESTCONF. This document defines an architectural framework for datastores based on the experience gained with the initial simpler model, addressing requirements that were not well supported in the initial model. This document updates RFC 7950. National Imagery and Mapping Agency. International Organization for Standardization Open Geospatial Consortium Open Geospatial Consortium This document specifies a Uniform Resource Identifier (URI) for geographic locations using the 'geo\' scheme name. A 'geo' URI identifies a physical location in a two- or three-dimensional coordinate reference system in a compact, simple, human-readable, and protocol-independent way. The default coordinate reference system used is the World Geodetic System 1984 (WGS-84). [STANDARDS-TRACK] YANG is a data modeling language used to model configuration data, state data, Remote Procedure Calls, and notifications for network management protocols. This document describes the syntax and semantics of version 1.1 of the YANG language. YANG version 1.1 is a maintenance release of the YANG language, addressing ambiguities and defects in the original specification. There are a small number of backward incompatibilities from YANG version 1. This document also specifies the YANG mappings to the Network Configuration Protocol (NETCONF). This document captures the current syntax used in YANG module tree diagrams. The purpose of this document is to provide a single location for this definition. This syntax may be updated from time to time based on the evolution of the YANG language.

Below is a fictitious module that uses the geo-location grouping.

Example YANG module using geo location."; description "Example use of geo-location"; revision 2019-02-02 { reference "None"; } container locatable-items { description "container of locatable items"; list locatable-item { key name; description "A of locatable item"; leaf name { type string; description "name of locatable item"; } uses geo:geo-location; } } } ]]>

Below is a the YANG tree for the fictitious module that uses the geo-location grouping. Below is some example YANG XML data for the fictitious module that uses the geo-location grouping.

Example XML data of geo location use. Gaetana's 40.73297 -74.007696 Pont des Arts 2012-03-31T16:00:00Z 48.8583424 2.3375084 35 Saint Louis Cathedral 2013-10-12T15:00:00-06:00 29.9579735 -90.0637281 Apollo 11 Landing Site 1969-07-21T02:56:15Z moon me 0.67409 23.47298 ]]>

We would like to thank Peter Lothberg for the motivation as well as help in defining a more broadly useful geographic location object. We would also like to thank Acee Lindem and Qin Wu for their work on a geographic location object that led to this documents creation.