1.3 リソースの記述フォーマット（§1.3）

このページでは、リソースのコンテンツがどのように記述され、どのように XML や JSON で表現されるかを記述します。

リソース・モデル定義（§1.3.1）

リソースは UML 図と、疑似 XML シンタックスの２通りの方法で表現されます。UML 図はリソースのコンテンツの概略を示し、疑似 XML シンタックスは、最終的にリソースのインスタンスがどのような姿になるかを視覚的に表現します。リソースの記述は XML 表記を基本にしていますが、JSON などの他の表記も同様に正当であることに注意してください。

XML（§1.3.1.1）

XML シンタックスは以下のような表記を用います。

解説：

• リソースのインスタンスを生成するには、XML要素のコンテンツを、各要素のコメントに含まれる多重度、タイプのルールおよびコンテンツの記述に従って、適切なコンテンツで置き換えるだけです。
• 要素には、その要素が何回現れてもよいか、あるいは現れなければならないかを指定する多重度が設定されています。多重度がピンクで表現されている場合には、許容される多重度に影響を与える追加の条件があることを示しています。その内容はマウス・オーバー・テキストおよび形象的定義の記載に含まれています。
• 要素に指定されるタイプはひとつのこともあれば複数のタイプをとることもあります。タイプの種類については、このページで後述する Resource と Narrative 以外は、データ・タイプのページで定義されています。タイプ名はハイパーリンクされています。
• 疑似シンタックス中の各要素名も、交換フォーマットの下敷きとなるデータ・ディクショナリ中の要素の形象定義にハイパーリンクされています。要素名に下線が引かれている場合には、アプリケーションはその要素をサポートおよび／または理解しなければなりません。
• XML 中で使われる文字セットはつねに Unicode です。文字のエンコード方法を指定するのは任意ですが、指定することが推奨されています。（デフォールト値は XML の場合、UTF-8 です。）Unicode と双方向の互換性があるエンコード方法は全て許容されます。
• FHIR 要素のネームスペースはつねに http://hl7.org/fhir です。これを通常、ルート要素でデフォルト・ネームスペースとして指定します。FHIR リソースで、他のネームスペースが現れるのは、リソースのコンテンツ・モデルで外部のコンテンツ・モデルが明示的に導入されている箇所のみです。例えば、後述するように XHTML は全てのリソースで現れます。
• 全ての XML 要素は、内部参照の宛先として機能する id 属性を持つことができます。id 属性は、このリソース・フォーマット中では表示されていません。
• FHIR の要素が空になることは決してありません。リソースの中に要素が現れた時には、テキスト、またはその要素のタイプで指定される子要素、または Narrative や Extension のリンク先である id 属性のいずれかを持たなければなりません。
• ルート要素には xml:lang 属性が現れてもよく、その場合はリソースの基調となる言語を指定します。この属性は attachment と XHTML コンテンツにも現れることができますが、その他の場所では禁じられています。
• この文章記述によるシンタックスに加えて、W3C スキーマやスキーマトロンを含む、他の形式でのシンタックス定義も提供されます。Relax NG スキーマ、RDF および eCore 形式のものが予定されています。

XML で表現された時には、リソースはスキーマを使って検証でき、そのためのスキーマも提供されますが、実稼動システムでの検証は義務づけられません。（但し、使われる XML はこの仕様や、スキーマやスキーマトロンに準拠していなければなりません。）シンプルなXMLによる記述に加えて、システム実装の助けになるよう、W3C スキーマ、UML モデルおよびその他の定義モデルが提供されます。

XML（§1.3.1.2）

UML 図は、XML 要素に対応する一連のクラスで、同じコンテンツを表現したものです。要素がリソースの時は "R"、データタイプの時は "D" というラベルが付きます。ラベルのついていないクラスは、リソースまたはデータタイプのコンテンツの一部である通常のクラスです。

要素が取りうるデータタイプに選択肢がある場合には、 XML 表記と同じ分岐形式で選択肢が示されます。UML の仕組み上、図の表記からは要素の実際の順番は決定することはできませんし、プロパティが要素か属性かも判定できません。

UML 図は、リソースのコンテンツを人間に伝えることを意図しています。コード生成用に適した代わりの図表記は、eCore 参照プラットフォームの一部として提供されます。

Narrative（§1.3.2）

全てのリソースは、リソースの内容の要約であり、人間向けのリソースの内容表示に使える、人間が読める形式の Narrative を含まなければなりません。Narrative には全ての構造化データを反映させる必要はありませんが、人間が Narrative のテキストを読むだけで済ませても「医療上安全」なだけの十分な詳細を含まなければなりません。リソースは、医療上の安全を保証するために、どのコンテンツを Narrative に含めるべきか定義することがあります。

