hcard-parsing

hCard parsing

by Tantek Çelik

introduction

When I first conceived of hCard, it was clear to me how to unambiguously parse both for the existence of hCards in arbitrary (X)HTML (and anywhere that arbitrary (X)HTML can be embedded, e.g. RSS, Atom, "generic XML"), and hCard properties and values.

I worked directly with Brian Suda to capture these thoughts in an implementation, and Brian wrote X2V, an XSLT script that converts hCards to vCards, thus simultaneously demonstrating the parsability of hCards, and the immediate utility of hCard content interoperating with widespread existing vCard applications.

I am now documenting those thoughts directly here so that additional implementations, rather than having to reverse engineer X2V, can be built directly from these elementary concepts.

scope

Although this page is written specifically to explain how to parse hCard, the concepts and algorithms contained therein serve as an example for how other compound microformats are to be parsed.

root class name

Each compound microformat starts with a root element with a relatively unique class name. By that I mean a class name which isn't simply a common word, and is unlikely to have been used outside the context of the microformat. By choosing such a root class name the microformat avoids (for all practical purposes) colliding with existing class names that may exist within the (X)HTML context. This is essential to enabling such compound microformats to be embedded inside current, existing content, as well as future content.

Fortunately this is not a new problem to solve. The root object names chosen for vCard (RFC 2426) and iCalendar (RFC 2445) similarly had to avoid such collisions and did so by choosing names that were unlikely to have been introduced into a MIME object context. The principle of reuse dictates that we should reuse the names for these root objects in those RFCs rather than invent our own. Given the same semantics, a design should reuse the names, rather than inventing a second name for the same semantic (a common design mistake made in environments that require namespaces).

In the vCard specification, the names are case-insensitive due to the (lack of) requirements of their context. (X)HTML class names are case sensitive per those specifications. Thus we are required to pick a canonical case for the class name equivalents of vCard object and property names. All lowercase is chosen to follow the precedent (i.e. reuse the pattern) set by XHTML, which similarly had to canonicalize the case of element and attribute names that it took from HTML4, which itself was case-insensitive due to its context (SGML). Additionally, reasons for avoiding mixed-case (e.g. camel case) in the context of class names may be found in the essay A Touch of Class, specifically, the section titled Class sensitivity.

Thus the root class name of an hCard is "vcard".

finding hCards

An (X)HTML document indicates that it may contain hCards by referencing the hCard XMDP profile. See XMDP for more details.

A parser finds hCards in an (X)HTML context by looking for elements with the root class name "vcard" just as the following CSS class selector does:

 .vcard

For example, the following CSS style rule sets the background of all hCards to green:

 .vcard { background: green; }

Note that the (X)HTML class attribute is a space separated set of class names.

Thus all of the following are valid hCard root elements:

• <div class="vcard"> </div>
• <span class="attendee vcard"> </span>
• <address class="vcard author"> </address>
• <li class="reviewer vcard first"> </li>

Once the root element of an hCard is found, that element and all its descendants are all that is needed to parse the hCard.

Thus it is possible for a well-formed hCard to be extracted from an overall non well-formed context, if the parser has the ability to find elements by class name within that non well-formed context.

hCard properties

The complete list of class names for hCard properties are documented in the hCard profile.

forward compatible parsing

When parsing the contents of an hCard, any unrecongized class names must be ignored.

Similarly, unrecognized values for hCard properties must also be ignored.

finding hCard properties

To parse an hCard for an hCard property (e.g. "fn"), the parser simply looks for the first element with that class name inside the hCard.

This can also be expressed as the first element that matches this CSS selector:

.vcard .fn

Some properties, like "fn", should only appear once, and thus the parser stops looking for the property after it has found one occurrence. Additional occurrences are ignored.

Other properties, like "adr", "email", "url", "tel", etc., may (and often do) appear more than once, and thus the parser continues to look for each occurrence within the contents of the hCard.

parsing hCard properties and values

Once an element for a property is found, the contents of the element are used for the value.

There are several exceptions to accomodate semantic XHTML and more semantic equivalents.

For the "email" property in particular, when the element is:

• <a href="mailto:..."> : use the value of the 'href' attribute, omitting the "mailto:" prefix in the attribute.

For properties of type URL or URI, when the element for a property is:

• <a href> : use the value of the 'href' attribute.
• <img src> : use the value of the 'src' attribute.
• <object data> : use the value of the 'data' attribute.

For properties NOT of type URL or URI, when the element for a property is:

• <img alt> : use the value of the 'alt' attribute.

For all properties, when the element for a property is:

• <abbr>: use the value of the 'title' attribute.

parsing hCard subproperties

& & & & & & & & & & & & & Work In Progress & & & & & & & & & & & & &

I'm still in the process of writing this document. Please avoid non-trivial edits. Thanks, Tantek

References

Normative References

• hCard
• vCard (RFC 2426)
• XHTML 1.0 Recommendation
• HTML 4.01 Recommendation
• XMDP

Informative References

• CSS1 Recommendation