h-card: Difference between revisions

From Microformats Wiki
Jump to navigation Jump to search
(use CC0+OWFa license template)
(editorial: drop explicit HTML5 from dfn, unnecessary)
(37 intermediate revisions by 17 users not shown)
Line 2: Line 2:
<span class="h-card vcard"><span class="p-name fn">[[User:Tantek|Tantek Çelik]]</span> (<span class="p-role role">Editor</span>)</span>
<span class="h-card vcard"><span class="p-name fn">[[User:Tantek|Tantek Çelik]]</span> (<span class="p-role role">Editor</span>)</span>
----
----
<dfn style="font-style:normal;font-weight:bold">h-card</dfn> is a simple, open format for publishing people and organisations on the web. h-card is one of several open [[microformats|microformat]] draft standards suitable for embedding data in HTML/HTML5.
<dfn style="font-style:normal;font-weight:bold">h-card</dfn> is a simple, open format for publishing people and organisations on the web. h-card is one of several open [[microformats|microformat]] draft standards suitable for embedding data in HTML.


h-card is the [[microformats2]] update to [[hCard]].
h-card is the [[microformats2]] update to [[hCard]].
Line 13: Line 13:
<source lang=html4strict>
<source lang=html4strict>
<a class="h-card" href="http://example.com">Joe Bloggs</a>
<a class="h-card" href="http://example.com">Joe Bloggs</a>
</source>
Parsed JSON:
<source lang=javascript>
{
  "items": [
    {
      "type": [
        "h-card"
      ],
      "properties": {
        "name": [
          "Joe Bloggs"
        ],
        "url": [
          "http://example.com"
        ]
      }
    }
  ]
}
</source>
</source>


Line 19: Line 40:
<source lang=html4strict>
<source lang=html4strict>
<p class="h-card">
<p class="h-card">
   <img class="u-photo" src="http://example.org/photo.png" />
   <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="p-name u-url" href="http://example.org">Joe Bloggs</a>
   <a class="u-email" href="mailto:joebloggs@example.com">joebloggs@example.com</a>
   <a class="u-email" href="mailto:joebloggs@example.com">joebloggs@example.com</a>,
   <p class="p-adr h-adr">
   <span class="p-street-address">17 Austerstræti</span>
    <span class="p-street-address">17 Austerstræti</span>
  <span class="p-locality">Reykjavík</span>
    <span class="p-locality">Reykjavík</span>
  <span class="p-country-name">Iceland</span>
    <span class="p-country-name">Iceland</span>
  </p>
</p>
</p>
</source>
</source>
Parsed JSON:
<source lang=javascript>
{
  "items": [
    {
      "type": [
        "h-card"
      ],
      "properties": {
        "photo": [
          "http://example.org/photo.png"
        ],
        "name": [
          "Joe Bloggs"
        ],
        "url": [
          "http://example.org"
        ],
        "email": [
          "mailto:joebloggs@example.com"
        ],
        "street-address": [
          "17 Austerstræti"
        ],
        "locality": [
          "Reykjavík"
        ],
        "country-name": [
          "Iceland"
        ]
      }
    }
  ]
}
</source>
Nested h-card example
<source lang=html4strict>
<div class="h-card">
  <a class="p-name u-url"
    href="http://blog.lizardwrangler.com/"
    >Mitchell Baker</a>
  (<a class="p-org h-card"
      href="http://mozilla.org/"
    >Mozilla Foundation</a>)
</div>
</source>
Parsed JSON:
<source lang=javascript>
{
  "items": [{
    "type": ["h-card"],
    "properties": {
      "name": ["Mitchell Baker"],
      "url": ["http://blog.lizardwrangler.com/"],
      "org": [{
        "value": "Mozilla Foundation",
        "type": ["h-card"],
        "properties": {
          "name": ["Mozilla Foundation"],
          "url": ["http://mozilla.org/"]
        }
      }]
    }
  }]
}
</source>
Note: the nested h-card has implied 'name' and 'url' properties, just like any other root-class-name-only h-card on an <code>&lt;a href&gt;</code> would.


=== Get started ===
=== Get started ===
Line 50: Line 141:
* '''<code>p-nickname</code>''' - nickname/alias/handle
* '''<code>p-nickname</code>''' - nickname/alias/handle
* '''<code>u-email</code>''' - email address
* '''<code>u-email</code>''' - email address
* '''<code>u-logo</code>'''
* '''<code>u-logo</code>''' - a logo representing the person or organisation
* '''<code>u-photo</code>'''
* '''<code>u-photo</code>'''
* '''<code>u-url</code>''' - home page
* '''<code>u-url</code>''' - home page
* '''<code>u-uid</code>''' - unique identifier
* '''<code>u-uid</code>''' - universally unique identifier, typically canonical URL
* '''<code>p-category</code>''' - category/tag
* '''<code>p-category</code>''' - category/tag
* '''<code>p-adr</code>''' - postal address, optionally embed an [[h-adr]] {{main|h-adr}}
* '''<code>p-adr</code>''' - postal address, optionally embed an [[h-adr]] {{main|h-adr}}
* '''<code>p-post-office-box</code>'''
* '''<code>p-post-office-box</code>'''
* '''<code>p-extended-address</code>'''
* '''<code>p-extended-address</code>''' - apartment/suite/room name/number if any
* '''<code>p-street-address</code>''' - street number + name
* '''<code>p-street-address</code>''' - street number + name
* '''<code>p-locality</code>''' - city/town/village
* '''<code>p-locality</code>''' - city/town/village
Line 75: Line 166:
* '''<code>p-job-title</code>''' - job title, previously 'title' in [[hCard]], disambiguated.
* '''<code>p-job-title</code>''' - job title, previously 'title' in [[hCard]], disambiguated.
* '''<code>p-role</code>''' - description of role  
* '''<code>p-role</code>''' - description of role  
* '''<code>u-impp</code>''' per RFC 4770, new in vCard4 (RFC6350)
* '''<code>u-impp</code>''' per RFC4770, new in vCard4 (RFC 6350)
* '''<code>p-sex</code>''' - biological sex, new in vCard4 (RFC6350)
* '''<code>p-sex</code>''' - biological sex, new in vCard4 (RFC 6350)
* '''<code>p-gender-identity</code>''' - gender identity, new in vCard4 (RFC6350)
* '''<code>p-gender-identity</code>''' - gender identity, new in vCard4 (RFC 6350)
* '''<code>dt-anniversary</code>'''
* '''<code>dt-anniversary</code>'''


Line 83: Line 174:


== Status ==
== Status ==
'''h-card''' is a microformats.org draft specification. Public discussion on h-card takes place on [[h-card-feedback]], the #microformats [[irc]] channel on irc.freenode.net, and [http://microformats.org/discuss/mail/microformats-new/ microformats-new mailing list].
'''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 ready to use and implemented in the wild, but for backwards compatibility you should also mark h-cards up as classic [[hCard]]s.
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.


== Property Details ==
== Property Details ==
(stub, to be expanded)
(stub, to be expanded)


<code>p-adr</code> can optionally embed an [[h-adr]] to cluster associated structured address properties. For example:
=== p-adr ===
<code>p-adr</code> can optionally embed an [[h-adr]] to cluster associated structured address properties. E.g. adding "p-adr" to the example earlier:


<source lang=html4strict>
<source lang=html4strict>
Line 103: Line 195:
</source>
</source>


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 [https://tools.ietf.org/html/rfc6350#section-4.3.1 the vcard spec] eg
* <code>1985-04</code> for April 1985
* <code>1985</code> for the year 1985
* <code>--04-12</code> for April 12th with no specified year
=== Reserved properties ===
Reserved properties (not used much, if at all, in practice):
Reserved properties (not used much, if at all, in practice):


Line 109: Line 215:
* '''<code>p-tz</code>''' - timezone offset, e.g. <code>&lt;data class="p-tz" value="-0800">PST&lt;/data></code>
* '''<code>p-tz</code>''' - timezone offset, e.g. <code>&lt;data class="p-tz" value="-0800">PST&lt;/data></code>
* '''<code>dt-rev</code>'''
* '''<code>dt-rev</code>'''
Note: use of 'value' within 'p-tel' should be automatically handled by the support of the [[value-class-pattern]]. And for now, the '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).


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


* ... add uses of h-card you see in the wild here.
* ... add uses of h-card you see in the wild here.
* App.net rolled out support for h-card and h-entry on all profile pages and permalink pages as of 2013-08-06 ([https://alpha.app.net/voidfiles example])
* Brett Comnes marks up his posts with h-card ([http://bret.io/2013/06/29/getting-started-with-bower/ example])
* Brett Comnes marks up his posts with h-card ([http://bret.io/2013/06/29/getting-started-with-bower/ example])
* Ben Werdmuller marks up his homepage and posts with h-card [http://werd.io/view/51d5097fbed7ded0633a5956 example])
* Ben Werdmuller marks up his homepage and posts with h-card [http://werd.io/view/51d5097fbed7ded0633a5956 example])
* [https://joelpurra.com/ Joel Purra] uses a hidden h-card with legacy [[hCard]] fallback markup (to satisfy [https://search.google.com/structured-data/testing-tool Google's Structured Data Testing Tool]) on the front page
* Sandeep Shetty marks his homepage and posts up with h-card and h-entry ([sandeep.io/101 example])
* Sandeep Shetty marks his homepage and posts up with h-card and h-entry ([sandeep.io/101 example])
* spreadly marks up share permalink pages with minimal h-cards inside h-entry ([http://my.spread.ly/share/51d570bc09e9486562000002 example])
* [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])
Line 135: Line 240:
* [http://indiewebcamp.com IndieWebCamp] has [[microformats2]] h-event markup with embedded h-cards for the organizers and the location.
* [http://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
* [http://cold32.com/about-the-author-and-contact.htm Cold32.com] uses h-card (and h-geo) on its about-the-author-and-contact page
* [https://workfrom.co/ Workfrom.co] renders h-cards for venues (e.g. [https://workfrom.co/palio-dessert-and-espresso-house])
* [http://www.pcwdld.com/ PCWDLD.com] renders h-cards for download pages(e.g. [http://www.pcwdld.com/solarwinds-network-topology-mapper-review Download page example])


=== offline ===
* spreadly marks up share permalink pages with minimal h-cards inside h-entry


== 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
{{h-spec-section-validating}}
{{h-spec-section-validating}}
== 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 [https://indieweb.org/ 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.
* [https://gnu.io/social/ GNUsocial] [https://git.gnu.io/gnu/gnu-social/ 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://github.com/dissolve/inkblot InkBlot]
* ...
* ...


== Backward Compatibility ==
== Backward Compatibility ==
Line 156: Line 282:


=== Parser Compatibility ===
=== Parser Compatibility ===
Microformats parsers {{should}} detect the following root class name and property names. A microformats2 parser may use existing microformats [[parsers]] to extract these properties. If an "h-card" is found, don't look for a "vcard" on the same element.
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: <code id="vcard">vcard</code><br/>
Compat. root class name: <code id="vcard">vcard</code><br/>
Line 197: Line 325:
* <code>tz</code>
* <code>tz</code>
* <code>rev</code> - parse as '''dt-'''
* <code>rev</code> - parse as '''dt-'''


== Background ==
== Background ==
Line 205: Line 332:


(stub, expand)
(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:
* [[h-card-brainstorming]]


== See Also ==
== See Also ==
* [[microformats2]]
* [[microformats2]]
* [[microformats2-parsing]]
* [[microformats2-parsing]]

Revision as of 21:34, 3 August 2017

<entry-title>h-card</entry-title> Tantek Çelik (Editor)


h-card is a simple, open format for publishing people and organisations on the web. h-card is one of several open microformat draft standards suitable for embedding data in HTML.

h-card is the microformats2 update to hCard.

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 is a simple minimal person example:

<a class="h-card" href="http://example.com">Joe Bloggs</a>

Parsed JSON:

{
  "items": [
    {
      "type": [
        "h-card"
      ],
      "properties": {
        "name": [
          "Joe Bloggs"
        ],
        "url": [
          "http://example.com"
        ]
      }
    }
  ]
}

And a slightly more complete example:

<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>

Parsed JSON:

{
  "items": [
    {
      "type": [
        "h-card"
      ],
      "properties": {
        "photo": [
          "http://example.org/photo.png"
        ],
        "name": [
          "Joe Bloggs"
        ],
        "url": [
          "http://example.org"
        ],
        "email": [
          "mailto:joebloggs@example.com"
        ],
        "street-address": [
          "17 Austerstræti"
        ],
        "locality": [
          "Reykjavík"
        ],
        "country-name": [
          "Iceland"
        ]
      }
    }
  ]
}

Nested h-card example

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

Parsed JSON:

{
  "items": [{ 
    "type": ["h-card"],
    "properties": {
      "name": ["Mitchell Baker"],
      "url": ["http://blog.lizardwrangler.com/"],
      "org": [{
        "value": "Mozilla Foundation",
        "type": ["h-card"],
        "properties": {
          "name": ["Mozilla Foundation"],
          "url": ["http://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.

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.

See microformats2-parsing to learn more about property classnames.

Properties

h-card properties, inside an element with class h-card:

  • p-name - The full/formatted name of the person or organisation
  • p-honorific-prefix - e.g. Mrs., Mr. or Dr.
  • p-given-name - given (often first) name
  • p-additional-name - other/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 organisation
  • u-photo
  • u-url - home page
  • u-uid - universally unique identifier, typically canonical URL
  • p-category - category/tag
  • p-adr - postal address, optionally embed an h-adr
    Main article: h-adr
  • p-post-office-box
  • 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

All properties are optional.

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 ready to use and implemented in the wild, but 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