リソースの Narrative には、人手で編集された内容を含む、構造化されたデータには含まれない追加の情報を持つことが許されています。そのような追加の情報は、リソースが表す対象範囲内に限定されていなければなりません。小規模の閉じた業務連携の相手同士では Narrative のテキストが必要ない場合があります。そのような場合には、実装システムは Narrative を「[リソース名] - このリソースには人間の読むためのテキストは含まれていません」と同等な意味の適切な言語のテキストで埋めることが許されます。実装者は、小規模の閉じた相手同士の業務連携だったものが、定義したリソースの寿命の間に大きく広がることが大いにあり得ることに注意すべきです。

Narrative は XHTML の断片で、必要があれば画像を含めることができます：

用語のバインディング（§1.3.2.1）

div 要素のコンテンツは XTHMLの断片で、HTMLの要素のうち、HLML 4.0 標準の 7 から 11 章（ただし、9 章の 4 節は除く）と 15 章の基本的な HTML のフォーマット要素、<a> 要素（name または href のいずれか）、image および文章内部に限定したスタイル属性しか含みません。XHTML要素に head および body 要素、外部のスタイルシートの参照、スクリプト、フォーム、base/link/xlink、フレーム、iframe および object を含めることは禁止されています。div 要素には何らかの空白文字でないコンテンツを含めなければなりません。

画像の参照先はリソース中のローカル参照も認められます。

これは、同じリソース中のある要素の id 属性への内部参照で、text 要素への添付画像を直接参照するか、あるいは "Attachment" タイプの要素を参照するかのいずれかです。

リソースの一部に含まれない画像の存在は保証されないので、Narrative の重要な部分を占める画像は、この例のように常にリソースの中に埋め込む必要があります。

XHTMLの文字スタイル（§1.3.2.2）

Narrative に含まれる XHTML の断片は、普通に CSS を使うときのように、クラスと id とインラインのスタイル要素の組み合わせで文字スタイルの設定ができます。Narrative の XHTML が人間に表示するためにリソースから抽出され、使用されるコンテキストに相応しい表示が生成される時には、特定の CSS スタイルシートが適用されます。Narrative の作成者は以下のコンテンツのスタイル属性を固定することができます：

• ボールド、イタリック、アンダーライン、打ち消し線
• フォントの色、種類、サイズ
• バックグラウンドカラー、テキストの配置
• 空白の解釈
• 番号付きリストの番号フォーマット（テキスト中で言及される場合があるため）

これらのスタイルの設定は、スタイル属性を使ってインラインで指定されます。"i" や "pre" のように、同等の HTML 要素が存在する時には、そちらを代わりに使うこともできますが、HTML 4 ではそのような要素のいくつかを今後使わないことを提唱しているので Narrative XHTML では使ってはいけない（"u" や "font" を含む）ことに注意してください。

表示システムは、XHTML でスタイルが指定された時には、それらに従うようにしなければなりませんが、適切に解釈し直すこと（例えば、暗室の低コントラストのコンテキストでは、暗室の条件に合わせて表示色が変更されることが考えられます）は認められています。

Narrative の作成者は CSS の使用に従って、追加のスタイルやスタイル属性を指定することが許容されていますが、それはこの仕様に対する拡張になり、表示システムはそれらに従うことを要求されていません。ただし、document のコンテキストに関しては追加のルールが適用になることに注意してください。

注意：リソースの中のスタイルは http://hl7.org/implement/standards/fhir/fhir.css にある標準の FHIR スタイルシートにあるスタイルを使うことができます。このスタイルシートは直接は参照されないので、表示システムは、そう望むのであれば自分自身のためのコピーを保持しておく方がいいかもしれません。Narrative を作成するシステムは、これらのスタイルが診療上のコンテンツ用に定義されていると当てにしてはいけません。

内部参照（§1.3.3）

リソース中の要素間の参照が起こるのは以下の 4 つのケースです。

• Extension 要素から、その対象となる要素への参照
• CodableConcept データタイプの内部で、第一選択のコードを指定する時
• <img src=""/> からの参照で、リソース中の画像を指す時
• Narrative の中の要素と構造化データの間

これらの参照は、id/idref を用いて表現され、参照元の要素が、参照先の要素と同一のコンテンツを保持していることを示します。参照先の要素の "id" 属性は、リソース中の他の id のどの値とも異なるユニークな値を持たなければなりません。"id" 属性は、どの名前空間にも属しません。参照元の要素は、コンテンツ（text または子要素）を全く持たず、"idref" という名の属性のみ持ちます。idref 属性の値は、同じリソース（あるいは、CodeableConcept の場合は、同じデータタイプ ）の中の id 属性と一致しなければなりません。

