Posted by 山崎富美 / Developer Relations Team

[先日「Google Person Finder API のドキュメンテーションの翻訳について」というブログ記事を公開しましたが、引き続きデータモデルの各フィールドの説明を中心に、ソフトウェアエンジニアの花岡 俊行が翻訳をしてくれました。なお、正式版の翻訳については code site に掲載されるのをお待ちください-山崎]

Data Model

2 つのタイプの record があります。PERSON record は静的な情報、NOTE record は動的な情報のための record です。NOTE は特定の PERSON に属し、PERSON はいくつでも NOTE を持つことができます。一度 record が作られたら、それは変化しません。ある PERSON に関してのデータが変化したことを示すには、時刻情報を付加した NOTE をその PERSON に関連付けて加えてください。

PERSON record は、行方不明者を探している人、行方不明者について情報を持っている人のどちらからも作られる可能性があります。ある人に対する PERSON record はすべての関係情報の集合点を表します。そして、その人に対する NOTE record は共有する情報を蓄積していくものです。

PERSON records

ある人に対する PERSON record は複数あるかもしれません。複数の source からデータをインポートするアプリケーションではある人に対する PERSON record が複数あるということが起こり得ます。それらの record を関連付けるかどうかはアプリケーションに任せられます。アプリケーションがすべての record のコピーを持ち、どの record が同じ人を指すかをそれとは別に追跡するという方法が推奨されます。

■メタ情報

人々が探しているデータの信頼性を調べられるようにするためのメタ情報です。

person_record_id (string):
あるレコードに対するユニーク ID であり、ドメイン名と、それにスラッシュとローカル ID が続く。ドメイン名はこのレコードに対して権限を持つホームレポジトリを示す。ローカル ID のフォーマットはホームレポジトリに任せられる。person_record_id が、そのアプリケーション自身と異なるドメインから始まっている場合、その record は他の source から得られたクローンであることを意味する。

entry_date (string in the form "yyyy-mm-ddThh:mm:ssZ"):
この record のコピーが保存された UTC 時刻。PFIF レポジトリは、record が追加時のこの値が単調増加することを保証しなければならない。それにより、クライアントは最後に受け取った entry_date 以降の entry_date をもつ record を要求することによってレポジトリのコピーを更新することができる。
author_name (string):
情報提供者のフルネーム。
author_email (string):
情報提供者のメールアドレス。
author_phone (string):
情報提供者の電話番号。
source_name (string):
この record のホームレポジトリの名前（情報元のサイト名）。
source_date (string in the form "yyyy-mm-ddThh:mm:ssZ"):
この record がホームレポジトリ内で作成された UTC 時刻 （情報元の投稿日）。
source_url (string):
この record のホームレポジトリにおける URL（情報元の URL ）。

■識別情報

これらのフィールドは人の識別情報用の変化しないデータです。これらは検索に使われます。

first_name (string):
探している人、見つかった人のファーストネーム。スペースに続けてミドルネームも追加できる。
last_name (string):
探している人、見つかった人のラストネーム。
home_city (string, city name):
探している人、見つかった人の市。
home_state (string):
探している人、見つかった人の都道府県。
国の行政区域を大文字 ISO 3166-2 形式で表現します。
訳注： http://ja.wikipedia.org/wiki/ISO_3166-2:JP を参照
home_neighborhood (string):
探している人、見つかった人の近隣の場所。
home_street (string):
探している人、見つかった人の町名。
home_postal_code (integer):
探している人、見つかった人の郵便番号。
photo_url (string):
探している人、見つかった人を識別する写真への URL。
other (large string):
自由形式のテキストデータで、他の source から持ち込まれた静的なデータに使われます（他の source からインポートされた動的なデータは NOTE record に保存されるべきです）。短いフィールドは一行で、フィールド名、コロン、値で表現されます。長いフィールドは、フィールド名とコロンの行に続いてインデントされた文字列で表現されます。機械的な処理で他の形式から PFIF 形式に record が変換された場合は、"automated-pfif-author"フィールドが存在すべきです。このフィールドは PFIF を作成したプログラム名を表します。PFIF レポジトリから record がエクスポートされた場合には"automated-piff-author"フィールドは付加されません。人に対する自由形式テキストの説明も"description"のフィールド名でここに表されます。たとえば、自由形式文字列フィールドを持つ PFIF 以外のフォーマットから record を取得するプログラムは other フィールドを含み、それは次のようになるでしょう：

description:
    Dark hair, in her late thirties.
    Also goes by the names "Kate" or "Katie".
automated-pfif-author: ScrapeMatic 0.5

他のアプリケーションからインポートされたフィールドに対する名前はドメイン名とスラッシュを始めに付加されるべきです。例えば、ICRC record から生年月日がインポートされた場合は次のようになります：
（訳注：この例は PFIF 1.1 当時のもの。実際には PFIF 1.2には生年月日専用のフィールドが用意されています）

