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 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 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 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 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 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: WG List: Author: Yi Yang Author: Wojciech Dec "; 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 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: name: iana-civic-address-type module: ietf-location reference: name: iana-geo-uri-type module: ietf-location reference: 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", . [CRS-REGISTRY] Internet Assigned Numbers Authority, "'geo' URI 'crs' Parameter Values", . [GEO-REGISTRY] Internet Assigned Numbers Authority, "'geo' URI Parameters", . [XML-REGISTRY] Internet Assigned Numbers Authority, "IETF XML Registry", . [YANG-REGISTRY] Internet Assigned Numbers Authority, "YANG Module Names", . [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]