単一のリソースでは、内部参照は xml:id/idref と全く同じように機能しますが、重要な違いがあります：リソースの場合の id のユニーク性と参照範囲は、その id を含む同じリソース内に限られます。Atom フィードの場合のように、複数のリソースがひとつの XML インスタンスに束ねられるような場合には、違うリソースの間では id の値の重複が起こりえます。このことは、リソースを読み込むアプリケーションが対応しなければなりません。

XHTML 要素とデータ要素の間の内部参照は "derived from" （一方がもう一方から由来したものである）の関係を成立させることに注意が必要です。その場合、参照先が元のコンテンツであり、参照元が由来したコンテンツになります。

リソースの JSON 表現（§1.3.4）

FHIR のリソースの表現形式は XML で記述されていますが、FHIR の仕様では、リソースの JSON による表現形式も定義しています。リソースの JSON による表現形式は、相互変換を容易になるよう、標準である XML の標準形式にほぼ忠実に倣っていて、XPath によるクエリーも JSON 構造でのクエリーに容易に書き換えできるようになっています。JSON による FHIR の表現形式の正式な MIME タイプは application/json+fhir です。

システムのクライアント側では、実装形式として XML を選ぶか JSON を選ぶかは自由です。サーバー側では XML をサポートする事は必須で、JSON もサポートするかは自由です。システムはどちらの表現形式をサポートしているか宣言しなければならない事に注意してください。また、参照実装システムには、ふたつの表現形式間の双方向の変換機能が含まれています。

JSON による表現形式は XML による表現形式を元にして次のように記述されています：

• JSON のオブジェクトのメンバーの名前は、XML の要素および属性の名前と同じです。このルールには繰り返し要素も含まれます。
• データタイプにおいては、文字列、10 進数のようなプリミティブ・データタイプの値表現は、XML と JSON で全く同じです。（これには instant データタイプを含み、JSON で提案されている専用の日時表現でなく、プレーンテキストで表現されます。）
• XML の時と同様に、JSON のプロパティの値が空になることはありません。空の値は省略してください。

両者には以下のような違いもあります：

• JSON 表現にはネームスペースはありません。
• JSON 表現では順番は重要ではありません。
• JSON では、属性と用途の区別がないので、属性（xml:id, value）は JSON におけるメンバーとして扱われます。（詳細については後述）
• JSON には、配列の概念があるので、繰り返し要素の表現にこれを用います。実際のインスタンスで、繰り返しがない時にも配列として表現する事に注意してください。
• Narravtive データタイプの XHTML 表現の <div> 要素は、XHTML のひとつのエスケープ文字列で表現されます。これは JSON のコンテンツの混同などを防ぐためです。それでも XHTML はほぼ上記のルールに準じています。

これらの違いから、特に、回避しようのない繰り返し要素に関する違いから、汎用の XML → JSON 変換ツールはうまく働かないことになります。参照実装システムは、これらの FHIR 特有の特徴を踏まえた XML ⇔ JSON 変換機能を備えています。

プリミティブ・データタイプの JSON 表現（§1.3.5）

プリミティブ・データタイプの値をとる FHIR の要素は、"value" プロパティに、value 属性で指定される値を持つ、同じ名前の JSON オプジェクトとして表現されます。

は、JSON では、以下のように表現されます：

XML と JSON で、データ保存の表現形式の同一性を保証するために、JSON の元々のデータタイプは "string" 以外は使われません。すべての XML 要素は "id" 属性を持つことができ、それは JSON では "_id" という名のプロパティで表されます。

は、JSON では、以下のように表現されます：

要素の繰り返し（§1.3.6）

要素の繰り返しは、JSON では、その要素の名前の配列で表現されます。したがって、XML での繰り返し要素 <dob>

は、JSON では、以下のように表現されます：

リソース、要素、データタイプの JSON 表現（§1.3.7）

リソースや要素やデータタイプ（他のデータタイプの値をとる名前を持った要素を持つデータタイプ）は、JSON では、その中のひとつひとつの要素をそれぞれメンバーとして持つオブジェクトとして表現されます。それぞれの構成要素も "id" 属性を持ちうるので、それはプリミティブ・データタイプの時と同様に JSON のメンバー値に変換されます。その際、"id" 属性から変換されたメンバーは、他のメンバーよりも先に来ます。例えば、

