Specifying Local Civic Address Fields in PIDF-LO
draft-winterbottom-geopriv-local-civic-03

Abstract

A backwardly-compatible mechanism for adding locally significant civic address elements to the Geopriv civic address format is described. A formal mechanism for handling unsupported extensions when translating between XML and DHCP civic address forms is defined for entities that need to perform this translation.

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 April 25, 2011.

Copyright Notice

Copyright (c) 2010 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.

Table of Contents

1.  Introduction
2.  Terminology
3.  Specifying Local Civic Elements
4.  Translating Unsupported Elements
    4.1.  DHCP to XML Format Translation
    4.2.  XML to DHCP Format Translation
        4.2.1.  Namespace CAtype
        4.2.2.  Element CAtype
        4.2.3.  Conversion Constraints
        4.2.4.  Conversion Example
        4.2.5.  Migration to Registered Elements
5.  Security Considerations
6.  IANA Considerations
    6.1.  CAtype Registration
    6.2.  URN Sub-Namespace Registration for urn:ietf:params:xml:ns:geopriv:held:id
    6.3.  XML Schema Registration
7.  Unsupported Extension XML Schema
8.  Acknowledgements
9.  References
    9.1.  Normative References
    9.2.  Informative References
Appendix A.  Identifying EXT Elements in LoST Validation
§  Authors' Addresses

1.  Introduction

The Geopriv civic location specifications ([RFC4776] (Schulzrinne, H., “Dynamic Host Configuration Protocol (DHCPv4 and DHCPv6) Option for Civic Addresses Configuration Information,” November 2006.), [RFC5139] (Thomson, M. and J. Winterbottom, “Revised Civic Location Format for Presence Information Data Format Location Object (PIDF-LO),” February 2008.)) define an XML and binary representtations for civic addresses that allow for the expression of civic addresses in most countries. Guidance for the use of these formats for the civic addresses in different countries is included in [RFC5774] (Wolf, K. and A. Mayrhofer, “Considerations for Civic Addresses in the Presence Information Data Format Location Object (PIDF-LO): Guidelines and IANA Registry Definition,” March 2010.).

Subsequent to these specifications being produced, use cases for locally significant civic address elements have emerged. These elements do not all readily fit existing elements, as recommended in [RFC5774] (Wolf, K. and A. Mayrhofer, “Considerations for Civic Addresses in the Presence Information Data Format Location Object (PIDF-LO): Guidelines and IANA Registry Definition,” March 2010.). These elements are also sufficiently domain-specific that they do not merit additions to the limited space available for globally recognized elements.

The XML format for civic addresses (Thomson, M. and J. Winterbottom, “Revised Civic Location Format for Presence Information Data Format Location Object (PIDF-LO),” February 2008.) [RFC5139] provides a mechanism that allows for the addition of standardized or privately understood elements. A similar facility for private extension is not provided for the DHCP format (Schulzrinne, H., “Dynamic Host Configuration Protocol (DHCPv4 and DHCPv6) Option for Civic Addresses Configuration Information,” November 2006.) [RFC4776], though new specifications are able to define new CAtypes (civic address types).

A recipient of a civic address in either format currently has no option than to ignore elements that it does not understand. Where a recipient performs a translation between the two formats, this results in the unsupported elements being discarded. In order for a new extension to be useful to a recipient that performs translation, the recipient has to understand the extension and know how to correlate an XML element with a CAtype.

This document defines a method that allows the specification of civic address elements with private or local significance. How these are defined and used in both XML and DHCP formats is described. This document also describes how a recipient can translate unsupported civic addresses between the two formats.

The additions described in this document are backwardly compatible. Furthermore, they allow for a civic address to be translated without loss of information.

2.  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 [RFC2119] (Bradner, S., “Key words for use in RFCs to Indicate Requirement Levels,” March 1997.).

3.  Specifying Local Civic Elements

The civic schema in [RFC5139] (Thomson, M. and J. Winterbottom, “Revised Civic Location Format for Presence Information Data Format Location Object (PIDF-LO),” February 2008.) defines an ordered structure of elements that can be combined to describe a civic address. The XML extension point at the bottom of the schema is used to include address elements of local significance into the main civic body.

New elements are defined in a new XML namespace (Hollander, D., Layman, A., Tobin, R., and T. Bray, “Namespaces in XML 1.1 (Second Edition),” August 2006.) [XMLNS]. This is true of address elements with significance within private or localized domains, as well as those that are intended for global applicability.

For example, suppose the (fictitious) Central Devon Canals Authority wishes to introduce a new civic element called "bridge". The authority defines an XML namespace that includes a "bridge" element. The namespace needs to be a unique URI, for example http://devon.canals.org.uk/civic.

