Internet DRAFT - draft-yang-netmod-location
draft-yang-netmod-location
NETMOD Working Group Y. Yang
Internet-Draft W. Dec
Intended status: Standards Track Cisco Systems
Expires: December 5, 2014 July 4, 2014
A YANG Data Model for Location Information
<draft-yang-netmod-location-00.txt>
Abstract
This document defines a YANG data model for RFC 5139 civic location information.
Status of this Memo
This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."
This Internet-Draft will expire on December 5, 2014.
Dec, et al. Expires December 5, 2014 [Page 1]
Internet-Draft YANG Location July 4, 2014
Copyright Notice
Copyright (c) 2014 IETF Trust and the persons identified as the
document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License.
Dec, et al. Expires December 5, 2014 [Page 2]
Internet-Draft YANG Location July 4, 2014
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . . 3
1.2. Tree Diagrams . . . . . . . . . . . . . . . . . . . . . . . 3
2. Data Model . . . . . . . . . . . . . . . . . . . . . . . . . . 4
2.1. Civic Address . . . . . . . . . . . . . . . . . . . . . . . 4
2.2. Geospatial Coordinates . . . . . . . . . . . . . . . . . . 4
2.3. Location Data Grouping . . . . . . . . . . . . . . . . . . 5
3. YANG Modules . . . . . . . . . . . . . . . . . . . . . . . . . 6
3.1. IANA Maintained Civic Address Type YANG Submodule . . . . . 6
3. IANA(??) Maintained Geo URI YANG Submodule . . . . . . . . . . 12
4. Location YANG module . . . . . . . . . . . . . . . . . . . . . 13
5. Security Considerations . . . . . . . . . . . . . . . . . . . . 19
6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . . 19
6.1. URI Registrations . . . . . . . . . . . . . . . . . . . . 20
6.2. YANG Module Registrations . . . . . . . . . . . . . . . . 20
7. Normative References . . . . . . . . . . . . . . . . . . . . . 20
Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . . . 21
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 22
1. Introduction
The physical location of objects, such as network devices, persons,
events and etc, can be described using location information defined in[GEOPRIV]. This document defines a YANG [YANG] data model for such location
information.
1.1. Terminology
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in [KEYWORD].
1.2. Tree Diagrams
A simplified graphical representation of the data model is used in
this document. The meaning of the symbols in these diagrams is as
follows:
o Brackets "[" and "]" enclose list keys.
o Abbreviations before data node names: "rw" means configuration
(read-write) and "ro" state data (read-only).
o Symbols after data node names: "?" means an optional node, "!"
Dec, et al. Expires December 5, 2014 [Page 3]
Internet-Draft YANG Location July 4, 2014
means a presence container, and "*" denotes a list and leaf-list.
o Parentheses enclose choice and case nodes, and case nodes are also
marked with a colon (":").
o Ellipsis ("...") stands for contents of subtrees that are not
shown.
2. Data Model
The yang location data model consists of the definition of the data-types for civic addresses, and geospatial coordinates, and a grouping of these
types. A simple, non identity based, data-type definition is used to simplifiy augmentations as well as the instantiated data structure and its processing. A grouping of the data-types is provided and intended to be used by importing modules intending to express location information about a particular subject.
2.1. Civic Address
A civic address includes various types of information about the
country, administrative units such as states, provinces, and cities,
as well as street addresses, postal community names, building
information, and etc [CIVIC].
These civic address types are registered and maintained in IANA's
"Civic Address Types Registry" [CATYPE-REGISTRY], and the
corresponding YANG data types are defined in the iana-civic-address-
type YANG submodule.
Whenever a new civic address type is added to the "Civic Address
Types Registry", the iana-civic-address-type submodule should be
updated by IANA.
2.2. Geospatial Coordinates
Geospatial coordinates indicate longitude, latitude, altitude, and
etc.
[GEO-URI] specifies a Uniform Resource Identifier (URI) for
geographic locations using the 'geo' scheme name, in a compact,
simple, human-readable, and protocol-independent way. The default
coordinate reference system used is the World Geodetic System 1984
(WGS-84). The "'geo' URI Parameters" registry [GEO-REGISTRY] is
maintained by IANA for the <parameter> component of the 'geo' URI,
and the sub-registry "'geo' URI 'crs' Parameter Values" [CRS-
REGISTRY] is maintained by IANA for the 'crs' parameter.
The iana-geo-uri-type submodule defines a data type that serializes
Dec, et al. Expires December 5, 2014 [Page 4]
Internet-Draft YANG Location July 4, 2014
the "geo" URI into YANG format.
Whenever a new "geo" URI parameter is added to the [GEO-REGISTRY], or
a new CRS parameter value is added to the [CRS-REGISTRY], The iana-
geo-uri-type YANG module should be updated by IANA.
2.3. Location Data Grouping
A containerized grouping of the location data is provided as per the following structure:
module: ietf-location
+--rw location
+--rw geo-uri? geo-uri
+--rw country? country
+--rw CA0? CA0
+--rw A1? A1
+--rw A2? A2
+--rw A3? A3
+--rw A4? A4
+--rw A5? A5
+--rw A6? A6
+--rw PRD? PRD
+--rw POD? POD
+--rw STS? STS
+--rw HNO? HNO
+--rw HNS? HNS
+--rw LMK? LMK
+--rw LOC? LOC
+--rw NAM? NAM
+--rw PC? PC
+--rw BLD? BLD
+--rw UNIT? UNIT
+--rw FLR? FLR
+--rw ROOM? ROOM
+--rw PLC? PLC
+--rw PCN? PCN
+--rw POBOX? POBOX
+--rw ADDCODE? ADDCODE
+--rw SEAT? SEAT
+--rw RD? RD
+--rw RDSEC? RDSEC
+--rw RDBR? RDBR
+--rw RDSUBBR? RDSUBBR
+--rw PRM? PRM
+--rw POM? POM
+--rw PN? PN
Dec, et al. Expires December 5, 2014 [Page 5]
Internet-Draft YANG Location July 4, 2014
+--rw MP? MP
+--rw STP? STP
+--rw HNP? HNP
+--rw STPS? STPS
+--rw LMKP? LMKP
+--rw CA128? CA128
3. YANG Modules
3.1. IANA Maintained Civic Address Type YANG Submodule
<CODE BEGINS> file "iana-civic-address-type@2014-05-08.yang"
submodule iana-civic-address-type {
belongs-to "ietf-location" {
prefix loc;
}
organization "IANA";
contact
" Internet Assigned Numbers Authority
Postal: ICANN
4676 Admiralty Way, Suite 330
Marina del Rey, CA 90292
Tel: +1 310 823 9358
E-Mail: iana&iana.org";
description
"This YANG module defines the iana-civic-address-type typedef,
which contains YANG definitions for IANA-registered civic
address types.
This YANG module is maintained by IANA, and reflects the
'Civic Address Types (CAtypes)' registry.
The latest revision of this YANG module can be obtained from
the IANA web site.
Requests for new values should be made to IANA via
email (iana&iana.org).
Copyright (c) 2014 IETF Trust and the persons identified as
authors of the code. All rights reserved.
Redistribution and use in source and binary forms, with or
Dec, et al. Expires December 5, 2014 [Page 6]
Internet-Draft YANG Location July 4, 2014
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
(http://trustee.ietf.org/license-info).";
revision 2014-05-08 {
description
"Initial revision.";
}
typedef iana-civic-address-type {
type string;
description
"A civic address type as defined by the IANA Civic Address
Types registry.";
}
typedef CA0 {
type iana-civic-address-type;
description
"Language.";
}
typedef A1 {
type iana-civic-address-type;
description
"National subdivisions:
state, canton, region, province, prefecture";
}
typedef A2 {
type iana-civic-address-type;
description
"county, parish, gun (JP), district (IN)";
}
typedef A3 {
type iana-civic-address-type;
description
"city, township, shi (JP)";
}
typedef A4 {
type iana-civic-address-type;
description
"city division, borough, city district, ward, chou (JP)";
}
Dec, et al. Expires December 5, 2014 [Page 7]
Internet-Draft YANG Location July 4, 2014
typedef A5 {
type iana-civic-address-type;
description
"neighborhood, block";
}
typedef A6 {
type iana-civic-address-type;
description
"group of streets below the neighborhood level";
}
typedef PRD {
type iana-civic-address-type;
description
"leading street direction";
}
typedef POD {
type iana-civic-address-type;
description
"trailing street suffix";
}
typedef STS {
type iana-civic-address-type;
description
"street suffix or type";
}
typedef HNO {
type iana-civic-address-type;
description
"house number";
}
typedef HNS {
type iana-civic-address-type;
description
"house number suffix";
}
typedef LMK {
type iana-civic-address-type;
description
"landmark or vanity address";
}
Dec, et al. Expires December 5, 2014 [Page 8]
Internet-Draft YANG Location July 4, 2014
typedef LOC {
type iana-civic-address-type;
description
"additional location information";
}
typedef NAM {
type iana-civic-address-type;
description
"name (residence and office occupant)";
}
typedef PC {
type iana-civic-address-type;
description
"postal/zip code";
}
typedef BLD {
type iana-civic-address-type;
description
"building (structure)";
}
typedef UNIT {
type iana-civic-address-type;
description
"unit (apartment, suite)";
}
typedef FLR {
type iana-civic-address-type;
description
"floor";
}
typedef ROOM {
type iana-civic-address-type;
description
"room number";
}
typedef PLC {
type iana-civic-address-type;
description
"type of place";
}
Dec, et al. Expires December 5, 2014 [Page 9]
Internet-Draft YANG Location July 4, 2014
typedef PCN {
type iana-civic-address-type;
description
"postal community name";
}
typedef POBOX {
type iana-civic-address-type;
description
"post office box (P.O. Box)";
}
typedef ADDCODE {
type iana-civic-address-type;
description
"additional code";
}
typedef SEAT {
type iana-civic-address-type;
description
"seat (desk, cubicle, workstation)";
}
typedef RD {
type iana-civic-address-type;
description
"Primary road or street";
}
typedef RDSEC {
type iana-civic-address-type;
description
"Road section";
}
typedef RDBR {
type iana-civic-address-type;
description
"Road branch";
}
typedef RDSUBBR {
type iana-civic-address-type;
description
"Road sub-branch";
}
Dec, et al. Expires December 5, 2014 [Page 10]
Internet-Draft YANG Location July 4, 2014
typedef PRM {
type iana-civic-address-type;
description
"Street name pre-modifier";
}
typedef POM {
type iana-civic-address-type;
description
"Street name post-modifier";
}
typedef PN {
type iana-civic-address-type;
description
"Post number that is attributed to a lamp post or utility
pole.";
}
typedef MP {
type iana-civic-address-type;
description
"Milepost: a marker indicating distance to or from a place
(often a town).";
}
typedef STP {
type iana-civic-address-type;
description
"Street Type Prefix.";
}
typedef HNP {
type iana-civic-address-type;
description
"House Number Prefix.";
}
typedef STPS {
type iana-civic-address-type;
description
"Separator between the existing Street Type Prefix (STP) and
the Road Name (RD) elements.";
}
typedef LMKP {
type iana-civic-address-type;
description
Dec, et al. Expires December 5, 2014 [Page 11]
Internet-Draft YANG Location July 4, 2014
"Component part of a Complete Landmark Name.";
}
typedef CA128 {
type iana-civic-address-type;
description
"script";
}
}
3. IANA(??) Maintained Geo URI YANG Submodule
<CODE BEGINS> file "iana-geo-uri-type@2014-05-08.yang"
submodule iana-geo-uri-type {
belongs-to "ietf-location" {
prefix loc;
}
import ietf-yang-types {
prefix yang;
}
organization "IANA";
contact
" Internet Assigned Numbers Authority
Postal: ICANN
4676 Admiralty Way, Suite 330
Marina del Rey, CA 90292
Tel: +1 310 823 9358
E-Mail: iana&iana.org";
description
"This YANG module defines the iana-geo-uri-type typedef,
which contains YANG definitions for IANA-registered geo uri.
This YANG module is maintained by IANA, serializes the existing
'geo' URI into YANG format, and reflects the 'geo URI
Parameters' registry and 'geo URI crs Parameter Values'
sub-registry.
The latest revision of this YANG module can be obtained from
the IANA web site.
Requests for new values should be made to IANA via
email (iana&iana.org).
Dec, et al. Expires December 5, 2014 [Page 12]
Internet-Draft YANG Location July 4, 2014
Copyright (c) 2014 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
(http://trustee.ietf.org/license-info).";
revision 2014-05-08 {
description
"Initial revision.";
}
typedef geo-uri {
type yang:uri {
pattern
'geo:'
+ '-?0*(90|(([1-8][0-9]|[0-9])(.[0-9]*)?))'
+ ',-?0*(180|((1[0-7][0-9]|[1-9][0-9]|[0-9])(.[0-9]*)?))'
+ '(,-?[0-9]+(.[0-9]*)?)?'
+ '(;crs=(wgs84|[-0-9a-zA-Z]+))?'
+ '(;u=[0-9]+(.[0-9]*)?)?'
+ '(;[-da-zA-Z]+'
+ '(=(([-_.!~*'()[]:&+$da-zA-Z]*)(%[da-fA-F]{2})*)*)?)*';
}
description
"The geo-uri type reprents a Uniform Resource Identifier for
Geographic Locations ('geo' URI) as defined by RFC 5870.";
reference
"RFC 5870: A Uniform Resource Identifier for Geographic
Locations";
}
}
4. Location YANG module
<CODE BEGINS> file "ietf-location@2014-05-08.yang"
module ietf-location {
namespace "urn:ietf:params:xml:ns:yang:ietf-location";
prefix loc;
include iana-civic-address-type {
revision-date 2014-05-08;
}
Dec, et al. Expires December 5, 2014 [Page 13]
Internet-Draft YANG Location July 4, 2014
include iana-geo-uri-type {
revision-date 2014-05-08;
}
organization
"IETF NETMOD (NETCONF Data Modeling Language) Working Group";
contact
"WG Web: <http://tools.ietf.org/wg/netmod/>
WG List: <mailto:netmod@ietf.org>
Author: Yi Yang
<mailto:yiya@cisco.com>
Author: Wojciech Dec
<mailto:wdec@cisco.com>";
description
"This YANG module defines a reusable group for location
information";
revision 2014-05-08 {
description
"Initial revision.";
}
typedef country {
type string {
pattern '[A-Z]{2}';
}
description
"ISO 3166 country code";
}
grouping location {
container location {
leaf geo-uri {
type geo-uri;
description
"Uniform Resource Identifier for Geographic Locations
('geo' URI) as defined by RFC 5870.";
}
leaf country {
type country;
description
"ISO 3166 country code";
}
Dec, et al. Expires December 5, 2014 [Page 14]
Internet-Draft YANG Location July 4, 2014
leaf CA0 {
type CA0;
description
"Language.";
}
leaf A1 {
type A1;
description
"National subdivisions:
state, canton, region, province, prefecture";
}
leaf A2 {
type A2;
description
"county, parish, gun (JP), district (IN)";
}
leaf A3 {
type A3;
description
"city, township, shi (JP)";
}
leaf A4 {
type A4;
description
"city division, borough, city district, ward, chou (JP)";
}
leaf A5 {
type A5;
description
"neighborhood, block";
}
leaf A6 {
type A6;
description
"group of streets below the neighborhood level";
}
leaf PRD {
type PRD;
description
"leading street direction";
}
Dec, et al. Expires December 5, 2014 [Page 15]
Internet-Draft YANG Location July 4, 2014
leaf POD {
type POD;
description
"trailing street suffix";
}
leaf STS {
type STS;
description
"street suffix or type";
}
leaf HNO {
type HNO;
description
"house number";
}
leaf HNS {
type HNS;
description
"house number suffix";
}
leaf LMK {
type LMK;
description
"landmark or vanity address";
}
leaf LOC {
type LOC;
description
"additional location information";
}
leaf NAM {
type NAM;
description
"name (residence and office occupant)";
}
leaf PC {
type PC;
description
"postal/zip code";
}
Dec, et al. Expires December 5, 2014 [Page 16]
Internet-Draft YANG Location July 4, 2014
leaf BLD {
type BLD;
description
"building (structure)";
}
leaf UNIT {
type UNIT;
description
"unit (apartment, suite)";
}
leaf FLR {
type FLR;
description
"floor";
}
leaf ROOM {
type ROOM;
description
"room number";
}
leaf PLC {
type PLC;
description
"type of place";
}
leaf PCN {
type PCN;
description
"postal community name";
}
leaf POBOX {
type POBOX;
description
"post office box (P.O. Box)";
}
leaf ADDCODE {
type ADDCODE;
description
"additional code";
}
Dec, et al. Expires December 5, 2014 [Page 17]
Internet-Draft YANG Location July 4, 2014
leaf SEAT {
type SEAT;
description
"seat (desk, cubicle, workstation)";
}
leaf RD {
type RD;
description
"Primary road or street";
}
leaf RDSEC {
type RDSEC;
description
"Road section";
}
leaf RDBR {
type RDBR;
description
"Road branch";
}
leaf RDSUBBR {
type RDSUBBR;
description
"Road sub-branch";
}
leaf PRM {
type PRM;
description
"Street name pre-modifier";
}
leaf POM {
type POM;
description
"Street name post-modifier";
}
leaf PN {
type PN;
description
"Post number that is attributed to a lamp post or utility
pole.";
}
Dec, et al. Expires December 5, 2014 [Page 18]
Internet-Draft YANG Location July 4, 2014
leaf MP {
type MP;
description
"Milepost: a marker indicating distance to or from a place
(often a town).";
}
leaf STP {
type STP;
description
"Street Type Prefix.";
}
leaf HNP {
type HNP;
description
"House Number Prefix.";
}
leaf STPS {
type STPS;
description
"Separator between the existing Street Type Prefix (STP)
and the Road Name (RD) elements.";
}
leaf LMKP {
type LMKP;
description
"Component part of a Complete Landmark Name.";
}
leaf CA128 {
type CA128;
description
"script";
}
}
}
}
5. Security Considerations
Since this document does not introduce any technology or protocol,
there are no security issues to be considered for this document
itself.
6. IANA Considerations
Dec, et al. Expires December 5, 2014 [Page 19]
Internet-Draft YANG Location July 4, 2014
This document defines the initial version of the IANA-maintained
iana-civic-address-type YANG submodule, and iana-geo-uri-type
submodule.
The iana-civic-address-type submodule is intended to reflect the IANA
"Civic Address Types Registry" [CATYPE-REGISTRY]. When an civic
address type is added to the "Civic Address Types Registry", a new
civic address data type must be added to the iana-civic-address-type
submodule. When the iana-civic-address-type YANG submodule is
updated, a new "revision" statement must be added in front of the
existing revision statements.
<## do we need IANA to maintain the geo-uri submodule? ##>
6.1. URI Registrations
<TBD> This document needs to register a URI in the "IETF XML
Registry" [XML-REGISTRY]. Following the format in [IETF-XML], the
following registration needs to be made.
URI: urn:ietf:params:xml:ns:yang:ietf-location
Registrant Contact: IANA.
XML: N/A; the requested URI is an XML namespace.
6.2. YANG Module Registrations
This document registers a YANG module and two YANG submodules in the
"YANG Module Names" registry [YANG-REGISTRY].
name: ietf-location
namespace: urn:ietf:params:xml:ns:yang:ietf-location
prefix: loc
reference: <TBD>
name: iana-civic-address-type
module: ietf-location
reference: <TBD>
name: iana-geo-uri-type
module: ietf-location
reference: <TBD>
7. Normative References
Dec, et al. Expires December 5, 2014 [Page 20]
Internet-Draft YANG Location July 4, 2014
[CATYPE-REGISTRY]
Internet Assigned Numbers Authority, "Civic Address Types
Registry", <http://www.iana.org/assignments/civic-address-
types-registry>.
[CRS-REGISTRY]
Internet Assigned Numbers Authority, "'geo' URI 'crs'
Parameter Values", <http://www.iana.org/assignments/geo-
uri-parameters/geo-uri-parameters.xhtml#geo-uri-
parameters-2>.
[GEO-REGISTRY]
Internet Assigned Numbers Authority, "'geo' URI
Parameters", <http://www.iana.org/assignments/geo-uri-
parameters>.
[XML-REGISTRY]
Internet Assigned Numbers Authority, "IETF XML Registry",
<http://www.iana.org/assignments/xml-registry>.
[YANG-REGISTRY]
Internet Assigned Numbers Authority, "YANG Module Names",
<http://www.iana.org/assignments/yang-parameters/yang-
parameters.xhtml#yang-parameters-1>.
[CIVIC] Schulzrinne, H., "Dynamic Host Configuration Protocol
(DHCPv4 and DHCPv6) Option for Civic Addresses
Configuration Information", RFC 4776, November 2006.
[GEOPRIV] Peterson, J., "A Presence-based GEOPRIV Location Object
Format", RFC 4119, December 2005.
[GEO-URI] Mayrhofer, A. and C. Spanring, "A Uniform Resource
Identifier for Geographic Locations ('geo' URI)", RFC
5870, June 2010.
[IEFT-XML] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688,
January 2004.
[KEYWORD] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997.
[YANG] Bjorklund, M., Ed., "YANG - A Data Modeling Language for
the Network Configuration Protocol (NETCONF)", RFC 6020,
October 2010.
Appendix A. Acknowledgments
Dec, et al. Expires December 5, 2014 [Page 21]
Internet-Draft YANG Location July 4, 2014
The draft text was produced using Stefan Santesson's NroffEdit
application.
Authors' Addresses
Yi Yang
Cisco Systems
7025 Kit Creek Road
RTP, NC 27709
USA
Email: yiya@cisco.com
Wojciech Dec
Cisco Systems
Haarlerbergpark
Haarlerbergweg 13-19
AMSTERDAM, NOORD-HOLLAND 1101 CH
NETHERLANDS
Email: wdec@cisco.com
Dec, et al. Expires December 5, 2014 [Page 22]
