< draft-chopps-netmod-geo-location-00.txt		draft-chopps-netmod-geo-location-01.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 26 February 2019		Intended status: Standards Track March 2, 2019
	Expires: 30 August 2019		Expires: September 3, 2019
	YANG Geo Location		YANG Geo Location
	draft-chopps-netmod-geo-location-00		draft-chopps-netmod-geo-location-01
	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 line 32 ¶		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 30 August 2019.		This Internet-Draft will expire on September 3, 2019.
	Copyright Notice		Copyright Notice
	Copyright (c) 2019 IETF Trust and the persons identified as the		Copyright (c) 2019 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 Simplified BSD License text as described in Section 4.e of
	provided without warranty as described in the Simplified BSD License.		the Trust Legal Provisions and are provided without warranty as
			described in the Simplified BSD License.
	Table of Contents		Table of Contents
	1. Introduction		1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
	1.1. Terminology		1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3
	2. The Geo Location Object		2. The Geo Location Object . . . . . . . . . . . . . . . . . . . 3
	2.1. Frame of Reference		2.1. Frame of Reference . . . . . . . . . . . . . . . . . . . 3
	2.2. Location		2.2. Location . . . . . . . . . . . . . . . . . . . . . . . . 4
	2.3. Motion		2.3. Motion . . . . . . . . . . . . . . . . . . . . . . . . . 4
	2.4. Tree		2.4. Nested Locations . . . . . . . . . . . . . . . . . . . . 5
	3. YANG Module		2.5. Non-location Attributes . . . . . . . . . . . . . . . . . 5
	4. ISO 6709:2008 Conformance		2.6. Tree . . . . . . . . . . . . . . . . . . . . . . . . . . 5
	5. Usability		3. YANG Module . . . . . . . . . . . . . . . . . . . . . . . . . 6
	5.1. Portability		4. ISO 6709:2008 Conformance . . . . . . . . . . . . . . . . . . 11
	5.1.1. IETF URI Value		5. Usability . . . . . . . . . . . . . . . . . . . . . . . . . . 12
	5.1.2. W3C		5.1. Portability . . . . . . . . . . . . . . . . . . . . . . . 12
	5.1.3. Geography Markup Language (GML)		5.1.1. IETF URI Value . . . . . . . . . . . . . . . . . . . 12
	5.1.4. KML		5.1.2. W3C . . . . . . . . . . . . . . . . . . . . . . . . . 12
	6. IANA Considerations		5.1.3. Geography Markup Language (GML) . . . . . . . . . . . 14
	6.1. Geodetic System Value Registry		5.1.4. KML . . . . . . . . . . . . . . . . . . . . . . . . . 15
	7. Security Considerations		6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 16
	8. Normative References		6.1. Geodetic System Value Registry . . . . . . . . . . . . . 16
	9. Informative References		7. Security Considerations . . . . . . . . . . . . . . . . . . . 17
	Appendix A. Examples		8. References . . . . . . . . . . . . . . . . . . . . . . . . . 17
	Appendix B. Acknowledgements		8.1. Normative References . . . . . . . . . . . . . . . . . . 17
	Author's Address		8.2. Informative References . . . . . . . . . . . . . . . . . 18
			Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 19
			Appendix B. Acknowledgements . . . . . . . . . . . . . . . . . . 22
			Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 22
	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 The Earth,
	it does not need to be. Indeed it is easy to imagine a network or		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		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 a different frames		Finally, one can imagine defining locations using different frames of
	of reference or even alternate systems (e.g., a simulations or		reference or even alternate systems (e.g., simulations or virtual
	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.
	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 defined in [RFC8342].
	1.1. Terminology		1.1. Terminology
	skipping to change at line 117 ¶		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 line 158 ¶		skipping to change at page 4, line 21 ¶
	standard location choice "latitude" and "longitude" are specified as		standard location choice "latitude" and "longitude" are specified as
	fractions of decimal degrees, and the "height" value is in fractions		fractions of decimal degrees, and the "height" value is in fractions
	of meters. For the Cartesian choice "x", "y" and "z" are in		of meters. For the Cartesian choice "x", "y" and "z" are in
	fractions of meters. In both choices the exact meanings of all of		fractions of meters. In both choices the exact meanings of all of
	the values are defined by the "geodetic-datum" value in the		the values are defined by the "geodetic-datum" value in the
	Section 2.1.		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 there are an additional 2 values		objects in relatively stable motion the grouping provides a
	to describe their velocity; these are "heading" and "speed". The		3-dimensional vector value. The components of the vector are
	"heading" value is relative to true-north as defined by the		"v-north", "v-east" and "v-up" which are all given in fractional
	"reference-frame" for the astronomical body. The "speed" value is in		meters per second. The values "v-north" and "v-east" are relative to
	fractional meters per second. For some applications that demand high		true-north as defined by the reference frame for the astronomical
	accuracy, and where the data is infrequently updated this value can		body, "v-up" is perpendicular to the plane defined by "v-north" and
	track very slow movement such as continental drift.		"v-east", and is pointed away from the center of mass.
	2.4. Tree		To derive the 2-dimensional heading and speed one would use the
			following formulas:
			,------------------------------
			speed = V v_{north}^{2} + v_{east}^{2}
			heading = arctan(v_{east} / v_{north})
			For some applications that demand high accuracy, and where the data
			is infrequently updated this velocity vector can track very slow
			movement such as continental drift.
			Tracking more complex forms of motion is outside the scope of this
			work. The intent of the grouping being defined here is to identify
			where something is located, and generally this is expected to be
			somewhere on or relative to the Earth (or another astronomical body).
			At least two options are available to YANG models that wish to use
			this grouping with objects that are changing location frequently in
			non-simple ways, they can add additional motion data to their model
			directly, or if the application allows it can require more frequent
			queries to keep the location data current.
			2.4. Nested Locations
			When locations are nested (e.g., a building may have a location which
			houses routers that also have locations) the module using this
			grouping is free to indicate in its definition that the "reference-
			frame" is inherited from the containing object so that the
			"reference-frame" need not be repeated in every instance of location
			data.
			2.5. Non-location Attributes
			During the development of this module, the question of whether it
			would support data such as orientation arose. These types of
			attributes are outside the scope of this grouping because they do not
			deal with a location but rather describe something more about the
			object that is at the location. Module authors are free to add these
			non-location attributes along with their use of this location
			grouping.
			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: geo-location		module: 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
	skipping to change at line 190 ¶		skipping to change at page 5, line 48 ¶
	+-- (location)		+-- (location)
	| +--:(ellipsoid)		| +--:(ellipsoid)
	| | +-- latitude degrees		| | +-- latitude degrees
	| | +-- longitude degrees		| | +-- longitude degrees
	| | +-- height? decimal64		| | +-- height? decimal64
	| +--:(cartesian)		| +--:(cartesian)
	| +-- x decimal64		| +-- x decimal64
	| +-- y decimal64		| +-- y decimal64
	| +-- z? decimal64		| +-- z? decimal64
	+-- velocity		+-- velocity
	| +-- heading? degrees		| +-- v-north? decimal64
	| +-- speed? decimal64		| +-- v-east? decimal64
			| +-- v-up? decimal64
	+-- timestamp? types:date-and-time		+-- timestamp? types:date-and-time
	Figure 1: Geo Location YANG tree diagram.
	3. YANG Module		3. YANG Module
	// -*- fill-column: 69 -*-		<CODE BEGINS> file "ietf-geo-location@2019-02-17.yang"
	module geo-location {		module ietf-geo-location {
	namespace "urn:ietf:geo-location";		namespace "urn:ietf:params:xml:ns:yang:ietf-geo-location";
	prefix geo;		prefix geo;
	import ietf-yang-types { prefix types; }		import ietf-yang-types { prefix types; }
	organization		organization
	"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 and		// RFC Ed.: replace XXXX with actual RFC number and
	// remove this note.		// remove this note.
	skipping to change at line 339 ¶		skipping to change at page 8, line 50 ¶
	type decimal64 {		type decimal64 {
	fraction-digits 6;		fraction-digits 6;
	}		}
	units "meters";		units "meters";
	description		description
	"The accuracy of height value. When specified it		"The accuracy of height value. When specified it
	overrides the geodetic-datum implied default. If		overrides the geodetic-datum implied default. If
	Cartesian coordinates ar in use this accuracy		Cartesian coordinates ar in use this accuracy
	corresponds to the Z component.";		corresponds to the Z component.";
	}		}
			// May wish to allow for height to be relative.
			// If so need to decide if we have a boolean (to ground)
			// or an enumeration (e.g., local ground, sea-floor,
			// ground floor, containing object, ...) or even allow
			// for a string for most generic but least portable
			// comparable
			// leaf height-relative {
			// }
	}		}
	}		}
	choice location {		choice location {
	mandatory true;		mandatory true;
	description		description
	"The location data either in lat/long or Cartesian values";		"The location data either in lat/long or Cartesian values";
	case ellipsoid {		case ellipsoid {
	leaf latitude {		leaf latitude {
	type degrees;		type degrees;
	mandatory true;		mandatory true;
	skipping to change at line 401 ¶		skipping to change at page 10, line 24 ¶
	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 describes this		"If the object is in motion the velocity vector describes
	motion at the the time given by the timestamp.";		this motion at the the time given by the timestamp.";
	leaf heading {		leaf v-north {
	type degrees;		type decimal64 {
	description		fraction-digits 12;
	"If the object is in motion then the heading will		}
	indicate the direction in which the object is		units "meters per second";
	currently moving. It is specified in fractions of		description
	degrees from true north of the astronomical object";		"v-north is the rate of change (i.e., speed) towards
			truth north as defined by the ~geodetic-system~.";
	}		}
	leaf speed {
			leaf v-east {
	type decimal64 {		type decimal64 {
	fraction-digits 12;		fraction-digits 12;
	}		}
	units "meters per second";		units "meters per second";
	description		description
	"If the object is in motion then the speed will		"v-east is the rate of change (i.e., speed) perpendicular
	indicate the rate at which the object is currently		to truth-north as defined by the ~geodetic-system~.";
	traveling along it's heading.";		}
			leaf v-up {
			type decimal64 {
			fraction-digits 12;
			}
			units "meters per second";
			description
			"v-up is the rate of change (i.e., speed) away from the
			center of mass.";
	}		}
	}		}
	leaf timestamp {		leaf timestamp {
	type types:date-and-time;		type types:date-and-time;
	description "Reference time when location was recorded.";		description "Reference time when location was recorded.";
	}		}
	}		}
	}		}
	}		}
			<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 non-applicable 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 reqd. for a geo. point | CRS is always |
	| | geo. point location | indicated |		| | location | indicated |
	+---------+----------------------+------------------+		| | | |
	| A.1.2.2 | Description of a CRS | CRS register is |		| A.1.2.2 | Description of a CRS from a | CRS register is |
	| | from a register | defined |		| | 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 horizontal | lat/long values |
	| | horizontal position | conform |		| | position | conform |
	+---------+----------------------+------------------+		| | | |
	| A.1.2.5 | representation of | height value |		| A.1.2.5 | representation of vertical | height value |
	| | vertical position | conforms |		| | position | conforms |
	+---------+----------------------+------------------+		| | | |
	| A.1.2.6 | text string | N/A - No string |		| A.1.2.6 | text string representation | N/A - No string |
	| | representation | format |		| | | format |
	+---------+----------------------+------------------+		+---------+-----------------------------------+---------------------+
	Table 1: Conformance Test Results		Conformance Test Results
	For test "A.1.2.1" the YANG geo location object either includes a CRS		For test "A.1.2.1" the YANG geo location object either includes a CRS
	("reference-frame") or has a default defined ([WGS84]).		("reference-frame") or has a 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 is
	also not required for conformance.		also not required for conformance.
	skipping to change at line 505 ¶		skipping to change at page 12, line 46 ¶
	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.		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 {
	readonly attribute double latitude;
	readonly attribute double longitude;
	readonly attribute double? altitude;
	readonly attribute double accuracy;
	readonly attribute double? altitudeAccuracy;
	readonly attribute double? speed;		interface GeolocationCoordinates {
	};		readonly attribute double latitude;
			readonly attribute double longitude;
			readonly attribute double? altitude;
			readonly attribute double accuracy;
			readonly attribute double? altitudeAccuracy;
	Figure 2: Snippet Showing Geo-Location Definition		readonly attribute double? speed;
			};
	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 |
			| | | | |
	| 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 | heading | dec64 fr 16 |		| heading | double | heading | dec64 fr 16 |
	+------------------+--------------+-----------------+-------------+		| | | | |
	| latitude | double | latitude | dec64 fr 16 |		| latitude | double | latitude | dec64 fr 16 |
	+------------------+--------------+-----------------+-------------+		| | | | |
	| longitude | double | longitude | dec64 fr 16 |		| longitude | double | longitude | dec64 fr 16 |
	+------------------+--------------+-----------------+-------------+		| | | | |
	| speed | double | speed | dec64 fr 12 |		| speed | double | speed | dec64 fr 12 |
	+------------------+--------------+-----------------+-------------+		| | | | |
	| timestamp | DOMTimeStamp | timestamp | string |		| timestamp | DOMTimeStamp | timestamp | string |
	+------------------+--------------+-----------------+-------------+		+------------------+--------------+-----------------+-------------+
	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 deg from true north
	increasing clock-wise.		increasing clock-wise.
	latitude, longitude (double) Standard lat/long values in decimal		latitude, longitude (double): Standard lat/long values in decimal
	degrees.		degrees.
	speed (double) Speed along heading in meters per second.		speed (double): Speed along 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 64 bit unsigned integer. The YANG model defines the
	with arbitrarily large precision by using a string which		timestamp 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 The 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.
	skipping to change at line 621 ¶		skipping to change at page 15, line 13 ¶
	the timestamp is mappable to and from the YANG grouping. Furthermore		the timestamp is mappable to and from the YANG grouping. Furthermore
	"gml:validTime" can either be an Instantaneous measure		"gml:validTime" can either be an Instantaneous measure
	("gml:TimeInstant") or a time period ("gml:TimePeriod"). Only the		("gml:TimeInstant") or a time period ("gml:TimePeriod"). Only the
	instantaneous "gml:TimeInstant" is mappable to and from the YANG		instantaneous "gml:TimeInstant" is mappable to and from the YANG
	grouping.		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 Open Geospatial Consortium (OGC)
	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 it's objects (e.g., <kml:Point or		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		<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 locations ground level		("clampToGround"), in relation to the locations ground level
	("relativeToGround"), or in relation to the geodetic datum		("relativeToGround"), or in relation to the geodetic datum
	skipping to change at line 700 ¶		skipping to change at page 17, line 7 ¶
	strike a good balance. If expert review is acceptable, would it also		strike a good balance. If expert review is acceptable, would it also
	be acceptable to update the policy on [RFC5870] and use it instead?		be acceptable to update the policy on [RFC5870] and use it instead?
	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 |
	+============+======================================================+
	| me | Mean Earth/Polar Axis (Moon) |
	+------------+------------------------------------------------------+		+------------+------------------------------------------------------+
			| me | Mean Earth/Polar Axis (Moon) |
			| | |
	| mola-vik-1 | MOLA Height, IAU Viking-1 PM (Mars) |		| mola-vik-1 | MOLA Height, IAU Viking-1 PM (Mars) |
	+------------+------------------------------------------------------+		| | |
	| wgs-84-96 | World Geodetic System 1984 [WGS84] w/ EGM96 |		| wgs-84-96 | World Geodetic System 1984 [WGS84] w/ EGM96 |
	+------------+------------------------------------------------------+		| | |
	| wgs-84-08 | World Geodetic System 1984 [WGS84] w/ [EGM08] |		| wgs-84-08 | World Geodetic System 1984 [WGS84] w/ [EGM08] |
			| | |
			| wgs-84 | World Geodetic System 1984 [WGS84] (EGM96 or better) |
	+------------+------------------------------------------------------+		+------------+------------------------------------------------------+
	| wgs-84 | World Geodetic System 1984 [WGS84] (EGM96 or |
	| | better) |
	+------------+------------------------------------------------------+
	Table 3
	7. Security Considerations		7. Security Considerations
	This document defines a common geo location grouping using the YANG		This document defines a common geo location grouping using the YANG
	data modeling language. The grouping itself has no security or		data modeling language. The grouping itself has no security or
	privacy impact on the Internet, but the usage of the grouping in		privacy impact on the Internet, but the usage of the grouping in
	concrete YANG modules might have. The security considerations		concrete YANG modules might have. The security considerations
	spelled out in the YANG 1.1 specification [RFC7950] apply for this		spelled out in the YANG 1.1 specification [RFC7950] apply for this
	document as well.		document as well.
	8. Normative References		8. References
	[EGM08] Pavlis, N.K., Holmes, S.A., Kenyon, S.C., and J.K. Factor,		8.1. Normative References
	"An Earth Gravitational Model to Degree 2160: EGM08.",
	Presented at the 2008 General Assembly of the European		[EGM08] Pavlis, N., Holmes, S., Kenyon, S., and J. Factor, "An
	Geosciences Union, Vienna, Arpil13-18, 2008, 2008,		Earth Gravitational Model to Degree 2160: EGM08.", 2008,
	<http://earth-info.nga.mil/GandG/wgs84/gravitymod/egm2008/		<http://earth-info.nga.mil/GandG/wgs84/gravitymod/egm2008/
	egm08_wgs84.html>.		egm08_wgs84.html>.
	[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.", 1998,
	EGM96.", Technical Report NASA/TP-1998-206861, NASA,
	Greenbelt., 1998,
	<https://cddis.nasa.gov/926/egm96/egm96.html>.		<https://cddis.nasa.gov/926/egm96/egm96.html>.
	[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,
	skipping to change at line 769 ¶		skipping to change at page 18, line 26 ¶
	2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,		2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
	May 2017, <https://www.rfc-editor.org/info/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,		Edition.", 1 2000, <http://earth-
	<http://earth-info.nga.mil/GandG/publications/tr8350.2/		info.nga.mil/GandG/publications/tr8350.2/wgs84fin.pdf>.
	wgs84fin.pdf>.
	9. Informative References		8.2. 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)", February 2019.		Language (GML)".
	[KML22] Wilson, T., Ed., "OGC KML (Version 2.2)", 14 April 2008,		[KML22] Wilson, T., Ed., "OGC KML (Version 2.2)", 4 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", 8 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
	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>.
	[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", 11 2016,
	2016, <https://www.w3.org/TR/2016/		<https://www.w3.org/TR/2016/
	REC-geolocation-API-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 uses-geo-location {		<CODE BEGINS> file "ietf-uses-geo-location@2019-02-02.yang"
	namespace "urn:ietf:uses-geo-location";		module ietf-uses-geo-location {
	prefix ugeo;		namespace
	import geo-location { prefix geo; }		"urn:ietf:params:xml:ns:yang:ietf-uses-geo-location";
	organization "Empty Org";		prefix ugeo;
	contact "Example Author <eauthor@example.com>";		import geo-location { prefix geo; }
	description "Example use of geo-location";		organization "Empty Org";
	revision 2019-02-02 { reference "None"; }		contact "Example Author <eauthor@example.com>";
	container locatable-items {		description "Example use of geo-location";
	description "container of locatable items";		revision 2019-02-02 { reference "None"; }
	list locatable-item {		container locatable-items {
	key name;		description "container of locatable items";
	description "A of locatable item";		list locatable-item {
	leaf name {		key name;
	type string;		description "A of locatable item";
	description "name of locatable item";		leaf name {
	}		type string;
	uses geo:geo-location;		description "name of locatable item";
	}		}
	}		uses geo:geo-location;
	}		}
			}
	Figure 3: Example YANG module using geo location.		}
			<CODE ENDS>
	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: uses-geo-location		module: ietf-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
	| +--rw alternate-system? string {alternate-systems}?		| +--rw alternate-system? string {alternate-systems}?
	| +--rw astronomical-body? string		| +--rw astronomical-body? string
	| +--rw geodetic-system		| +--rw geodetic-system
	| +--rw geodetic-datum? string		| +--rw geodetic-datum? string
	| +--rw coord-accuracy? decimal64		| +--rw coord-accuracy? decimal64
	skipping to change at line 858 ¶		skipping to change at page 20, line 27 ¶
	+--rw (location)		+--rw (location)
	| +--:(ellipsoid)		| +--:(ellipsoid)
	| | +--rw latitude degrees		| | +--rw latitude degrees
	| | +--rw longitude degrees		| | +--rw longitude degrees
	| | +--rw height? decimal64		| | +--rw height? decimal64
	| +--:(cartesian)		| +--:(cartesian)
	| +--rw x decimal64		| +--rw x decimal64
	| +--rw y decimal64		| +--rw y decimal64
	| +--rw z? decimal64		| +--rw z? decimal64
	+--rw velocity		+--rw velocity
	| +--rw heading? degrees		| +--rw v-north? decimal64
	| +--rw speed? decimal64		| +--rw v-east? decimal64
			| +--rw v-up? decimal64
	+--rw timestamp? types:date-and-time		+--rw timestamp? 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.
	<ns0:config xmlns:ns0="urn:ietf:params:xml:ns:netconf:base:1.0">		<ns0:config xmlns:ns0="urn:ietf:params:xml:ns:netconf:base:1.0">
	<locatable-items xmlns="urn:ietf:uses-geo-location">		<locatable-items
	<locatable-item>		xmlns="urn:ietf:params:xml:ns:yang:ietf-uses-geo-location">
	<name>Gaetana's</name>		<locatable-item>
	<geo-location>		<name>Gaetana's</name>
	<latitude>40.73297</latitude>		<geo-location>
	<longitude>-74.007696</longitude>		<latitude>40.73297</latitude>
	</geo-location>		<longitude>-74.007696</longitude>
	</locatable-item>		</geo-location>
	<locatable-item>		</locatable-item>
	<name>Pont des Arts</name>		<locatable-item>
	<geo-location>		<name>Pont des Arts</name>
	<timestamp>2012-03-31T16:00:00Z</timestamp>		<geo-location>
	<latitude>48.8583424</latitude>		<timestamp>2012-03-31T16:00:00Z</timestamp>
	<longitude>2.3375084</longitude>		<latitude>48.8583424</latitude>
	<height>35</height>		<longitude>2.3375084</longitude>
	</geo-location>		<height>35</height>
	</locatable-item>		</geo-location>
	<locatable-item>		</locatable-item>
	<name>Saint Louis Cathedral</name>		<locatable-item>
	<geo-location>		<name>Saint Louis Cathedral</name>
	<timestamp>2013-10-12T15:00:00-06:00</timestamp>		<geo-location>
	<latitude>29.9579735</latitude>		<timestamp>2013-10-12T15:00:00-06:00</timestamp>
	<longitude>-90.0637281</longitude>		<latitude>29.9579735</latitude>
	</geo-location>		<longitude>-90.0637281</longitude>
	</locatable-item>		</geo-location>
	<locatable-item>		</locatable-item>
	<name>Apollo 11 Landing Site</name>		<locatable-item>
	<geo-location>		<name>Apollo 11 Landing Site</name>
	<timestamp>1969-07-21T02:56:15Z</timestamp>		<geo-location>
	<reference-frame>		<timestamp>1969-07-21T02:56:15Z</timestamp>
	<astronomical-body>moon</astronomical-body>		<reference-frame>
	<geodetic-system>		<astronomical-body>moon</astronomical-body>
	<geodetic-datum>me</geodetic-datum>		<geodetic-system>
	</geodetic-system>		<geodetic-datum>me</geodetic-datum>
	</reference-frame>		</geodetic-system>
	<latitude>0.67409</latitude>		</reference-frame>
	<longitude>23.47298</longitude>		<latitude>0.67409</latitude>
	</geo-location>		<longitude>23.47298</longitude>
	</locatable-item>		</geo-location>
	</locatable-items>		</locatable-item>
	</ns0:config>		</locatable-items>
			</ns0:config>
	Figure 4: Example XML data of geo location use.
	Appendix B. Acknowledgements		Appendix B. Acknowledgements
	We would like to thank Peter Lothberg for the motivation as well as		We would like to thank Peter Lothberg for the motivation as well as
	help in defining a more broadly useful geographic location object.		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		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.		a geographic location object that led to this documents creation.
	Author's Address		Author's Address
End of changes. 59 change blocks.
	225 lines changed or deleted		280 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/