h-adr: Difference between revisions
(Added parsed JSON to primary example) |
GRegorLove (talk | contribs) m (s/<source>/<syntaxhighlight>/) |
||
(10 intermediate revisions by 4 users not shown) | |||
Line 1: | Line 1: | ||
<dfn style="font-style:normal;font-weight:bold">h-adr</dfn> is a simple, open format for publishing structured locations such as addresses, physical and/or postal. h-adr is one of several open [[microformats|microformat]] draft standards suitable for embedding data in HTML. | |||
<dfn style="font-style:normal;font-weight:bold">h-adr</dfn> is a simple, open format for publishing structured locations such as addresses, physical and/or postal. h-adr is one of several open [[microformats|microformat]] draft standards suitable for embedding data in HTML | |||
h-adr is the [[microformats-2]] update to [[adr]]. It is most commonly used as part of an [[h-card]] or [[h-event]]. | h-adr is the [[microformats-2]] update to [[adr]]. It is most commonly used as part of an [[h-card]] or [[h-event]]. | ||
{{cc0-owfa-license}} | For named addresses, e.g. people or venues, use [[h-card]]. | ||
;<span id="Status">Status</span> | |||
:This is a '''Draft Specification''' | |||
;Participate | |||
:[[IRC]]: [irc://irc.libera.chat/microformats #microformats on Libera] | |||
;Editor | |||
:<span class="h-card vcard"><span class="p-name fn">[[User:Tantek|Tantek Çelik]]</span> (<span class="p-role role">Editor</span>)</span> | |||
;License | |||
:{{cc0-owfa-license}} | |||
__TOC__ | |||
== Example == | == Example == | ||
Here is a simple postal address example: | Here is a simple postal address example: | ||
< | <syntaxhighlight lang="html"> | ||
<p class="h-adr"> | <p class="h-adr"> | ||
<span class="p-street-address">17 Austerstræti</span> | <span class="p-street-address">17 Austerstræti</span> | ||
Line 18: | Line 25: | ||
<span class="p-postal-code">107</span> | <span class="p-postal-code">107</span> | ||
</p> | </p> | ||
</ | </syntaxhighlight> | ||
Parsed JSON: | Parsed JSON: | ||
< | <syntaxhighlight lang="json"> | ||
{ | { | ||
"items": [ | "items": [ | ||
Line 49: | Line 56: | ||
] | ] | ||
} | } | ||
</ | </syntaxhighlight> | ||
The implicit "name" property that is generated from parsing an h-adr is there for consuming applications to have a simple flattened string representation of an h-adr. | |||
For an explicitly named address (such as a mailing address to a specific person), use [[h-card]]. | |||
=== Get started === | === Get started === | ||
Line 74: | Line 85: | ||
All properties are optional. | All properties are optional. | ||
* '''<code>p-name</code>''' - there is no "p-name" property in h-adr. If your address has an explicit name, it's likely a venue, and you should use [[h-card]] instead. | |||
== Status == | == Status == | ||
'''h-adr''' is a microformats.org draft specification. Public discussion on h-adr takes place on [[h-adr-feedback]] | '''h-adr''' is a microformats.org draft specification. Public discussion on h-adr takes place on [[h-adr-feedback]] and the #microformats [[irc]] channel on irc.freenode.net. | ||
h-adr is ready to use and implemented in the wild, but for backwards compatibility you should also mark h-adrs up with classic [[adr]] classnames. | h-adr is ready to use and implemented in the wild, but for backwards compatibility you should also mark h-adrs up with classic [[adr]] classnames. | ||
Line 89: | Line 102: | ||
{{h-spec-section-validating}} | {{h-spec-section-validating}} | ||
== Backward | == Backward Compatibility == | ||
=== Publisher Compatibility === | === Publisher Compatibility === | ||
For backward compatibility, you may wish to use classic [[adr]] classnames in addition to the more future-proof h-adr properties, for example: | For backward compatibility, you may wish to use classic [[adr]] classnames in addition to the more future-proof h-adr properties, for example: | ||
< | <syntaxhighlight lang="html"> | ||
<p class="h-adr adr"> | <p class="h-adr adr"> | ||
<span class="p-street-address street-address">123 Main St.</span>, | <span class="p-street-address street-address">123 Main St.</span>, | ||
Line 99: | Line 112: | ||
... | ... | ||
</p> | </p> | ||
</ | </syntaxhighlight> | ||
The class '''<code>adr</code>''' is a ''backward compatible root class name'' that indicates the presence of an [[adr]]. | The class '''<code>adr</code>''' is a ''backward compatible root class name'' that indicates the presence of an [[adr]]. | ||
Line 127: | Line 140: | ||
A: In short yes. You can do: | A: In short yes. You can do: | ||
< | <syntaxhighlight lang="html"> | ||
<span class="p-country-name">UK</span> | <span class="p-country-name">UK</span> | ||
</ | </syntaxhighlight> | ||
However it's better if you mark it up with the <code>abbr</code> element and provide the full name as well, e.g. | However it's better if you mark it up with the <code>abbr</code> element and provide the full name as well, e.g. | ||
< | <syntaxhighlight lang="html"> | ||
<abbr class="p-country-name" title="United Kingdom">UK</abbr> | <abbr class="p-country-name" title="United Kingdom">UK</abbr> | ||
</ | </syntaxhighlight> | ||
Consuming applications may interpret any 2-3 character country-name per the table of 2-3 character [http://en.wikipedia.org/wiki/ISO_3166-1#Officially_assigned_code_elements country codes in ISO3166]. | Consuming applications may interpret any 2-3 character country-name per the table of 2-3 character [http://en.wikipedia.org/wiki/ISO_3166-1#Officially_assigned_code_elements country codes in ISO3166]. | ||
Line 144: | Line 157: | ||
* [[h-geo]] can be embedded in h-adr | * [[h-geo]] can be embedded in h-adr | ||
* [[h-card]] and [[h-event]] often contain h-adr | * [[h-card]] and [[h-event]] often contain h-adr | ||
* [[vcard]] (most recently vCard4 RFC6350) vocabulary is re-used by h-adr. | |||
* [[address-formats]] | |||
[[Category:Draft Specifications]] | [[Category:Draft Specifications]] |
Latest revision as of 21:13, 26 July 2023
h-adr is a simple, open format for publishing structured locations such as addresses, physical and/or postal. h-adr is one of several open microformat draft standards suitable for embedding data in HTML.
h-adr is the microformats-2 update to adr. It is most commonly used as part of an h-card or h-event.
For named addresses, e.g. people or venues, use h-card.
- Status
- This is a Draft Specification
- Participate
- IRC: #microformats on Libera
- Editor
- Tantek Çelik (Editor)
- License
- Per CC0, to the extent possible under law, the editors have waived all copyright and related or neighboring rights to this work. In addition, as of 2024-11-22, the editors have made this specification available under the Open Web Foundation Agreement Version 1.0.
Example
Here is a simple postal address example:
<p class="h-adr">
<span class="p-street-address">17 Austerstræti</span>
<span class="p-locality">Reykjavík</span>
<span class="p-country-name">Iceland</span>
<span class="p-postal-code">107</span>
</p>
Parsed JSON:
{
"items": [
{
"type": [
"h-adr"
],
"properties": {
"street-address": [
"17 Austerstræti"
],
"locality": [
"Reykjavík"
],
"country-name": [
"Iceland"
],
"postal-code": [
"107"
],
"name": [
"17 Austerstræti Reykjavík Iceland 107"
]
}
}
]
}
The implicit "name" property that is generated from parsing an h-adr is there for consuming applications to have a simple flattened string representation of an h-adr.
For an explicitly named address (such as a mailing address to a specific person), use h-card.
Get started
The class h-adr
is a root class name that indicates the presence of an h-adr.
p-street-address, p-locality, p-country-name, p-postal-code and all the other h-adr property class names listed below define properties of the h-adr.
See microformats-2-parsing to learn more about property class names.
Properties
h-adr properties, inside an element with class h-adr:
p-street-address
- house/apartment number, floor, street namep-extended-address
- additional street detailsp-post-office-box
- post office mailboxp-locality
- city/town/villagep-region
- state/county/provincep-postal-code
- postal code, e.g. ZIP in the USp-country-name
- should be full name of country, country code okp-label
- a mailing label, plain text, perhaps with preformattingp-geo
(or u-geo with a RFC 5870 geo: URL), optionally embedded h-geop-latitude
- decimal latitudep-longitude
- decimal longitudep-altitude
- decimal altitude - new in vCard4 (RFC6350)
All properties are optional.
p-name
- there is no "p-name" property in h-adr. If your address has an explicit name, it's likely a venue, and you should use h-card instead.
Status
h-adr is a microformats.org draft specification. Public discussion on h-adr takes place on h-adr-feedback and the #microformats irc channel on irc.freenode.net.
h-adr is ready to use and implemented in the wild, but for backwards compatibility you should also mark h-adrs up with classic adr classnames.
Property Details
(stub, add any property explanations here)
Examples in the Wild
- … add any h-adr examples you find in the wild
Validating
Test and validate microformats2 markup in general with:
- https://pin13.net/mf2/ - enter your markup directly
- https://pin13.net/ - enter a URL to a page to test where it says "Microformats Parser"
Backward Compatibility
Publisher Compatibility
For backward compatibility, you may wish to use classic adr classnames in addition to the more future-proof h-adr properties, for example:
<p class="h-adr adr">
<span class="p-street-address street-address">123 Main St.</span>,
<span class="p-locality locality">Pleasantville</span>
...
</p>
The class adr
is a backward compatible root class name that indicates the presence of an adr.
street-address, locality, and all the other backward compatibility adr property class names are listed below.
Parser Compatibility
Microformats parsers should detect classic properties only if a classic root class name is found and parse them as microformats2 properties.
If an "h-adr" is found, don't look for an "adr" on the same element.
Compatibility root class name: adr
Properties: (parsed as p- plain text unless otherwise specified)
- post-office-box
- extended-address
- street-address
- locality
- region
- postal-code
- country-name
FAQ
What about country codes
Q: When marking up an address, can p-country-name be used to markup two letter country codes like "UK"? Or others like 3 letter Olympic country codes?
A: In short yes. You can do:
<span class="p-country-name">UK</span>
However it's better if you mark it up with the abbr
element and provide the full name as well, e.g.
<abbr class="p-country-name" title="United Kingdom">UK</abbr>
Consuming applications may interpret any 2-3 character country-name per the table of 2-3 character country codes in ISO3166.
Background
h-adr is based on the existing adr specification, which was extracted from hCard in order to allow it to be used for applications other than contact information.
See Also
- microformats2
- h-geo can be embedded in h-adr
- h-card and h-event often contain h-adr
- vcard (most recently vCard4 RFC6350) vocabulary is re-used by h-adr.
- address-formats