icrc.org/birthdate: 1976-02-26
sex (string):
探している人、見つかった人の身体的性別。female、male、 other の 3 つのうち 1 つで指定されます。性別不明の場合はこのフィールドを省略してください。
date_of_birth (string):
探している人、見つかった人の正確な生年月日(YYYY-MM-DD)またはだいたいの生年月日(YYYY, YYYY-MM)。
age (string):
探している人、見つかった人のだいたいの年齢。source_date 時点での、生年月日からの年数。このフィールドの値はひとつの 10 進数整数か、2 つの 10 進整数をハイフンでわけた包含範囲を取る。source_date が指定されていない場合、このフィールドは定義されません。（訳注： 27 歳→ "27", 25 から 30 歳→"25-30"）
home_country (string):
探している人、見つかった人の母国。大文字 2 文字の ISO 3166-1 country code で指定されます。

NOTE records

NOTE record はちょうどひとつの PERSON record に属します。ある PERSON record には任意の数の NOTE record が関連付けられます。すべての note はタイムスタンプと note の著者情報を持ちます。アプリケーションはタイムスタンプを、フィールドの最新情報を決定するのに使えます。ユーザーは著者情報をフィールドの信頼性を確かめるために使うことができます。

これらのフィールドは時間とともに変化する情報を保存します。これらのフィールドが NOTE record に現れたときは、この record はこれらのフィールドに対する新しい値を定めます。source_date フィールドは新しい値が効力を持つ日付を示します。例えば、最新の場所情報を表示したいアプリケーションは、last_known_location フィールドを持っていてるもののうち最新の source_data を持つ NOTE を参照すればいいことになります。

note_record_id (string):
この record のユニーク ID であり、ドメイン名にスラッシュ、ローカル ID が続きます。ドメイン名はこの record の権限を持つホームレポジトリの識別子です。ローカル ID のフォーマットはホームレポジトリに任されています。note_record_id がアプリケーションのドメインと異なったドメインから始まっている場合、この record は他の source からのクローンであることを意味します。
entry_date (string in the form "yyyy-mm-ddThh:mm:ssZ"):
この record のコピーが保存された UTC 時刻。PFIF レポジトリは、record が追加時のこの値が単調増加することを保証しなければなりません。それにより、クライアントは最後に受け取った entry_date 以降のentry_date をもつ record を要求することによってレポジトリのコピーを更新することができます。
author_name (string):
情報提供者のフルネーム。
author_email (string):
情報提供者の e-mail address。
author_phone (string):
情報提供者の電話番号。
source_date (string in the form "yyyy-mm-ddThh:mm:ssZ"):
この record がホームレポジトリ内で作成された時刻（情報元の投稿日）。ほとんどのケースで、note はこのフィールドでソートして表示されるべきでしょう。
found (boolean string, "true" or "false"):
行方不明者に連絡が取れた場合、会えた場合は"true", さもなくば"false"の値をとります。この note の text フィールドで、いつどこで連絡が取れたか、会えたかを説明するべきです。
email_of_found_person (string):
見つかった人の連絡先 e-mail です。このフィールドは人物が見つかった場合のみ存在します。この note の text フィールドでどのように連絡先情報が決定されたか説明するべきです。
phone_of_found_person (string):
見つかった人の連絡先電話番号です。このフィールドは人物が見つかった場合のみ存在します。この note の text フィールドでどのように連絡先情報が決定されたか説明するべきです。
last_known_location (string):
捜索されている人を最後に見かけた場所を述べた自由形式説明であり、市や都道府県など、できるだけ詳細に述べた情報です。この note の text フィールドはどのように所在地が決定されたか述べるべきです。
text (large string):
自由形式の文字列であり、人物の状態や状況、最後に目撃された所在地の詳細の説明です。他の情報の訂正であることもあるでしょう。
status (string):
探している人、見つかった人の状態で次の 5 つの文字列のうちの 1 つを取ります。
information_sought
情報提供者は対象の person の情報を探しています。
is_note_author
情報提供者は対象の person 自身です。
believed_alive
情報提供者は対象の person が生きているという情報を入手しました。
believed_missing
情報提供者には対象の person が行方不明と判断した理由があります。
believed_dead
情報提供者は対象の person が亡くなっているという情報を入手しました。

person_record_id (string):
この NOTE record が関連づいている PERSON record の person_record_id です。
linked_person_record_id (string):
この NOTE record が、同一人物に対する重複 record であると主張している他の PERSON record のperson_record_id です。
ユーザーがある 2 つの PERSON record を重複だと示すときには、NOTE record をそれら両方の PERSON record に付加し、それぞれに linked_person_record_id フィールドを持たせ、相互に指し示します。これらの NOTE record はこれらを重複だと示した関係者を示す author_name フィールドを持ち、text フィールドに重複だと判断するにいたった理由を付加します。

Notes

String fields は non-ASCII character を含められます。

PFIF 1.2 では person 要素の外にトップレベルの note 要素を許します。正しい PFIF ドキュメントはひとつの pfif 要素からなり、それはひとつ以上の person か note 要素を持ちます。

note 要素が person 要素の外に現れる場合、note は person_record_id をもつ必要があります。それ以外の場合には person_record_id フィールドは任意ですが、存在する場合には note を含んでいる person の person_record_id と一致する必要があります。

person 要素の中では、 必須の person_record_id がはじめにくる必要があり、note 要素は最後に来る必要があります。note 要素の中では、note_record_id が最初に来る必要があり、もし存在するときには person_record_id がそれに続くべきです。残りのフィールドは任意の順番であらわれることができます。