hcard-design-methodology
hCard design methodology
This page captures some of the design methodology that went into the hCard microformat.
Most of the details of hCard were very deliberately designed based on principles. By capturing some of those principles and methodological techniques, hopefully future microformats can benefit by reusing some of this methodology.
- Author
- Tantek Çelik
Semantic XHTML Design Principles
The semantic-xhtml-design-principles were largely created and captured as a result of explicit design decisions for how to best re-use vCard RFC2426 terminology in the context of semantic XHTML.
In particular:
- Reuse the schema (names, objects, properties, values, types, hierarchies, constraints) as much as possible from pre-existing, established, well-supported standards by reference. Avoid restating constraints expressed in the source standard. Informative mentions are ok.
For hCard, the pre-existing, established, well-supported standard re-used was/is vCard.
- Use class names based on names from the original schema, unless the semantic XHTML building block precisely represents that part of the original schema. If names in the source schema are case-insensitive, then use an all lowercase equivalent. Components names implicit in prose (rather than explicit in the defined schema) should also use lowercase equivalents for ease of use. Spaces in component names become dash '-' characters.
vCard uses case-insensitive identifiers, but by convention most vCards have, and vCard implementations produce, all UPPERCASE identifiers, e.g. VCARD, N, FN etc. Since the HTML4 'class' attribute is case-sensitive, for microformats I had to pick a specific case to use for property names. I decided to explicitly follow the precedent and example set by XHTML from HTML4 of using the lowercase version of element names from HTML4 which itself similar to vCard had case-insensitive element names (due to its use of SGML) and by convention used all UPPERCASE element names in documentation.
Thus where HTML4 to XHTML looked like this:
<HTML>became<html><HEAD>became<head><BODY>became<body>- ... etc.
vCard to hCard looked like this:
BEGIN:VCARDbecameclass="vcard"N:becameclass="n"FN:becamseclass="fn"- ... etc.
- For types with multiple components, use nested elements with class names equivalent to the names of the components.
In the vCard specification, properties are referred to has "types", and thus the above principle invokes that same language to refer to such "types", specifically those that have some structure to them, with a set of values that relate specific semantics.
The primary example of this in hCard are the "n" and "adr" properties, each of which have sub-properties (e.g. "given-name", "family-name", etc. for "n", "street-address", "locality", etc. for "adr").
- Plural components are made singular, and thus multiple nested elements are used to represent multiple text values that are comma-delimited.
There are several properties in vCard that are either plural (e.g. CATEGORIES) or are simply defined to take multiple values (e.g. NICKNAME), or are sub-properties that are plural (e.g. additional names). As one of few exceptions to the "reuse names exactly" aka "don't change the names" design principle, plural names of properties or sub-properties are explicitly changed to their singular equivalents, e.g.:
- CATEGORIES became "category"
- NICKNAME became "nickname"
- "additional names" became "additional-name"
And in all cases of such plural or multi-valued properties, the hCard specification permits multiple instances of the singular form which are then combined as appropriate to the equivalent property when transforming to vCard.
- Finally, if the format of the data according to the original schema is too long and/or not human-friendly, use
<abbr>instead of a generic structural element, and place the literal data into the 'title' attribute (where abbr expansions go), and the more brief and human-readable equivalent into the element itself. Further informative explanation of this use of<abbr>: abbr-design-pattern, Human vs. ISO8601 dates problem solved, and hAccessibility aka "abbr-design-pattern considered harmful."
Motivated originally by the development of hCalendar which itself is based on iCalendar RFC2445, which needed a way to capture and represent datetimes, this technique is similarly used in several instances in hCard, e.g.
- the "bday" property, e.g.:
<abbr class="bday" title="2005-06-20">June 20th</abbr>
- the "region" sub-property, e.g.:
<abbr class="region" title="California">CA</abbr>
- the "country-name" sub-property, e.g.:
<abbr class="country-name" title="United States of America">USA</abbr>