A civic address that includes the new "bridge" element is shown in Figure 1 (Local Civic Object Example).

   <civicAddress xml:lang="en-GB"
        xmlns="urn:ietf:params:xml:ns:pidf:geopriv10:civicAddr"
        xmlns:cdc="http://devon.canals.org.uk/civic">
     <country>UK</country>
     <A1>Devon</A1>
     <A3>Monkokehampton</A3>
     <RD>Deckport</RD>
     <STS>Cross</STS>

     <cdc:bridge>21451338</cdc:bridge>

   </civicAddress>

An entity that receives this location information might not understand the locally specified address element. As long as the added element is able to be safely ignored, the remainder of the civic address can be used. The result is that the information is not as useful as it could be, but the added element does not prevent the use of the remainder of the address.

The address can be passed to other applications, such as a LoST server (Hardie, T., Newton, A., Schulzrinne, H., and H. Tschofenig, “LoST: A Location-to-Service Translation Protocol,” August 2008.) [RFC5222], without modification. If the application understands the added elements, it is able to make use of that information. For example, if this civic address is acquired using HELD (Barnes, M., “HTTP-Enabled Location Delivery (HELD),” September 2010.) [RFC5985], it can be included in a LoST request directly.

4.  Translating Unsupported Elements

Unsupported civic address elements can be carried without consequence only as long as the format of the address does not change. When converting between the XML and DHCP formats, these unsupported elements are necessarily discarded: the entity performing the translation has no way to know the correct element to use in the target format.

4.1.  DHCP to XML Format Translation

The registration of a new CAtype following the process in [RFC4776] (Schulzrinne, H., “Dynamic Host Configuration Protocol (DHCPv4 and DHCPv6) Option for Civic Addresses Configuration Information,” November 2006.) means that a recipient is potentially unable to produce a complete XML representation of the DHCP civic address.

To address this, a new EXT XML element is defined that allows the XML format to carry an unsupported CAtype without modification. This type extends the base civic address element type by adding a CAtype attribute that identifies the CAtype.

For example, if CAtype 199 is defined, but not understood, this is carried in the XML format as shown in Figure 2 (XML Civic Address with Unsupported Extension).

   <civicAddress xml:lang="en-GB"
     xmlns="urn:ietf:params:xml:ns:pidf:geopriv10:civicAddr"
     xmlns:ext="urn:ietf:params:xml:ns:pidf:geopriv10:civicAddr:ext">
     <country>UK</country>
     <A1>Devon</A1>
     <A3>Monkokehampton</A3>
     <RD>Deckport</RD>
     <STS>Cross</STS>

     <ext:EXT CAtype="199">21451338</ext:EXT>

   </civicAddress>

No facility is provided for the conversion of private or local use CAtypes when translating from DHCP to XML. Extensions for private or local use do not use new CAtypes. Private or local use extensions MUST be defined using the XML extension mechanism.

4.2.  XML to DHCP Format Translation

Extensions to the XML format are defined in a new XML namespace. Extensions that have global applicability might have a specific CAtype allocated. Extensions that are only for private or local use have no corresponding CAtype and always use this translation mechanism.

Unsupported extensions in the XML format can be added to a DHCP format civic address using two new elements: the Namespace CAtype and the Element CAtype.

4.2.1.  Namespace CAtype

The "Namespace" CAtype (CAtype XX [IANA/RFC-Editor: please use assigned value]) provides the definition of an XML namespace and a corresponding namespace prefix. This is analogous to attributes beginning with xmlns in [XMLNS] (Hollander, D., Layman, A., Tobin, R., and T. Bray, “Namespaces in XML 1.1 (Second Edition),” August 2006.).

The Abstract Backus-Naur Form (ABNF) (Crocker, D. and P. Overell, “Augmented BNF for Syntax Specifications: ABNF,” January 2008.) [RFC5234] for this CAtype uses a Unicode character as the basic element and borrows BNF definitions from [XMLNS] (Hollander, D., Layman, A., Tobin, R., and T. Bray, “Namespaces in XML 1.1 (Second Edition),” August 2006.):

   ns-CAtype      = Prefix "=" *UCHAR
   UCHAR          = <any Unicode character>

The Namespace CAtype is sent multiple times if elements from multiple namespaces are required.

4.2.2.  Element CAtype

The "Element" CAtype (CAtype YY [IANA/RFC-Editor: please use assigned value]) conveys a single element and its value. The element name includes a namespace prefix, as bound by the "Namespace" CAtype, plus the local name from the corresponding XML element. This is followed by the value of the element. Prefix and local name are separated by a colon (:) as in [XMLNS] (Hollander, D., Layman, A., Tobin, R., and T. Bray, “Namespaces in XML 1.1 (Second Edition),” August 2006.); element name and value are separated by an equals sign (=).