は、JSON では、以下のように表現されます：

注意点は：

• given と family は、XML では繰り返し要素なので、そのインスタンスで繰り返されるかどうかに関わりなく、JSON では配列として表現されます。
• プリミティブ・データタイプの要素に "id" 属性があるので、JSON オブジェクトとして表現されます。
• "name" 要素の family の部分では、"_id" が最初のメンバーとして追加されます。
• Narrative 要素 "text" の "div" 要素の XHTML コンテンツは、JSON では value プロバティのエスケープ文字列として表現されます。XHTML のルート要素は XHTML ネームスペースの <div> でなければなりません。

バンドル（§1.3.8）

バンドルはひとつのドキュメントに複数のリソースをまとめたものです。

Atom でのバンドルの表現形式（§1.3.8.1）

XML 形式のバンドルは、以下のテンプレートに従って、Atom 形式（http://tools.ietf.org/html/rfc4287）で表現されます：

注意事項（§1.3.8.1.1）

• 理屈としては、バンドルは、どこか他の場所で利用するために取りまとめられたリソースの集合、「フィード」です。
• Atom フィードの中では、リソースの順番は意味を持ちません（しかし、entry の場合は違い、entry の順番は重要です。）Atom のネームスペースでの要素の順番は、ここで挙げた例に従う必要はありません。
• feed や entry の title は、人間が読むべき便宜的なコンテンツで、自動処理には一切使用してはいけません。アプリケーションは（受信側ではなく）自分の都合で好きなように値を入れることができます。
• すべてのバンドルは、ユニークな id を持たねばならず、その id は適切な絶対 URL でなければなりません。UUID（urn:uuid:...）の使用が推奨されます。
• entry 要素は、次の 3 つのメタデータを持ちます：Id (.id), Version Id (.link), Last Updated (.updated)
• entry.id は、絶対 URL でなければならず、その tail 要素はリソースの論理 id でなければなりません。id はバージョン依存しない参照になります。
• entry.link の "self" への参照は、リソースのバージョン依存の参照になります。
• RESTful 実装で用いる時には、entry.link と entry.id は、そのシステム上の URL になります。バージョン依存の link は、update 操作による、Atom バンドルを使う公開側／購読側のシステム間の同期の基盤として用いることができます。
• すべての entry において author は必要ですが、それらの属する feed に author が指定されている場合には、個々の entry には author を指定する必要はありません。
• FHIR のリソースでは一般的に必要ありませんが、content 要素には xml:base 要素を指定することができます。
• Atom 仕様（セクション 5.1）に記述されているように、バンドル全体を、単一のエンベロープ化されたデジタル署名で署名することができます。詳しくは後述を参照してください。
• XML で表現されたバンドルの MIME タイプは application/atom+xml です。
• rel 属性に "self" が指定された feed.link 要素は、FHIR 仕様では特定の意味を定義されていませんが、search 操作は例外で、フィードの送信元を特定するために使うことができます。
• rel 属性に "first"、"last"、"previous" および "next" が指定された feed.link 要素は、ページ指定機能と共に用いて、クライアントが複数ページの結果をブラウズするのに用いることができます。詳しくは search 機能の項を参照してください。

バンドルのバージョン管理−削除の表現（§1.3.8.1.2）

リソースのバージョン履歴を返す場合には、削除済みのエントリについては、その事を示す必要があります。Atom フィードに含まれる削除済みのリソースは、rfc6721.txt での定義に従い、以下のように表現されます：

RESTful インターフェースで削除済みのリソースにアクセスすると 410 エラーとなります。

バイナリ表現のリソース（§1.3.8.1.3）

状況によっては、バンドル中のリソースをバイナリ形式で表現することが、有用または必要になることがあります。そのようなリソースは、FHIR のリソースの中から（通常 URI で）参照されているリソースで、参照のまま残しておくより Atom フィードに含めてしまった方が便利な場合です。

バイナリ表現のリソースのフィードでの表現形式は、HTTP で指定される MIME タイプを content-type に持つ base64 エンコードとして content 要素に格納されます：

summary は、適切な言語での「バイナリ・リソース」という意味の文言になります。

リソース参照されたリソースの取得（§1.3.8.1.4）

リソースのバンドルを読み込む側は、リソース参照を見つけた時は、常に Atom フィードの中に含まれているリソースをまず照合する必要があります。以下のような、リソースのタイプと、参照先のリソースの ID である相対 URL を持ったリソース参照があったとします：

