h-card: Difference between revisions

From Microformats Wiki
Jump to navigation Jump to search
(start manually fixing spec styling until we can actually fix the default mediawiki theme to be as much the same as previously as possible)
(editorial: replace examples with examples from hCard spec, upgrade a few links to https, drop redlinked h-card-feedback as a place and link to mf chat archives and github issues instead)
Line 18: Line 18:


== Example ==
== Example ==
Here is a simple minimal person example:
Here are a couple of minimal examples:


<source lang=html4strict>
<source lang=html4strict>
<a class="h-card" href="http://example.com">Joe Bloggs</a>
<a class="h-card" href="https://tantek.com/">Tantek Çelik</a>,
 
<span class="h-card">
  <a class="p-name p-org u-url" href="https://microformats.org/">microformats.org</a>
</span>
</source>
</source>


Line 29: Line 33:
   "items": [
   "items": [
     {
     {
       "type": [
       "type": ["h-card"],
        "h-card"
      ],
       "properties": {
       "properties": {
         "name": [
         "name": ["Tantek Çelik"],
          "Joe Bloggs"
         "url": ["https://tantek.com/"]
        ],
         "url": [
          "http://example.com"
        ]
       }
       }
     }
     },
  ]
}
</source>
 
And a slightly more complete example:
 
<source lang=html4strict>
<p class="h-card">
  <img class="u-photo" src="http://example.org/photo.png" alt="" />
  <a class="p-name u-url" href="http://example.org">Joe Bloggs</a>
  <a class="u-email" href="mailto:joebloggs@example.com">joebloggs@example.com</a>,  
  <span class="p-street-address">17 Austerstræti</span>
  <span class="p-locality">Reykjavík</span>
  <span class="p-country-name">Iceland</span>
</p>
</source>
 
Parsed JSON:
<source lang=javascript>
{
  "items": [
     {
     {
       "type": [
       "type": ["h-card"],
        "h-card"
      ],
       "properties": {
       "properties": {
         "photo": [
         "name": ["microformats.org"],
          "http://example.org/photo.png"
         "org": ["microformats.org"],
        ],
         "url": ["https://microformats.org/"]
         "name": [
          "Joe Bloggs"
        ],
         "url": [
          "http://example.org"
        ],
        "email": [
          "mailto:joebloggs@example.com"
        ],
        "street-address": [
          "17 Austerstræti"
        ],
        "locality": [
          "Reykjavík"
        ],
        "country-name": [
          "Iceland"
        ]
       }
       }
     }
     }
Line 93: Line 50:
}
}
</source>
</source>
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
Nested h-card example:


<source lang=html4strict>
<source lang=html4strict>
<div class="h-card">
<div class="h-card">
   <a class="p-name u-url"
   <a class="p-name u-url"
     href="http://blog.lizardwrangler.com/"  
     href="https://blog.lizardwrangler.com/"  
     >Mitchell Baker</a>  
     >Mitchell Baker</a>  
   (<a class="p-org h-card"  
   (<a class="p-org h-card"  
       href="http://mozilla.org/"
       href="https://mozilla.org/"
     >Mozilla Foundation</a>)
     >Mozilla Foundation</a>)