The Abstract Backus-Naur Form (ABNF) (Crocker, D. and P. Overell, “Augmented BNF for Syntax Specifications: ABNF,” January 2008.) [RFC5234] for this CAtype uses a Unicode character as the basic element and borrows BNF definitions for Prefix and LocalPart from [XMLNS] (Hollander, D., Layman, A., Tobin, R., and T. Bray, “Namespaces in XML 1.1 (Second Edition),” August 2006.):

   element-CAtype = Prefix ":" LocalPart "=" *UCHAR

An Element CAtype that includes a prefix that has not been bound in a Namespace CAtype is ignored.

4.2.3.  Conversion Constraints

This conversion only works for elements that have textual content and an optional xml:lang attribute. Elements with complex content or other attributes - aside from namespace bindings - MUST be ignored if they are not understood.

A Namespace CAtype MUST precede the Element CAtype that uses the binding it defines. A Namespace CAtype MUST NOT reuse a prefix. To aid in client parsing and reduce the likelihood of server configuration errors, all Namespace CAtypes SHOULD proceed any Element CAtypes.

4.2.4.  Conversion Example

The following example civic address contains two private use extensions:

   <civicAddress xml:lang="en-US"
        xmlns="urn:ietf:params:xml:ns:pidf:geopriv10:civicAddr"
        xmlns:post="http://postsoftheworld.net/ns/posts"
        xmlns:ap="http://www.example.com/airport/5.0">
     <country>US</country>
     <A1>CA</A1>

     <post:lamp>2471</post:lamp>
     <post:pylon>AQ-374-4(c)</post:pylon>

     <ap:airport>LAX</ap:airport>
     <ap:terminal>Tom Bradley</ap:terminal>
     <ap:concourse>G</ap:concourse>
     <ap:gate>36B</ap:gate>
   </civicAddress>

Might be converted to the DHCP form as follows:

   country     = US
   CAtype[0]   = en-US
   CAtype[1]   = CA
   CAtype[XX]  = post=http://postsoftheworld.net/ns/posts
   CAtype[XX]  = ap=http://www.example.com/airport/5.0
   CAtype[YY]  = post:lamp=2471
   CAtype[YY]  = post:pylon=AQ-374-4(c)
   CAtype[YY]  = ap:airport=LAX
   CAtype[YY]  = ap:terminal=Tom Bradley
   CAtype[YY]  = ap:concourse=G
   CAtype[YY]  = ap:gate=36B

4.2.5.  Migration to Registered Elements

An element that is initially added as a local extension might be recognized as being more widely applicable. In this case, a CAtype might be allocated for this extension. Depending on whether a client is aware of the CAtype allocation, they could convert the XML form differently. A recipient that understands a CAtype MUST treat the extended form as being semantically equivalent.

For example, if the bridge element from the examples in Figure 1 (Local Civic Object Example) and Figure 2 (XML Civic Address with Unsupported Extension) is allocated a CAtype of 199, a recipient treats all of the four following forms as equivalent:

   <cdc:bridge
     xmlns:cdc="http://devon.canals.org.uk/civic">
     21451338
   </cdc:bridge>

   <ext:EXT CAtype="199"
     xmlns:ext="urn:ietf:params:xml:ns:pidf:geopriv10:civicAddr:ext">
     21451338
   </ext:EXT>

   CAtype[XX]  = canal=http://devon.canals.org.uk/civic
   CAtype[YY]  = canal:bridge=21451338

   CAtype[199] = 21451338

5.  Security Considerations

This document defines a formal way to extend the existing Geopriv civic schema. No security threats are introduced by this document.

Security threats applicable to the civic address formats are described in [RFC4776] (Schulzrinne, H., “Dynamic Host Configuration Protocol (DHCPv4 and DHCPv6) Option for Civic Addresses Configuration Information,” November 2006.) (DHCP) and [RFC5139] (Thomson, M. and J. Winterbottom, “Revised Civic Location Format for Presence Information Data Format Location Object (PIDF-LO),” February 2008.) (XML).

6.  IANA Considerations

Two civic address types are registered for the DHCP format. An XML namespace and schema are registered for the XML format in accordance with guidelines in [RFC3688] (Mealling, M., “The IETF XML Registry,” January 2004.).

6.1.  CAtype Registration

This document registers two civic address types in the "CAtypes" registry established by [RFC4776] (Schulzrinne, H., “Dynamic Host Configuration Protocol (DHCPv4 and DHCPv6) Option for Civic Addresses Configuration Information,” November 2006.). The following CAtypes are added:

[[IANA/RFC-EDITOR: Please replace XX and YY with the allocated CAtype]]

6.2.  URN Sub-Namespace Registration for urn:ietf:params:xml:ns:geopriv:held:id

This section registers a new XML namespace, urn:ietf:params:xml:ns:pidf:geopriv10:civicAddr:ext, as per the guidelines in [RFC3688] (Mealling, M., “The IETF XML Registry,” January 2004.).

urn:ietf:params:xml:ns:pidf:geopriv10:civicAddr:ext

IETF, GEOPRIV working group (geopriv@ietf.org), James Winterbottom (james.winterbottom@andrew.com).

    BEGIN
      <?xml version="1.0"?>
      <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
        "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
      <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
        <head>
          <title>Unsupported Civic Address Extension</title>
        </head>
        <body>
          <h1>Namespace for Unsupported Civic Address Extension</h1>
          <h2>urn:ietf:params:xml:ns:pidf:geopriv10:civicAddr:ext</h2>
[[NOTE TO IANA/RFC-EDITOR: Please update RFC URL and replace XXXX
    with the RFC number for this specification.]]
          <p>See <a href="[[RFC URL]]">RFCXXXX</a>.</p>
        </body>
      </html>
    END

6.3.  XML Schema Registration

This section registers an XML schema as per the guidelines in [RFC3688] (Mealling, M., “The IETF XML Registry,” January 2004.).

URI:

urn:ietf:params:xml:ns:pidf:geopriv10:civicAddr:ext

Registrant Contact:

IETF, GEOPRIV working group (geopriv@ietf.org), James Winterbottom (james.winterbottom@andrew.com).

Schema:

The XML for this schema can be found as the entirety of Section 7 (Unsupported Extension XML Schema) of this document.

7.  Unsupported Extension XML Schema

<?xml version="1.0"?>
<xs:schema
targetNamespace="urn:ietf:params:xml:ns:pidf:geopriv10:civicAddr:ext"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:ca="urn:ietf:params:xml:ns:pidf:geopriv10:civicAddr"
xmlns:ext="urn:ietf:params:xml:ns:pidf:geopriv10:civicAddr:ext"
xmlns:xml="http://www.w3.org/XML/1998/namespace"
elementFormDefault="qualified" attributeFormDefault="unqualified">

  <xs:import
      namespace="urn:ietf:params:xml:ns:pidf:geopriv10:civicAddr"/>

  <xs:element name="EXT" type="ext:caExtType"/>
  <xs:complexType name="caExtType">
    <xs:simpleContent>
      <xs:extension base="ca:caType">
        <xs:attribute name="CAtype" use="required">
          <xs:simpleType>
            <xs:restriction base="xs:nonNegativeInteger">
              <xs:maxInclusive value="255"/>
            </xs:restriction>
          </xs:simpleType>
        </xs:attribute>
      </xs:extension>
    </xs:simpleContent>
  </xs:complexType>
</xs:schema>

8.  Acknowledgements

Thanks to Brian Rosen, Delaine Arnold, Robins George, and anyone else who has tried to extend the civic schema and found it a little unintuitive.

9.  References

9.1. Normative References

9.2. Informative References

Appendix A.  Identifying EXT Elements in LoST Validation

LoST (Hardie, T., Newton, A., Schulzrinne, H., and H. Tschofenig, “LoST: A Location-to-Service Translation Protocol,” August 2008.) [RFC5222] uses the name of civic address elements to identify them when validating the content of an address. An EXT element can appear multiple times, each one with a different CAtype attribute to distinguish it. In this case, a LoST response is unable to distinguish between one EXT element and another. In order to identify a specific EXT element, the CAtype is also needed.

To deal with this problem, a set of pseudo-elements are defined. These pseudo-elements exist in the urn:ietf:params:xml:ns:pidf:geopriv10:civicAddr:ext namespace, like the EXT element, but are not defined in the corresponding schema. The local name of each of these elements is formed from the string CAtype plus the decimal value of the CAtype attribute. This pseudo-element name is included in addition to the EXT element name.

For instance, a civic address might contain the following EXT elements:

   <ext:EXT CAtype="199">21451338</ext:EXT>
   <ext:EXT CAtype="231">Rubbish</ext:EXT>

These can be identified in a LoST response as follows:

   <locationValidation xmlns="urn:ietf:params:xml:ns:lost1"
       xmlns:ext="urn:ietf:params:xml:ns:pidf:geopriv10:civicAddr:ext">
     <valid>ext:EXT ext:CAtype199</valid>
     <invalid>ext:EXT ext:CAtype231</invalid>
   </locationValidation>

Authors' Addresses