読み込み側のシステムは、この institution 要素が示すリソースを探す際に、他の場所を探す前に、常に Atom フィードに含まれるエントリを全て照合しなければなりません。もし、上記のリンクを含むリソースの entry.id が http://example.org/patient/@1 であった場合、絶対 URL は http://example.org/organization/@23 になります。もし、この organization がフィード中に含まれていたとすると、例えば以下のようになります：

リソースの場所を、絶対 URL で特定可能な時もあります。この場合、id 要素には、リソースの場所への直接参照が含まれています：

Atom フィード中のリソースにひとつも該当する URL を持つものがなかった時は、アプリケーションは、直接指定された URL にアクセスするか、その他の実装システムに固有の該当リソースの照会方法を用いることになります。

実装上の注意（§1.3.9）

• Atom フィードは Atom 仕様に記述されたルールに従って署名することができます。ドキュメントに署名すると、その結果として URL や ID や内部参照が凍結され、変更できなくなります。これは、望まれる機能であるかもしれませんが、ID の振り直しが頻繁に起こる閉じた動作環境では、相互運用性に支障をきたす恐れがあります。このため、ドキュメントのバンドルだけを対象として、しかもすべての関連するリソースがバンドルの中に見いだされた時だけ、署名する事を推奨します。
• FHIR のリソースでは、リソース間の内部参照で、 id 属性をその参照先として使用します。これらの id 属性はユニークでひとつのリソースのコンテクストの中で完結します。リソースがバンドルにまとめられた時には、異なるリソースの間で id 属性の重複が起こりえます。このため、id 属性の照会の範囲をその id 属性が宣言されたリソースの範囲内だけに限定する事が重要です。

JSON でのバンドルの表現形式（§1.3.9.1）

JSON では、バンドルは、バンドル特有の要件に合わせて特化した JSON 形式で表現されます。XML 形式でのフィード定義の各要素は、対応する同じ名称の JSON オブジェクト・メンバーを持ちます。人物のクエリに対する検索結果を返すフィードの例を以下に示します：

変換手法に一貫性をもたらすために、繰り返し可能な要素のプロパティ名を複数形にしていない事に注意してください。

JSON バンドルの MIME タイプも application/json+fhir です。

バンドルのバージョン管理−削除の表現（§1.3.9.1.1）

リソースのバージョン履歴を返すときには、削除済みである事を示すバージョンが含まれることがあります。XML 形式では RFC 6721 に従いますが、JSON 形式ではエントリの論理的順序を保持するために、以下のように entry アイテムを使用する必要があります：

このエントリは、削除日時が与えられているので、削除済みである事が示されます。 id は必須で、link は任意です。

バイナリ表現のリソース（§1.3.9.1.2）

バイナリのリソースがフィードに表現される時は、HTTP で示された MIME タイプの content-type と共に、base64 エンコードされた content に格納されます。

summary は、適切な言語での「バイナリ・リソース」という意味の文言になります。

XML スキーマとスキーマトロン（§1.3.10）

この仕様に記述されているコンテンツ・モデルには、全てスキーマ定義が用意されています。基本となるスキーマは"fhir-base.xsd"という名前で、全てのデータタイプと、このページに記述されている全ての基本インフラストラクチャー・タイプが定義されています。それに加えて、各リソースにはひとつづつスキーマが用意され、共通のスキーマ fhir-all.xsd には、全てのリソース・スキーマが含まれます。カスタマイズされた Atom スキーマ fhir-atom.xsd がリソースのバンドルを検証するために用意されています。

この仕様には、W3C スキーマのファイルに加えて、データタイプやリソースに対して定義された様々な制約条件を適用するために、スキーマトロンのファイルも用意されています。各リソースに対する個々のスキーマトロン・ファイルと、すべてのリソースに対するルールを取り込んだ複合ファイルの hir-atom.sch とがあります。

FHIR で交換される XML は W3C スキーマとスキーマトロンの検証に通るものでなければなりませんが、いずれの検証も必須ではありませんし、スキーマあるいはスキーマトロンの検証に合格しただけでは、コンフォーマントなインスタンスの十分条件ではありません。（この仕様には、いくつかの、スキーマとスキーマトロンのどちらでも検証できないルールが存在します。）交換されるコンテンツでは、リソース自身の中に、スキーマを指定したり、あるいはスキーマ・インスタンスの名前空間を含めてもいけません。

注意：FHIR は、正式な HL7 標準として投票される以前の、現在開発中のドラフト仕様です。

実装者がここで定義されている内容での試験実装を行うことは歓迎されていますが、内容が事前の通知無しで変更される可能性があることを明記して下さい。

© HL7.org 2011 - 2012 License