</div>
</div>
Line 114: Line 72:
     "properties": {
     "properties": {
       "name": ["Mitchell Baker"],
       "name": ["Mitchell Baker"],
       "url": ["http://blog.lizardwrangler.com/"],
       "url": ["https://blog.lizardwrangler.com/"],
       "org": [{
       "org": [{
         "value": "Mozilla Foundation",
         "value": "Mozilla Foundation",
Line 120: Line 78:
         "properties": {
         "properties": {
           "name": ["Mozilla Foundation"],
           "name": ["Mozilla Foundation"],
           "url": ["http://mozilla.org/"]
           "url": ["https://mozilla.org/"]
         }
         }
       }]
       }]
Line 135: Line 93:
For minimal examples where at most <code>p-name</code>, <code>u-url</code> and <code>u-photo</code> are required (such as the first given above), only the root class name is needed — see [[microformats-2-implied-properties|implied properties]].
For minimal examples where at most <code>p-name</code>, <code>u-url</code> and <code>u-photo</code> are required (such as the first given above), only the root class name is needed — see [[microformats-2-implied-properties|implied properties]].


For more complex examples, 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.
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.


See [[microformats2-parsing]] to learn more about property classnames.
See [[microformats2-parsing]] to learn more about property classnames.
Line 143: Line 101:
* See [[microformats2-parsing]] to learn more about property classnames.
* See [[microformats2-parsing]] to learn more about property classnames.


<div style="margin-top:-.4em; float:right;"><span>Example h-card with common properties:</span>
<ul style="list-style:none"><li><code>&lt;div class="'''h-card'''"&gt;</code>
<ul style="list-style:none; margin-top:-.02em">
<li><code>&lt;span class="'''p-name'''"&gt;Sally Ride&lt;/span&gt;</code></li>
<li><code>&lt;span class="'''p-honorific-prefix'''"&gt;Dr.&lt;/span&gt;</code></li>
<li><code>&lt;span class="'''p-given-name'''"&gt;Sally&lt;/span&gt;</code></li>
<li><code>&lt;abbr class="'''p-additional-name'''"&gt;K.&lt;/abbr&gt;</code></li>
<li><code>&lt;span class="'''p-family-name'''"&gt;Ride&lt;/span&gt;</code></li>
<li><code>&lt;span class="'''p-honorific-suffix'''"&gt;Ph.D.&lt;/span&gt;,</code></li>
<li><code>&lt;span class="'''p-nickname'''"&gt;sallykride&lt;/span&gt; (IRC)</code></li>
<li><code>&lt;div class="'''p-org'''"&gt;Sally Ride Science&lt;/div&gt;</code></li>
<li><code>&lt;img class="'''u-photo'''" src="<nowiki>http://example.com/sk.jpg</nowiki>"/&gt; </code></li>
<li><code>&lt;a class="'''u-url'''" href="<nowiki>http://sally.example.com</nowiki>"&gt;w&lt;/a&gt;,</code></li>
<li><code>&lt;a class="'''u-email'''" href="<nowiki>mailto:sally@example.com</nowiki>"&gt;e&lt;/a&gt; </code></li>
<li><code>&lt;div class="'''p-tel'''"&gt;+1.818.555.1212&lt;/div&gt;</code></li>
<li><code>&lt;div class="'''p-street-address'''"&gt;123 Main st.&lt;/div&gt;</code></li>
<li><code>&lt;span class="'''p-locality'''"&gt;Los Angeles&lt;/span&gt;, </code></li>
<li><code>&lt;abbr class="'''p-region'''" title="California"&gt;CA&lt;/abbr&gt;, </code></li>
<li><code>&lt;span class="'''p-postal-code'''"&gt;91316&lt;/span&gt;</code></li>
<li><code>&lt;div class="'''p-country-name'''"&gt;U.S.A&lt;/div&gt;</code></li>
<li><code>&lt;time class="'''dt-bday'''"&gt;1951-05-26&lt;/time&gt; birthday</code></li>
<li><code>&lt;div class="'''p-category'''"&gt;physicist&lt;/div&gt;</code></li>
<li><code>&lt;div class="'''p-note'''"&gt;First American woman in space.&lt;/div&gt;</code></li></ul></li>
<li><code>&lt;/div&gt;</code></li></ul>
</div>
Core properties:
Core properties:
* '''<code>p-name</code>''' - The full/formatted name of the person or organization
* '''<code>p-name</code>''' - The full/formatted name of the person or organization
Line 188: Line 171:
** Used by [https://vanderven.se/martijn/ Martijn van der Ven] with a clip of his given name.
** Used by [https://vanderven.se/martijn/ Martijn van der Ven] with a clip of his given name.
** Needs a GitHub issue to track.
** Needs a GitHub issue to track.


== Status ==
== Status ==
'''h-card''' is a microformats.org draft specification. Public discussion on h-card takes place on [[h-card-feedback]] and the #microformats [[irc]] channel on irc.freenode.net.
'''h-card''' is a microformats.org draft specification. Public discussion on h-card takes place on the [[irc|#microformats channel on irc.freenode.net]] ([https://chat.indieweb.org/microformats view recent discussions]), and specific issues [https://github.com/microformats/h-card/issues may be filed on GitHub].


h-card is ready to use and implemented in the wild, but for backwards compatibility you should also mark up top-level h-cards as classic [[hCard]]s.
h-card is ready to use and implemented in the wild. For backwards compatibility you should also mark up top-level h-cards as classic [[hCard]]s.


== Property Details ==
== Property Details ==
Line 244: Line 228:
* [http://eschnou.com/ Laurent Eschenauer] marks his homepage profile up using h-card
* [http://eschnou.com/ Laurent Eschenauer] marks his homepage profile up using h-card
* [http://tommorris.org/ Tom Morris] marks himself up with h-card as well as venues he’s checked into ([http://tommorris.org/posts/8408 example])
* [http://tommorris.org/ Tom Morris] marks himself up with h-card as well as venues he’s checked into ([http://tommorris.org/posts/8408 example])
* [http://www.w3.org/conf/ W3Conf 2013] uses h-card for all the event speakers and notable attendees. The h-cards make particularly good use of implied name, url, and photo properties.
* [https://www.w3.org/conf/ W3Conf 2013] uses h-card for all the event speakers and notable attendees. The h-cards make particularly good use of implied name, url, and photo properties.
* [http://wordpress.org/extend/themes/sempress SemPress] is a WordPress theme that supports h-card, h-feed/h-entry and h-as-*
* [http://wordpress.org/extend/themes/sempress SemPress] is a WordPress theme that supports h-card, h-feed/h-entry and h-as-*
* [http://the-pastry-box-project.net/ The Pastry Box Project] use h-card markup on their homepage and individual thoughts pages
* [http://the-pastry-box-project.net/ The Pastry Box Project] use h-card markup on their homepage and individual thoughts pages
* Tom Morris uses h-card and [[XFN]] to markup [http://tommorris.org/pages/blogroll his blogroll].
* Tom Morris uses h-card and [[XFN]] to markup [http://tommorris.org/pages/blogroll his blogroll].
* Aaron Parecki uses h-card to markup both authorship and references to people in his notes permalinks, e.g. [http://aaronparecki.com/2012/230/reply/1 2012/230/reply/1].
* Aaron Parecki uses h-card to markup both authorship and references to people in his notes permalinks, e.g. [https://aaronparecki.com/2012/230/reply/1 2012/230/reply/1].
* [http://tantek.com/ Tantek Çelik] uses h-card  on his home page as well as within [[h-entry]]s on permalink pages to indicate authorship.
* [https://tantek.com/ Tantek Çelik] uses h-card  on his home page as well as within [[h-entry]]s on permalink pages to indicate authorship.
* [http://waterpigs.co.uk/ Barnaby Walters] uses h-card on his home page, as well as within h-entries for notes and articles, both to indicate authorship and also when mentioning people within the body of the notes.
* [http://waterpigs.co.uk/ Barnaby Walters] uses h-card on his home page, as well as within h-entries for notes and articles, both to indicate authorship and also when mentioning people within the body of the notes.
* [http://tantek.com/presentations/2012/06/microformats microformats.org at 7 years] presentation with and h-card markup for people and organizations.
* [https://tantek.com/presentations/2012/06/microformats microformats.org at 7 years] presentation with and h-card markup for people and organizations.
* [http://tantek.com/presentations/2012/06/pdf2012-indieweb.html Rise of the Indie Web hCards] (from Personal Democracy Forum 2012 #pdf12 #pdf2012) has [[microformats2]] h-card markup
* [https://tantek.com/presentations/2012/06/pdf2012-indieweb.html Rise of the Indie Web hCards] (from Personal Democracy Forum 2012 #pdf12 #pdf2012) has [[microformats2]] h-card markup
* WebMaker by Mozilla has [[microformats2]] h-card on event search (e.g. [https://webmaker.org/en-US/events/near/?lat=45.5234515&lng=-122.6762071 search near Portland Oregon]) and event pages (e.g. [https://webmaker.org/en-US/events/192f56eb9/ IndieWebCamp 2012]).[https://twitter.com/microformats/status/212207925643587585]
* WebMaker by Mozilla has [[microformats2]] h-card on event search (e.g. [https://webmaker.org/en-US/events/near/?lat=45.5234515&lng=-122.6762071 search near Portland Oregon]) and event pages (e.g. [https://webmaker.org/en-US/events/192f56eb9/ IndieWebCamp 2012]).[https://twitter.com/microformats/status/212207925643587585]
* WebFWD by Mozilla has [[microformats2]] h-card markup on [https://webfwd.org/about/experts/ experts] and [https://webfwd.org/about/team/ team] pages
* WebFWD by Mozilla has [[microformats2]] h-card markup on [https://webfwd.org/about/experts/ experts] and [https://webfwd.org/about/team/ team] pages
* [http://indiewebcamp.com IndieWebCamp] has [[microformats2]] h-event markup with embedded h-cards for the organizers and the location.
* [https://indiewebcamp.com IndieWebCamp] has [[microformats2]] h-event markup with embedded h-cards for the organizers and the location.
* [https://wiki.mozilla.org/Events Mozilla Events] page has [[microformats2]] h-event markup with attendees marked up with h-card.
* [https://wiki.mozilla.org/Events Mozilla Events] page has [[microformats2]] h-event markup with attendees marked up with h-card.
* [https://tristanthomas.me Tristan Thomas] uses h-card on his home page
* [https://tristanthomas.me Tristan Thomas] uses h-card on his home page
Line 266: Line 250:


== Validating ==
== Validating ==
* '''[http://indiewebify.me/validate-h-card/ indiewebify.me h-card validator]''' parses [[h-card]] markup and makes suggestions for things to add, with code samples
* '''[https://indiewebify.me/validate-h-card/ indiewebify.me h-card validator]''' parses [[h-card]] markup and makes suggestions for things to add, with code samples
{{h-spec-section-validating}}
{{h-spec-section-validating}}


Line 278: Line 262:
* [https://hubzilla.org/hubzilla/ Hubzilla] [https://github.org/redmatrix/hubzilla source code]
* [https://hubzilla.org/hubzilla/ Hubzilla] [https://github.org/redmatrix/hubzilla source code]
* [http://friendica.com/ Friendica] [https://github.org/friendica/friendica source code]
* [http://friendica.com/ Friendica] [https://github.org/friendica/friendica source code]
* [http://github.com/dissolve/inkblot InkBlot]
* [https://github.com/dissolve/inkblot InkBlot]
* ...
* ...
* ...
* ...

Revision as of 01:18, 25 August 2020

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 open microformat draft standards suitable for embedding data in HTML.

h-card is the microformats2 update to hCard.

Status
This is a Living Specification yet mature enough to encourage additional implementations and feedback.
Participate
Open Issues
IRC: #microformats on Freenode
Editor
Tantek Çelik
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-03-28, the editors have made this specification available under the Open Web Foundation Agreement Version 1.0.

Example

Here are a couple of minimal examples:

<a class="h-card" href="https://tantek.com/">Tantek Çelik</a>, 

<span class="h-card">
  <a class="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:

<div class="h-card">
  <a class="p-name u-url"
     href="https://blog.lizardwrangler.com/" 
    >Mitchell Baker</a> 
  (<a class="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 class h-card is a root class name that indicates the presence of an h-card.

For minimal examples where at most p-name, u-url and u-photo are required (such as the first given above), only the root class name is needed — see implied 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.

See microformats2-parsing to learn more about property classnames.

Properties

h-card properties, inside an element with class h-card. All properties are optional and may be plural.

Example h-card with common properties:
  • <div class="h-card">
    • <span class="p-name">Sally Ride</span>
    • <span class="p-honorific-prefix">Dr.</span>
    • <span class="p-given-name">Sally</span>
    • <abbr class="p-additional-name">K.</abbr>
    • <span class="p-family-name">Ride</span>
    • <span class="p-honorific-suffix">Ph.D.</span>,
    • <span class="p-nickname">sallykride</span> (IRC)
    • <div class="p-org">Sally Ride Science</div>
    • <img class="u-photo" src="http://example.com/sk.jpg"/>
    • <a class="u-url" href="http://sally.example.com">w</a>,
    • <a class="u-email" href="mailto:sally@example.com">e</a>
    • <div class="p-tel">+1.818.555.1212</div>
    • <div class="p-street-address">123 Main st.</div>
    • <span class="p-locality">Los Angeles</span>,
    • <abbr class="p-region" title="California">CA</abbr>,
    • <span class="p-postal-code">91316</span>
    • <div class="p-country-name">U.S.A</div>
    • <time class="dt-bday">1951-05-26</time> birthday
    • <div class="p-category">physicist</div>
    • <div class="p-note">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 an h-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 or u-geo, optionally embed an h-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 an h-card
  • p-job-title - job title, previously 'title' in hCard, 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 issues may 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 classic hCards.

Property Details

(stub, to be expanded)

p-adr

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

<div class="h-card">
  <p class="p-name">Joe Bloggs</p>
  <p class="p-adr 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>
  </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 the value-class-pattern. And for now, the former hCard '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 in the vcard spec eg

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

Reserved properties

Reserved properties (not used much, if at all, in practice):

  • p-organization-name
  • p-organization-unit
  • p-tz - timezone offset, e.g. <data class="p-tz" value="-0800">PST</data>
  • dt-rev

Examples in the wild

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

Validating

Main article: validators

Test and validate microformats2 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 every indie web site supports publishing h-card by default.)

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 classic hCard classnames in addition to the more future-proof h-card properties, for example:

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

The class vcard is a backward compatible root class name that indicates the presence of an hCard.

fn, org, and all the other backward compatibility hCard 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-card" is found, don't look for a "vcard" on the same element.

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

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

Reserved: (backward compat properties that parsers MAY implement, if they do, they MUST implement in this way:

  • tz
  • rev - parse as dt-

Background

This work is based on the existing hCard and vcard 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