A YANG Grouping for Geographic Locations
Extracted elements (23)
A separate 'Geodetic System Values' registry was created rather than reusing the 'geo' URI 'crs' Parameter Values registry from RFC 5870 because that registry has a very strict modification policy by design. This module requires broader scope (non-Earth bodies, alternate systems) and easier modification to avoid proliferation issues.
Orientation and other non-location attributes were deliberately excluded from the grouping scope; module authors are free to add such attributes alongside the grouping. The grouping is limited to location data only.
The grouping supports locations on any astronomical body (planets, moons, asteroids, comets) and even alternate systems (virtual realities), not just Earth, making it broadly reusable across networking and non-networking applications.
The 'wgs-84' default geodetic datum is defined to include the EGM96 geoid update for height values, so that a single 'wgs-84' entry is sufficient for most GPS-based use cases without requiring separate EGM96 or EGM08 entries unless higher precision is needed.
GML 'gml:pos' values can be mapped directly to the YANG grouping (with possible decimal64 precision loss). Mapping YANG back to GML is fully supported for Earth-based geodetic systems. GML's 'gml:validTime' time period maps to 'valid-until' at second resolution.
KML 2.2/2.3 location values can be mapped bidirectionally to the YANG grouping when using supported altitude modes ('clampToGround' or 'absolute'). The relative height cases ('relativeToGround', 'relativeToSeaFloor') are not directly supported; applications must convert to absolute height before using the YANG grouping.
This specification conforms to ISO 6709:2008 for standard representation of geographic point location. It passes conformance tests A.1.2.1, A.1.2.2, A.1.2.4, and A.1.2.5; tests A.1.2.3 (CRS definition) and A.1.2.6 (text string representation) are not applicable.
URI (RFC 5870) values can be mapped to and from the YANG grouping, but some precision loss may occur at extremes because the YANG grouping uses decimal64 values rather than strings.
W3C Geolocation API values can be mapped to the YANG grouping with potential precision loss. Only YANG values for Earth using 'wgs-84' as geodetic-datum can be directly mapped back to W3C values, as W3C lacks support for non-Earth bodies or alternate systems.
All data nodes in the YANG module are writable/creatable/deletable (config true by default). The module defines only groupings, so security and access-control considerations are primarily the responsibility of designers of modules that use these groupings.
Geodetic System Values registry entries SHOULD use an acronym when available, MUST be converted to lowercase, and spaces MUST be changed to dashes '-'.
The 'astronomical-body' leaf value SHOULD have uppercase converted to lowercase and SHOULD NOT include control characters (values 32–64 and 91–126). Any preceding 'the' in the name SHOULD NOT be included.
The 'geodetic-datum' leaf value SHOULD have uppercase converted to lowercase and SHOULD NOT include control characters. The IANA registry further restricts the value by converting all spaces to dashes '-'.
Since the grouping identifies physical locations, authors using it SHOULD consider privacy issues when the data is readable, such as exposure of customer device locations. Read access to location data nodes should be controlled.
An optional 'alternate-systems' YANG feature enables an 'alternate-system' leaf in the reference frame, allowing location data to be defined relative to systems other than the natural universe (e.g., virtual realities or simulations). The definition of alternate systems is outside the scope of this document.
Location is specified as a YANG choice between 'ellipsoid' (latitude and longitude as decimal64 with 16 fraction-digits, height as decimal64 with 6 fraction-digits in meters) and 'cartesian' (x, y, z as decimal64 with 6 fraction-digits in meters).
The 'geo-location' YANG grouping defines a container for specifying a location on or around an astronomical object. It includes sub-containers for 'reference-frame', a choice of 'location' (ellipsoid or Cartesian), 'velocity', and leaf nodes for 'timestamp' and 'valid-until'.
The 'reference-frame' container defines what location values refer to, comprising 'alternate-system' (optional feature), 'astronomical-body' (default 'earth'), and 'geodetic-system' (containing 'geodetic-datum', 'coord-accuracy', and 'height-accuracy').
The 'timestamp' leaf (type yang:date-and-time) records when the location was captured; 'valid-until' (same type) indicates the expiry of the location data. If 'valid-until' is absent, the location has no specific expiration.
The 'velocity' container captures three-dimensional motion via 'v-north', 'v-east', and 'v-up' leaves, all typed as decimal64 with 12 fraction-digits in meters per second. Two-dimensional heading and speed are derived using arctan(v_east/v_north) and sqrt(v_north^2 + v_east^2).
IANA created the 'Geodetic System Values' registry under the 'YANG Geographic Location Parameters' registry group. Allocation policy is First Come First Served. Initial entries include 'wgs-84', 'wgs-84-96', 'wgs-84-08' (WGS-84 variants), and 'me' (Mean Earth/Polar Axis for the Moon).
This document registers the URI 'urn:ietf:params:xml:ns:yang:ietf-geo-location' in the IETF XML Registry (RFC 3688), and registers the YANG module 'ietf-geo-location' in the YANG Module Names Registry (RFC 6020) with prefix 'geo'.
The YANG module is accessed via NETCONF (mandatory secure transport: SSH) or RESTCONF (mandatory secure transport: TLS). Access control is managed via the NETCONF access control model (RFC 8341) to restrict operations and content per user.