h-card

From Microformats Wiki
Jump to navigationJump to search

h-card is a simple, open format for publishing people and organisations on the web. h-card is often used on home pages and individual blog posts. h-card is one of several openmicroformat draft standards suitable for embedding data in HTML.

h-card is themicroformats2 update tohCard.

Status
This is aLiving Specification yet mature enough to encourage additional implementations andfeedback.
Participate
Open Issues
IRC
Editor
Tantek Çelik
License
PerCC0, to the extent possible under law, the editors have waived all copyright and related or neighboring rights to this work. In addition, as of 2025-12-02, the editors have made this specification available under theOpen Web Foundation Agreement Version 1.0.

Example

Here are a couple of minimal examples:

<aclass="h-card"href="https://tantek.com/">Tantek Çelik</a>,<spanclass="h-card"><aclass="p-name p-org u-url"href="https://microformats.org/">microformats.org</a></span>

Parsed JSON:

{"items":[{"type":["h-card"],"properties":{"name":["Tantek Çelik"],"url":["https://tantek.com/"]}},{"type":["h-card"],"properties":{"name":["microformats.org"],"org":["microformats.org"],"url":["https://microformats.org/"]}}]}

Note a single element was sufficient for the simple person example with implied name and URL properties, while for an organization, which requires a name and org, it needed explicit markup for the h-card and all properties, though still with only two elements.

Nested h-card example:

<divclass="h-card"><aclass="p-name u-url"href="https://blog.lizardwrangler.com/">Mitchell Baker</a>   (<aclass="p-org h-card"href="https://mozilla.org/">Mozilla Foundation</a>)</div>

Parsed JSON:

{"items":[{"type":["h-card"],"properties":{"name":["Mitchell Baker"],"url":["https://blog.lizardwrangler.com/"],"org":[{"value":"Mozilla Foundation","type":["h-card"],"properties":{"name":["Mozilla Foundation"],"url":["https://mozilla.org/"]}}]}}]}

Note: the nested h-card has implied 'name' and 'url' properties, just like any other root-class-name-only h-card on an<a href> would.

Get started

The classh-card is aroot class name that indicates the presence of an h-card.

For minimal examples where at mostp-name,u-url andu-photo are required (such as the first given above), only the root class name is needed — seeimplied properties.

When more than those three minimal properties are needed, the root class name must be placed on an element which encloses all the desired properties, and then the properties themselves marked up using the classnames given below.

Seemicroformats2-parsing to learn more about property classnames.

Properties

h-card properties, inside an element with classh-card. All properties are both optional and may have multiple instances, e.g. multiple name, url, photo etc. properties.

Example h-card with common properties:
  • <div>
    • <span>Sally Ride</span>
    • <span>Dr.</span>
    • <span>Sally</span>
    • <abbr>K.</abbr>
    • <span>Ride</span>
    • <span>Ph.D.</span>,
    • <span>sallykride</span> (IRC)
    • <div>Sally Ride Science</div>
    • <img src="http://example.com/sk.jpg"/>
    • <a href="http://sally.example.com">w</a>,
    • <a href="mailto:sally@example.com">e</a>
    • <div>+1.818.555.1212</div>
    • <div>123 Main st.</div>
    • <span>Los Angeles</span>,
    • <abbr title="California">CA</abbr>,
    • <span>91316</span>
    • <div>U.S.A</div>
    • <time>1951-05-26</time> birthday
    • <div>physicist</div>
    • <div>First American woman in space.</div>
  • </div>

Core properties:

  • p-name - The full/formatted name of the person or organization
  • p-honorific-prefix - e.g. Mrs., Mr. or Dr.
  • p-given-name - given (often first) name
  • p-additional-name - other (e.g. middle) name
  • p-family-name - family (often last) name
  • p-sort-string - string to sort by
  • p-honorific-suffix - e.g. Ph.D, Esq.
  • p-nickname - nickname/alias/handle
  • u-email - email address
  • u-logo - a logo representing the person or organization (e.g. a face icon)
  • u-photo - a photo of the person or organization
  • u-url - home page or other URL representing the person or organization
  • u-uid - universally unique identifier, preferably canonical URL
  • p-category - category/tag
  • p-adr - postal address, optionally embed anh-adr
    Main article:h-adr
  • p-post-office-box - post office box description if any
  • p-extended-address - apartment/suite/room name/number if any
  • p-street-address - street number + name
  • p-locality - city/town/village
  • p-region - state/county/province
  • p-postal-code - postal code, e.g. US ZIP
  • p-country-name - country name
  • p-label
  • p-geo oru-geo, optionally embed anh-geo
    Main article:h-geo
  • p-latitude - decimal latitude
  • p-longitude - decimal longitude
  • p-altitude - decimal altitude
  • p-tel - telephone number
  • p-note - additional notes
  • dt-bday - birth date
  • u-key - cryptographic public key e.g. SSH or GPG
  • p-org - affiliated organization, optionally embed anh-card
  • p-job-title - job title, previously 'title' inhCard, disambiguated.
  • p-role - description of role
  • u-impp per RFC4770, new in vCard4 (RFC 6350)
  • p-sex - biological sex, new in vCard4 (RFC 6350)
  • p-gender-identity - gender identity, new in vCard4 (RFC 6350)
  • dt-anniversary

