Geopriv WG James Polk Internet-Draft Allan Thomson Expires: January 6, 2010 Marc Linsner Intended Status: Standards Track (PS) Cisco Systems July 2009 A Conversion of Location Related eXtensible Markup Language (XML) Elements to Type-Length-Value (TLV) Fields draft-polk-geopriv-xml-to-tlv-00 Status of this Memo This Internet-Draft is submitted to IETF in full conformance with the provisions of BCP 78 and BCP 79. This document may contain material from IETF Documents or IETF Contributions published or made publicly available before November 10, 2008. The person(s) controlling the copyright in some of this material may not have granted the IETF Trust the right to allow modifications of such material outside the IETF Standards Process. Without obtaining an adequate license from the person(s) controlling the copyright in such materials, this document may not be modified outside the IETF Standards Process, and derivative works of it may not be created outside the IETF Standards Process, except to format it for publication as an RFC or to translate it into languages other than English. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet- Drafts. 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." The list of current Internet-Drafts can be accessed at http://www.ietf.org/ietf/1id-abstracts.txt. The list of Internet-Draft Shadow Directories can be accessed at http://www.ietf.org/shadow.html. This Internet-Draft will expire on January 6, 2010. Copyright Notice Copyright (c) 2009 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 in effect on the date of publication of this document (http://trustee.ietf.org/license-info). Please review these documents carefully, as they describe your Polk, et al. Expires July 6, 2009 [Page 1] Internet-Draft Location XML-to-TLV Conversion Jan 2010 rights and restrictions with respect to this document. Legal This documents and the information contained therein are provided on an "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION THEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Abstract This document specifies how to translate geolocation related eXtensible Markup Language (XML) elements to Type-Length-Value (TLV) fields, specifically where XML is not optimal or not appropriate to use for transporting geolocation related values. This document specifies a payload for binary protocols to use. This document makes no recommendations about which protocols should use this payload. Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 1.1 Open Questions on How to Proceed . . . . . . . . . . . . 4 2. Location TLV Format . . . . . . . . . . . . . . . . . . . . . 6 2.1 The Geoelement Shape for a 2D/3D Point . . . . . . . . . 8 2.2 The Geoelement Shape for a 2D/3D Circle . . . . . . . . . 9 2.3 The Geoelement Shape for a 2D/3D Polygon . . . . . . . . 11 2.4 The Geoelement Shape for a 2D Ellipse . . . . . . . . . . 15 2.5 The Geoelement Shape for a 2D Arc Band . . . . . . . . . 15 2.6 The Geoelement Shape for a 3D Sphere . . . . . . . . . . 16 2.7 The Geoelement Shape for a 3D Ellipsoid . . . . . . . . . 16 2.8 The Geoelement Shape for a 3D Prism . . . . . . . . . . . 16 2.9 Additional Optional Loctypes . . . . . . . . . . . . . . 16 3. What to do with Civic CAtypes and this Proposal . . . . . . . 17 4. Recommendations for Converting this Option into a PIDF-LO . . 17 5. Security considerations . . . . . . . . . . . . . . . . . . . 21 6. IANA considerations . . . . . . . . . . . . . . . . . . . . . 21 7. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 22 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 23 8.1. Normative References . . . . . . . . . . . . . . . . . 23 8.2. Informative References . . . . . . . . . . . . . . . . 23 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . 23 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", Polk, et al. Expires July 6, 2009 [Page 2] Internet-Draft Location XML-to-TLV Conversion Jan 2010 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 [1]. 1. Introduction This document defines a common TLV (Type/Length/Value) payload for communicating a location shape towards another entity. Specifically, the intent is to emulate in an easy TLV format, XML elements that are used within the Geopriv architecture, which includes OpenGIS's Geography Markup Language (GML) [OpenGIS]. GML is an extensive syntax for expressing all the individual shape elements that make up a point, a circle, a polygon, an arc-band, ellipsoid and other shapes. This document describes the payload of the communication, it does not specify any protocol transport. The driving reason for this capability is that not every transport protocol can incorporate XML into their payloads easily or at all. Certainly not as easy as text-based protocols such as SIP or HTTP. Though, this document does not prohibit these text-based protocols from carrying this TLV payload, the payload is generalized for binary protocols to easily transport this location information parts from one entity to another. There is no assumption made about how the sending entity attained this location information. This document is describing the TLV payload, most of which are present in GML. Because of this, these payload types will map back to XML in a Presence Information Data Format - Location Object (PIDF-LO), defined in RFC 4119 [RFC4119] for an entity to transport a Location Object when the identity of the location target is included (even if as an RFC 3693 [RFC3693] defined unlinkable pseudonym). This initial version of this document maps 8 location shapes to meet the shapes defined in [RF5491], as follows, o a single point - in 2D and 3D; o a circle - 2D o a polygon - in 2D and 3D o an ellipse - 2D o an arc band - 2D o a sphere - 3D o an ellipsoid - 3D o a prism - 3D Polk, et al. Expires July 6, 2009 [Page 3] Internet-Draft Location XML-to-TLV Conversion Jan 2010 [Editor's Note: these are currently not proposed to be IANA registered as separate TLV types, meaning it is left to the receiver of the payload to determine what shape is being communicated. Should the 'shape' being communicated in the payload be explicitly identified?] The use of the term "point" has been changed in GML from the version 3.0 specification, which is mandatory to implement according to [RFC4119], and the 2.1 specification [OpenGIS]. A point (GML3.0) became a "position" (GML2.1). For the remainder of this document, we do not distinguish between the two terms. A reader of this document needs to consider these two terms as interchangeable. In both GML3.0 and GML2.1 (and more recently GML2.2) - a point or position is contained within the feature.xsd schema, which relates directly to what RFC 4119 [RFC4119] mandates support of, but that is all RFC 4119 requires support of as far as GML schemas are concerned. This becomes a problem when more complex shapes are to be included. A circle is not defined within the feature.xsd schema, but rather the geometryPrimitives.xsd schema in GML 2.1.1. If this TLV shape were used by implementers to place location information in a PIDF-LO, additional support for the geometryPrimitives.xsd schema in GML 2.1.1 is necessary. Section 6 of this document is dedicated to give guidance to implementers for just such a conversion from this TLV payload to a PIDF-LO. A polygon is also not defined within the feature.xsd schema, and is also defined in the geometryPrimitives.xsd schema in GML 2.1.1. Therefore, just as converting a circle from this TLV shape into a PIDF-LO requires the geometryPrimitives.xsd schema, so too does a polygon representation in a PIDF-LO. Additional location shapes can require the geometryPrimitives.xsd schema be implemented, or another GML schema. Because this document describes a binary TLV payload, there are no topological environmental constraints foreseen when using this payload. The transport protocol can have such constraints, and that MUST be addressed in the definition of how this payload is carried by those protocols - but not here. This TLV is independent of the choice for IPv4 and IPv6 - meaning it does not matter which is used. 1.1 Open Questions on How to Proceed Individual TLV types can be identified in ranges from type 1 through type 65,535 (i.e., a 16 bit value). This complete range can be Polk, et al. Expires July 6, 2009 [Page 4] Internet-Draft Location XML-to-TLV Conversion Jan 2010 subdivided into blocks of common purpose types, such as specific GML elements such as an X-coordinate, Y-coordinate, radius, Unit of measurement for Altitude (meters or floors), etc. This is where a decision needs to be made moving forward. - of the 255 values of individual types, are they listed linearly, or grouped into categories? Here are two options to move forward with: Option-A Range the Types based on Geo only. Option-B Range the Types based on all we can realistically import into a TLV format. Strawman for Option-A Loctypes 1-254 are dedicated for coordinate or GML based registrations to equate with GML XML elements. Strawman for Option-B Specify the type numbering scheme in such a way to merge the existing civic CAtypes, yet not force any renumbering to be done within the CAtypes. Each listing of TLV types would be in a block or range of type numbers. For example, Range A - all existing and future CAtypes Range B - all Geo specific types Range C - all generic TLV types Range D - all policy related types Ranges C & D would be optional, and left to the WG to decide their validity and applicability. Determining what is included in this payload would dictate where each range of type numbering would start and end. For simplicity, this document proposes that CAtypes be included, but not described. Each valid CAtype from RFC 4776, 5139 and subsequent updates would be immediately cross-registered into this range. There are 39 CAtypes, so (for simplicity) say the range of civic types is 1-100. With 101 on up be specific to what this document describes for Geo types. The generic type classification of "Loc" will be used (i.e., Loctype, Loclength, Locvalue), but can be changed based on WG consensus. The range can also change for each type, given that 16 bits are used Polk, et al. Expires July 6, 2009 [Page 5] Internet-Draft Location XML-to-TLV Conversion Jan 2010 for the type field, for expansion and extendability reasons. All of this directly affects the Type numbering throughout this document and in the IANA registry. 2. Location TLV Format The "Loc" TLV has the following format: 0 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Loctype | Loclength | Locvalue ... +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ Figure 3. Loc-element Format for both IPv4 and IPv6 Loctype: A one-byte identifier of the data location value. Loclength: The length, in bytes, of the Locvalue, not including the Loclength field itself, up to a maximum of 255 bytes. Locvalue: The location shape value, as described in detail below. The Locvalue is always in UTP-8. The Loctypes this document defines (and IANA registers) for a point are: Loctype=101 X-coordinate - this necessitates there be a Latitude Locvalue present. Loctype=102 Y-coordinate - this necessitates there be a Longitude Locvalue present. Loctype=103 Z-coordinate - this necessitates there be an Altitude Locvalue present. Loctype=104 Unit of Measurement Altitude (UofMA) - this necessitates there be an Altitude unit of measurement Locvalue present. The first byte of the Locvalue for Loctypes =101 and =102 MUST be a plus '+' or minus '-' sign byte, indicating: For Loctype=101 - whether the latitude is positive (above the equator) or negative (below the equator). Polk, et al. Expires July 6, 2009 [Page 6] Internet-Draft Location XML-to-TLV Conversion Jan 2010 For Loctype=102 - whether the longitude is positive (East of the prime meridian of the datum used) or negative (West of the prime meridian of the datum used). This document defines (and IANA registers) 2 Altitude units of measurement (Loctype=4). Loctype=104, Locvalue=1 - meters above or below the datum 0 plane. Loctype=104, Locvalue=2 - building floor above or below the ground floor. This value has local significance only. When Loctype=104 (UofMA) has a Locvalue=2 (building floor), the Locvalue for Loctype=103 (Z-coordinate) is alpha characters, meaning there is no need to include a plus '+' or minus '-' sign byte (more on this below table 2). When Loctype=104 (UofMA) has a Locvalue=1 (meters), first byte of the Locvalue=3 MUST be a plus '+' or minus '-' sign byte, indicating: For Loctype=103 - whether the altitude Locvalue is positive (above datum 0) or negative (below datum 0). +---------+----------------------------------+---------+ | Loctype | Geoelement | PIDF-LO | +---------+----------------------------------+---------+ | 101 | X-Coordinate (Latitude) | Sec 5.1 | | | | | | 102 | Y-Coordinate (Longitude) | Sec 5.1 | | | | | | 103 | Z-Coordinate (Altitude) | Sec 5.1 | | | | | | 104 | Unit of Measurement Altitude * | Sec 5.2 | +---------+----------------------------------+---------+ Table 1. Loctypes for a Basic 3D Point * For Loctype=104 (Unit of Measurement Altitude), the following table applies: +---------+--------------------------------------------------------+ | Loctype | Locvalue | Description | +---------+--------------------------------------------------------+ | 104 | 1 | meters above or below the datum 0 plane | | | | | | 104 | 2 | building floor | +---------+--------------------------------------------------------+ Table 2. Unit of Measurement for the Altitude value Polk, et al. Expires July 6, 2009 [Page 7] Internet-Draft Location XML-to-TLV Conversion Jan 2010 The Unit of Measurement Altitude (UofMA) field in this TLV shape will define what is considered the 3-Dimensional 0 (zero) altitude. For example, it could be the ground, Mean-lowest-Low-tide or Mean-Tide level at a given X/Y coordinate. The 'floor', Locvalue=2, SHOULD match the locally significant description for identifying floors in a multi-floor building. Values for this option would include '1' or '2' and could include 'basement' or 'mezzanine' or any other floor identifier determined by local administration. For example, for a Loctype=104 (UofMA), the Locvalue in Loctype=103 (Z-Coordinate) would be 'basement' or 'mezzanine', either spelled out. For any point, there MUST be a Loctype=101 (X-coordinate) and Loctype=102 (Y-coordinate) present. Loctype=103 (Z-coordinate) and Loctype=104 (UofMA) MUST be implemented to comply with this specification, but are OPTIONAL to use for any given communication. That said, if there is an altitude provide (Loctype=103), there MUST be a (Loctype=104) present as well. 2.1 The Geoelement Shape for a 2D/3D Point The elements defined in Section 3 define how to communicate a point (shape=1). These additional rules need to be followed for a point: o There MUST NOT be more than one Loctype=103 (Z-coordinate) or more than one Loctype=104 (UofMA) within this TLV type when shape=1. o These are the Loctypes that MUST be present for a 2D point within this TLV type: o Loctype=101 (X-Coordinate (Latitude)) o Loctype=102 (Y-Coordinate (Longitude)) o These are the Loctypes that MUST NOT be present for a 2D point within this TLV type: o Loctype=103 (Z-Coordinate (Altitude)) o Loctype=104 (Unit of Measurement Altitude) o Loctype=105 (Radius) o Loctype=106 (# of Points) o Loctype=107 (Centerpoint X-Coordinate (Lat)) o Loctype=108 (Centerpoint Y-Coordinate (Long)) o Loctype=109 (Centerpoint Z-Coordinate (Alt)) o Loctype=110(Centerpoint Unit of Measurement Altitude) Polk, et al. Expires July 6, 2009 [Page 8] Internet-Draft Location XML-to-TLV Conversion Jan 2010 All other Loctypes are OPTIONAL, but MAY change in future extension(s) to this document. o These are the Loctypes that MUST be present for a 3D point within this TLV type: o Loctype=101 (X-Coordinate (Latitude)) o Loctype=102 (Y-Coordinate (Longitude)) o Loctype=103 (Z-Coordinate (Altitude)) o Loctype=104 (Unit of Measurement Altitude) o These are the Loctypes that MUST NOT be present for a 3D point within this TLV type: o Loctype=105 (Radius) o Loctype=106 (# of Points) o Loctype=107 (Centerpoint X-Coordinate (Lat)) o Loctype=108 (Centerpoint Y-Coordinate (Long)) o Loctype=109 (Centerpoint Z-Coordinate (Alt)) o Loctype=110 (Centerpoint Unit of Measurement Altitude) Loctypes=111(Datum) and =112(Valid-for) are OPTIONAL, but MAY change in future extension(s) to this document. 2.2 The Geoelement Shape for a 2D/3D Circle The elements defined in section 2.1 define how to communicate a point (shape=1). The additional element needed to communicate a circle (shape=2) is a radius Loctype. The a unit of measurement of for the radius (UofMR) is always meters, therefore, there does not need to be a separate value for this - having only one to choose from. Loctype=105 Radius - the straight line from the point at the center of the circle, extending out a given distance (this is the Locvalue of the Radius Loctype). +---------+----------------------------------+---------+ | Loctype | Geoelement | PIDF-LO | +---------+----------------------------------+---------+ | 105 | Radius | Sec 5.3 | +---------+----------------------------------+---------+ Table 3. Required Radius Geoelement Information When the TLV type communicates a circle (shape=2), the following Loctype MUST be present in the TLV type: Loctype=101 (the X-coordinate representing the center of the circle) Polk, et al. Expires July 6, 2009 [Page 9] Internet-Draft Location XML-to-TLV Conversion Jan 2010 Loctype=102 (the Y-coordinate representing the center of the circle) Loctype=105 (the Radius value from the center X/Y point of the circle) An altitude (Loctypes 103 & 104) coordinate is OPTIONAL, but both Loctypes MUST appear in the TLV type if either appears for shape=102 (a circle). Loctypes=107 through =110, which detail a Centerpoint (see Section 2.3 below) MUST NOT appear in a shape=102 (circle) TLV type. There is already an implicit centerpoint of the circle, and that is the one X/Y point in the TLV type. The following additional rules need to be followed for a circle: o There MUST NOT be more than one Loctype=103 (Z-coordinate) or more than one Loctype=104 (UofMA) within this TLV type when shape=2. o These are the Loctypes that MUST be present for a 2D circle within this TLV type: o Loctype=101 (X-Coordinate (Latitude)) o Loctype=102 (Y-Coordinate (Longitude)) o Loctype=105 (Radius) o These are the Loctypes that MUST NOT be present for a 2D circle within this TLV type: o Loctype=103 (Z-Coordinate (Altitude)) o Loctype=104 (Unit of Measurement Altitude) o Loctype=106 (# of Points) o Loctype=107 (Centerpoint X-Coordinate (Lat)) o Loctype=108 (Centerpoint Y-Coordinate (Long)) o Loctype=109 (Centerpoint Z-Coordinate (Alt)) o Loctype=110 (Centerpoint Unit of Measurement Altitude) All other Loctypes are OPTIONAL, but MAY change in future extension(s) to this document. o These are the Loctypes that MUST be present for a 3D circle within this TLV type: o Loctype=101 (X-Coordinate (Latitude)) o Loctype=102 (Y-Coordinate (Longitude)) o Loctype=103 (Z-Coordinate (Altitude)) o Loctype=104 (Unit of Measurement Altitude) o Loctype=105 (Radius) o These are the Loctypes that MUST NOT be present for a 3D circle within this TLV type: Polk, et al. Expires July 6, 2009 [Page 10] Internet-Draft Location XML-to-TLV Conversion Jan 2010 o Loctype=106 (# of Points) o Loctype=107 (Centerpoint X-Coordinate (Lat)) o Loctype=108 (Centerpoint Y-Coordinate (Long)) o Loctype=109 (Centerpoint Z-Coordinate (Alt)) o Loctype=110(Centerpoint Unit of Measurement Altitude) Loctypes=111 (Datum) and =112 (Valid-for) are OPTIONAL, but MAY change in future extension(s) to this document. 2.3 The Geoelement Shape for a 2D/3D Polygon The elements defined in this section define how to communicate a polygon (shape=103). A polygon is a series of X/Y coordinate points, or X/Y/Z coordinate groupings. There MUST be at least 4 points to shape a polygon (which would result in a triangle), to be consistent with the GML 2.1 specification [OpenGIS]. A minimum of 4 Points make up a polygon in GML because the first and last point in a polygon are the same, i.e., the first point is repeated to indicate the representation has completed (or circled). There can be more points included in the polygon. There is one additional Loc-element that MUST be present in shape=103 (polygon) of this TLV type, and that is an indication of the number of points in the polygon. Loctypes=101 and =102 create an X/Y point. Loctype=106 # of Points - each point, in 2D, is a point of X and Y coordinates. If a 3rd dimension exists for a point, Loctype=103 (the Z-coordinate) is added to Loctype=101 and =2. +---------+----------------------------------+---------+ | Loctype | Geoelement | PIDF-LO | +---------+----------------------------------+---------+ | 106 | # of Points | N/A | +---------+----------------------------------+---------+ Table 4. Required Number of Points within "this" Polygon For shape=103 (polygon), the Loctype=106 MUST be the first element in the TLV type -- as this will indicate how many points (respectively) there are in the TLV type; thus giving the remaining length of the TLV type from a number of Loc-elements point of view. When this TLV type indicates it contains a polygon (shape=103), coordinate points or 3D combinations (X, Y and Z coordinates describing a 3D point) MUST have a specific order or grouping of Loctype elements. The order is this: Polk, et al. Expires July 6, 2009 [Page 11] Internet-Draft Location XML-to-TLV Conversion Jan 2010 For 2D points, this TLV type MUST have this point order: Loctype=106, Loctype=101, Loctype=102, Loctype=101, Loctype=102, Loctype=101, Loctype=102, etc... for however many coordinate points are in the polygon. In other words, the "# of Points" indicator is indicated first, followed by at least 3 sets of points: (# of Points), (x/y), (x/y), (x/y) (more if there are more 2D points in the polygon) For 3D Points, this TLV type MUST have this point order: Loctype=106, Loctype=101, Loctype=102, Loctype=103, Loctype=104, Loctype=101, Loctype=102, etc ... for however many coordinate points are in the polygon. In other words, the "# of Points" is indicated first, followed by at least 3 sets of points: (# of Points), (x/y/z), (x/y/z), (x/y/z) (more if there are more 3D points in the polygon) This TLV type does not repeat the first and last points as GML mandates for a Linear Ring representation of a polygon in XML. That function is part of the conversion from this TLV type to a PIDF-LO, which is described in section 5 of this document. Any polygon can contain an OPTIONAL Centerpoint Loc-element, which is identified by the following Loctypes: Loctype=107 Polygon Centerpoint X-Coordinate - server calculated center point X-Coordinate within a supplied polygon. Loctype=108 Polygon Centerpoint Y-Coordinate - server calculated center point X-Coordinate within a supplied polygon. Loctype=109 Polygon Centerpoint Z-Coordinate - server calculated center point X-Coordinate within a supplied polygon. Loctype=110 Polygon Centerpoint Unit of Measurement Altitude - this is the same as the (UofMA) for Loctype=104 (from section 2.1). An application on another entity, calculates the centerpoint (in 2D or 3D), and provides this via this TLV type to the client. The Location Recipient MUST NOT assume the Location Target is at the centerpoint. This information can be used by applications - making it valuable in some situations. Polk, et al. Expires July 6, 2009 [Page 12] Internet-Draft Location XML-to-TLV Conversion Jan 2010 Loctypes=107 through =110 MUST NOT appear in a shape=102 (circle) TLV type. There is already an implicit centerpoint of the circle, and that is the one X/Y(/Z) point provided to the client in the TLV type. +---------+----------------------------------+---------+ | Loctype | Geoelement | PIDF-LO | +---------+----------------------------------+---------+ | | | | | 107 | Centerpoint X-Coordinate | Sec 5.5 | | | | | | 108 | Centerpoint Y-Coordinate | Sec 5.5 | | | | | | 109 | Centerpoint Z-Coordinate | Sec 5.5 | | | | | | 110 | Centerpoint Unit of Measurement | Sec 5.6 | | | Altitude | | +---------+----------------------------------+---------+ Table 5. Centerpoint Loctypes If there is a centerpoint contained in the TLV type (of a polygon), it has its own order of Loctypes, which is as follows: Loctype=107, Loctype=108, Loctype=109, Loctype=110 There are no additional Loctypes involved with centerpoint. So this looks like the following: center-x, center-y (and optionally) center-z, center-UofMA This order above MUST NOT be altered, and MUST be the last 2D or 3D point of (shape=103) polygon Loc-elements. It is its own separate point. There MUST NOT be more than 1 altitude Loctype within this TLV type, unless each coordinate point in the polygon is a 3D point. In other words, if there is an altitude (Loctype=103) -- the rule is every point is in 3D, or only one of them is in 3D. If none of points are in 3D, then the centerpoint can have the only altitude (Loctype=103). If one of the polygon points is in 3D, the centerpoint MUST NOT have an altitude (Loctype=103). It is RECOMMENDED that if there is a centerpoint within this TLV type, the centerpoint is the one point that includes the altitude for the TLV type. The following additional rules need to be followed for a polygon: o There MUST NOT be more than one Loctype=103 (Z-coordinate) or more than one Loctype=104 (UofMA) within this TLV type when Polk, et al. Expires July 6, 2009 [Page 13] Internet-Draft Location XML-to-TLV Conversion Jan 2010 shape=3. o If the Centerpoint does not include altitude (Loctype=103), or if there is no Centerpoint, and one point of a polygon is defined as 3D - it is REQUIRED (with one exception) the remaining points are defined as 2D, it is assumed the remaining points are at the same altitude as the point that has the altitude (Loctype=103) for that TLV type. The exception to the above rule is when all points include altitude (Loctype=103). In other words, it is an 'only one has it (Z-coordinate), or they all have it' rule. o These are the Loctypes that MUST be present for a 2D polygon within this TLV type: o Loctype=101 (X-Coordinate) o Loctype=102 (Y-Coordinate) o Loctype=106 (# of Points) The shape=103 (polygon) TLV type MUST contain at least 4 points to be a Polygon in this TLV type . See earlier in this section for the order rules around more than one Loctype=101 and =102 (and the centerpoint, if present). o These are the Loctypes that are OPTIONAL for a 2D polygon within this TLV type: o Loctype=107 (Centerpoint X-Coordinate) o Loctype=108 (Centerpoint Y-Coordinate) o These are the Loctypes that MUST NOT be present for a 2D polygon within this TLV type: o Loctype=103 (Z-Coordinate (Altitude)) o Loctype=104 (Unit of Measurement Altitude) o Loctype=105 (Radius) o Loctype=109 (Centerpoint Z-Coordinate (Alt)) o Loctype=110 (Centerpoint Unit of Measurement Altitude) All other Loctypes are OPTIONAL, but MAY change in future extension(s) to this document. o These are the Loctypes that MUST be present for a 3D polygon within this TLV type: o Loctype=101 (X-Coordinate (Latitude)) o Loctype=102 (Y-Coordinate (Longitude)) o Loctype=106 (# of Points) plus either of these two sets: Polk, et al. Expires July 6, 2009 [Page 14] Internet-Draft Location XML-to-TLV Conversion Jan 2010 o Loctype=103 (Z-Coordinate (Altitude)) o Loctype=104 (Unit of Measurement Altitude) or o Loctype=109 (Centerpoint Z-Coordinate (Alt)) o Loctype=110 (Centerpoint Unit of Measurement Altitude) Each UofMA Loctype (=104 and =110) MUST be the same Locvalue, regardless of how many altitudes are in the TLV type for shape=103 (polygon). Loctype=109 and =110 MUST NOT be present without the corresponding Loctypes=107 and =108. To reduce complexity, it is RECOMMENDED that all altitudes - when all points are in 3D - be the same value (i.e., parallel to the ground). The shape=103 (polygon) Option MUST contain at least 3 points to be a polygon. See earlier in this section for the order rules around more than one Loctype=101, =102 and =103 point set. o These are the Loctypes that are OPTIONAL for a 2D polygon within this TLV type: o Loctype=103 (Z-Coordinate (Altitude)) o Loctype=104 (Unit of Measurement Altitude) o Loctype=107 (Centerpoint X-Coordinate (Lat)) o Loctype=108 (Centerpoint Y-Coordinate (Long)) o Loctype=109 (Centerpoint Z-Coordinate (Alt)) o Loctype=110 (Centerpoint Unit of Measurement Altitude) o This Loctype MUST NOT be present for a 3D polygon within this TLV type: o Loctype=105 (Radius) Loctypes=111 (Datum) and =112 (Valid-for) are OPTIONAL in either a 2D or 3D polygon, but MAY change in future extension(s) to this document. 2.4 An Ellipse To be Completed... 2.5 An Arc Band To be Completed... Polk, et al. Expires July 6, 2009 [Page 15] Internet-Draft Location XML-to-TLV Conversion Jan 2010 2.6 A Sphere To be Completed... 2.7 An Ellipsoid To be Completed... 2.8 A Prism To be Completed... 2.9 Additional Optional Loctypes The following Loctypes are OPTIONAL: Loctype=111 Datum - the base line of reference from which measurements are taken out from (here both horizontally and vertically). When not present, WGS84 2D or 3D (EPSG 4326 and 4979 respectively) MUST be assumed. This Loctype indicates another Datum is assigned to all coordinate Loctypes in TLV shape (meaning each X-coordinate, Y-coordinate, Z-coordinate, including Centerpoint coordinates). The WGS84 datum can be made explicit, but including this Loctype=111, Locvalue=1; two other datum combinations are included here. This document establishes the following alternate (to WGS84) datums: Datum = 1 denotes WGS84 (EPSG4326) for 2D, and (EPSG4979) for 3D (depending on whether an altitude Loctype is present). Datum = 2 denotes the horizontal datum NAD83 as defined by the EPSG as their CRS Code 4269; North American Vertical Datum of 1988 (NAVD88) is the associated vertical datum for NAD83 Datum = 3 denotes the horizontal datum NAD83 as defined by the EPSG as their CRS Code 4269; Mean Lower Low Water (MLLW) is the associated vertical datum for NAD83 Each of the above is IANA registered. Loctype=112 Valid-for - measured in seconds the location within this TLV type is to be considered good, before needing a refresh, which maps to PIDF. Polk, et al. Expires July 6, 2009 [Page 16] Internet-Draft Location XML-to-TLV Conversion Jan 2010 +---------+----------------------------------+---------+ | Loctype | Geoelement | PIDF-LO | +---------+----------------------------------+---------+ | | | | | 111 | Datum | Sec 5.7 | | | | | | 112 | Valid-for | Sec 5.8 | +---------+----------------------------------+---------+ Table 6. List of Additional non-grouped Loctypes Loctypes 113 - 255 are reserved. NOTE: the authors are open to including both the Confidence and/or Uncertainty Loctypes if the WG can reasonably provide valid use-cases, as well as industry accepted definitions. Currently, the US Federal Communications Commission (FCC), as one source, is ambiguous about either of these fields, including lacking a good definition for either. 3. What to do with Civic CAtypes and this Proposal Loctypes 1-100 are reserved for civic registrations within IANA, which are valid if using this TLV payload to communicate. 4. Recommendations for Converting this Option into a PIDF-LO The following examples show how the TLV shapes map into a PIDF-LO. Currently, not every Geoelement maps properly into the PIDF-LO. Those mappings are for another effort. 4.1 X-, Y- and Z-Coordinate placement in the PIDF-LO The following 2D XML element is where the X-, Y-coordinates go into the PIDF-LO: 32 -86 The following 3D XML element is where the X-, Y-, Z-coordinates go into the PIDF-LO: 32 -86 10 Polk, et al. Expires July 6, 2009 [Page 17] Internet-Draft Location XML-to-TLV Conversion Jan 2010 4.2 Unit of Measurement Altitude (UofMA) in the PIDF-LO GML expects altitude (Loctype=103) to be in meters only. This is not possible today because the need express altitude in floors. This results in the following ways of expressing the Z-coordinate: - if Z-coordinate (Loctype=103) is given in floors (Loctype=104, Locvalue=3), the PIDF-LO generator needs to place the altitude value into the element. - if Z-coordinate (Loctype=103) is given in meters (Loctype=104, Locvalue=1), PIDF-LO generator has two options: Choice#1 - placing the altitude value into the same element that Lat and Long go; Choice#2 - shown this way 15 [Editor's Note: if this solution is chosen, then one of the two choices above for altitude placement needs to be mandatory to implement, with the other being optional.] 4.3 A Circle expressed within the PIDF-LO The Loctype=102 part of this TLV payload is shown at the beginning of the XML as . The schema for a circle is defined in [GeoShape]. The following is where Loctype=105 fits into the PIDF-LO, as described in the GML2.1 specification here [OpenGIS]: 32.51 -86.51 33 Polk, et al. Expires July 6, 2009 [Page 18] Internet-Draft Location XML-to-TLV Conversion Jan 2010 4.4 A Polygon placement within a PIDF-LO The Loctype=103 part of this TLV payload is shown at the beginning of the XML as . As stated earlier, a polygon has to have at least 4 linear ring points within it. Also stated earlier, if there is a 3rd dimension, there can only be one altitude value, or every point has to have the same altitude value. This is to reduce complexity. The XML for a circle is defined in [GeoShape]. 32.51 -86.51 32.56 -86.56 32.56 -86.61 32.51 -86.66 32.46 -86.61 32.46 -86.56 32.51 -86.51 4.5 Centerpoint X-, Y- and Z-Coordinate placement in the PIDF-LO This is defined in [ID-Cent], but is not in any part of the GML specification family (for any geometry, including triangle, square or rectangle, polygon, etc). 4.6 Centerpoint Unit of Measurement Altitude (CUofMA) placement in the PIDF-LO TBD GML does not specify XML for a centerpoint of an area. There is a draft that currently defines how this is done in a PIDF-LO [ID-Cent], but not GML. Polk, et al. Expires July 6, 2009 [Page 19] Internet-Draft Location XML-to-TLV Conversion Jan 2010 4.7 Datum placement in the PIDF-LO At issue here is that GML specifically assumes WGS84 2D or 3D to be the datum, therefore a datum element is not present for the PIDF-LO. For points, circles and polygons using the WGS84 datum, each accomplishes this identification with the use of srsName="urn:ogc:def:crs:EPSG::4326" for 2D representations, and srsName="urn:ogc:def:crs:EPSG::4979" for 3D representations. Unfortunately, WGS84 is a goal for many (all?) systems; one in which some have not achieved yet. Some systems believe it might be decades before they are converted over to the WGS84 datum. For a 2D or 3D non-WGS84 datum, this is the XML schema from [OpenGIS]: For 1D Vertical only coordinate reference system utilized for heights and depths, where WGS84 2D is used horizontally, the following schema from [OpenGIS] is this: Polk, et al. Expires July 6, 2009 [Page 20] Internet-Draft Location XML-to-TLV Conversion Jan 2010 4.8 Valid-for placement in the PIDF-LO TBD (this is likely part of the PIDF specification) 5. Security considerations There are no additional security considerations in addition to those contained within RFC 4776. 6. IANA considerations This IANA registers the following fields introduced by this TLV format. 6.1 The Individual TLV Types +------+-----------------------------------------------+-----------+ | Type | Description | Reference | +------+-----------------------------------------------+-----------+ | 101 | X-Coordinate (Latitude) | RFC XXXX* | | 102 | Y-Coordinate (Longitude) | RFC XXXX* | | 103 | Z-Coordinate (Altitude) | RFC XXXX* | | 104 | Unit of Measurement Altitude ** | RFC XXXX* | | 105 | Radius | RFC XXXX* | | 106 | # of Points | RFC XXXX* | | 107 | Centerpoint X-Coordinate (Lat) | RFC XXXX* | | 108 | Centerpoint Y-Coordinate (Long) | RFC XXXX* | | 109 | Centerpoint Z-Coordinate (Alt) | RFC XXXX* | | 110 | Centerpoint Unit of Measurement | RFC XXXX* | | | Altitude ** | | | 111 | Datum | RFC XXXX* | | 112 | Valid-for | RFC XXXX* | | . | | RFC XXXX* | | . | | RFC XXXX* | | . | | RFC XXXX* | * RFC-Editor -- where "RFC XXXX" appears, please replace this string with the RFC number assigned to this document, if and when it is published as an RFC. ** Both Units of Measurement for Altitude are IANA registered in section 6.2. Loctypes 1-100 are reserved (and could be mapped 1:1 to CAtypes). Polk, et al. Expires July 6, 2009 [Page 21] Internet-Draft Location XML-to-TLV Conversion Jan 2010 Loctypes 113 - 255 are reserved for future assignment. Additions, modifications or deletions to the above table require a standards track RFC. 6.2 The Unit of Measurement for Altitude This document IANA registers the following Unit of Measurement for Altitude. For Loctype=104 (UofMA) and Loctype=110 (Centerpoint UofMA), the following IANA registrations are necessary, and identical for either Loctype: +---------+----------+---------------------------------------------+ | Loctype | Locvalue | Description | +---------+----------+---------------------------------------------+ | 104 | 1 | meters above or below the datum 0 plane | | | | | | 104 | 2 | floors - defined by local administration | | | | | +---------+----------+---------------------------------------------+ Additions, modifications or deletions to the above table require expert review, followed by a published RFC. 6.3 Datums Registered by this Document This document IANA registers the following Datums to be used by the Loctype=111 (Datum). If no Loctype=111 is present in this Option, it the default datum will be either EPSG-4326 for 2D, and EPSG-4979 for 3D. Datum = 1 denotes WGS84 (EPSG4326) for 2D, and (EPSG4979) for 3D (depending on whether an altitude Loctype is present). Datum = 2 denotes the horizontal datum NAD83 as defined by the EPSG as their CRS Code 4269; North American Vertical Datum of 1988 (NAVD88) is the associated vertical datum for NAD83 Datum = 3 denotes the vertical datum NAD83 as defined by the EPSG as their CRS Code 4269; Mean Lower Low Water (MLLW) is the associated vertical datum for NAD83 7. Acknowledgments Your name here... Polk, et al. Expires July 6, 2009 [Page 22] Internet-Draft Location XML-to-TLV Conversion Jan 2010 8. References 8.1 Normative References [RFC2119] S. Bradner, "Key words for use in RFCs to Indicate Requirement Levels", RFC 2119, March 1997 [OpenGIS] - http://www.opengeospatial.org/standards/gml [RFC4119] J. Peterson, "A Presence-based GEOPRIV Location Object Format", RFC 4119, December 2005 [RFC3693] J. Cuellar, J. Morris, D. Mulligan, J. Peterson. J. Polk, "Geopriv Requirements", RFC 3693, February 2004 [GeoShape] Thomson, M. and C. Reed, "GML 2.1.1 PIDF-LO Shape Application Schema for use by the Internet Engineering Task Force (IETF)", Candidate OpenGIS Implementation Specification 06-142, Version: 0.0.9, December 2006. [RFC5491] J. Winterbottom, M. Thomson, H. Tschofenig, "GEOPRIV PIDF-LO Usage Clarification, Considerations, and Recommendations ", RFC 5491, March 2009 [ID-Cent] J. Polk, A. Thomson, M. Linsner, "Defining a Centerpoint for the PIDF-LO", "work in progress", Mar 2009 8.2 Informative References There are no Informational references at this time Authors' Addresses James Polk 3913 Treemont Circle Colleyville, Texas, USA +1.817.271.3552 mailto: jmpolk@cisco.com Allan Thomson Cisco Systems, Inc. San Jose, California, USA Email: althomso@cisco.com Polk, et al. Expires July 6, 2009 [Page 23] Internet-Draft Location XML-to-TLV Conversion Jan 2010 Marc Linsner Cisco Systems, Inc. Marco Island, Florida, USA Email: mlinsner@cisco.com Polk, et al. Expires July 6, 2009 [Page 24]