RFC 5139
Revised Civic Location Format for Presence Information Data Format Location Object (PIDF-LO)
RFC 5139: Revised Civic Location Format for PIDF-LO 🎀
Okay bestie, here's the title block tea ☕. This is RFC 5139, titled Revised Civic Location Format for Presence Information Data Format Location Object (PIDF-LO) 🦋. It came out of the Network Working Group, the authors are M. Thomson and J. Winterbottom (from Andrew 💅), it's a Standards Track doc, and it's dated February 2008. It updates RFC 4119 🔥. There's no Obsoletes line, so it doesn't replace anything outright.
Status of This Memo ✨
This document is an Internet standards track protocol for the Internet community, and it's basically asking everyone to talk about it and suggest improvements 🗣️. For the official standardization state and status of this protocol, check the current edition of "Internet Official Protocol Standards" (STD 1). Distribution of this memo is unlimited, so share away 💜.
Abstract 🌸
This doc defines an XML format for representing civic location 🏡. It's made for PIDF-LO documents and it replaces the civic location format in RFC 4119, so it's giving "new and improved" 💖. It's based on the civic address definition in PIDF-LO, but it adds a bunch of new elements inspired by the civic types defined for Dynamic Host Configuration Protocol (DHCP) 🧚. It also adds a hierarchy so complicated road identity schemes can finally be expressed 🛣️. Plus it supports the xml:lang language tag and restricts the types of elements where appropriate 🌈.
Table of Contents 🍓
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3
2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3
3. Changes from PIDF-LO . . . . . . . . . . . . . . . . . . . . . 3
3.1. Additional Civic Address Types . . . . . . . . . . . . . . 3
3.2. New Thoroughfare Elements . . . . . . . . . . . . . . . . 4
3.2.1. Street Numbering . . . . . . . . . . . . . . . . . . . 5
3.2.2. Directionals and Other Qualifiers . . . . . . . . . . 5
3.3. Country Element . . . . . . . . . . . . . . . . . . . . . 6
3.4. A1 Element . . . . . . . . . . . . . . . . . . . . . . . . 6
3.5. Languages and Scripts . . . . . . . . . . . . . . . . . . 6
3.5.1. Converting from the DHCP Format . . . . . . . . . . . 7
3.5.2. Combining Multiple Elements Based on Language
Preferences . . . . . . . . . . . . . . . . . . . . . 7
3.6. Whitespace . . . . . . . . . . . . . . . . . . . . . . . . 7
4. Civic Address Schema . . . . . . . . . . . . . . . . . . . . . 8
5. Example . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
6. Security Considerations . . . . . . . . . . . . . . . . . . . 10
7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10
7.1. URN sub-namespace registration for
'urn:ietf:params:xml:ns:pidf:geopriv10:civicAddr' . . . . 10
7.2. XML Schema Registration . . . . . . . . . . . . . . . . . 11
7.3. CAtype Registry Update . . . . . . . . . . . . . . . . . . 11
8. References . . . . . . . . . . . . . . . . . . . . . . . . . . 12
8.1. Normative References . . . . . . . . . . . . . . . . . . . 12
8.2. Informative References . . . . . . . . . . . . . . . . . . 12
Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 131. Introduction 💫
So, ever since the original PIDF-LO civic spec landed in [RFC4119], people realized it was missing a bunch of extra parameters that let you pin down a civic location more precisely 🎯. Most of those extra parameters got gathered up in [RFC4776] 📚.
This doc revises the GEOPRIV civic form so it includes those additional civic parameters from [RFC4776] 💅. It also introduces a hierarchical structure for thoroughfare (road) identification, which some countries actually use 🛣️. On top of that, new elements are defined so you can get even more precise about where a place is 🔍.
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]. Those are the official vocab words, so pay attention to them 👀.
Here, "thoroughfare" means a road, part of a road, or some other access route where a final point is identified 🛤️. That matches the definition used in [UPU-S42], so everyone's on the same page 📖.
3. Changes from PIDF-LO 🦋
3.1. Additional Civic Address Types
[RFC4776] gives you a full set of parameters you can use to describe a civic location 🗺️. Specifically, it lists several civic address types (CAtypes) that need support in the formal PIDF-LO definition, and those types aren't in [RFC4119] 🙈.
Some of these changes add new elements that are needed to support more complex structures for naming street addresses 🏘️. You can read more about that in Section 3.2 💖.
+-----------+--------+-------------------------------+--------------+
| New Field | CAtype | Description | Example |
+-----------+--------+-------------------------------+--------------+
| BLD | 25 | Building (structure) | Hope Theatre |
| | | | |
| UNIT | 26 | Unit (apartment, suite) | 12a |
| | | | |
| ROOM | 28 | Room | 450F |
| | | | |
| PLC | 29 | Place-type | office |
| | | | |
| PCN | 30 | Postal community name | Leonia |
| | | | |
| POBOX | 31 | Post office box (P.O. box) | U40 |
| | | | |
| ADDCODE | 32 | Additional Code | 13203000003 |
| | | | |
| SEAT | 33 | Seat (desk, cubicle, | WS 181 |
| | | workstation) | |
| | | | |
| RD | 34 | Primary road or street | Broadway |
| | | | |
| RDSEC | 35 | Road section | 14 |
| | | | |
| RDBR | 36 | Road branch | Lane 7 |
| | | | |
| RDSUBBR | 37 | Road sub-branch | Alley 8 |
| | | | |
| PRM | 38 | Road pre-modifier | Old |
| | | | |
| POM | 39 | Road post-modifier | Extended |
+-----------+--------+-------------------------------+--------------+
Table 1: New Civic PIDF-LO TypesFull descriptions of all of these types live in [RFC4776] 📚✨.
3.2. New Thoroughfare Elements 🛣️
In some countries, a thoroughfare can be split up into sections, and street numbers often get reused between those sections 🔁. That's why a road section identifier is required to make an address unique 🫶. Like, "West Alice Parade" in the figure below has 5 sections, each numbered from 1, so unless you say which section you mean, "7 West Alice Parade" could exist in 5 different places 😭. The "RDSEC" element is what you use to specify the section 💅.
Minor streets can share the same name, so the only way to tell them apart is the major thoroughfare they intersect 🚦. For example, both "West Alice Parade, Section 3" and "Bob Street" could be intersected by a "Carol Lane" 🤯. The "RDBR" element specifies a road branch when the branch name doesn't uniquely identify the road 🌿. Road branches MAY also be used where a major thoroughfare is split into sections 🍰.
A road sub-branch is related to a road branch the same way a road branch is related to a road 🧁. The "RDSUBBR" element is used to identify road sub-branches 🔍.
The "A6" element is kept for countries that need this level of detail 🌍. But if "A6" was used for street names in [RFC4119], it MUST NOT be used now; the "RD" element MUST be used for thoroughfare data 🚫. No exceptions, bestie 💀.
Here's a fictional arrangement of roads where these new thoroughfare elements apply 🗺️:
| ||
| ---------------||
| Carol La. Carol La. || Bob
| || St.
| West Alice Pde. ||
==========/=================/===============/==========||===========
Sec.1 Sec.2 Sec.3 | Sec.4 || Sec.5
| ||
----------| Carol ||
Alley 2 | La. ||
| ||3.2.1. Street Numbering 🔢
Adding the new thoroughfare elements changes how more specific civic address data gets read 👀. Street numbering (the "HNO" element) applies to the most specific road element you specify, which means the first one you specify out of "RDSUBBR", "RDBR", "RDSEC", or "RD" 🎯.
3.2.2. Directionals and Other Qualifiers 🧭
The "PRM", "POM", "PRD", "POD", and "STS" elements always apply to the value of the "RD" element only 💖. If road branches or sub-branches need street suffixes or qualifiers, they MUST be included in the "RDBR" or "RDSUBBR" element text 📝. Don't skip it!! 😤
3.3. Country Element 🌏
The "country" element is different from the one in [RFC4119] because its value space is now restricted to two uppercase characters 🔠. Those characters correspond to the alpha-2 codes in [ISO.3166-1] 🏳️🌈.
3.4. A1 Element 🏙️
The "A1" element is for the top-level subdivision within a country 🗾. If there's no country-specific guide for using the A-series of elements, the second part of the ISO 3166-2 code [ISO.3166-2] for a country subdivision SHOULD be used 💅. An ISO 3166-2 code is a country code and a hyphen, plus a code of one, two, or three characters or numerals 🔤. For the "A1" element, you drop the leading country code and hyphen and only include the subdivision code ✂️.
For example, Canada's codes include CA-BC, CA-ON, and CA-QC 🍁. Luxembourg only has three single-character codes: LU-D, LU-G, and LU-L 🇱🇺. Australia uses both two- and three-character codes, like AU-ACT, AU-NSW, and AU-NT 🦘. France uses numerical codes for mainland France and letters for territories, like FR-75 and FR-NC 🥖. This gives you these fragments:
<country>CA</country><A1>ON</A1>
<country>LU</country><A1>L</A1>
<country>AU</country><A1>ACT</A1>
<country>FR</country><A1>75</A1>3.5. Languages and Scripts ✨
okay so the civic address XML schema lets you slap an xml:lang attribute on basically every element 🌈 the exceptions are country and PLC, because those two are language-neutral vibes. country values come from [ISO.3166-1], and PLC values come from the IANA registry set up by [RFC4589] 🌍
The script field from [RFC4776] is gone, bestie 💅 Instead you use xml:lang with a script subtag from [RFC4646] ✨
It is RECOMMENDED that each "civicAddress" element uses one language only, or a mix of languages that makes sense together 🫶 If a civic location is written in several languages, you SHOULD include multiple "civicAddress" elements in the PIDF-LO document 🦋
For civic addresses that form a complex describing the same location, you SHOULD put them all inside the same tuple 🎀 keep the family together, obviously 💖
3.5.1. Converting from the DHCP Format
the DHCP format for civic addresses [RFC4776] lets an element show up more than once, each time in a different language or script 🌸 but this XML form only allows one instance of each element 😭 so if any element is duplicated across languages, you need multiple "civicAddress" elements. If the same language and script are used everywhere, or nothing is duplicated, you can convert it into one single civic address ✨
when elements are duplicated in different languages, you make a "civicAddress" element for each language that shows up 🌈 then you pop in every element that's in that language. Language-independent stuff, like "country" and "PLC", gets copied into every "civicAddress" element 🧚
3.5.2. Combining Multiple Elements Based on Language Preferences
if the receiver of the XML is known and has told you its language preferences, you can build a single XML format using those preferences 💅 for example, the preferences can be shown through the "Accept-Language" header in SIP or HTTP 🎀
anything with only one value, no matter the language, gets used as-is 💖 when there are multiple values, each one gets a weighting based on the language preferences, and the highest weighting wins 👑 it's a random pick if two values tie, if there's no preference for the languages available, or if there are conflicting values in the same language 🙈
3.6. Whitespace 🫧
the XML schema [W3C.REC-xmlschema-2-20041028] in Section 4 uses a base type of "token" instead of "string", which is what [RFC4119] uses. Lowkey a glow-up 💜
the "token" type makes sure whitespace inside instance documents gets normalised and collapsed before a processor sees it 🧼 so these fragments count as equivalent to XML processors, iconic:
<A4>North Wollongong</A4>
<A1>North
Wollongong</A1>
<A1>
North Wollongong
</A1>if you really want whitespace in a value, you can use character references, like " " ✨
4. Civic Address Schema 🎀
this is the actual schema, so copy it exactly, no vibes-based editing 💅
<?xml version="1.0"?>
<xs:schema
targetNamespace="urn:ietf:params:xml:ns:pidf:geopriv10:civicAddr"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:ca="urn:ietf:params:xml:ns:pidf:geopriv10:civicAddr"
xmlns:xml="http://www.w3.org/XML/1998/namespace"
elementFormDefault="qualified" attributeFormDefault="unqualified">
<xs:import namespace="http://www.w3.org/XML/1998/namespace"
schemaLocation="http://www.w3.org/2001/xml.xsd"/>
<xs:simpleType name="iso3166a2">
<xs:restriction base="xs:token">
<xs:pattern value="[A-Z]{2}"/>
</xs:restriction>
</xs:simpleType>
<xs:complexType name="caType">
<xs:simpleContent>
<xs:extension base="xs:token">
<xs:attribute ref="xml:lang" use="optional"/>
</xs:extension>
</xs:simpleContent>
</xs:complexType>
<xs:element name="civicAddress" type="ca:civicAddress"/>
<xs:complexType name="civicAddress">
<xs:sequence>
<xs:element name="country" type="ca:iso3166a2" minOccurs="0"/>
<xs:element name="A1" type="ca:caType" minOccurs="0"/>
<xs:element name="A2" type="ca:caType" minOccurs="0"/>
<xs:element name="A3" type="ca:caType" minOccurs="0"/>
<xs:element name="A4" type="ca:caType" minOccurs="0"/>
<xs:element name="A5" type="ca:caType" minOccurs="0"/>
<xs:element name="A6" type="ca:caType" minOccurs="0"/>
<xs:element name="PRM" type="ca:caType" minOccurs="0"/>
<xs:element name="PRD" type="ca:caType" minOccurs="0"/>
<xs:element name="RD" type="ca:caType" minOccurs="0"/>
<xs:element name="STS" type="ca:caType" minOccurs="0"/>
<xs:element name="POD" type="ca:caType" minOccurs="0"/>
<xs:element name="POM" type="ca:caType" minOccurs="0"/>
<xs:element name="RDSEC" type="ca:caType" minOccurs="0"/>
<xs:element name="RDBR" type="ca:caType" minOccurs="0"/>
<xs:element name="RDSUBBR" type="ca:caType" minOccurs="0"/>
<xs:element name="HNO" type="ca:caType" minOccurs="0"/>
<xs:element name="HNS" type="ca:caType" minOccurs="0"/>
<xs:element name="LMK" type="ca:caType" minOccurs="0"/>
<xs:element name="LOC" type="ca:caType" minOccurs="0"/>
<xs:element name="FLR" type="ca:caType" minOccurs="0"/>
<xs:element name="NAM" type="ca:caType" minOccurs="0"/>
<xs:element name="PC" type="ca:caType" minOccurs="0"/>
<xs:element name="BLD" type="ca:caType" minOccurs="0"/>
<xs:element name="UNIT" type="ca:caType" minOccurs="0"/>
<xs:element name="ROOM" type="ca:caType" minOccurs="0"/>
<xs:element name="SEAT" type="ca:caType" minOccurs="0"/>
<xs:element name="PLC" type="xs:token" minOccurs="0"/>
<xs:element name="PCN" type="ca:caType" minOccurs="0"/>
<xs:element name="POBOX" type="ca:caType" minOccurs="0"/>
<xs:element name="ADDCODE" type="ca:caType" minOccurs="0"/>
<xs:any namespace="##other" processContents="lax"
minOccurs="0" maxOccurs="unbounded"/>
</xs:sequence>
<xs:anyAttribute namespace="##any" processContents="lax"/>
</xs:complexType>
</xs:schema>5. Example 🌸
here's a full example, and it's giving Wollongong realness 🇦🇺🦘
<civicAddress xml:lang="en-AU"
xmlns="urn:ietf:params:xml:ns:pidf:geopriv10:civicAddr">
<country>AU</country>
<A1>NSW</A1>
<A3> Wollongong
</A3><A4>North Wollongong
</A4>
<RD>Flinders</RD><STS>Street</STS>
<RDBR>Campbell Street</RDBR>
<LMK>
Gilligan's Island
</LMK> <LOC>Corner</LOC>
<NAM> Video Rental Store </NAM>
<PC>2500</PC>
<ROOM> Westerns and Classics </ROOM>
<PLC>store</PLC>
<POBOX>Private Box 15</POBOX>
</civicAddress>6. Security Considerations 🔒
⚠️ this part is seriously important, so read it like it matters 💀
the XML representation in this document is designed to be included in a PIDF-LO document 🫶 which means it gets the same security considerations described in [RFC4119] 🔐 Anything about putting this representation inside other XML documents is out of scope for this document, so don't go assuming it's covered here 🙈
7. IANA Considerations 🦋
7.1. URN sub-namespace registration for 'urn:ietf:params:xml:ns:pidf:geopriv10:civicAddr'
this document defines a new XML namespace (following the guidelines in [RFC3688]), and it's been registered with IANA 🎀
URI: urn:ietf:params:xml:ns:pidf:geopriv10:civicAddr
Registrant Contact: IETF, GEOPRIV working group (geopriv@ietf.org), Martin Thomson (martin.thomson@andrew.com).
XML:
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>GEOPRIV Civic Address</title>
</head>
<body>
<h1>Format for Distributing Civic Address in GEOPRIV</h1>
<h2>urn:ietf:params:xml:ns:pidf:geopriv10:civicAddr</h2>
<p>See <a href="http://www.rfc-editor.org/rfc/rfc5139.txt">
RFC5139</a>.</p>
</body>
</html>
END7.2. XML Schema Registration 📜
this section registers an XML schema following the procedures in [RFC3688] 💖
URI: urn:ietf:params:xml:schema:pidf:geopriv10:civicAddr
Registrant Contact: IETF, GEOPRIV working group (geopriv@ietf.org), Martin Thomson (martin.thomson@andrew.com).
The XML for this schema is the entirety of Section 4 of this document 🫶
7.3. CAtype Registry Update 🌈
this document updates the civic address type registry set up by [RFC4776] ✨ the "PIDF" column of the CAtypes table has been updated to include the types shown in the first column of Table 1 💅
8. References 📚
8.1. Normative References
- [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997.
- [W3C.REC-xmlschema-2-20041028] Biron, P. and A. Malhotra, "XML Schema Part 2: Datatypes Second Edition", World Wide Web Consortium Recommendation REC-xmlschema-2-20041028, October 2004, <http://www.w3.org/TR/2004/REC-xmlschema-2-20041028>.
- [RFC4119] Peterson, J., "A Presence-based GEOPRIV Location Object Format", RFC 4119, December 2005.
- [RFC4589] Schulzrinne, H. and H. Tschofenig, "Location Types Registry", RFC 4589, July 2006.
- [RFC4646] Phillips, A. and M. Davis, "Tags for Identifying Languages", BCP 47, RFC 4646, September 2006.
- [RFC4776] Schulzrinne, H., "Dynamic Host Configuration Protocol (DHCPv4 and DHCPv6) Option for Civic Addresses Configuration Information", RFC 4776, November 2006.
- [ISO.3166-1] International Organization for Standardization, "Codes for the representation of names of countries and their subdivisions - Part 1: Country codes", ISO Standard 3166- 1:1997, 1997.
- [ISO.3166-2] International Organization for Standardization, "Codes for the representation of names of countries and their subdivisions - Part 2: Country subdivision code", ISO Standard 3166-2:1998, 1998.
8.2. Informative References
- [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, January 2004.
- [UPU-S42] Universal Postal Union (UPU), "International Postal Address Components and Templates", UPS SB42-4, July 2004.
Appendix A. Acknowledgements 🙏
the authors want to thank Henning Schulzrinne for helping define the additional civic address types 💜 especially for his research into different addressing schemes, which led to the thoroughfare elements 🧠 Rohan Mahy suggested the ISO 3166-2 recommendation for A1 🌸 and they also thank Jon Peterson for his work defining the PIDF-LO 🫶
Authors' Addresses 🦋
Martin Thomson Andrew PO Box U40 Wollongong University Campus, NSW 2500 AU
Phone: +61 2 4221 2915 EMail: martin.thomson@andrew.com URI: http://www.andrew.com/
James Winterbottom Andrew PO Box U40 Wollongong University Campus, NSW 2500 AU
Phone: +61 2 4221 2938 EMail: james.winterbottom@andrew.com URI: http://www.andrew.com/
Full Copyright Statement ✨
Copyright (C) The IETF Trust (2008) 💖
okay so this bit is the legal stuff, but it's still important bestie 🫶 This document is subject to the rights, licenses and restrictions in BCP 78. Except for what BCP 78 says, the authors keep all their rights 📜
This document and everything in it is provided "AS IS" 🫠 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 all say they have NO warranties, express or implied. That includes no promise that using the information here won't infringe any rights, and no implied warranties of merchantability or fitness for a particular purpose 💀
Intellectual Property 🦋
The IETF is not picking a side on whether any Intellectual Property Rights (or other rights) that might be claimed about the technology in this document are valid or how far they reach 🙈 It also doesn't say whether licenses for those rights are available, and it hasn't checked for any such rights itself. If you want the procedures for rights in RFC documents, look in BCP 78 and BCP 79 📚
Copies of IPR disclosures sent to the IETF Secretariat are available, along with any assurances of licenses to be made available. You can also get the results of an attempt to obtain a general license or permission for implementers or users of this specification to use the proprietary rights. All of that lives in the IETF's online IPR repository at http://www.ietf.org/ipr 🌸
The IETF invites anyone interested to bring to its attention any copyrights, patents, patent applications, or other proprietary rights that might cover technology needed to implement this standard 👑 Send that info to the IETF at ietf-ipr@ietf.org ✨
And that's the whole RFC, bestie! 🌈💅
📦 where this page comes from
- ietf: rfc5139 2008-02
- 💖 girlified by claude-haiku-5-5 on : a language model's rewrite of the original, under its terms