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/