Experimental properties currently in use in the wild but not (yet) part of the official h-card spec.

  • u-sound - sound file containing the proper pronunciation of the name property, per vCard (RFC 6350).

Status

h-card is a microformats.org draft specification. Public discussion on h-card takes place on the#microformats channel on irc.freenode.net (view recent discussions), and specific issuesmay be filed on GitHub.

h-card is ready to use and implemented in the wild. For backwards compatibility you should also mark up top-level h-cards as classichCards.

Property Details

(stub, to be expanded)

p-adr

p-adr can optionally embed anh-adr to cluster associated structured address properties. E.g. adding "p-adr" to the example earlier:

<divclass="h-card"><pclass="p-name">Joe Bloggs</p><pclass="p-adr h-adr"><spanclass="p-street-address">17 Austerstræti</span><spanclass="p-locality">Reykjavík</span><spanclass="p-country-name">Iceland</span></p></div>

Q: Why would you use "p-adr" to cluster associated structured address properties?

A: Because if you have more than one structured address, clustering which properties go with which address keeps them deterministically together, instead of depending on array indices or other heuristics.

p-tel

Note: use of 'value' within 'p-tel' should be automatically handled by the support of thevalue-class-pattern. And for now, the formerhCard 'type' subproperty of 'tel' is dropped/ignored. If there is demonstrable documented need for additional tel types (e.g. fax), we can introduce new flat properties as needed (e.g. p-tel-fax).

dt-bday

Using truncated representations of dates for birth date is often good practice as noted inthe vcard spec eg

  • 1985-04 for April 1985
  • 1985 for the year 1985
  • --04-12 for April 12th with no specified year

Reserved properties

The following properties were supported by the legacy hCard format, but were not carried over to h-card due to lack of real-world usage, or other problems. They are not part of h-card and should not be published, consumed, or proposed.

  • p-organization-name
  • p-organization-unit
  • p-tz — timezone offset
    • it's going to be a hard one to "get right", as the way timezones work in vcard/ical is very weird, and timezones as a whole are an iffy thing to denote (quite the disconnect between complexity, automated processing ability, actually representing what a user would want to show/display or already does on their homepage, and actually representing something useful to parse and do something with)
    • there's certainly no ecosystem of publishers & consumers supporting p-tz in any meaningful interoperable way —tantek in #microformats
  • dt-rev

Examples in the wild

See also:h-card Examples on indieweb.org

Real world in the wild examples of sites and services that publish or consume h-card:

offline

  • spreadly marks up share permalink pages with minimal h-cards inside h-entry
  • App.net rolled out support for h-card and h-entry on all profile pages and permalink pages as of 2013-08-06 (example)
  • Sandeep Shetty marks his homepage and posts up with h-card and h-entry (example)

Validating

Main article:validators

Test and validatemicroformats2 markup in general with:

Implementations

Software implementations that publish or consume h-card, including themes, plugins, or extensions:

(This section is a stub that needs expansion! In practice, nearly every CMS on everyindie web site supports publishing h-card by default, and most sites which support receiving webmentions parse h-card for authorship data.)

When adding an implementation, please provide and link to its home page and open source repo if any.

Backward Compatibility

Publisher Compatibility

For backward compatibility, you may wish to use classichCard classnames in addition to the more future-proof h-card properties, for example:

<pclass="h-card vcard"><spanclass="p-name fn">Joe Bloggs</span>,<spanclass="p-org org">Awesome Nonprofit</span>  ...</p>

The classvcard is abackward compatible root class name that indicates the presence of anhCard.

fn,org, and all the other backward compatibility hCard property class names are listed below.

Parser Compatibility

Microformats parsersSHOULD detect classic properties only if a classic root class name is found and parse them as microformats2 properties.

If an "h-card" is found, don't look for a "vcard" on the same element.

Compat. root class name:vcard
Properties: (parsed asp- plain text unless otherwise specified)

  • fn - parse asp-name
  • honorific-prefix
  • given-name
  • additional-name
  • family-name
  • honorific-suffix
  • nickname
  • email - parse asu-
  • logo - parse asu-
  • photo - parse asu-
  • url - parse asu-
  • uid - parse asu-
  • category
  • adr - parse asp-adr h-adr including compat root classadr
  • extended-address
  • street-address
  • locality
  • region
  • postal-code
  • country-name
  • label
  • geo - parse asp-geo h-geo including compat root classgeo
  • latitude
  • longitude
  • tel
  • note
  • bday - parse asdt-
  • key - parse asu-
  • org
  • organization-name
  • organization-unit
  • title - parse asp-job-title
  • role

Reserved: (backward compat properties that parsersMAY implement, if they do, theyMUST implement in this way:

  • tz
  • rev - parse asdt-

Background

This work is based on the existinghCard andvcard specifications.

Design Principles

(stub, expand)

Additions

We've tried very hard with h-card to stay compatible with the vCard4 vocabulary, and thus additions should be proposed on the vCard4 mailing list.

However, you may still use this wiki to capture additions for h-card here:

See Also

Retrieved from "http://microformats.org/wiki/index.php?title=h-card&oldid=70686"
Category: