hcard-ja

From Microformats Wiki
Revision as of 14:19, 30 October 2007 by Vantguarde (talk | contribs)
Jump to navigation Jump to search

hCard

hCard は vCard (RFC2426) のプロパティと値を用い、セマンティックな XHTML で人や会社、組織や場所を表現するシンプルなフォーマットです。hCard は microformats のひとつであり、(X)HTML や Atom、RSS やその他の XML に埋め込むことができます。

hCard を利用してみたいですか?ではまず、hCard creator を使い、コンタクト情報を公開してください。または、hCard authoring tips を読み、あなたのコンタクトページをhCardでマークアップしてください。

hCard 仕様書

編集者
Tantek Çelik (Technorati, Inc.)
作成者
Tantek Çelik (Technorati, Inc.)
Brian Suda
謝辞
謝辞のセクションをご覧ください。

権利に関する情報は、著作権特許のセクションをご覧ください。

はじめに

vCard (RFC2426) は、Apple のアドレスブック機能をはじめさまざまなところで実装され、広く使われているフォーマットです。

さて、多くのブロガーは、自分の名前を出し友人や家族のことを書いています。人に関するこれらの情報にすこし構造を加えるだけで、アグリゲーターやスパイダーがその情報を取得し、vCard へ自動的に変換しアプリケーションで利用することができます。

この仕様は、hCard というフォーマットを定義します。これは vCard のプロパティや値を、XTHML でそのまま表現しようとするものです。ブロガーはhCard を Web ページに埋め込み、CSS で思うようにデザインすることができます。また、hCard はアプリケーションが他のファイルを参照することなしに、そのページから情報を取り出すことを可能とします。

hCard creator を使い、出てきた HTML コードを blog や Web サイトに貼り付け、コンタクト情報を公開してみてください。

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.

フォーマット

基本情報

vCard (RFC2426) のプロパティ名や値が、hCard の基礎を構成します。

hCard は、vCard のオブジェクト/プロパティ名を小文字にしたものを class 属性の値として使用します。vCard オブジェクトの入れ子関係は、そのまま XHTML 要素の入れ子関係に置き換えられます。

ルート class 名

hCard のルート class 名は "vcard" です。"vcard" という class 名が指定された要素を、hCard と呼びます。

プロパティとサブプロパティ

hCard のプロパティは、hCard 内の要素によって表されます。次にリストするプロパティを class 属性に指定することにより、プロパティを表現します。いくつかのプロパティはサブプロパティを持ちますが、これらはプロパティ要素の中にサブプロパティ要素を設け表現します。

プロパティリスト

hCard のプロパティは次の通りです。サブプロパティは括弧内に記述しています。

必須プロパティ

  • fn
  • n* (family-name, given-name, additional-name, honorific-prefix, honorific-suffix)

任意プロパティ

  • nickname, sort-string
  • url, email (type, value), tel** (type, value)
  • adr (post-office-box, extended-address, street-address, locality, region, postal-code, country-name, type, value), label
  • geo (latitude, longitude), tz
  • photo, logo, sound, bday
  • title, role, org (organization-name, organization-unit)
  • category, note
  • class, key, mailer, uid, rev

プロパティについて

* 'n' プロパティは、"n" の推測処理にあるルールに当てはまる場合は、任意 (OPTIONAL) プロパティとなります。
** tel - 電話番号は、E.123に従って記述することができます (MAY)。

複数のプロパティ

ひとつの hCard は、一つ以上の 'fn'、'n'、'bday'、'tz'、'geo'、'sort-string'、'uid'、'class' を持つことはありません。これらのプロパティが複数ある場合は、最初の値を残し、他の値を無視することが推奨されます。

他のプロパティは複数あっても構いません (MAY)。この場合、複数あるプロパティはその数だけ新しいインスタンスを作成します。

"Human readable" か "Machine readable" か

要素の内容のうち、人間に見えるテキスト情報が、そのプロパティの値を表します。しかし、いくつか例外が存在します。

もし <abbr> 要素がプロパティに用いられている場合、要素の内容ではなく <abbr> 要素の 'title' 属性値がプロパティの値となります。要素の内容は、より人間にとって読みやすい値の表現となります。

もし <a> 要素が一つ以上のプロパティに用いられている場合、次のように処理される必要があります (MUST)。

  1. 'photo' プロパティと、他に URL を取るすべてのプロパティでは、href="..." 属性の値がプロパティの値となります。
  2. その他のプロパティでは、要素の内容がプロパティの値となります。

もし <img> 要素が一つ以上のプロパティに用いられている場合、次のように処理される必要があります (MUST)。

  1. 'photo' プロパティと、他に URL を取るすべてのプロパティでは、src="..." 属性の値がプロパティの値となります。
  2. その他のプロパティでは、<img> 要素の 'alt' 属性の値がプロパティの値となります。

もし <object> 要素が一つ以上のプロパティに用いられている場合、次のように処理される必要があります (MUST)。

  1. 'photo' プロパティと、他にURLを取るすべてのプロパティでは、data="..." 属性の値がプロパティの値となります。
  2. その他のプロパティでは、要素の内容がプロパティの値となります。

値の抜粋

要素の一部だけがプロパティの値として当てはまるという場合があります。例えば、'tel' のように、サブタイプを持つようなプロパティです。このような場合は特別な class 名である "value" を用い、プロパティの値として適切なものをマークアップします。家の電話番号をマークアップする hCard を例に取り説明しましょう。

vCard:

TEL;TYPE=HOME:+1.415.555.1212

hCard:

<span class="tel">
 <span class="type">home</span>:
 <span class="value">+1.415.555.1212</span>
</span>

この hCard は次のように表示されるでしょう。

home: +1.415.555.1212


プロパティの例外

vCard には、Web ページの内容としてあまり意味をなさない、もしくは何らかのかたちですでに存在しているプロパティが存在しています。このセクションでは、そのようなプロパティに対し、何を行い、何を行わないかを説明します。

  1. vCard の NAMEPROFILESOURCEPRODIDVERSION プロパティは RFC2426 のセクション2.1.2、2.1.3、2.1.4、3.6.3、3.6.9 で定義されていますが、hCard ではこれらのプロパティを使ってはいけません (MUST NOT)。hCard を利用するものは、もしこれらのプロパティが使われていた場合、それらを無視する必要があります (MUST)。hCard から vCard へ変換するコンバーターは、これらのプロパティの代わりに hCard が埋め込まれている Web ページの情報を用いて、これらのプロパティを埋めることになります。まず、NAME プロパティは文書のタイトル ((X)HTML 文書の場合、<title> 要素) を用いることが推奨されます (SHOULD)。PROFILE の値には、RFC2426 より "VCARD" の値を使うことができます (MAY)。SOURCE プロパティには、ページの URL を用いることが推奨されます (SHOULD)。hCard を vCard に変換するサービスならば、そのパラメーターとしても用いることができるでしょう。PRODID プロパティは、実際に vCard を出力するサービスやアプリケーションのみが記述するべきです (SHOULD)。同様に、そのようなアプリケーションのみが、RFC2426 のセクション 3.6.9 に倣い、VERSION プロパティに "3.0" という値をつけるべきです (SHOULD)。

組織のコンタクト情報

もし、"FN" と "ORG" プロパティが同じ値を持っている場合 (多くの場合、これらは class="fn org" と同じ要素に記述されています)、その hCard は会社や組織、場所のコンタクト情報を表すものとみなされます (SHOULD)。このとき、作成者は "N" プロパティを記述することはできない (MUST NOT)、もしくは、"" と、空文字列を記述する必要があります。このため、パーサは "N" プロパティの省略をふまえた対応が推奨されます (SHOULD)。この場合は、全ての "N" サブプロパティに空文字列があるものとみなします。

"n" の推測処理

vCard では "N" プロパティの記述が必須となっています。ところが vCard 仕様書 (RFC2426) では、最後の方 (p.38) にある作者の vCard に "N" プロパティが含まれていません。この明らかな矛盾は、"FN" プロパティがこの仕様書のように、多くの場合において "N" プロパティの内容を暗示していると解釈すれば問題なくなります。というわけで、hCard では次のように規定します。

もし "FN" と "ORG" プロパティが同じではなく、また "FN" の値がホワイトスペースで区切られた二つの単語のみで構成されており、さらに "N" プロパティが存在しない場合、"N" は "FN" プロパティの値から推測されます。もし "FN" が単語一つの場合は次の段落を、もし "FN" が三つ以上の単語である場合、作成者は "N" プロパティを明示的にマークアップする必要があります (MUST)。しかし、組織名の場合はこのルールに当てはまりません。この場合は組織のコンタクト情報で書かれているルールが適用されます。

  1. "FN" の内容は、ホワイトスペースで区切られた二つの "単語" に分解されます。
  2. "FN" の 最初の 単語は、"N" プロパティの "given-name" として扱われます。
  3. "FN" の 次の/最後の 単語は、"N" プロパティの "family-name" として扱われます。
  4. 例外: もし最初の単語がコンマ "," で終わる、または二つ目の単語が一文字 (または一文字とピリオド ".")であった場合、コンマを抜いた最初の単語が "family-name" となり、二つ目の単語が "given-name" となります。

これらのルールにより、次の表記であれば簡単に名前を "FN" に記述することができます。

  • given-name (スペース) family-name
  • family-name (コンマ) given-name
  • family-name (コンマ) given-nameのイニシャル
  • family-name (スペース) given-nameのイニシャル (任意のピリオド)

"nickname" の推測処理

ユーザーレビューの作者など、Web においてニックネームやハンドル、そしてユーザーネームは広く普及しています。そこで、hCard は "nickname" を推測する処理方法を規定しました。

"nickname" の推測機構は "n" の推測処理と似ています。もし "FN" と "ORG" プロパティが同じではなく、また "FN" の値が単語一つで構成され、さらに "N" プロパティが存在しない場合、次のような処理がなされます。

  1. "FN" プロパティの内容は "nickname" プロパティの値として解釈される必要があります (MUST)。
  2. パーサは存在しない "N" プロパティについて、"N" のサブプロパティに空の値を与えたと仮定し、処理することが推奨されます (SHOULD)。

パーサはニックネームの推測処理に従う必要がありますが (MUST)、hCard の作成者は "nickname" プロパティを明示することが推奨されます (SHOULD)。次のような場合においてもです。

<span class="vcard">
 <span class="fn nickname">daveman692</span>
</span>

また、hCard は推測されたニックネームに加え、明示的に記述された "nickname" プロパティを持つことができます (MAY)。

"organization-name" の推測処理

"ORG" プロパティは organization-name と organization-unit という二つのサブプロパティを持っています。しかしほとんどの場合、作成者は organization-name のみを記述します。よって、もし "ORG" プロパティが "organization-name" プロパティを内側に持たない場合、"ORG" プロパティの内容は必ず "organization-name" とみなされます (MUST)。

カテゴリーとしてのタグ

hCard のカテゴリーは rel-tag を用い、タグとして表現することも可能です (MAY)。"category" プロパティが rel-tag である場合、そのタグはカテゴリーとして扱われます。

'type' サブプロパティの値

'type' サブプロパティがとる値は、その親プロパティによって異なります。これらの 'type' サブプロパティの値は大文字小文字を区別しません (case-INSENSITIVE)。よって "Home" は "home" と同じであり、その他の値と組み合わせた場合についても同様です。たとえば、家の電話番号で、かつ優先番号であるものは次のようになります。

vCard:

TEL;TYPE=HOME,PREF:+1.415.555.1212

hCard:

<span class="tel"><span class="type">Home</span> (<span class="type">pref</span>erred):
 <span class="value">+1.415.555.1212</span>
</span>

この例は次のように表示されるでしょう。

Home (preferred): +1.415.555.1212

次のリストは 参考情報 です。規範的な type の値は RFC2426 のセクション 3.2.1 ADR、3.3.1 TEL、3.3.2 EMAIL を参照してください。ここでは利便性の為にコピーしています。type サブプロパティのデフォルト値はリストの最初に並んでおり、また大文字で記述されています。また、これらの type は複数指定することができます。

  • adr type: INTL, POSTAL, PARCEL, WORK, dom, home, pref
  • tel type: VOICE, home, msg, work, pref, fax, cell, video, pager, bbs, modem, car, isdn, pcs
  • email type: INTERNET, x400, pref, "IANA に登録された他のアドレスタイプ"

XMDP プロファイル

hCard の XMDP プロファイルは hcard-profile をご覧ください。hcard-profile には上で説明したプロパティの全てが、RFC2426 のセクション番号付きでリスト化されています。

パース処理

hCard parsing をご覧ください。

hCard の例

このセクションは参考情報です。

vCard のサンプル

次にあるのは vCard のサンプルです。

BEGIN:VCARD
VERSION:3.0
N:Çelik;Tantek
FN:Tantek Çelik
URL:http://tantek.com/
ORG:Technorati
END:VCARD

この vCard を hCard で表現すると次のようになります。なお、推測処理ができるプロパティについては省略してあります。他の例は hCard Example 1 をご覧ください。

<div class="vcard">
 <a class="url fn" href="http://tantek.com/">Tantek Çelik</a>
 <div class="org">Technorati</div>
</div>

この hCard は次のように表示されるでしょう。

Tantek Çelik
Technorati

Note: hCard のマークアップにはバージョン情報が必要ありません。なぜならバージョンは <head> 要素の 'profile' 属性に記述されたプロファイルで定義されているからです。

hCard の実例

次にあるのは WikiMedia Foundation のコンタクト情報です。この情報は hCard を用いて記述されているので、microformats をパース処理するツールにより見つけることができます。

Wikimedia Foundation Inc.

work

200 2nd Ave. South #358
St. Petersburg FL  33701-4313
USA
Phone: work+1-727-231-0101
Email:
Fax: +1-727-258-0207

このマークアップは次のようになっています (見やすいように加工しています)。

<div class="vcard">
  <div class="fn org">Wikimedia Foundation Inc.</div>
  <div class="adr">
    <span class="type">work</span>
    <div class="street-address">200 2nd Ave. South #358</div>
    <div>
      <span class="locality">St. Petersburg</span> 
      <abbr class="region" title="Florida">FL</abbr>  <span class="postal-code">33701-4313</span>
    </div>
    <div class="country-name">USA</div>
  </div>
  <div>Phone: <span class="tel"><span class="type">work</span>+1-727-231-0101</span></div>
  <div>Email: <span class="email">info@wikimedia.org</span></div>
  <div>
    <span class="tel"><span class="type">Fax</span>: 
    <span class="value">+1-727-258-0207</span></span>
  </div>
</div>

その他の例

hCard examples には vCard 仕様書 RFC2426 の例をすべて hCard にしたものをはじめ、もっとたくさんの例があります。

hCard ボタン

hCard を使ったあなたのページに、次にあるボタンを貼り付けましょう。buttons#hCard には、最近追加されたボタンもあります。

実世界での例

このセクションは参考情報です。すでに世界には多くの hCard が存在しています。以前はこの仕様書で紹介していましたが、数が増えすぎてしまったため、別のページを用意しました。

hCard Examples in the wild で、実際に使われている hCard をご覧ください。

実装

このセクションは参考情報です。前のセクションと同じく、hCard の実装についても別のページを用意しています。

hCard Implementations で、hCard の実装についてご覧ください。

著作権

仕様の作成者である Tantek Çelik および Brian Suda が、自分のページでパブリックドメインの声明を行っています。よって、この仕様はパブリックドメインです。

Public Domain Contribution Requirement. Since the author(s) released this work into the public domain, in order to maintain this work's public domain status, all contributors to this page agree to release their contributions to this page to the public domain as well. Contributors may indicate their agreement by adding the public domain release template to their user page per the Voluntary Public Domain Declarations instructions. Unreleased contributions may be reverted/removed.

特許

This specification is subject to a royalty free patent policy, e.g. per the W3C Patent Policy, and IETF RFC3667 & RFC3668.

参考文献

規範的な参考文献

その他の参考文献

hCard を利用する仕様

hCard に似通っているもの

原案及び謝辞

Thanks to: my good friend Vadim who introduced me to vCard many years ago, and if I'd only paid more attention then, perhaps I could have helped a lot of people avoid wasting a lot of time reinventing various standards wheels.

Notes on derivation from vCard

This section is informative.

More Semantic Equivalents

For some properties there are HTML elements which better match and convey their semantics. The following properties SHOULD be encoded with the following (X)HTML:

  • URL in vCard becomes <a class="url" href="...">...</a> inside the element with class="vcard" in hCard.
  • Similarly, EMAIL in vCard becomes <a class="email" href="mailto:...">...</a>
  • PHOTO in vCard becomes <img class="photo" src="..." alt="Photo of ..." /> or <object class="photo" data="..." type="...">Photo of ...</object>
  • UID in vCard simply becomes another semantic applied to a specific URL (or EMAIL) for an hCard.

Singular and Plural derivations

The lists of singular and plural properties have been derived by analyzing the semantics of the individual properties in vCard RFC2426 and determining logically that they MUST be singular per their semantics. See hcard-singular-properties for explanations.

Plural Properties Singularized

Since plural property names become their singular equivalents, even if the original plural property permitted only a single value with multiple components, those multiple components are represented each with their own singularly named property and the the property is effectively multivalued and subject to the above treatment of multivalued properties.

Further Reading

Related Pages

The hCard specification is a work in progress. As additional aspects are discussed, understood, and written, they will be added. These thoughts, issues, and questions are kept in separate pages.