【注意】 このドキュメントは、W3CのJSON-LD 1.1 : A JSON-based Serialization for Linked Data W3C Recommendation 16 July 2020の和訳です。
このドキュメントの正式版はW3Cのサイト上にある英語版であり、このドキュメントには翻訳に起因する誤りがありえます。誤訳、誤植などのご指摘は、訳者までお願い致します。
First Update: 2020年11月24日
公開以後に報告されたエラーや問題がないか正誤表を確認してください。
翻訳版も参照してください。
このドキュメントは、規範以外の形式でも入手できます: EPUB
Copyright © 2010-2020 W3C® (MIT, ERCIM, Keio, Beihang). W3C liability, trademark and permissive document license rules apply.
JSONは、データのシリアル化と送受信に便利な形式です。この仕様では、リンクト・データをシリアル化するためのJSONベースの形式であるJSON-LD 1.1を定義しています。この構文は、既にJSONを用いている展開済みのシステムに容易に統合できるように設計されており、JSONからJSON-LDにスムーズにアップグレードするための道筋を示します。これは、ウェブ・ベースのプログラミング環境におけるリンクト・データの利用、相互運用可能なウェブ・サービスの構築、JSONベースのストレージ・エンジン内のリンクト・データの格納のための手段となることを主に意図しています。
この仕様は、JSON-LD 1.0[JSON-LD10]で定義している機能の上位集合を記述しており、特に明記していない限り、この仕様のバージョン1.0を用いて作成されたドキュメントは、JSON-LD 1.1との互換性を維持しています。
この項は、このドキュメントの公開時のステータスについて記述しています。他のドキュメントがこのドキュメントに取って代わることがありえます。現行のW3Cの刊行物およびこの技術報告の最新の改訂版のリストは、https://www.w3.org/TR/のW3C技術報告インデックスにあります。
このドキュメントは、JSON-LDワーキンググループによって開発され、JSON-LDコミュニティグループの最終レポートから派生したものです。
このドキュメントで記述している機能を実証できる実演型JSON-LDプレイグラウンドがあります。
この仕様は、JSON-LD 1.0[JSON-LD10]仕様に取って代わることを目的としています。
このドキュメントは、JSON-LDワーキンググループによって勧告として公開されました。
この仕様の議論にはGitHub Issuesをお勧めします。または、メーリング・リストにコメントを送信することもできます。コメントは[email protected](アーカイブ)に送信してください。
ワーキンググループの実装報告書を参照してください。
このドキュメントは、W3Cメンバー、ソフトウェア開発者、他のW3Cグループ、および他の利害関係者によりレビューされ、W3C勧告として管理者の協賛を得ました。これは確定済みドキュメントであり、参考資料として用いたり、別のドキュメントで引用することができます。勧告の作成におけるW3Cの役割は、仕様に注意を引き付け、広範囲な開発を促進することです。これによってウェブの機能性および相互運用性が増強されます。
このドキュメントは、W3C特許方針の下で活動しているグループによって作成されました。W3Cは、このグループの成果物に関連するあらゆる特許の開示の公開リストを維持し、このページには特許の開示に関する指示も含まれています。不可欠な請求権(Essential Claim(s))を含んでいると思われる特許に関して実際に知っている人は、W3C特許方針の6項に従って情報を開示しなければなりません。
このドキュメントは、2019年3月1日のW3Cプロセス・ドキュメントによって管理されています。
このドキュメントは、JSON-LDワーキンググループが作成した次の3つのJSON-LD 1.1勧告うちの1つです。
この項は非規範的です。
リンクト・データ[LINKED-DATA]は、様々なドキュメントやウェブ・サイトにまたがる標準に基づく、機械が解釈可能なデータのネットワークを作成する方法です。これにより、アプリケーションは、1つのリンクト・データから出発し、ウェブ上の様々なサイトで提供されている他のリンクト・データへの組み込みリンクを辿ることができます。
JSON-LDは、リンクト・データをJSON[RFC8259]でシリアル化するための軽い構文です。その設計により、既存のJSONを最小限の変更でリンクト・データとして解釈できるようになります。JSON-LDは、ウェブ・ベースのプログラミング環境におけるリンクト・データの利用、相互運用可能なウェブ・サービスの構築、JSONベースのストレージ・エンジン内のリンクト・データの格納のための手段となることを主に意図しています。JSON-LDはJSONと100%互換性があるため、現在利用可能な多数のJSONパーサやライブラリを再利用できます。JSONが提供するすべての機能に加えて、JSON-LDでは以下を導入しています。
JSON-LDは、RDF[RDF11-CONCEPTS]の知識がなくても、そのままJSONとして利用できるように設計されています。また、SPARQL[SPARQL11-OVERVIEW]などの他のリンクト・データ技術と組み合わせてRDFとして使用できるようにも設計されています。上記の機能を必要とする開発者や、RDFグラフやデータセットをJSONベースの構文でシリアル化する必要のある開発者は、JSON-LDに興味を持つでしょう。JSON-LDをRDFツールとともに用いようとしている人は、[Turtle]や[TriG]のように、別のRDF構文として使用できることに気付くでしょう。JSON-LDとRDFがどのように関係しているかに関する完全な詳細は、§ 10. RDFとの関係の項にあります。
この構文は、JSONに基づいて稼働している展開済みのシステムを妨げることなく、JSONからJSON-LDにスムーズにアップグレードするための道筋を示すように設計されています。そのようなデータの形は非常に多様であるため、JSON-LDは、ドキュメントを確定的な構造に再整形して処理をシンプルにする方法を備えています。
この項は非規範的です。
このドキュメントは、リンクト・データをJSONでシリアル化するための詳細仕様です。このドキュメントは、主に次の読者を対象としています。
関連ドキュメントであるJSON-LD 1.1処理アルゴリズムとAPI仕様[JSON-LD11-API]は、共通するJSON-LDの操作のための標準的なライブラリ・インターフェースを提供することにより、より高いレベルでJSON-LDを扱う方法を規定しています。
この仕様の基本を理解するためには、まず、[RFC8259]で詳細に説明されているJSONに精通していなければなりません。
このドキュメントでは、ハイパーリンクについて論じる場合には、ほぼIRI(Internationalized Resource Indicator)という用語のみを用います。多くのウェブ開発者には、URL(Uniform Resource Locator)という用語の方が馴染みがあるでしょう。このドキュメントでは、稀であるものの、URI(Uniform Resource Indicator)という用語も用います。技術コミュニティでは、これらの用語は同じ意味で用いられることが多いですが、互いに重要な差異があるため、この仕様では労を惜しまずに常に適切な用語を用いるよう努めています。
このドキュメントでは、JSON-LD 1.0バージョン以降の変更点を強調表示できます。変更のを選択してください。
この項は非規範的です。
この仕様の開発にご参加いただける方法がいくつかあります。
この項は非規範的です。
この仕様では、表記に関して次の規定を用いています。
マークアップ
定義の参照のマークアップ
外部定義の参照のマークアップ
注は、緑色の左枠線と緑色の「注」という見出しが付いた薄緑色のボックスに入っています。注は常に参考情報です。
例は、カーキ色の左枠線と番号付きのカーキ色の「例」という見出しが付いた薄カーキ色のボックスに入っています。 例は常に参考情報です。例の内容は等幅フォントで、構文の色が付いている可能性があります。 例を他の表現に変換した結果を示すために、例にはタブ型のナビゲーション・ボタンが含まれている場合があります。
この項は非規範的です。
このドキュメントでは、外部仕様で定義されている次の用語を用いるとともに、JSON-LD固有の用語も定義しています。
ECMAScript言語仕様[ECMASCRIPT]、JSON(The JavaScript Object Notation)データ交換フォーマット[RFC8259]、インフラ標準[INFRA]、およびWeb IDL[WEBIDL]からインポートした用語
true
とfalse
の値。内部表現では、JSONオブジェクトは、キー/値のペアを持つエントリーで構成されるマップ([INFRA]を参照)として記述されます。
API(Application Programming Interface)では、マップは[WEBIDL]のレコードを用いて記述されます。
@id
がnull
である場合の@context
内のマップ・エントリーは、用語とIRIとの関連性を明示的に切り離します。値がnull
であるJSON-LDドキュメントの本文内のマップ・エントリーは、マップ・エントリーが定義されていない場合と同じ意味を持ちます。@value
、@list
、または@set
が展開形式でnull
に設定されていれば、JSONオブジェクト全体が無視されます。true
、false
のいずれかです。IRI(Internationalized Resource Identifiers)[RFC3987]からインポートした用語
@type
の値、および語彙に対して相対的であると定義されている用語の値は、基底IRIではなく、語彙マッピングに対して解決されることに注意してください。RDF 1.1概念および抽象構文[RDF11-CONCEPTS]、RDFスキーマ1.1[RDF-SCHEMA]、およびリンクト・データの設計上の課題[LINKED-DATA]からインポートした用語
_:
という接頭辞で始まる識別子が割り当てられます。_:
で始まります。rdf:langString
である場合はオプションの言語タグが含まれます。"ltr"
、"rtl"
、null
のいずれかの文字列でなければならない@direction
キーを用いてコンテキスト内で設定できます。規範的な記述については、JSON-LD 1.1のコンテキスト定義の項を参照してください。null
を表す文字列でなければならない@language
キーを用いてコンテキスト内で設定できます。規範的な記述については、JSON-LD 1.1のコンテキスト定義の項を参照してください。@default
キーを持つマップです。@context
エントリーとして現れるコンテキストです。その値はIRIとしての、または上記のいずれかを組み合わせた配列としての、コンテキスト定義のマップでありえます。@graph
エントリーを持っていなければならず、@id
と@index
のエントリーを持つことができます。シンプルなグラフ・オブジェクトは、@id
エントリーを持っていないグラフ・オブジェクトです。ノード・オブジェクトは@graph
エントリーを持つことができますが、他のエントリーが含まれている場合には、グラフ・オブジェクトとは見なされないことに注意してください。@graph
で構成される最上位のオブジェクトも、グラフ・オブジェクトではありません。ノード・オブジェクトは、他のプロパティーが含まれている場合は、名前付きグラフも表すことができることに注意してください。規範的な記述については、JSON-LD 1.1のグラフ・オブジェクトの項を参照してください。@container
を@id
に設定して定義した用語のマップの値です。idマップの値はノード・オブジェクトでなければならず、そのキーは、関連付けられているノード・オブジェクトの@id
を表すIRIとして解釈されます。idマップの値に@id
へと展開するキーが含まれている場合、その値はidマップの参照キーと同等でなければなりません。規範的な記述については、JSON-LD 1.1のIdマップの項を参照してください。@container
を@graph
に設定した展開用語定義を持つマップ・エントリーの値から作成される名前付きグラフ。@included
または@included
のエイリアスであり、値が1つ以上のノード・オブジェクトであるノード・オブジェクトのエントリーです。規範的な記述については、JSON-LD 1.1の包含ブロックの項を参照してください。@container
を@index
に設定して定義した用語のマップの値であり、その値は文字列、数値、true
、false
、null、ノード・オブジェクト、値オブジェクト、リスト・オブジェクト、集合オブジェクト、上記の0以上の配列のいずれかでなければなりません。形式的な記述については、JSON-LD 1.1のインデックス・マップの項を参照してください。rdf:JSON
であるリテラルです。値オブジェクトの表現では、@type
の値は@json
です。JSONリテラルは、有効なJSON[RFC8259]である値を表します。規範的な記述については、JSON-LD 1.1のrdf:JSON
データ型の項を参照してください。true
かfalse
、型付き値、または言語タグ付き文字列です。これは、RDFリテラルを表します。@container
を@language
に設定して定義した用語のマップの値であり、そのキーは[BCP47]言語コードを表す文字列でなければならず、その値はnull、文字列、上記の0以上の配列のいずれかの型でなければなりません。規範的な記述については、JSON-LD 1.1の言語マップの項を参照してください。
@list
キーを持つマップです。@index
キーを含むこともできますが、その他のエントリーを含むことはできません。規範的な記述については、JSON-LD 1.1のリストと集合の項を参照してください。@context
キーワードにより指定されます。@id
キーのみを持つノードを参照するために用いられるノード・オブジェクト。@version
エントリーを用いて異なるバージョンを定義することで、JSON-LD 1.0[JSON-LD10]に準拠しているプロセッサが誤ってJSON-LD 1.1ドキュメントを処理し、異なる出力を作成する可能性がないことを保証できます。APIが処理モードをjson-ld-1.0
に設定するオプションを提供すると、JSON-LD 1.1の機能がアクティブ化されなくなったり、コンテキストの@version
エントリーが明示的に1.1
に設定されている場合にエラーになったりします。この仕様は、json-ld-1.1
の処理モードによりJSON-LD 1.0を拡張したものです。@context
エントリーを用いた展開用語定義の一部です。これは、組み込みコンテキストと同じ形式を有しています。用語を型として用いる場合は型の範囲付きコンテキスト(type-scoped context)を定義し、プロパティーとして用いる場合はプロパティーの範囲付きコンテキスト(property-scoped context)を定義します。@set
エントリーを持つマップです。@index
キーを含むこともできますが、その他のエントリーを含むことはできません。規範的な記述については、JSON-LD 1.1のリストと集合の項を参照してください。@container
を@type
に設定して定義した用語のマップの値であり、そのキーは、関連付けられているノード・オブジェクトの@type
を表すIRIとして解釈されます。その値はノード・オブジェクトまたはノード・オブジェクトの配列でなければなりません。@type
に展開される用語が値に含まれている場合、その値は展開時にマップの値と統合されます。規範的な記述については、JSON-LD 1.1の型マップの項を参照してください。@value
エントリーを持つマップです。規範的な記述については、JSON-LD 1.1の値オブジェクトの項を参照してください。null
でなければならない@vocab
キーを用いてコンテキスト内で設定されます。規範的な記述については、JSON-LD 1.1のコンテキスト定義の項を参照してください。この項は非規範的です。
JSON-LDは、次の設計目標を満たしています。
@context
プロパティーを含めつつも無視することだけを知っていれば十分です。この項は非規範的です。
一般的に言えば、JSON-LDドキュメントで記述されているデータ・モデルは、ラベル付きの有向グラフです。グラフには、有向アークで接続されたノードが含まれています。ノードは、プロパティーを持つ資源か、文字列、数値、型付き値(日付や時刻など)、IRIなどのプロパティーのデータ値のいずれかです。
有向グラフ内では、ノードは資源であり、名前がない、つまり、IRIで識別されない場合があり、これは空白ノードと呼ばれ、空白ノード識別子を用いて識別できます。この識別子は、JSONなどのツリー構造を用いて完全に接続されたグラフを表すために必要でありえますが、それ以外には本質的な意味はありません。文字列や数値などのリテラル値も資源と見なされ、JSON-LDは様々な種類の資源を区別するために、ノード・オブジェクトと値オブジェクトを区別します。
このシンプルなデータ・モデルは非常に柔軟かつ強力であり、いかなる種類のデータでもほとんどモデル化できます。データ・モデルのより深い説明については、§ 8. データ・モデルの項を参照してください。
リンクト・データの技術に精通している開発者は、データ・モデルをRDFデータ・モデルとして認識するでしょう。JSON-LDとRDFの関係についてさらに深く知りたい場合は、§ 10. RDFとの関係を参照してください。
表層レベルでは、JSON-LDドキュメントは単なるJSONであり、[RFC8259]で詳細に説明されています。コアなデータ構造を記述するために、これは、配列、マップ(JSONオブジェクトの解析済みバージョン)、文字列、数値、ブール、nullに限定されており、JSON-LD内部表現と呼ばれます。これにより、JSON以外の表層構文は、構文が同等のコアなデータ構造にマッピングされている場合に、同じアルゴリズムを用いて操作できます。
この仕様では論じていませんが、YAML(YAML Ain’t Markup Language)(YAML™)バージョン1.2[YAML]やCBOR(Concise Binary Object Representation)[RFC7049]などのバイナリ表現を用いた並行作業を、内部表現へのマッピング用に使用でき、それにより、JSON-LD 1.1 API[JSON-LD11-API]は、情報源がJSONドキュメントであるかのように動作できます。
この項は非規範的です。
JSON-LDは、言語のコアとなるいくつかの構文トークンとキーワードを規定しています。キーワードの規範的な記述は、§ 9.16 キーワードで示しています。
:
@base
@container
@context
@context
キーワードについては、§ 3.1 コンテキストで詳細に説明しています。@direction
@graph
@id
@id
プロパティーのみを含んでいるノード・オブジェクトであり、ドキュメントの他の場所にあるノード・オブジェクトへの参照を表すことができます。@import
@included
@index
@json
@type
の値として用います。このキーワードについては、§ 4.2.2 JSONリテラルで説明しています。@language
@list
@nest
@none
@prefix
true
の場合は、この用語を用いて短縮時に短縮IRIを構築できます。値がfalse
の場合は、この用語では短縮IRIを構築できません。また、短縮IRIの展開時に用語が考慮されるかどうかも決定します。@propagate
true
で、コンテキストがノード・オブジェクト全体に伝播することを意味します(デフォルトでfalse
に設定される型の範囲付きコンテキストを除く)。これをfalse
に設定すると、そのコンテキスト内で作成された用語定義は、新しいノード・オブジェクトの入力時に削除されます。@protected
@reverse
@set
@type
@type
を用いてノード・オブジェクトと値オブジェクトの両方の型を定義することで、リテラル値や、より複雑な資源であっても、データの型付けに関する基本的なニーズに対応できます。専門家は、両方の目的のために@type
キーワードが過剰に用いられていることに気づくかもしれませんが、@type
を用いて型付きリテラル値を表す頻度ははるかに低いため、ウェブの開発者がこの機能を複数年にわたって用いても、誤用は生じていないことに注意すべきです。@value
@version
json-ld-1.0
に設定されている場合には使用できません。
@version
の文字列の値を受け入れることはできても、数値は拒否するため、コンテキスト定義内では@version
は"json-ld-1.1"
ではなく、1.1
という特定の値を取ります。@version
の値に1.1
を用いるのは、JSON-LD 1.0プロセッサの処理を停止させるのが目的です。これは明らかにJSON-LD 1.1に関するものですが、それ以外の点ではセマンティック・バージョニングの要件に準拠していません。@vocab
@type
のプロパティーと値を展開するために用います。このキーワードについては、§ 4.1.2 デフォルトの語彙で説明しています。JSON-LDのすべてのキー、キーワード、および値は、大文字と小文字を区別します。
非規範的と記している項と同じく、この仕様のすべての作成ガイドライン、図、例、注は、非規範的です。この仕様のその他の部分はすべて規範的です。
このドキュメントの「することができる/してもよい(MAY)」、「しなければならない(MUST)」、「してはならない(MUST NOT)」、「推奨される(RECOMMENDED)」、「すべきである/する必要がある(SHOULD)」、「すべきでない/する必要がない(SHOULD NOT)」というキーワードは、ここで示しているように、すべて大文字で表示されている場合にのみ、BCP 14[RFC2119] [RFC8174]で記述されているように解釈されるべきです。
JSON-LDドキュメントは、付録§ 9. JSON-LD文法の規範的なステートメントに従っていれば、この仕様に準拠しています。JSONドキュメントは、§ 6.1 JSONをJSON-LDとして解釈の規範的なステートメントに従うことで、JSON-LDとして解釈できます。便宜上、ドキュメントに関する規範的なステートメントは、多くの場合、ドキュメントのプロパティーのステートメントとして表されます。
この仕様では、次の名前空間接頭辞を用います。
接頭辞 | IRI |
---|---|
dc11 | http://purl.org/dc/elements/1.1/ |
dcterms | http://purl.org/dc/terms/ |
cred | https://w3id.org/credentials# |
foaf | http://xmlns.com/foaf/0.1/ |
geojson | https://purl.org/geojson/vocab# |
prov | http://www.w3.org/ns/prov# |
i18n | https://www.w3.org/ns/i18n# |
rdf | http://www.w3.org/1999/02/22-rdf-syntax-ns# |
schema | http://schema.org/ |
skos | http://www.w3.org/2004/02/skos/core# |
xsd | http://www.w3.org/2001/XMLSchema# |
これらは、このドキュメント内では、http://purl.org/dc/terms/title
を表すためのdcterms:title
など、結果のIRIの省略形としての短縮IRIの一部として用います。
この項は非規範的です。
JSON[RFC8259]は、軽く、言語に依存しないデータ交換フォーマットです。解析も生成も容易です。しかし、データに他のデータ情報源と競合するキーが含まれうるため、様々な情報源のJSONを統合することは困難です。さらに、JSONには、ウェブの基本的な構成要素であるハイパーリンクに対する組み込み済みのサポートがありません。この項の残りの部分で用いることになる例を見てみましょう。
{
"name": "Manu Sporny",
"homepage": "http://manu.sporny.org/",
"image": "http://manu.sporny.org/images/manu.png"
}
データが「Manu Sporny」というname
(名前)の人物に関するものであり、homepage
(ホームページ)というプロパティーにその人物のホームページのURLが含まれていることは、人間には明らかです。機械にはそのような直感的な理解はできず、人間にとっても、そのような表現のあいまいさを解決することは困難な場合があります。この問題は、「名前」、「ホームページ」などのトークンの代わりに、明確な識別子を用いて異なる概念を示すことで解決できます。
リンクト・データやウェブ全般では、明確な識別のためにIRI([RFC3987]で記述されているInternationalized Resource Identifier)を用います。IRIを用いて、他の開発者が用いる可能性のあるデータに明確な識別子を割り当てるという考え方です。name
やhomepage
などの用語は、開発者が互いの用語を誤って用いないように、IRIに展開しておくと有益です。さらに、開発者と機械はこのIRIを用いて用語に移動し(例えば、ウェブ・ブラウザーを用いて)、用語の意味の定義を取得できます。この処理は、IRIの逆参照として知られています。
よく知られているschema.orgの語彙を活用すると、上記の例は次のように明確に表現できます。
上記の例では、すべてのプロパティーはIRIによって明確に識別され、IRIを表すすべての値は@id
キーワードによって明記されています。これは、データに関して非常に具体的な、有効なJSON-LDドキュメントですが、ドキュメントがあまりにも冗長でもあり、人間の開発者にとっては扱い難いです。この課題に対処するため、JSON-LDは次の項で説明しているとおり、コンテキストという概念を導入しています。
この項では、JSON-LDの最も基本的な機能のみを扱っています。型付き値、インデックス付きの値、名前付きグラフなどのより高度な機能は、§ 4. 高度な概念にあります。
この項は非規範的です。
2人がコミュニケーションを取り合う場合、会話は「会話のコンテキスト」と通常呼ばれる共有環境で行われます。このコンテキストの共有により、共通の友人のファースト・ネームなど、省略形の用語を個々が用いて、正確さを失うことなく、より迅速にやり取りを行えます。JSON-LDのコンテキストもこれと同じように機能します。これにより、2つのアプリケーションが省略形の用語を用いて、正確さを失うことなく、より効率的にコミュニケーションを取り合えます。
シンプルに言えば、コンテキストは用語をIRIにマッピングするために用います。用語は大文字と小文字を区別し、予約済みのJSON-LDキーワードではない最も有効な文字列を用語として使用できます。例外は、空の文字列である""
と、キーワードの形式を持つ文字列(つまり、"@"
で始まり、1つ以上のALPHA文字([RFC5234]を参照)のみが続く文字列)で、これらを用語として用いてはなりません。IRIの形式を持つ文字列(":"
を含んでいるものなど)は、用語として用いるべきではありません。
前項のドキュメントの例の場合、コンテキストは次のようになります。
{ "@context": { "name": "http://schema.org/name", ↑ これは「name」が「http://schema.org/name」の省略形であることを意味します。 "image": { "@id": "http://schema.org/image", ↑ これは「image」が「http://schema.org/image」の省略形であることを意味します。 "@type": "@id" ↑ これは、「image」に関連付けられている文字列値が IRIである識別子として解釈されるべきであることを意味します。 }, "homepage": { "@id": "http://schema.org/url", ↑ これは、「homepage」が「http://schema.org/url」の省略形であることを意味します。 "@type": "@id" ↑ これは、「homepage」に関連付けられている文字列値が IRIである識別子として解釈されるべきであることを意味します。 } } }
上記のコンテキストが示しているように、用語定義の値は、用語をIRIにマッピングしているシンプルな文字列かマップのいずれかでありえます。
コンテキストは、@context
キーを持つエントリーを用いて導入され、ノード・オブジェクトまたは値オブジェクト内に出現できます。
用語キーを持つエントリーにマップの値がある場合、そのマップは展開用語定義と呼ばれます。上記の例では、image
(画像)とhomepage
(ホームページ)の値が文字列の場合、それらをIRIとして解釈すべきであると指定しています。展開用語定義により、用語をインデックス・マップに用いたり、配列の値を集合やリストとして解釈すべきかどうかを指定したりすることもできます。展開用語定義は、IRIや短縮IRIをキーとして用いて定義でき、これは主に型や言語の情報をIRIや短縮IRIに関連付けるために用います。
コンテキストは、ドキュメントに直接組み込むか(組み込みコンテキスト)、URLを用いて参照することができます。前の例のコンテキスト・ドキュメントをhttps://json-ld.org/contexts/person.jsonld
で取得できると仮定すると、1行追加すればそれを参照でき、以下の例で示しているように、JSON-LDドキュメントをより簡潔に表現できるようになります。
参照されているコンテキストは、Schema.org語彙で用語をIRIにどのようにマッピングするかを指定するだけでなく、homepage
とimage
のプロパティーに関連付けられている文字列の値がIRIとして解釈できることも指定しています("@type": "@id"
。詳細は§ 3.2 IRIを参照)。この情報により、開発者は、サイトごとにデータの相互運用方法について同意する必要なく、データを相互に再利用できます。外部のJSON-LDコンテキスト・ドキュメントには、ドキュメントで宣言されている用語に関するドキュメントなど、@context
キーの外部にある追加情報を含むことができます。ドキュメントが外部のJSON-LDコンテキスト・ドキュメントとして用いられていれば、@context
の値の外部で含まれている情報は無視されます。
遠隔のコンテキストは、相対URLを用いて参照することもでき、その参照を含んでいるドキュメントの位置に対して相対的に解決されます。例えば、ドキュメントがhttp://example.org/document.jsonld
にあり、context.jsonld
に対する相対参照が含まれている場合、参照されるコンテキスト・ドキュメントはhttp://example.org/context.jsonld
で相対的に見つかるでしょう。
{
"@context": "context.jsonld",
"name": "Manu Sporny",
"homepage": "http://manu.sporny.org/",
"image": "http://manu.sporny.org/images/manu.png"
}
コンテキストのURLに対する相対参照の解決は、それ自体に他のコンテキストへの参照が含まれている場合があるため、遠隔のコンテキスト・ドキュメントにも適用されます。
JSONドキュメントは、§ 6.1 JSONをJSON-LDとして解釈で説明しているように、HTTPリンク・ヘッダーを介してコンテキストを参照して変更する必要なく、JSON-LDとして解釈できます。また、JSON-LD 1.1 API[JSON-LD11-API]を用いてカスタマイズしたコンテキストを適用することもできます。
JSON-LDドキュメントでは、コンテキストをインラインで指定することもできます。これには、ウェブへの接続がない場合でもドキュメントを処理できるという利点があります。結局のところ、これはモデル化の判断であり、ユースケースが異なれば、異なる対応が必要になりえます。遠隔のコンテキストの使用に関する議論については、§ C. IANAに関する留意点のセキュリティに関する留意点を参照してください。
この項では、JSON-LDコンテキストの最も基本的な機能のみを扱っています。コンテキストを用いて、インデックス付きの値、順序付きの値、入れ子のプロパティーなど、他のより複雑なJSONデータ構造の解釈に役立てることもできます。JSON-LDコンテキストに関連するより高度な機能については、§ 4. 高度な概念で扱っています。
この項は非規範的です。
IRI(Internationalized Resource Identifiers[RFC3987])は、ほとんどのノードとプロパティーがこの方法で識別されるため、リンクト・データの基本です。JSON-LDでは、IRIはIRI参照として表すことができます。IRIは、スキームとともにパスやオプションのクエリとフラグメントのセグメントを含むと[RFC3987]で定義されています。相対IRI参照は、他のIRIに対して相対的なIRIです。JSON-LDでは、以下に示す例外を除いて、すべての相対IRI参照は基底IRIに対して相対的に解決されます。
§ 1.1 このドキュメントの読み方で述べたように、IRIはURL(Uniform Resource Locators)と混同されることがよくあります。主な違いは、URLはウェブ上の資源の位置を指定し(locate)、IRIは資源を識別する(identify)という点です。資源の識別子を逆参照可能にすることは良い習慣ですが、これが現実的でない場合もあります。特に、UUIDなどのURN(Uniform Resource Name)の[URN]スキームに注意してください。UUIDの例は、urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6
です。
プロパティー、@type
の値、および語彙マッピングに対して相対的であると定義している用語定義を持つプロパティーの値は、相対IRI参照の形式を取ることがありますが、基底IRIではなく語彙マッピングを用いて解決されます。
文字列は、@id
というキーを持つマップ・エントリーの値である場合、IRIとして解釈されます。
{ ... "homepage": { "@id": "http://example.com/" } ... }
IRIとして解釈される値は、相対IRI参照として表すこともできます。例えば、次のドキュメントがhttp://example.com/about/
にあると仮定すると、相対IRI参照../
は、http://example.com/
に展開されます(相対IRI参照を使用できる場所に関する詳細については、§ 9. JSON-LD文法を参照してください)。
{ ... "homepage": { "@id": "../" } ... }
IRIは、次のようにキーの位置で直接表すことができます。
{ ... "http://schema.org/name": "Manu Sporny", ... }
上記の例では、http://schema.org/name
というキーはIRIとして解釈されます。
用語からIRIへの展開は、キーがアクティブ・コンテキスト内で定義されている用語と一致する場合に発生します。
上記の例のstatus
など、IRIに展開されないJSONキーは、リンクト・データではないため、処理時に無視されます。
特定の用語やプロパティーのIRIに対して@context
で型の強制規則が指定されている場合は、IRIが生成されます。
上記の例では、http://manu.sporny.org/
という値はJSONの文字列として表されているため、データを処理する際に型の強制規則によって値がIRIに変換されます。この機能の詳細については、§ 4.2.3 型の強制を参照してください。
要約すると、JSON-LDではIRIを次の様々な方法で表現できます。
@id
または@type
を用いて指定された文字列の値に対して生成されます。@id
または@vocab
の値に設定されている@type
キーを含んでいる強制規則があるキーの文字列の値に対して生成されます。この項では、JSON-LDのIRIに関連する最も基本的な機能のみを扱っています。IRIに関するより高度な機能については、§ 4. 高度な概念の項で扱っています。
この項は非規範的です。
RDFグラフ内のノードを外部参照できるようにするには、ノードが識別子を持っていることが重要です。IRIは、リンクト・データの基本的な概念であり、ノードが真にリンク付けされるためには、識別子を逆参照すると、そのノードが表されるようになるべきです。これにより、アプリケーションはノードに関する詳細情報を取得できます。
JSON-LDでは、ノードは@id
キーワードを用いて識別されます。
上記の例には、http://me.markus-lanthaler.com/
というIRIによって識別されるノード・オブジェクトが含まれています。
この項では、JSON-LDのノード識別子に関連する最も基本的な機能のみを扱っています。ノード識別子に関するより高度な機能については、§ 4. 高度な概念で扱っています。
この項は非規範的です。
JSONには、構文として次の限られた数の構文要素しかありません。
true
とfalse
。リテラルのブール値です。null
。値がないことを記述します。JSON-LDデータ・モデルでは、RDFデータ・モデルに基づく、より豊かな資源の集合が可能です。データ・モデルについては、§ 8. データ・モデルでより完全に説明します。JSON-LDは、JSONオブジェクトを用いて、様々な資源を、その資源の間の関係性とともに記述します。
@list
キーの下でマップに配列をラップすることにより順序付きの値を表すために用います。集合オブジェクトは、統一性のために存在し、@set
キーの配列の値と同等です。詳細については、§ 4.3.1 リストと§ 4.3.2 集合を参照してください。@index
により、複数の値(ノード・オブジェクトまたは値オブジェクト)をインデックス化できます。詳細については、§ 4.6.1 データのインデックス化を、規範的な定義については、§ 9.9 インデックス・マップを参照してください。@id
により、複数のノード・オブジェクトをインデックス化できます。詳細については、§ 4.6.3 ノード識別子のインデックス化を、規範的な定義については、§ 9.11 idマップを参照してください。@type
により、複数のノード・オブジェクトをインデックス化できます。詳細については、§ 4.6.4 ノード型のインデックス化を、規範的な定義については、§ 9.12 型マップを参照してください。この項は非規範的です。
リンクト・データでは、グラフ・ノードの型を指定するのが一般的です。多くの場合、これは、特定のノード・オブジェクト内で用いられているプロパティーや、ノードが値であるプロパティーに基づいて推測できます。例えば、schema.org語彙では、givenName(名)プロパティーは、Person(人)に関連付けられます。したがって、ノード・オブジェクトにgivenNameというプロパティーが含まれていれば、型はPersonであると推論でき、@type
でこれを明示すると関連性が明確になります。
特定のノードの型は、@type
キーワードを用いて指定できます。リンクト・データでは、型はIRIで一意に識別されます。
配列を用いて、ノードに複数の型を割り当てることができます。
@type
キーの値は、アクティブ・コンテキストで定義される用語にすることもできます。
ノードの型の設定に加え、@type
を用いて値の型を設定し、型付き値を作成することもできます。この@type
の使用方法は、ノード・オブジェクトの型を定義するためのものと似ていますが、値オブジェクトは1つの型しか持てないように制限されています。@type
を用いた型付き値の作成については、§ 4.2.1 型付き値でより完全に論じています。
型付き値は、展開用語定義で@type
を指定することにより、暗黙的に定義することもできます。これについては、§ 4.2.3 型の強制でより完全に扱っています。
この項は非規範的です。
JSON-LDには、上記のコアな機能性を超える機能性を提供する機能が多数あります。JSONを用いると、このような構造を用いたデータを表現でき、この項で説明している機能を用いると、様々なJSON構造をリンクト・データとして解釈できます。JSON-LDプロセッサは、提供されたコンテキストと組み込まれたコンテキストを用いて、様々な慣用的な方法でプロパティー値を解釈します。
JSONにおける1つのパターンは、プロパティーの値を文字列にすることです。多くの場合、この文字列は、実際には、IRI、日付、特定の言語の文字列など、何らかの他の型付き値を表します。このような値の型を記述する方法に関する詳細については、§ 4.2 値の記述を参照してください。
JSONでは、配列の値を持つプロパティーは順序を暗示します。JSON-LDの配列は、組み込み構造を用いたり、コンテキスト定義により定義しない限り、デフォルトでは含まれている要素の順序を伝えません。詳細な議論については、§ 4.3 値の順序付けを参照してください。
APIでよく見られる別のJSONの慣用表現は、中間オブジェクトを用いてオブジェクトの関連プロパティーをグループ化するというものです。JSON-LDでは、これは入れ子のプロパティーと呼ばれ、§ 4.4 入れ子のプロパティーで説明しています。
リンクト・データとは、要するに様々な資源間の関係を記述することです。この関係は、ウェブ上の様々なドキュメントで定義されている資源間の場合もあれば、資源が同じドキュメント内で記述されている場合もあります。
このケースでは、http://manu.sporny.org/about
にあるドキュメントには、上記の例が含まれていて、同様の表現が含まれている可能性のあるhttps://greggkellogg.net/foaf
にある別のドキュメントを参照している可能性があります。
JSONの使用に見られる一般的な慣用表現は、JSON-LDでオブジェクトの組み込みと呼んでいる、他のオブジェクトの値として指定されているオブジェクトです。例えば、次のような、Person(人)のオブジェクト値として指定されている友人です。
これらの関係の詳細は、§ 4.5 組み込みを参照してください。
JSONのもう1つの一般的な慣用表現は、中間オブジェクトを用いて、インデックス化によりプロパティー値を表すことです。JSON-LDでは、§ 4.6 インデックス付きの値で詳述しているように、様々な方法でデータをインデックス化できます。
JSON-LDは有向グラフをシリアル化します。つまり、すべてのプロパティーは、あるノードから別のノードや値を指し示します。しかし、§ 4.8 逆プロパティーで詳述しているように、逆方向にシリアル化することが望ましい場合もあります。
以下の項では、そのような高度な機能についてより詳細に説明します。
この項は非規範的です。
§ 3.1 コンテキストの項では、JSON-LDが機能するための基本について紹介しました。この項では、コンテキストの基本原則を拡張し、JSON-LDを用いてより高度なユースケースを実現する方法を示します。
一般的に、コンテキストはマップが定義されていればいつでも使用できます。コンテキストを表現できないのは、(展開用語定義の一部としてではなく)別のコンテキスト定義の直接の子としてのみです。例えば、JSON-LDドキュメントは、1つ以上のノード・オブジェクトで構成される配列の形式を取ることができ、これは、それぞれの最上位のノード・オブジェクトでコンテキスト定義を用います。
外部の配列は、展開ドキュメント形式およびフラット化ドキュメント形式のドキュメントのための標準であり、ノードが相互参照を行えない、切断されたグラフを記述するときに必要になりえます。このようなケースでは、@graph
プロパティーを持つ最上位のマップを用いると、@context
の繰り返しを省くのに便利でありえます。詳細については、§ 4.5 組み込みを参照してください。
重複するコンテキストの用語は、最も直近に定義されたものが有効となるメカニズムを用いて上書きされます。
上記の例では、name
という用語は、独自の組み込みコンテキストを用いている、より深い入れ子のdetails
構造では上書きされます。これが良いオーサリング方法であることは稀であり、通常は、マップの特定の構造に依存する旧式アプリケーションを扱うときに用いられるものであることに注意してください。コンテキスト内で用語が再定義されると、以前の定義に関連付けられていた以前のすべての規則が削除されます。用語をnull
に再定義すると、アクティブ・コンテキストで定義されている用語のリストからその用語が効果的に削除されます。
複数のコンテキストは、配列を用いて組み合わせることができ、順番に処理されます。特定のマップ内で定義されているコンテキストの集合は、ローカル・コンテキストと呼ばれます。アクティブ・コンテキストとは、ドキュメント内の特定の位置で範囲内にあるローカル・コンテキストの蓄積を意味します。ローカル・コンテキストをnull
に設定すると、アクティブ・コンテキストが空のコンテキストへと効果的にリセットされ、用語定義、デフォルトの言語、または以前のコンテキスト内で定義されていたその他のものがなくなります。次の例では、外部コンテキストを指定した後に、その外部コンテキストの上に組み込みコンテキストをレイヤー状に配置しています。
JSON-LD 1.1には、範囲付きコンテキストやインポートされたコンテキストなど、コンテキストを導入する方法が他にもあり、用語定義の保護という新しい方法もあるため、最後に定義されたインラインのコンテキストが必ずしも用語の範囲を定義するものではない場合があります。詳細については、§ 4.1.8 範囲付きコンテキスト、§ 4.1.9 コンテキストの伝播、§ 4.1.10 インポートされたコンテキスト、§ 4.1.11 保護された用語定義を参照してください。
可能であれば、コンテキスト定義はJSON-LDドキュメントの最上部に置くべきです。それにより、ドキュメントが読みやすくなり、ストリーミング・パーサーの効率が上がります。最上部にコンテキストがないドキュメントも、適合JSON-LDです。
前方互換性の課題を回避するために、@
という文字で始まり、1つ以上のALPHA文字([RFC5234]を参照)のみが続く用語は、JSON-LDの将来のバージョンでキーワードとして用いられる可能性があるため、避けるべきです。JSON-LD 1.1のキーワードではない@
という文字で始まる用語は、その他の用語として扱われる、つまり、IRIにマッピングされていなければ無視されます。さらに、すべてのプログラミング言語が空のJSONキーを処理できるわけではないため、空の用語(""
)の使用は許されていません。
この項は非規範的です。
JSON-LD 1.1で定義している新機能は、処理モードがjson-ld-1.0
に設定されていない場合に使用できます。これは、APIのオプションにより設定できます。処理モードは、1.1
という数値の値として設定されたコンテキストで@version
エントリーを用いるか、APIのオプションによって明示的にjson-ld-1.1
に設定できます。処理モードを明示的にjson-ld-1.1
に設定することにより、JSON-LD 1.0プロセッサが誤ってJSON-LD 1.1ドキュメントを処理することが禁じられます。
{ "@context": { "@version": 1.1, ... }, ... }
@version
が含まれているドキュメントを処理する際に、APIのオプションで明示的に定義されていなければ、最初に遭遇したcontext
によってprocessing mode
(処理モード)が決まります。つまり、@version
のないコンテキストを処理した後に"@version": 1.1
に遭遇した場合、後者によって、その内部では"@version": 1.1
が定義されていたものと解釈されます。
JSON-LD 1.0プロセッサがJSON-LD 1.1ドキュメントを誤って処理して異なる結果を生成するのを防ぐために、処理モードを明示的にjson-ld-1.1
に設定することが推奨されます(RECOMMENDED)。
この項は非規範的です。
すべてのプロパティーと型が同じ語彙に由来する場合があります。JSON-LDの@vocab
キーワードにより、作成者は、語彙マッピングとして用いられ、用語に一致せず、IRIでも短縮IRIでもない(つまり、コロンを含まない)すべてのプロパティーと型に用いられる共通の接頭辞を設定できます。
@vocab
が用いられているけれども、マップ内の特定のキーを語彙IRIを用いて展開すべきではない場合は、コンテキスト内で用語を明示的にnullに設定できます。例えば、下記の例では、databaseId
エントリーはIRIに展開されず、展開時にプロパティーが削除されます。
JSON-LD 1.1以降は、ローカル・コンテキストの語彙マッピングは、アクティブ・コンテキストの語彙マッピングに連結された相対IRI参照に設定できます(アクティブ・コンテキストに語彙マッピングがない場合に、これがどのように適用されるかについては、§ 4.1.4 デフォルト語彙に対するドキュメントの基底の使用を参照してください)。
次の例は、相対IRI参照を用いてプロパティーを展開した場合の影響を示したもので、下記の展開形(結果)のタブで示しています。
§ 9.15 コンテキスト定義で定義している@vocab
の文法では、値を用語または短縮IRIにすることができます。@vocab
の値で用いられている用語は、コンテキストの導入時に範囲内になければならず、それ以外の場合は、@vocab
と同じコンテキストで定義されている他の用語との間に循環依存関係が存在するだろうということに注意してください。
この項は非規範的です。
JSON-LDにより、[RFC3986]の5.1項 基底URIの確立に従って、ドキュメントの基底に対して解決される相対形式でIRIを指定できます。基底IRIは、@base
キーワードを用いてコンテキストで明示的に設定できます。
例えば、JSON-LDドキュメントがhttp://example.com/document.jsonld
から取得された場合、相対IRI参照はそのIRIに対して解決されます。
{
"@context": {
"label": "http://www.w3.org/2000/01/rdf-schema#label"
},
"@id": "",
"label": "Just a simple document"
}
このドキュメントでは、ドキュメントの基底に対して解決される空の@id
を用います。しかし、ドキュメントが別の場所に移動すると、IRIは変わります。IRIを用いずにこれを防ぐためには、コンテキストで@base
マッピングを定義し、ドキュメントの基底IRIを上書きできます。
@base
をnullに設定すると、相対IRI参照がIRIに展開されるのを防ぐことができます。
@base
が外部コンテキストで用いられている場合には無視されることに注意してください。
この項は非規範的です。
語彙の用語は、外部の語彙ではなく、ドキュメント自体の中で直接定義される場合もあります。JSON-LD 1.1以降は、ローカル・コンテキストの語彙マッピングは、相対IRI参照に設定できます。つまり、範囲に語彙マッピングがなければ、基底IRIに対して解決されます。これにより、ノード・オブジェクトのキーなど、語彙に対して相対的に展開される用語が基底IRIに基づいてIRIを作成するようになります。
{ "@context": { "@version": 1.1, "@base": "http://example/document", "@vocab": "#" }, "@id": "http://example.org/places#BrewEats", "@type": "Restaurant", "name": "Brew Eats" ... }
このドキュメントがhttp://example/document
にあったとすれば、次のように展開されるでしょう。
この項は非規範的です。
短縮IRIは、コロン(:
)で区切られた接頭辞と接尾辞を用いてIRIを表す方法です。接頭辞は、アクティブ・コンテキストから取得した用語であり、JSON-LDドキュメント内の特定のIRIを識別する短い文字列です。例えば、foaf
という接頭辞は、http://xmlns.com/foaf/0.1/
というIRIを用いて識別される、FOAF(Friend-of-a-Friend)の語彙の省略形として使用できます。開発者は、任意のFOAF語彙用語を接頭辞の末尾に追加して、語彙用語に対するIRIの省略バージョンを指定できます。例えば、foaf:name
は、http://xmlns.com/foaf/0.1/name
というIRIに展開されます。
上記の例では、foaf:name
はhttp://xmlns.com/foaf/0.1/name
というIRIに展開され、foaf:Person
はhttp://xmlns.com/foaf/0.1/Person
に展開されます。
値の形式がprefix:suffix
の組み合わせとして表される短縮IRIであり、接頭辞がアクティブ・コンテキスト内で定義されている用語と一致し、接尾辞が2つのスラッシュ(//
)で始まっていなければ、接頭辞は展開されます。短縮IRIは、接頭辞にマッピングされているIRIを(空でありえる)接尾辞に連結することによって展開されます。接頭辞がアクティブ・コンテキストで定義されていない場合や、接尾辞が2つのスラッシュで始まる場合には(http://example.com
など)、値はIRIとして解釈されます。接頭辞が下線(_
)の場合には、値は空白ノード識別子として解釈されます。
次の例で示しているように、コンテキスト内で短縮IRIを用いることもできます。
JSON-LD 1.0互換用の処理モードで明示的に動作する場合、値がURI gen-delim文字(例えば、/
、#
など。[RFC3986]を参照)で終わるシンプルな用語定義が用いられている場合に限り、短縮時に用語を短縮IRI接頭辞として選択できます。
JSON-LD 1.1では、値がURI gen-delim文字で終わるシンプルな用語定義が用いられている場合、またはその展開用語定義に値がtrue
である@prefix
エントリーが含まれている場合に限り、展開時または短縮時に用語を短縮IRI接頭辞として選択できます。シンプルな用語定義がURI gen-delim文字で終わっていない場合や、展開用語定義に値がfalse
である@prefix
エントリーが含まれている場合は、用語は短縮IRIの展開や短縮IRIへのIRIの短縮には使用されないでしょう。
ここで報告しているJSON-LD 1.0の誤植の結果として、1.0プロセッサの用語選択の動作が変更されました。これは、既存のJSON-LDドキュメントの処理の動作には影響しませんが、短縮IRIを用いたドキュメントの短縮時にわずかな変化が生じます。
短縮時の動作は、次の入力ドキュメントを展開形式で考えることで例示できます。
[{
"http://example.com/vocab/property": [{"@value": "property"}],
"http://example.com/vocab/propertyOne": [{"@value": "propertyOne"}]
}]
property(プロパティー)に関連付けられているIRIが元のIRIをより多く捕捉する場合でも、1.0の処理モードで次のコンテキストを用いると、propertyではなくvocabという用語が選択されます。
{
"@context": {
"vocab": "http://example.com/vocab/",
"property": "http://example.com/vocab/property"
}
}
上記の展開された入力ドキュメントで前のコンテキストを用いて短縮すると、次の短縮結果になります。
元の[JSON-LD10]では、用語選択アルゴリズムによりpropertyが選択され、property:Oneという短縮IRIが作成されるでしょう。@prefix
を用いて、元の動作を明示することができます。
{
"@context": {
"@version": 1.1,
"vocab": "http://example.com/vocab/",
"property": {
"@id": "http://example.com/vocab/property",
"@prefix": true
}
}
}
このケースでは、propertyという用語は、展開用語定義で定義されていることと、その@id
がgen-delim文字で終わっていないことの両方の理由により、通常は接頭辞として使用できません。"@prefix": true
を追加することで、短縮IRIであるproperty:Oneの接頭辞部分として使用できるようになります。
この項は非規範的です。
@context
を除く個々のJSON-LDのキーワードは、アプリケーション固有のキーワードにエイリアシングできます。この機能により、旧式ドキュメントの既存のJSONキーを再利用することで、旧式JSONコンテンツをJSON-LDで利用できます。この機能により、開発者はJSON-LDのコンテキストのみを用いたドメイン固有の実装を設計することもできます。
上記の例では、@id
と@type
のキーワードにそれぞれurlとaというエイリアスが指定されています。
@type
の場合を除き、用語がキーワードである展開用語定義のプロパティーはエラーになります。処理モードがjson-ld-1.0
に設定されていない場合は、@type
には例外もあります。詳細と使用例については、§ 4.3.3 @type
とともに@set
を使用を参照してください。
処理モードがjson-ld-1.0
に設定されていない場合は、キーワードのエイリアスは、値がキーワードであるシンプルな用語定義か、@id
エントリーと、オプションで@protected
エントリーを持つ展開用語定義のいずれかで、その他のエントリーは許されていません。上記のように、@type
のエイリアスには例外もあります。@protected
の使用の詳細については、§ 4.1.11 保護された用語定義を参照してください。
キーワードは再定義できないため、他のキーワードのエイリアスにすることもできません。
エイリアシングされたキーワードは、コンテキスト自体の中では使用できません。
すべてのキーワードの規範的な定義については、§ 9.16 キーワードを参照してください。
この項は非規範的です。
一般的に、通常のIRIの展開規則は、IRIが予期される場所であればどこにでも適用されます(§ 3.2 IRIを参照)。コンテキスト定義内では、これは、循環依存関係がない限り、コンテキスト内で定義された用語はそのコンテキスト内でも使用できることを意味しえます。例えば、型付き値を定義する際には、xsd
名前空間を用いるのが一般的です。
{ "@context": { "xsd": "http://www.w3.org/2001/XMLSchema#", "name": "http://xmlns.com/foaf/0.1/name", "age": { "@id": "http://xmlns.com/foaf/0.1/age", "@type": "xsd:integer" }, "homepage": { "@id": "http://xmlns.com/foaf/0.1/homepage", "@type": "@id" } }, ... }
この例では、xsd
用語を定義しており、age
(年齢)プロパティーの@type
強制の接頭辞として用いています。
{ "@context": { "foaf": "http://xmlns.com/foaf/0.1/", "xsd": "http://www.w3.org/2001/XMLSchema#", "name": "foaf:name", "age": { "@id": "foaf:age", "@type": "xsd:integer" }, "homepage": { "@id": "foaf:homepage", "@type": "@id" } }, ... }
{ "@context": { "foaf": "http://xmlns.com/foaf/0.1/", "xsd": "http://www.w3.org/2001/XMLSchema#", "name": "foaf:name", "foaf:age": { "@id": "http://xmlns.com/foaf/0.1/age", "@type": "xsd:integer" }, "foaf:homepage": { "@type": "@id" } }, ... }
この例では、短縮IRIの形式を2つの異なる方法で用いています。最初のアプローチでは、foaf:age
は、(短縮形を用いた)用語のIRIと、用語に関連付けられた@type
の両方を宣言しています。2番目のアプローチでは、用語に関連付けられた@type
のみを指定しています。foaf:homepage
の完全なIRIは、コンテキスト内でfoaf
接頭辞を検索することによって決まります。
短縮IRIを用語として用いる場合は、展開した時に短縮IRIが自然と持つと考えられる値に展開されなければなりません。これは、用語が別のIRIに展開されて望ましくない結果になりえることを防ぐための元の1.0のアルゴリズムに対する変更点です。
{ "@context": { "foaf": "http://xmlns.com/foaf/0.1/", "xsd": "http://www.w3.org/2001/XMLSchema#", "name": "foaf:name", "foaf:age": { "@id": "http://xmlns.com/foaf/0.1/age", "@type": "xsd:integer" }, "foaf:homepage": { "@id": "http://schema.org/url", "@type": "@id" } }, ... }
{ "@context": { "foaf": "http://xmlns.com/foaf/0.1/", "xsd": "http://www.w3.org/2001/XMLSchema#", "name": "foaf:name", "foaf:age": { "@id": "http://xmlns.com/foaf/0.1/age", "@type": "xsd:integer" }, "http://xmlns.com/foaf/0.1/homepage": { "@type": "@id" } }, ... }
上記のIRIが一致するためには、JSON-LDドキュメントでIRIを用いる必要があります。また、foaf:homepage
はhttp://xmlns.com/foaf/0.1/homepage
と同じではないため、foaf:homepage
は{ "@type": "@id" }
という宣言を用いないことに注意してください。つまり、接頭辞の検索メカニズムが適用される前に、文字列を直接比較することによりコンテキスト内で用語が検索されます。
コンテキスト内で用語を用いる場合のその他の唯一の例外は、循環定義が許されないことです。つまり、term2がterm1に依存している場合は、term1の定義はterm2の定義に依存できません。例えば、次のコンテキスト定義は無効です。
{ "@context": { "term1": "term2:foo", "term2": "term1:bar" }, ... }
この項は非規範的です。
展開用語定義には@context
プロパティーを含めることができます。これは、その用語を用いて定義されたプロパティーの値のコンテキスト(範囲付きコンテキスト)を定義します。プロパティーに用いた場合、これはプロパティーの範囲付きコンテキストと呼ばれます。これにより、値は、値が含まれているノード・オブジェクトとは異なる用語定義、基底IRI、語彙マッピング、デフォルトの言語を、コンテキストが値自体の中で指定されているかのように使用できます。
このケースでは、ソーシャル・プロファイルはschema.org語彙を用いて定義していますが、関心(interest)はFOAFからインポートされています。そして、それを用いて、プロパティーがFOAF語彙に由来するようになったManuの関心の1つを表すノードを定義しています。
このドキュメントを展開すると、外部コンテキストで定義されている用語と、プロパティーの範囲付きコンテキスト内でその用語に対して特別に定義されている用語の組み合わせが用いられます。
範囲付けは、@type
の値として用いられる用語を用いて実行することもできます。
@type
での範囲付けは、異なる型のものを共通のプロパティーを用いて関連付ける場合に役立ち、その場合、異なるエンティティー内で用いられている語彙には、異なるコンテキストの範囲が必要です。例えば、hasPart
/partOf
はドキュメントで用いられる共通の用語でありえますが、コンテキストによって異なる意味になります。型の範囲付きコンテキストは、型が用いられているノード・オブジェクトに対してのみ有効です。以前の範囲内のコンテキストは、別のノード・オブジェクトにトラバースするときに再び有効になります。§ 4.1.9 コンテキストの伝播でさらに説明しているように、これは@propagate
キーワードを用いて制御できます。
ノード・オブジェクトに導入されていたプロパティーの範囲付きやローカル・コンテキストは、別のノード・オブジェクトへとトラバースする場合にも有効です。
展開時には、@type
の各値は、その値が独自の型の範囲付きコンテキストを持つアクティブ・コンテキスト内の用語でもある場合に考慮されます(辞書順に順序付け)。その場合には、その範囲付きコンテキストがアクティブ・コンテキストに適用されます。
@type
の値は順不同であるため、複数の型が列挙されている場合、型の範囲付きコンテキストが適用される順序は、辞書順です。
例えば、次のセマンティック的に同等な例について考えてみましょう。最初の例は、プロパティーと型が独自の範囲付きコンテキストを定義する方法を示しており、それは展開時に含まれます。
{
"@context": {
"@version": 1.1,
"@vocab": "http://example.com/vocab/",
"property": {
"@id": "http://example.com/vocab/property",
"@context": {
"term1": "http://example.com/vocab/term1"
↑ "property"の範囲付きコンテキストはterm1を定義します。
}
},
"Type1": {
"@id": "http://example.com/vocab/Type1",
"@context": {
"term3": "http://example.com/vocab/term3"
↑ "Type1"の範囲付きコンテキストはterm3を定義します。
}
},
"Type2": {
"@id": "http://example.com/vocab/Type2",
"@context": {
"term4": "http://example.com/vocab/term4"
↑ "Type2"の範囲付きコンテキストはterm4を定義します。
}
}
},
"property": {
"@context": {
"term2": "http://example.com/vocab/term2"
↑ 組み込みコンテキストはterm2を定義します。
},
"@type": ["Type2", "Type1"],
"term1": "a",
"term2": "b",
"term3": "c",
"term4": "d"
}
}
コンテキストは、その定義方法に応じて処理されます。プロパティーの範囲付きコンテキストが最初に処理され、次に組み込みコンテキスト、続いて最後に型の範囲付きコンテキストが、適切な順序で処理されます。前の例は、論理的に次の例と同等です。
{
"@context": {
"@vocab": "http://example.com/vocab/",
"property": "http://example.com/vocab/property",
"Type1": "http://example.com/vocab/Type1",
"Type2": "http://example.com/vocab/Type2"
},
"property": {
"@context": [{
"term1": "http://example.com/vocab/term1"
↑ 以前の"property"の範囲付きコンテキストは、term1を定義します。
}, {
"term2": "http://example.com/vocab/term2"
↑ 組み込みコンテキストはterm2を定義します。
}, {
"term3": "http://example.com/vocab/term3"
↑ 以前の"Type1"の範囲付きコンテキストはterm3を定義します。
}, {
"term4": "http://example.com/vocab/term4"
↑ 以前の"Type2"の範囲付きコンテキストはterm4を定義します。
}],
"@type": ["Type2", "Type1"],
"term1": "a",
"term2": "b",
"term3": "c",
"term4": "d"
}
}
用語が範囲付きコンテキストを定義していて、その用語が後で再定義された場合、以前の展開用語定義で定義されていたコンテキストの関連付けは、その再定義の範囲内では失われます。これは、§ 4.1 高度なコンテキストの使用で説明しているように、以前のあまり深く入れ子になっていなかった定義の以前の用語定義を上書きする用語の用語定義と整合性があります。
範囲付きコンテキストは、JSON-LD 1.1の新機能です。
この項は非規範的です。
一度導入したコンテキストは、型の範囲付きコンテキストを除き、@context
をnull
に設定したり用語を再定義したりすることにより、後続のコンテキストによって削除されるまで有効であり続け、次のノード・オブジェクトが入力されるまでそのコンテキストの効果を制限します。この動作は、@propagate
キーワードを用いて変更できます。
次の例では、@propagate
をfalse
に設定したコンテキストで定義されている用語が、新しいノード・オブジェクトへと伝わる際にどのように効果的に削除されるかを示しています。
JSON-LD 1.1処理アルゴリズムとAPIにおけるロールバックの定義方法のため、配列内に含まれるコンテキストはすべて@propagate
に対して同じ値を持っていなければなりません。
この項は非規範的です。
JSON-LD 1.0では、有効なコンテキストを変更するためのメカニズムを導入しました。これには、遠隔のコンテキストを読み込んで処理した後で、新しいコンテキストを介してそれに変更を追加適用する機能が含まれていました。
しかし、JSON-LD 1.1の導入にあたっては、遠隔のコンテキスト、特に既存のJSON-LD 1.0のコンテキスト、を読み込み、処理前にJSON-LD 1.1機能を適用できることも望まれます。
コンテキストで@import
キーワードを用いることにより、別の遠隔のコンテキスト(インポートされたコンテキストと呼ぶ)を処理前に読み込んで変更できます。変更点は、@import
キーワードが含まれているコンテキスト(ラッピング・コンテキストと呼ぶ)で表されます。インポートされたコンテキストが読み込まれると、処理前にラッピング・コンテキストの内容がそれに結合されます。結合の操作により、ラッピング・コンテキスト内の個々のキー-値のペアは、ラッピング・コンテキストのキー-値のペアを優先して、読み込まれてインポートされたコンテキストに追加されます。
既存のコンテキストを再利用し、処理前にインラインで編集できるようにすることにより、コンテキスト全体のキーワードを適用して、インポートされたコンテキストのすべての用語定義を調整することができます。同様に、処理前に用語定義を置き換えることができ、それによって、例えば、用語定義を以前保護されていた用語と一致させたり、追加の型強制の情報を含めるなどの調整が可能になります。
次の例は、他の同様の変更を加えるための技術として、@import
を用いてインポートされたコンテキストを読み込み、@propagate
をtrue
に設定する、型の範囲付きコンテキストを表す方法を示しています。
https://json-ld.org/contexts/remote-context.jsonld
というURLを介して遠隔で参照できる次のコンテキストがあったとします。
{
"@context": {
"Type1": "http://example.com/vocab/Type1",
"Type2": "http://example.com/vocab/Type2",
"term1": "http://example.com/vocab#term1",
"term2": "http://example.com/vocab#term2",
...
}
}
ラッピング・コンテキストを用いて、それを取得して変更できます。
{ "@context": { "@version": 1.1, "MyType": { "@id": "http://example.com/vocab#MyType", "@context": { "@version": 1.1, "@import": "https://json-ld.org/contexts/remote-context.jsonld", "@propagate": true } } } }
結果は、インポートされたコンテキスト全体が型の範囲付きコンテキストにコピーされた場合と同じです。
{
"@context": {
"@version": 1.1,
"MyType": {
"@id": "http://example.com/vocab#MyType",
"@context": {
"@version": 1.1,
"Type1": "http://example.com/vocab/Type1",
"Type2": "http://example.com/vocab/Type2",
"term1": "http://example.com/vocab#term1",
"term2": "http://example.com/vocab#term2",
...
"@propagate": true
}
}
}
}
同様に、ラッピング・コンテキストは、用語定義を置き換えたり、インポートされたコンテキスト用語定義の処理方法に影響を与える可能性がある他のコンテキスト全体のキーワードを設定したりすることができます。
{ "@context": { "@version": 1.1, "@import": "https://json-ld.org/contexts/remote-context.jsonld", "@vocab": "http://example.org/vocab#", ↑ これにより、処理前に以前の@vocab定義が置き換えられます。 "term1": { "@id": "http://example.org/vocab#term1", "@type": "http://www.w3.org/2001/XMLSchema#integer" } ↑ これにより、処理前に古いterm1の定義が置き換えられます。 } }
この場合も、インポートされたコンテキスト全体がコンテキストにコピーされた場合と同じ結果になります。
{ "@context": { "@version": 1.1, "Type1": "http://example.com/vocab/Type1", "Type2": "http://example.com/vocab/Type2", "term1": { "@id": "http://example.org/vocab#term1", "@type": "http://www.w3.org/2001/XMLSchema#integer" }, ↑ term1は処理前に置き換えられたことに注意してください。 "term2": "http://example.com/vocab#term2", ..., "@vocab": "http://example.org/vocab#" } }
インポートされたコンテキストを読み込んだ結果は、IRIや配列ではなく、コンテキスト定義でなければなりません。さらに、インポートされたコンテキストに@import
エントリーを含めることはできません。
この項は非規範的です。
JSON-LDは、多くの仕様で規定のデータ形式として用いられています。しかし、JSON-LDのアルゴリズムを用いずに、一部のJSON-LDコンテンツをプレーンなJSONとして処理したいという要望もあります。JSON-LDは非常に柔軟性が高いため、元の形式の一部の用語は、組み込みコンテキストを用いてローカルで上書きされ、JSON-LDベースの実装では異なる意味を持つことがあります。一方、「プレーンなJSON」の実装は、これらの組み込まれたコンテキストを解釈できない場合があり、したがって、これらの用語を元の意味で解釈します。この解釈の相違を防ぐために、JSON-LD 1.1では用語定義を保護することができます。
保護された用語の定義(protected term definition)は、@protected
エントリーをtrue
に設定した用語定義です。一般的に、同じ用語の新しい定義を用いるか、 "@context": null
でコンテキストを消去することにより、それ以上のコンテキストによってこの用語の定義が上書きされることを防止します。このような試みを行うと、エラーが発生し、処理が中止されます(下記で説明している特定の状況を除く)。
{
"@context": [
{
"@version": 1.1,
"Person": "http://xmlns.com/foaf/0.1/Person",
"knows": "http://xmlns.com/foaf/0.1/knows",
"name": {
"@id": "http://xmlns.com/foaf/0.1/name",
"@protected": true
}
},
{
– この試みはエラーで失敗します。
"name": "http://schema.org/name"
}
],
"@type": "Person",
"name": "Manu Sporny",
"knows": {
"@context": [
– この試みもエラーで失敗します。
null,
"http://schema.org/"
],
"name": "Gregg Kellogg"
}
}
コンテキストのすべてまたは大部分の用語定義を保護する必要がある場合は、@protected
エントリーをtrue
に設定してコンテキスト自体に追加することができます。これは、それぞれの用語定義を個別に保護するのと同じ効果があります。一部の用語定義で@protected
エントリーをfalse
に設定して追加することにより、例外とすることができます。
保護された用語は一般的に上書きできませんが、この規則には2つの例外があります。最初の例外は、新しい定義が、保護されている用語の定義と同じである場合には(@protected
フラグを法として)、コンテキストは保護された用語を再定義できるというものです。原理は、新しい定義は、保護された用語のセマンティクスを変更しないため、保護に違反しないというものです。これは、@type
からtype
へのエイリアシングなど、いくつかのコンテキストで(保護された形式を含む)発生しえる広範な用語定義に役立ちます。
2番目の例外は、プロパティーの範囲付きコンテキストは保護の影響を受けないため、新しい用語の定義を用いるか、"@context": null
でコンテキストを消去するかのいずれかによって、保護された用語を上書きできます。
原理は、特定の仕様に依存している「プレーンなJSON」実装は、その仕様で定義されているプロパティーのみをトラバースするということです。指定されたプロパティーに属する範囲付きコンテキストは仕様の一部であるため、「プレーンなJSON」の実装では、それによって生じるセマンティクスの変更を認識していることが期待されます。その他のプロパティーに属している範囲付きコンテキストは、「プレーンなJSON」の実装で無視されるドキュメントの一部に適用されます。したがって、いずれの場合でも、JSON-LDに対応している実装と「プレーンなJSON」の実装との間で解釈が異なるリスクがないため、上書きが許されます。
用語の上書きを防ぐことにり、保護によって用語の調節(例えば、より詳細なデータ型を定義する、用語の使用をリストに制限するなど)もできなくなります。この種の調節は、一部の汎用的なコンテキストで頻繁に発生するため、保護によってユーザビリティーが妨げられるでしょう。そのため、コンテキストの公開者はこの機能を注意して用いる必要があります。
保護された用語の定義は、JSON-LD 1.1の新機能です。
この項は非規範的です。
値は、文字列、日付、時刻、その他のアトミック値などのスカラー値に関連付けられたグラフのリーフ・ノード(leaf node)です。
この項は非規範的です。
型付き値としても知られる、型を関連付けられた値は、値を値の型を示すIRIに関連付けることによって示されます。JSON-LDでは、型付き値は次の3つの方法で表現できます。
最初の例では、@type
キーワードを用いて、@context
内の特定の用語に型を関連付けています。
上記のmodified(変更)キーの値は、情報が@context
で指定されているため、自動的にdateTime値として解釈されます。例のタブは、JSON-LDプロセッサがデータをどのように解釈するかを示しています。
2番目の例では、JSON-LDドキュメントの本文に型情報を設定する展開形式を用いています。
上記のどちらの例でも、http://www.w3.org/2001/XMLSchema#dateTime
という型を持つ2010-05-29T14:17:39+02:00
という値が生成されます。型の値を表すために、用語や短縮IRIを用いることもできることに注意してください。
展開時に、用語定義内で定義されている@type
を文字列の値に関連付けて、展開された値オブジェクトを作成できます。これについては、§ 4.2.3 型の強制で説明しています。型の強制は文字列の値に対してのみ行われ、展開形式のノード・オブジェクトや値オブジェクトなどのマップである値に対しては行われません。
ノード型は、人、場所、イベント、ウェブ・ページなどの記述されているものの型を規定します。値型は、整数、浮動小数点数、日付などの特定の値のデータ型を規定します。
{ ... "@id": "http://example.org/posts#TripToWestVirginia", "@type": "http://schema.org/BlogPosting", ← これはノード型です。 "http://purl.org/dc/terms/modified": { "@value": "2010-05-29T14:17:39+02:00", "@type": "http://www.w3.org/2001/XMLSchema#dateTime" ← これは値型です。 } ... }
最初の@type
の使用により、ノード型(http://schema.org/BlogPosting
)が@id
キーワードを用いて表されているノードに関連付けられます。2番目の@type
の使用により、値型(http://www.w3.org/2001/XMLSchema#dateTime
)が@value
キーワードを用いて表されている値に関連付けられます。原則として、@value
と@type
が同じマップ内で用いられている場合、@type
キーワードは値型を表します。それ以外の場合は、@type
キーワードはノード型を表します。上記の例は、次のデータを表します。
この項は非規範的です。
JSON-LDとして解釈されないJSON-LD内にJSONを含めると便利な場合があります。一般的に、JSON-LDプロセッサはIRIにマッピングされていないプロパティーを無視しますが、これにより、そのプロパティーは、様々なアルゴリズム変換の実行時に除外されます。しかし、記述されているデータ自体がJSONである場合は、アルゴリズム変換を切り抜けて存続することが重要です。
JSON-LDは、コンテキストを用いることにより、ネイティブなJSONを解釈できるようにすることを目指しています。JSONリテラルを用いると、解釈に使用できないデータのブロブ(blob)が作成されます。これは、JSONをJSON-LDとして表現できない稀なケースでのみ用います。
@type
を@json
に設定して用語を定義すると、JSON-LDプロセッサは値をJSON-LDとして解釈するのではなく、JSONリテラルとして扱います。展開ドキュメント形式では、このようなJSONは、"@type": "@json"
を持つ値オブジェクト内の@value
の値になるでしょう。
JSONリテラルは、RDFに変換すると、[JSON-LD11-API]の短縮アルゴリズムとJSONデータ型で記述されているとおり、JSONの特定のシリアル化に基づく字句形式になります。
次の例は、プロパティーの値として含まれているJSONリテラルの例を示しています。RDFの結果では、正規化形式のJSONを用いて、異なるプロセッサ間の相互運用性を確保していることに注意してください。JSONの正規化については、[JSON-LD11-API]のデータ・ラウンドトリップで説明しています。
この項は非規範的です。
JSON-LDは、特定のデータ型に対する文字列の値の強制をサポートしています。型の強制により、JSON-LDを展開している人が文字列のプロパティー値を用いて、IRIを展開された値オブジェクト表現の値に関連付けることにより、その値を型付き値として解釈させることができます。型の強制を用いると、個々のデータでデータ型を明示的に指定する必要なく、文字列の値の表現を使用できます。
型の強制は、@type
キーを用いて展開用語定義内で指定します。このキーの値はIRIに展開されます。または、@id
や@vocab
のキーワードを値として用いて、JSON-LDドキュメントの本文内で、@id
や@vocab
に強制された用語の文字列の値をIRIとして解釈することを示すこともできます。@id
と@vocab
の違いは、値がIRIに展開される方法です。@vocab
は、最初にそれを用語として解釈することによって値を展開しようとします。一致する用語がアクティブ・コンテキスト内で見つからなければ、値にコロンがある場合はIRIまたは短縮IRIとして展開しようとします。それ以外の場合は、アクティブ・コンテキストの語彙マッピングがあれば、それを用いて値を展開します。対照的に、@id
に強制された値は、コロンが存在する場合、IRIか短縮IRIとして展開されます。それ以外の場合は、相対IRI参照として解釈されます。
用語定義を用いて値を強制する性能は、ノード・オブジェクトに1つ以上の型を設定することとは異なります。これは、前者ではグラフに新しいデータが追加されませんが、後者はグラフに関係を追加することによりノード型を管理するためです。
@type
キーの値として用いられる用語や短縮IRIは、同じコンテキスト内で定義できます。つまり、xsd
のような用語を指定した後で、同じコンテキスト定義内でxsd:integer
を使用できます。
以下の例は、JSON-LDの作成者が値を型付き値とIRIに強制する方法を示しています。
用語は、マップ・エントリーのキーや値など、語彙に対して相対的な(vocabulary-relative)位置の展開でのみ用いられることに注意することが重要です。@id
の値はドキュメントに対して相対的(document-relative)であると見なされ、展開に用語定義を用いません。例えば、次について考えてみましょう。
予期しない結果として、「barney」は、どこで遭遇したかに応じてhttp://example1.com/barney
とhttp://example2.com/barney
の両方に展開されます。関連付けられている用語定義のためにIRIとして解釈される文字列の値は通常、ドキュメントに対して相対的であると見なされます。場合によっては、用語定義で"@type": "@vocab"
を用いて規定されているこれらを、語彙に対して相対的に解釈することは理にかなっていますが、このような予期せぬ結果を招く可能性があります。
前の例では、「barney」は2回登場します。1回は常にドキュメントに対して相対的なIRIとして解釈される@id
の値として登場し、もう1回は語彙に対して相対的であると定義されている「fred」の値(したがって、異なる展開値)として登場します。
これに関する詳細については、§ 4.1.2 デフォルトの語彙を参照してください。
@vocab
の代わりに"@type": "@id"
を用いている前の例のバリエーションは、ドキュメントに対して相対的に「barney」を解釈した場合の動作を示しています。
ex1:fred ex2:knows ex1:barney .
というトリプルが2回出力されますが、重複するトリプルであるため、出力データセットには1回だけ存在します。
用語は、IRIまたは短縮IRIを用いて定義することもできます。これにより、シンプルな用語として表されていないキーに強制規則を適用できます。例えば、次のとおりです。
このケースでは、用語定義内の@id
の定義はオプションです。これがある場合は、—接頭辞が定義されているか否かに関わらず—用語を表すIRIまたは短縮IRIは、常に@id
で定義されているIRIに展開されます。
型の強制は常に展開されていないキーの値を用いて実行されます。上記の例では、型の強制はアクティブ・コンテキスト内でfoaf:age
を探して行われるのであって、対応する展開されたhttp://xmlns.com/foaf/0.1/age
というIRIで行われるのではないことを意味します。
コンテキスト内のキーは、展開および値の強制を目的とした用語として扱われます。その結果、同じ展開済みのIRIに対して複数の表現がありえます。例えば、dog
(犬)とcat
(猫)の両方をhttp://example.com/vocab#animal
に展開するように指定することができます。これを行うことは、異なる型の強制や言語仕様の規則を確立するのに役立ちます。
この項は非規範的です。
文字列にその言語に関するアノテーションを付けることが重要な場合があります。JSON-LDでは、これは様々な方法で可能です。最初に、コンテキストで@language
キーを設定することにより、JSON-LDドキュメントのデフォルトの言語を定義できます。
上記の例では、ja
という言語タグを花澄と科学者の2つの文字列に関連付けています。言語タグは[BCP47]で定義されています。デフォルトの言語は、型の強制が行われていないすべての文字列の値に適用されます。
サブツリーのデフォルトの言語を消去するためには、次のとおり、範囲付きコンテキストなどの中間コンテキストで@language
をnull
に設定できます。
{ "@context": { ... "@version": 1.1, "@vocab": "http://example.com/", "@language": "ja", "details": { "@context": { "@language": null } } }, "name": "花澄", "details": {"occupation": "Ninja"} }
次に、展開用語定義を用いて、言語を特定の用語に関連付けることができます。
{ "@context": { ... "ex": "http://example.com/vocab/", "@language": "ja", "name": { "@id": "ex:name", "@language": null }, "occupation": { "@id": "ex:occupation" }, "occupation_en": { "@id": "ex:occupation", "@language": "en" }, "occupation_cs": { "@id": "ex:occupation", "@language": "cs" } }, "name": "Yagyū Muneyoshi", "occupation": "忍者", "occupation_en": "Ninja", "occupation_cs": "Nindža", ... }
上記の例では、忍者は指定されているデフォルトの言語タグであるja
に、Ninjaは言語タグen
に、Nindžaは言語タグcs
に関連付けられるでしょう。展開用語定義で@language
がnullにリセットされたため、name
(名前)の値であるYagyū Muneyoshiはどの言語タグにも関連付けられないでしょう。
上記の例のとおり、システムは複数の言語でプロパティーの値を表す必要がある場合が多いです。通常、このようなシステムでは、開発者が言語固有のデータのデータ構造をプログラムで簡単にナビゲートできるようにしようとします。この場合、言語マップを利用できます。
{ "@context": { ... "occupation": { "@id": "ex:occupation", "@container": "@language" } }, "name": "Yagyū Muneyoshi", "occupation": { "ja": "忍者", "en": "Ninja", "cs": "Nindža" } ... }
上記の例は、前の例とまったく同じ情報を表しますが、すべての値を1つのプロパティーに統合しています。オブジェクト・プロパティーに対してドット表記法アクセサをサポートするプログラミング言語において特定の言語の値にアクセスするために、開発者はproperty.language
のパターンを使用できます(言語が主要言語のサブタグに限定されており、"en-us"
などのその他のサブタグに依存していない場合)。例えば、英語で職業にアクセスするために、開発者はobj.occupation.en
というコード・スニペットを用いるでしょう。
3番目に、値オブジェクトを用いてデフォルトの言語を上書きすることができます。
{ "@context": { ... "@language": "ja" }, "name": "花澄", "occupation": { "@value": "Scientist", "@language": "en" } }
これにより、@language
タグを省略したり、値オブジェクトを用いて表現する際にnull
に設定したりして、プレーンな文字列を指定できます。
{ "@context": { ... "@language": "ja" }, "name": { "@value": "Frank" }, "occupation": { "@value": "Ninja", "@language": "en" }, "speciality": "手裏剣" }
マッピングされている値の言語設定を行うための言語マップを用いた記述については、§ 9.8 言語マップを参照してください。
この項は非規範的です。
文字列や言語タグ付き文字列に、その基本書字方向のアノテーションを付けることもできます。言語と同様に、コンテキストで@direction
キーを設定することにより、JSON-LDドキュメントのデフォルトの基本書字方向を定義できます。
上記の例では、ar-EG
という言語タグと「rtl」という基本書字方向がHTML و CSS: تصميم و إنشاء مواقع الويبとمكتبةという2つの文字列に関連付けられるでしょう。デフォルトの基本書字方向は、型の強制が行われていないすべての文字列の値に適用されます。
サブツリーでデフォルトの基本書字方向を消去するためには、次のとおり、範囲付きコンテキストなどの中間コンテキストで@direction
をnull
に設定できます。
{ "@context": { ... "@version": 1.1, "@vocab": "http://example.com/", "@language": "ar-EG", "@direction": "rtl", "details": { "@context": { "@direction": null } } }, "title": "HTML و CSS: تصميم و إنشاء مواقع الويب", "details": {"genre": "Technical Publication"} }
次に、展開用語定義を用いて、基本書字方向を特定の用語に関連付けることができます。
{ "@context": { ... "@version": 1.1, "@language": "ar-EG", "@direction": "rtl", "ex": "http://example.com/vocab/", "publisher": { "@id": "ex:publisher", "@direction": null }, "title": { "@id": "ex:title" }, "title_en": { "@id": "ex:title", "@language": "en", "@direction": "ltr" } }, "publisher": "مكتبة", "title": "HTML و CSS: تصميم و إنشاء مواقع الويب", "title_en": "HTML and CSS: Design and Build Websites", ... }
上記の例では、次の3つのプロパティーが作成されます。
主語 | プロパティー | 値 | 言語 | 方向 |
---|---|---|---|---|
_:b0 | http://example.com/vocab/publisher | مكتبة | ar-EG | |
_:b0 | http://example.com/vocab/title | HTML و CSS: تصميم و إنشاء مواقع الويب | ar-EG | rtl |
_:b0 | http://example.com/vocab/title | HTML and CSS: Design and Build Websites | en | ltr |
3番目に、値オブジェクトを用いてデフォルトの基本書字方向を上書きすることができます。
{ "@context": { ... "@language": "ar-EG", "@direction": "rtl" }, "title": "HTML و CSS: تصميم و إنشاء مواقع الويب", "author": { "@value": "Jon Duckett", "@language": "en", "@direction": null } }
基本書字方向のより深い議論については、ウェブ上の文字列: 言語と方向のメタデータ[string-meta]を参照してください。
この項は非規範的です。
JSON-LDの作成者は、配列を用いることにより、コンパクトな形で複数の値を表現できます。グラフにはノード間のリンクの順序は記述されないため、デフォルトでは、JSON-LD内の配列は含まれている要素の順序を伝えません。これは、デフォルトで順序付けされている通常のJSON配列とは正反対です。例えば、次のシンプルなドキュメントについて考えてみましょう。
複数の値は、展開形式を用いて表すこともできます。
上記の例は、ステートメントを生成しますが、それにも固有の順序はありません。
プロパティーの複数の値は通常同じ型ですが、JSON-LDではこれに制限はなく、プロパティーは様々な型の値を持つことができます。
ステートメントとして見た場合、値には固有の順序はありません。
この項は非規範的です。
順序付きコレクションという概念はデータ・モデル化においてかなり重要であるため、特定言語のサポートがあると有用です。JSON-LDでは、次のように、@list
キーワードを用いてリストを表すことができます。
これは、この配列の使用を順序付きとして記述しており、ドキュメントを処理する際に順序が維持されます。指定された複数の値のプロパティーが、いずれもリストを用いる場合は、コンテキストで@container
を@list
に設定することで簡略化できます。
RDFにおけるリストの実装は、「ステートメント」タブで示しているように、リストの末尾をrdf:nil
という資源として定義し、rdf:first
とrdf:rest
のプロパティーを用いて匿名ノードを互いにリンク付けすることに依存しています。これにより、順不同の一連のステートメント内で順序を表すことができます。
JSON-LDとTurtleはどちらも、順序付きリストを表すための省略形を提供しています。
JSON-LD 1.1は、リスト・オブジェクトの値自体がリスト・オブジェクトでありえる、リストのリストを完全にサポートしています。
"@container": "@list"
という定義は、リストの配列の値をそれ自体がリストであると再帰的に記述することに注意してください。例えば、GeoJSON形式([RFC7946]を参照)では、座標は位置の順序付きリストであり、2つ以上の数値の配列として表されます。
{
"type": "Feature",
"bbox": [-10.0, -10.0, 10.0, 10.0],
"geometry": {
"type": "Polygon",
"coordinates": [
[
[-10.0, -10.0],
[10.0, -10.0],
[10.0, 10.0],
[-10.0, -10.0]
]
]
}
//...
}
これらの例では、bboxと座標内で表されている値が順序を維持することが重要であり、組み込みリスト構造を用いる必要があります。JSON-LD 1.1では、適切なコンテキスト定義を追加するだけで、再帰リストを用いてこれを表現できます。
座標に3つのレベルのリストが含まれていることに注意してください。
@list
コンテナに関連付けられている用語の値は、1つの値しかない場合や値がまったくない場合でも、常に配列の形式で表されます。
この項は非規範的です。
@list
は順序付きリストの記述に用いますが、@set
キーワードは順不同の集合の記述に用います。JSON-LDドキュメントの本文における@set
の使用は、単なる糖衣構文であるため、ドキュメントの処理時に最適化によって削除されます。しかし、@set
はドキュメントのコンテキスト内で使用すると有用です。@set
コンテナに関連付けられている用語の値は、通常であれば短縮形式の配列でない形式に最適化される、値が1つしかない場合であっても、常に配列の形式で表されます(§ 5.2 短縮ドキュメント形式を参照)。これにより、配列に1つの値しか含まれていない場合でも、データは常に配列形式であるため、JSON-LDドキュメントの後処理が容易になります。
これは、この配列の使用は順不同であると記述しており、ドキュメントを処理する際に順序が変わる場合があります。値の配列は、デフォルトで順不同ですが、コンテキストで@container
を@set
に設定することでそれを明示できます。
JSON-LD 1.1以降、@set
キーワードは、展開用語定義内で他のコンテナ仕様と組み合わせ、同様に配列を用いてインデックスの短縮形の値を一貫して表すようにすることができます。詳細な議論については、§ 4.6 インデックス付きの値を参照してください。
@type
とともに@set
を使用この項は非規範的です。
処理モードがjson-ld-1.0
に設定されていない場合は、@container
を@set
に設定した展開用語定義内で@type
を使用できます。この展開用語定義内にその他のエントリーを設定することはできません。これは、@type
(またはエイリアス)の値を常に配列で表すために短縮アルゴリズムで用います。
{
"@context": {
"@version": 1.1,
"@type": {"@container": "@set"}
},
"@type": ["http:/example.org/type"]
}
この項は非規範的です。
多くのJSON APIは、中間オブジェクトを用いてプロパティーをエンティティーから分離します。JSON-LDでは、これを入れ子のプロパティーと呼びます。例えば、ラベルの集合を共通のプロパティー下でグループ化することができます。
@nest
キーワードを用いてlabels(ラベル)を定義すると、JSON-LDプロセッサは、labelsプロパティーを用いて作成された入れ子を無視し、含んでいるオブジェクト内でそれが直接宣言されているかのようにコンテンツを処理します。この場合、labelsプロパティーはセマンティック的に無意味です。それを@nest
と同等と定義すると、展開時に無視され、次と同等になります。
同様に、用語定義には、@nest
へとエイリアス化された用語を参照する@nest
プロパティーを含むことができ、それによって、そのプロパティーは短縮時にそのエイリアス化された用語下で入れ子になります。以下の例では、main_label
とother_label
の両方が"@nest": "labels"
で定義されており、これにより、短縮時にlabels
下でシリアル化されます。
[{ "@id": "http://example.org/myresource", "http://xmlns.com/foaf/0.1/homepage": [ {"@id": "http://example.org"} ], "http://www.w3.org/2004/02/skos/core#prefLabel": [ {"@value": "This is the main label for my resource"} ], "http://www.w3.org/2004/02/skos/core#altLabel": [ {"@value": "This is the other label"} ] }]
{ "@context": { "@version": 1.1, "skos": "http://www.w3.org/2004/02/skos/core#", "labels": "@nest", "main_label": {"@id": "skos:prefLabel", "@nest": "labels"}, "other_label": {"@id": "skos:altLabel", "@nest": "labels"}, "homepage": {"@id": "http://xmlns.com/foaf/0.1/homepage", "@type": "@id"} } }
入れ子のプロパティーは、JSON-LD 1.1の新機能です。
この項は非規範的です。
組み込みは、作成者がノード・オブジェクトをプロパティー値として使用できるようにするJSON-LDの機能です。これは、2つのノード間に親-子関係を作成するために一般的に用いられる方法です。
組み込みを行わくても、別のノード・オブジェクトの識別子を参照することによりノード・オブジェクトをリンクすることができます。例えば、次のとおりです。
前の例では、文字列の値を識別子として扱うためにknows
プロパティーを定義して、ManuとGreggの2つのノード・オブジェクトを記述しています。組み込みにより、Greggのノード・オブジェクトをknows
プロパティーの値として組み込むことができます。
上記で用いたようなノード・オブジェクトは、JSON-LDドキュメントの本文の任意の値の位置で使用できます。
グラフ内のノードを識別することがベスト・プラクティスであると考えられていますが、これが実用的でない場合もあります。データ・モデルでは、明示的な識別子のないノードを空白ノードと呼び、空白ノード識別子を用いてJSON-LDなどのシリアル化で表すことができます。前の例では、Manuの最上位ノードには識別子がなく、データ・モデル内でそれを記述する必要はありません。しかし、GreggからManuへのknows(知っている)という関係を記述したい場合は、空白ノード識別子(ここでは_:b0
)を導入する必要があるでしょう。
空白ノード識別子は、フラット化(flattening)などのアルゴリズムによって自動的に導入される場合がありますが、作成者がそのような関係を直接記述するのにも有用です。
この項は非規範的です。
IRIでノードを一意に識別できなくても情報を表現できる必要がある場合があります。この種のノードは、空白ノードと呼ばれます。JSON-LDでは、すべてのノードを@id
を用いて識別する必要はありません。しかし、一部のグラフのトポロジーでは、識別子をシリアル化できる必要があります。例えば、ループが含まれているグラフは、組み込みのみを用いてシリアル化することはできず、@id
を用いてノードを接続しなければなりません。これらの状況では、下線(_
)をスキームとして用いたIRIのように見える空白ノード識別子を使用できます。これにより、ドキュメント内でローカルにノードを参照できますが、外部ドキュメントからノードを参照することはできなくなります。空白ノード識別子は、それが用いられているドキュメントを範囲とします。
上記の例には、IRIで識別できない2つの秘密のエージェントに関する情報が含まれています。空白ノード識別子を用いなくてもagent 1がagent 2を知っていることを表すことはできますが、agent 2から参照できるように、agent 1に識別子を割り当てる必要があります。
処理中に空白ノード識別子を再びラベル付けできることは注目に値します。空白ノードを複数回参照することに開発者が気づいた場合は、他のドキュメントからも参照できるように、逆参照可能なIRIを用いてノードに名前を付けることを検討すべきです。
この項は非規範的です。
複数の配列の値を繰り返すのではなく、より直接的な方法で複数のプロパティー値にアクセスする必要がある場合があります。JSON-LDは、中間マップを用いて関連する値に特定のインデックスを関連付けられるようにするインデックス化のメカニズムを提供します。
JSON-LDでのインデックス化のその他の使用方法については、§ 4.9 名前付きグラフを参照してください。
この項は非規範的です。
データベースは通常、データへのアクセスをより効率化するために用います。開発者はこの種の機能をアプリケーション・データに拡張して、同様のパフォーマンス向上を実現することがよくあります。このデータはリンクト・データの観点からは意味がないかもしれませんが、アプリケーションには有用です。
JSON-LDでは、より効率的にアクセスできる形式にデータを構造化するために使用できるインデックス・マップという概念を導入しています。データのインデックス化機能により、作成者は、キーをIRIにマッピングしないシンプルなキー-値マップを用いてデータを構造化できます。これにより、特定のアイテムを探すために配列をスキャンする必要なく、データに直接アクセスできるようになります。JSON-LDでは、このようなデータは、コンテキスト内で@index
キーワードを@container
宣言に関連付けることで指定できます。
上記の例では、athletes(アスリート)という用語がインデックス・マップとして記述されています。catcher(キャッチャー)とpitcher(ピッチャー)のキーは、JSON-LDプロセッサによって、セマンティック的には無視されますが、構文的には保持されます。これをJavaScriptで用いると、開発者はobj.athletes.pitcher
というコード・スニペットを用いて特定のアスリートにアクセスできるようになります。
データの解釈は、ステートメントの表で示しています。インデックスのキーがステートメントに表示されないことに注意が必要ですが、JSON-LDプロセッサを用いてドキュメントが短縮または展開される場合は(§ 5.2 短縮ドキュメント形式と§ 5.1 展開ドキュメント形式を参照)、存在し続けるでしょう。
RDFへのラウンドトリップ時にはデータのインデックスは保持されないため、この機能は慎重に用いるべきです。多くの場合、保持される、他のインデックス化方法のほうがより適切です。
@container
の値は、@index
と@set
の両方が含まれている配列にすることもできます。これにより、短縮時にJSON-LDプロセッサがインデックスのすべての値に対して確実に配列形式を用いるようになります。
処理モードがjson-ld-1.0
に設定されていない場合は、@none
という特別なインデックスは、インデックスが関連付けられていないデータをインデックス化するために用いられ、正規化表現を維持するのに便利です。
この項は非規範的です。
(上記の例のように)最もシンプルな形式では、データのインデックス化によってインデックス・マップのキーにセマンティクスは割り当てられません。しかし、オブジェクトのインデックス化に用いられるキーがそのオブジェクトにセマンティック的にリンクされていて、構文的にだけでなくセマンティック的にも保持すべきである場合もあります。
処理モードがjson-ld-1.0
に設定されていない場合は、用語の記述の"@container": "@index"
に"@index"
キーを付けることができます。そのキーの値は、各オブジェクトをそのキーにリンクしているセマンティックなプロパティーを識別するIRIにマッピングしなければなりません。
プロパティー・ベースのデータのインデックス化を用いる場合、インデックス・マップはノード・オブジェクトでのみ使用でき、値オブジェクトやグラフ・オブジェクトでは使用できません。値オブジェクトは特定のキーのみを持つように制限されており、任意のプロパティーをサポートしていません。
この項は非規範的です。
複数の言語の文字列の値が含まれているJSONは、言語タグによってプロパティー値を容易にインデックス化できるように、言語マップを用いて表すことができます。これにより、特定のアイテムを探すために配列をスキャンする必要なく、言語の値に直接アクセスできるようになります。JSON-LDでは、このようなデータは、コンテキスト内で@language
キーワードを@container
宣言に関連付けることで指定できます。
上記の例では、label(ラベル)という用語が言語マップとして記述されています。enとdeのキーは、JSON-LDプロセッサによってそれぞれの値に暗黙的に関連付けられます。これにより、開発者はobj.label.de
というコード・スニペットを用いてドイツ語版のラベルにアクセスでき、これも、言語が主要言語のサブタグに限定されており、その他の"de-at"
などのサブタグに依存しない場合にのみ適切です。
@container
の値は、@language
と@set
の両方が含まれている配列にすることもできます。これにより、短縮時にJSON-LDプロセッサが言語タグのすべての値に対して確実に配列形式を用いるようになります。
処理モードがjson-ld-1.0
に設定されていない場合は、@none
という特別なインデックスは、言語のない文字列をインデックス化するために用いられます。これは、データ型のない文字列の値の正規化表現を維持するのに便利です。
この項は非規範的です。
JSON-LDでは、インデックス・マップに加えて、データを構造化するためのidマップという概念を導入しています。IDのインデックス化機能により、作成者は、キーをIRIにマッピングしたシンプルなキー-値マップを用いてデータを構造化できます。これにより、特定のアイテムを探すために配列をスキャンする必要なく、関連付けられているノード・オブジェクトに直接アクセスできるようになります。JSON-LDでは、このようなデータは、コンテキスト内で@id
キーワードを@container
宣言に関連付けることで指定できます。
上記の例では、post
(投稿)という用語がidマップとして記述されています。http://example.com/posts/1/en
とhttp://example.com/posts/1/de
のキーは、ノード・オブジェクトの値の@id
プロパティーとして解釈されるでしょう。
上記のデータの解釈は、JSON-LDプロセッサを用いた§ 4.6.1 データのインデックス化とまったく同じです。
@container
の値は、@id
と@set
の両方が含まれている配列にすることもできます。これにより、短縮時にJSON-LDプロセッサがノード識別子のすべての値に対して確実に配列形式を用いるようになります。
@none
という特別なインデックスは、@id
のないノード・オブジェクトをインデックス化するために用いられ、正規化表現を維持するのに便利です。@none
というインデックスは、以下の例で用いているnoneという用語のように、@none
に展開される用語にすることもできます。
idマップは、JSON-LD 1.1の新機能です。
この項は非規範的です。
JSON-LDでは、idマップとインデックス・マップに加えて、データを構造化するための型マップという概念を導入しています。型のインデックス化機能により、作成者は、キーをIRIにマッピングしたシンプルなキー-値マップを用いてデータを構造化できます。これにより、特定のノード・オブジェクトの@type
に基づいてデータを構造化できます。JSON-LDでは、このようなデータは、コンテキスト内で@type
キーワードを@container
宣言に関連付けることで指定できます。
上記の例では、affiliation
(提携)という用語が型マップとして記述されています。schema:Corporation
とschema:ProfessionalService
のキーは、ノード・オブジェクトの値の@type
プロパティーとして解釈されるでしょう。
@container
の値は、@type
と@set
の両方が含まれている配列にすることもできます。これにより、短縮時にJSON-LDプロセッサが型のすべての値に対して確実に配列形式を用いるようになります。
@none
という特別なインデックスは、@type
のないノード・オブジェクトをインデックス化するために用いられ、正規化表現を維持するのに便利です。@none
というインデックスは、以下の例で用いているnoneという用語のように、@none
に展開される用語にすることもできます。
idマップと同様に、@type
と一緒に用いると、@set
コンテナにを含めて、キーの値が常に確実に配列に含まれるようにすることができます。
型マップは、JSON-LD 1.1の新機能です。
この項は非規範的です。
ノード・オブジェクトを別のノード・オブジェクトの一部として記載すると便利な場合があります。例えば、他の資源によって用いられている資源の集合を表すために。包含ブロックは、一次ノード・オブジェクトから参照できるそのような二次ノード・オブジェクトをまとめるためにも使用できます。例として、様々なアイテムのリストが含まれていて、その一部が共通要素を共有しているノード・オブジェクトについて考えてみましょう。
{
"@context": {
"@version": 1.1,
"@vocab": "http://example.org/",
"classification": {"@type": "@vocab"}
},
"@id": "http://example.org/org-1",
"members": [{
"@id":"http://example.org/person-1",
"name": "Manu Sporny",
"classification": "employee"
}, {
"@id":"http://example.org/person-2",
"name": "Dave Longley",
"classification": "employee"
}, {
"@id": "http://example.org/person-3",
"name": "Gregg Kellogg",
"classification": "contractor"
}],
"@included": [{
"@id": "http://example.org/employee",
"label": "An Employee"
}, {
"@id": "http://example.org/contractor",
"label": "A Contractor"
}]
}
これにより、フラット化時にemployee
(従業員)とcontractor
(請負人)の要素は、包含ブロックから外部の配列へと移動します。
包含される資源については、一部の一次資源に関連付けられている関連資源を含める方法として、JSON API[JSON.API]の関連資源の包含で説明されています。@included
は、JSON-LDでそれに似た可能性を提供します。
ノード・オブジェクト内での@included
の使用の副産物として、マップに@included
のみを含むことができ、§ 4.1 高度なコンテキストの使用で説明しているものと同様の機能を提供します。その場合、@graph
は切断されたノードを記述するために用います。
しかし、@graph
とは対照的に、@included
は同じマップ内に含まれる他のプロパティーとは相互作用を行いません。この機能については、§ 4.9 名前付きグラフで詳細に論じています。
この項は非規範的です。
JSON-LDは有向グラフをシリアル化します。つまり、すべてのプロパティーは、あるノードから別のノードや値を指し示します。しかし、逆方向にシリアル化することが望ましい場合もあります。例えば、ある人とその子供がドキュメントに記述されているべきケースについて考えてみましょう。用いている語彙で子供のプロパティーではなく親のプロパティーのみが提供されている場合、次の例のように、子供を表すすべてのノードを、親を指し示すプロパティーを用いて表さなければなりません。
JSON-LDの@reverse
キーワードを用いると、このようなデータをよりシンプルに表現できます。
この項は非規範的です。
単なる1つのノードでなく、グラフそのものに関するステートメントを作成する必要がある場合があります。これは、@graph
キーワードを用いてノードの集合をグループ化することで行えます。次の例で示しているように、開発者は、@graph
キーワードを用いて表されているデータを@id
キーワードとペアにすることで、それに名前を付けることもできます。
上記の例は、http://example.org/foaf-graph
というIRIによって識別される名前付きグラフを表しています。そのグラフは、ManuとGreggに関するステートメントで構成されています。グラフそのものに関するメタデータは、グラフがいつ生成されたかを指定するgeneratedAt
プロパティーにより表されています。
JSON-LDドキュメントの最上位構造が、@graph
キーのみ(およびオプションで@context
)を含むマップである場合(IRIまたはキーワードにマッピングされていないプロパティーは無視される)、@graph
は、通常であれば暗黙的であるデフォルト・グラフを表していると見なされます。このメカニズムは、同じコンテキストを共有するノードがドキュメントの最上位に多数存在する場合、例えば、ドキュメントがフラット化されている場合に有用です。@graph
キーワードは、そのようなノードを配列にまとめ、共有コンテキストの使用を可能にします。
このケースでは、グラフには関係付けられていないノードが含まれているため、組み込みは使用できません。これは、配列で複数のノード・オブジェクトを用い、個々のノード・オブジェクト内で@context
を定義することと同等です。
この項は非規範的です。
JSON表現内で明示せずにデータを論理的に個別のグラフに分離すると便利な場合もあります。例えば、JSONドキュメントには、他のメタデータが言明されているデータを含むことができますが、@graph
キーワードに関連付けられている構文オーバーヘッドなしに、名前付きグラフの概念を用いてデータ・モデル内でこのデータを分離すると便利です。
展開用語定義では、@graph
を@container
の値として使用できます。これは、この用語の値を名前付きグラフと見なすべきであることを示しており、そのグラフ名は、暗黙的な名前付きグラフを作成する自動的に割り当てられた空白ノード識別子です。展開した時に、これはシンプルなグラフ・オブジェクトになります。
別の例では、次のように、匿名の名前付きグラフを用いています。
上記の例は、ステートメントを作成する匿名の名前付きグラフを表します。デフォルト・グラフには、主語がそのステートメントを書いたと述べるステートメントが含まれています。これは、複数のステートメントを名前付きグラフに分離し、その名前付きグラフに含まれているステートメントについて言明を行う例です。
グラフ・コンテナは、JSON-LD 1.1の新機能です。
この項は非規範的です。
インデックスによるノード・オブジェクトのインデックス化に加えて、グラフ・オブジェクトもインデックスによってインデックス化できます。@index
に加えて§ 4.9.1 グラフ・コンテナで紹介した@graph
コンテナ型を用いることにより、そのようなプロパティーのオブジェクト値は、キーがIRIにマッピングされていないけれども、その値である名前付きグラフに関連付けられた@index
プロパティーから取得されるキー-値マップとして扱われます。これは、展開した時にシンプルなグラフ・オブジェクトでなければなりません。
次の例では、インデックス・マップを用いて複数の名前付きグラフを参照するデフォルト・グラフについて説明します。
インデックス・マップと同様に、@graph
と一緒に用いると、@set
をコンテナに含めて、キーの値が常に確実に配列に含まれるようにすることができます。
@none
という特別なインデックスは、@index
キーのないグラフをインデックス化するために用いられ、正規化表現を維持するのに便利です。しかし、@none
インデックスを用いて複数の識別子のない名前付きグラフが短縮されているドキュメントを短縮すると、それらのグラフの内容が統合されることに注意してください。これを防ぐには、個々のグラフに別個の@index
キーを指定します。
名前付きグラフ・データのインデックス化は、JSON-LD 1.1の新機能です。
この項は非規範的です。
識別子によるノード・オブジェクトのインデックス化に加えて、グラフ・オブジェクトもそのグラフ名によってインデックス化できます。@id
に加えて§ 4.9.1 グラフ・コンテナで紹介した@graph
コンテナ型を用いることにより、そのようなプロパティーのオブジェクト値は、キーがその値である名前付きグラフの識別子を表すキー-値マップとして扱われます。
次の例では、idマップを用いて複数の名前付きグラフを参照するデフォルト・グラフについて説明します。
idマップと同様に、@graph
と一緒に用いると、@set
をコンテナに含めて、キーの値が常に確実に配列に含まれるようにすることができます。
idマップと同様に、@none
という特別なインデックスは、@id
のない名前付きグラフをインデックス化するために用いられ、正規化表現を維持するのに便利です。@none
というインデックスは、@none
に展開される用語にすることもできます。しかし、複数のグラフが@id
なしに表されている場合、それらは展開時に統合されることに注意してください。これを防ぐには、@none
を慎重に用いて、グラフに独自の識別子を付けることを検討してください。
グラフ・コンテナは、JSON-LD 1.1の新機能です。
この項は非規範的です。
JSON-LD 1.1処理アルゴリズムとAPI仕様[JSON-LD11-API]は、JSON-LDプロセッサに対するインターフェースについて定義しており、様々な形式のJSON-LDを操作するための方法が多く含まれています(§ 5. JSON-LDの形式を参照)。これには、参照されているJSON-LDドキュメントと遠隔のコンテキストを含む、遠隔のドキュメントを読み込むためのメカニズムと、潜在的に[HTML]などの他の形式から組み込まれているJSON-LDを抽出するための一般的なメカニズムが含まれます。これについては、[JSON-LD11-API]の遠隔のドキュメントとコンテキストの取得でより完全に説明しています。
documentLoaderは、遠隔のドキュメントの読み込みが問題となりえるいくつかのコンテキストで便利でありえます。
この項は非規範的です。
多くのデータ形式と同様に、JSON-LDでデータを正しく記述する方法は1つではありません。しかし、JSON-LDはグラフを記述するために用いられるため、リンクト・データとしての意味を変更せずに、特定の変換によってデータの形を変更できます。
@context
が不要となるようにコンテキストを適用する処理です。この処理については、§ 5.1 展開ドキュメント形式で詳細に説明しています。この項は非規範的です。
JSON-LD 1.1処理アルゴリズムとAPI仕様[JSON-LD11-API]は、JSON-LDドキュメントを展開する方法を定義しています。展開とは、JSON-LDドキュメントを取得し、すべてのIRI、型、値が展開されるようにコンテキストを適用し、@context
が不要となるようにする処理です。
例えば、次のJSON-LD入力ドキュメントを想定してみましょう。
{
"@context": {
"name": "http://xmlns.com/foaf/0.1/name",
"homepage": {
"@id": "http://xmlns.com/foaf/0.1/homepage",
"@type": "@id"
}
},
"name": "Manu Sporny",
"homepage": "http://manu.sporny.org/"
}
上記のJSON-LD入力ドキュメントに対してJSON-LD展開アルゴリズムを実行した結果は、次の出力になるでしょう。
JSON-LDのメディア・タイプは、展開ドキュメント形式を通知またはリクエストするために使用できるprofile
パラメータを定義します。展開ドキュメント形式を識別するプロファイルURIはhttp://www.w3.org/ns/json-ld#expanded
です。
この項は非規範的です。
JSON-LD 1.1処理アルゴリズムとAPI仕様[JSON-LD11-API]は、JSON-LDドキュメントを短縮する方法を定義しています。短縮とは、開発者が提供するコンテキストを適用し、IRIを用語や短縮IRIに短縮したり、展開形式で表現されているJSON-LD値を文字列や数値などのシンプルな値に短縮したりする処理です。多くの場合、データはアプリケーション固有の用語で表されるため、ドキュメントの操作がよりシンプルになります。短縮されたドキュメントは、通常、人間にとっても読みやすくなります。
例えば、次のJSON-LD入力ドキュメントを想定してみましょう。
[
{
"http://xmlns.com/foaf/0.1/name": [ "Manu Sporny" ],
"http://xmlns.com/foaf/0.1/homepage": [
{
"@id": "http://manu.sporny.org/"
}
]
}
]
さらに、開発者が提供する次のJSON-LDコンテキストを想定してみましょう。
{
"@context": {
"name": "http://xmlns.com/foaf/0.1/name",
"homepage": {
"@id": "http://xmlns.com/foaf/0.1/homepage",
"@type": "@id"
}
}
}
上記のJSON-LD入力ドキュメントに対して上記で提供されたコンテキストを指定してJSON-LD短縮アルゴリズムを実行すると、次の出力が生成されるでしょう。
JSON-LDのメディア・タイプは、短縮ドキュメント形式を通知またはリクエストするために使用できるprofile
パラメータを定義します。短縮ドキュメント形式を識別するプロファイルURIはhttp://www.w3.org/ns/json-ld#compacted
です。
短縮の詳細は、[JSON-LD11-API]の短縮アルゴリズムで説明されています。この項では、JSON-LDドキュメントの短縮に用いるコンテキストを作成する作成者へのガイドとして、アルゴリズムがどのように動作するかを簡潔に説明します。
短縮の目的は、既存のJSON-LDドキュメントに用語定義、語彙マッピング、デフォルト言語、基底IRIを適用し、JSON-LDドキュメントの使用に合った形式で直接JSONとして表せるようにすることです。これには、可能な場合は、値を値オブジェクトではなく文字列として表すこと、リスト・オブジェクトの使用をシンプルな配列に短縮すること、ノード間の関係を逆にすること、複数の値を値の配列として表す代わりにデータ・マップを用いてインデックス化することが含まれます。
この項は非規範的です。
展開されたJSON-LDドキュメントでは、IRIは常に絶対IRIとして表されます。多くの場合、相対IRI参照、短縮IRI、用語のいずれかのより短いバージョンを用いることをお勧めします。短縮では、コンテキスト内の要素の組み合わせを用いて、これらのIRIの短縮形が作成されます。詳細については、§ 4.1.2 デフォルトの語彙、§ 4.1.3 基底IRI、および§ 4.1.5 短縮IRIを参照してください。
語彙マッピングは、語彙マッピングと一致するIRI接頭辞を削除することにより、語彙に対して相対的でありえるIRIを短縮するために使用できます。これは、IRIが語彙に対して相対的であると判断される場合、つまり、プロパティー、@type
の値、または"@type": "@vocab"
として記述された用語の値として用いられる場合に必ず行われます。
この項は非規範的です。
明確化のために、展開ドキュメント形式は常にノード・オブジェクトと値オブジェクトを用いてノードと値を表します。さらに、プロパティー値は、値が1つしかない場合でも、常に配列内に含まれます。これはアクセスの統一性を維持するのに有用な場合がありますが、ほとんどのJSONデータは可能な限りシンプルな表現を用います。つまり、プロパティーは1つの値を持ち、文字列、またはノード・オブジェクトなどの構造化された値として表されます。デフォルトでは、短縮はシンプルな文字列である値を文字列として表しますが、値はIRI、日付、またはシンプルな文字列表現では情報が失われるその他の型付き値である場合があります。これを用語定義内で指定することにより、プロパティーとして用いられている用語の定義から文字列の値のセマンティクスを推測できます。詳細については、§ 4.2 値の記述を参照してください。
この項は非規範的です。
§ 4.3.1 リストで説明しているように、JSON-LDには、@list
キーワードを用いた、順序付きの値を表すための展開構文があります。JSON-LDの表現を簡略化するために、用語を"@container": "@list"
で定義でき、それにより、この用語を用いているプロパティーのすべての値は順序付きであると見なされます。
この項は非規範的です。
例えば、2人の人と、共通する1人の親との関係を記述する場合など、ノードに逆方向があると、2つのノードを関連付けるためのプロパティーをより適切に表現できる場合があります。詳細については、§ 4.8 逆プロパティーを参照してください。
逆プロパティーは、フレーム化と組み合わせるとさらに便利で、それにより、実際にノード・オブジェクトをドキュメントの最上位で定義して、組み込みノードにすることができます。JSON-LDは、用語定義内で適切な@container定義を定義することにより、そのような値をインデックス化する手段を提供します。
この項は非規範的です。
複数の値を持つプロパティーは通常、順不同の配列を用いて表されます。つまり、そのJSONの内部化された表現を扱うアプリケーションは、en
という言語を用いた言語タグ付き文字列などの、特定のパターンに一致する値を見つけるために、配列の値を順に処理する必要があります。
データは、@id、@type、@language、@indexなどを含む、様々なキーでインデックス化できます。詳細については、§ 4.6 インデックス付きの値および§ 4.9 名前付きグラフを参照してください。
この項は非規範的です。
ドキュメントを短縮すると便利な場合がありますが、ノード・オブジェクトと値オブジェクトの表現は保持してください。このために、用語定義で"@type": "@none"
と設定できます。これにより、値の短縮のアルゴリズムは常に値のオブジェクト形式を用いるようになりますが、その値の要素は短縮できます。
この項は非規範的です。
一般的に、短縮時には、値が1つしかないプロパティーは文字列またはマップとして表され、複数の値を持つプロパティーは文字列またはマップの配列として表されます。つまり、このようなプロパティーにアクセスするアプリケーションは、どちらの表現も受け入れられるようにしておく必要があります。配列を用いて強制的にすべての値を表すためには、用語定義で"@container": "@set"
と設定できます。さらに、@set
は他のコンテナ設定と組み合わせて使用できます。例えば、§ 5.2.5 値のインデックス化の言語マップの例を見てください。
この項は非規範的です。
短縮時に、短縮アルゴリズムは、そのプロパティーの値がその用語定義の@container
、@type
、および@language
の仕様と一致する場合にのみ、プロパティーの用語を用いて短縮します。これにより、すべて同じIRIを持つ異なるプロパティー間で値を実際に分割することができます。一致する用語定義がない場合は、短縮アルゴリズムは、プロパティーの絶対IRIを用いて短縮を行います。
この項は非規範的です。
JSON-LD 1.1処理アルゴリズムとAPI仕様[JSON-LD11-API]は、JSON-LDドキュメントをフラット化する方法を定義しています。フラット化は、1つのマップ内のノードのすべてのプロパティーをまとめ、すべての空白ノードを空白ノード識別子でラベル付けします。これにより、データの形が確保され、特定のアプリケーションでJSON-LDを処理するために必要なコードを大幅に簡略化できます。
例えば、次のJSON-LD入力ドキュメントを想定してみましょう。
{
"@context": {
"name": "http://xmlns.com/foaf/0.1/name",
"knows": "http://xmlns.com/foaf/0.1/knows"
},
"@id": "http://me.markus-lanthaler.com/",
"name": "Markus Lanthaler",
"knows": [
{
"@id": "http://manu.sporny.org/about#manu",
"name": "Manu Sporny"
}, {
"name": "Dave Longley"
}
]
}
上記の例のJSON-LD入力ドキュメントに対してJSON-LDのフラット化アルゴリズムを実行し、同じコンテキストを用いると、次の出力が生成されます。
JSON-LDのメディア・タイプは、フラット化ドキュメント形式を通知またはリクエストするために使用できるprofile
パラメータを定義します。フラット化ドキュメント形式を識別するプロファイルURIはhttp://www.w3.org/ns/json-ld#flattened
です。これは、展開ドキュメント形式または短縮ドキュメント形式を識別するプロファイルURIと組み合わせることができます。
この項は非規範的です。
JSON-LD 1.1フレーム化仕様[JSON-LD11-FRAMING]は、JSON-LDドキュメントをフレーム化する方法を定義しています。フレーム化は、JSON-LDドキュメントのデータを整形するために用います。これには、フラット化されたデータを一致させるためと、結果として得られるデータをどのように整形すべきかの例を示すための両方に用いられるフレーム・ドキュメントの例を用います。
例えば、次のJSON-LDフレームを想定してみましょう。
{
"@context": {
"@version": 1.1,
"@vocab": "http://example.org/"
},
"@type": "Library",
"contains": {
"@type": "Book",
"contains": {
"@type": "Chapter"
}
}
}
このフレーム・ドキュメントは、Library(図書館)という型を持つオブジェクトを最上部に配置し、プロパティー値として組み込まれたcontains(含む)プロパティーを用いてそのLibraryオブジェクトにリンク付けられたBook(図書)という型のオブジェクトを用いた、組み込み構造を記述しています。また、参照しているBookオブジェクト内にChapter(章)という型のオブジェクトをBookオブジェクトの組み込み値として配置しています。
フレーム要素と一致するフラット化されたオブジェクトの集合を用いる場合は、次の通りです。
{
"@context": {
"@vocab": "http://example.org/",
"contains": {"@type": "@id"}
},
"@graph": [{
"@id": "http://example.org/library",
"@type": "Library",
"contains": "http://example.org/library/the-republic"
}, {
"@id": "http://example.org/library/the-republic",
"@type": "Book",
"creator": "Plato",
"title": "The Republic",
"contains": "http://example.org/library/the-republic#introduction"
}, {
"@id": "http://example.org/library/the-republic#introduction",
"@type": "Chapter",
"description": "An introductory chapter on The Republic.",
"title": "The Introduction"
}]
}
フレーム・アルゴリズムは、フレームの構造に従った新しいドキュメントを作成できます。
JSON-LDのメディア・タイプは、フレーム化ドキュメント形式を通知またはリクエストするために使用できるprofile
パラメータを定義します。フレーム化ドキュメント形式を識別するプロファイルURIはhttp://www.w3.org/ns/json-ld#framed
です。
JSON-LDのメディア・タイプは、フレームが含まれているHTMLドキュメント内のスクリプト要素を識別するために使用できるprofile
パラメータも定義しています。application/ld+json;profile=http://www.w3.org/ns/json-ld#frame
という型の最初のスクリプト要素がフレームの検索に用いられるでしょう。
HTTPリンク・ヘッダー[RFC8288]を用いてJSON-LD処理の特定部分を変更することができます。これは、それ自体はJSON-LDではないけれども、リンク関係内の情報を用いてJSON-LDとして解釈できる資源を取得するときに使用できます。
通常のJSONドキュメントを処理する場合、§ 6.1 JSONをJSON-LDとして解釈で説明しているように、遠隔のドキュメントを取得した時に返されるHTTPリンク・ヘッダーを用いてリンク関係を指定できます。
それ以外のケースとしては、資源がJSON-LDとして容易に解釈できない表現を用いて返される場合があります。通常、HTTP内容交渉は、クライアントが別の表現よりもJSON-LDのプレファレンスを優先して指定できるようにするために用いますが、特定の状況では、サーバーがそのようなリクエストに適切に応答することは不可能であったり現実的ではなかったりします。このために、HTTPリンク・ヘッダーを用いて、§ 6.2 代替ドキュメントの位置で説明しているように、元々リクエストされた資源の代わりに用いられる代替のドキュメントの位置を提供できます。
通常のJSONドキュメントは、明示的なJSON-LDのコンテキスト・ドキュメントを提供することにより、JSON-LDとして解釈できます。これを提供する方法の1つは、HTTPリンク・ヘッダーでJSON-LDのコンテキスト・ドキュメントを参照することです。そうすることで、開発者がドキュメントを大幅に変更する必要なく、JSONを明確に機械可読にすることができ、application/json
というメディア・タイプや[RFC6839]で定義されている+json
という接尾辞を持つメディア・タイプに依存している既存のクライアントを壊すことなく、既存のインフラストラクチャ用のアップグレード方法を提供できます。
通常のJSONドキュメントで外部コンテキストを用いるためには、HTTPを介して通常のJSONドキュメントを取得する際に、プロセッサは、下記のリンク・ヘッダーで参照されるJSON-LDドキュメントの取得を試みなければなりません(MUST)。
rel="http://www.w3.org/ns/json-ld#context"
、およびtype="application/ld+json"
。参照されるドキュメントには、最上位のJSONオブジェクトがなければなりません(MUST)。そのオブジェクト内の@context
エントリーは、参照しているドキュメントの最上位のJSONオブジェクトに追加されます。参照しているドキュメントの最上位にあるのが配列であり、そのアイテムがJSONオブジェクトである場合、@context
サブツリーがすべての配列アイテムに追加されます。参照されているドキュメントの@context
サブツリーの外部にあるすべての追加情報は破棄しなければなりません(MUST)。これは事実上、アクティブ・コンテキストが、参照されている外部のコンテキストで初期化されることを意味します。応答には、http://www.w3.org/ns/json-ld#context
のリンク関係を用いて複数のHTTPリンク・ヘッダーを含めてはなりません(MUST NOT)。
JSON-LDコンテキストを提供するためのその他のメカニズムを、他のURIスキームに対して記述することができます(MAY)。
JSON-LD 1.1処理アルゴリズムとAPI仕様[JSON-LD11-API]は、JSONドキュメントをプログラムで展開するときに用いるコンテキストを指定するためのexpandContextというオプションを提供しています。
次の例は、HTTP上の通常のJSONドキュメントでの外部コンテキストの使用を示しています。
GET /ordinary-json-document.json HTTP/1.1 Host: example.com Accept: application/ld+json,application/json,*/*;q=0.1 ==================================== HTTP/1.1 200 OK ... Content-Type: application/json Link: <https://json-ld.org/contexts/person.jsonld>; rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json" { "name": "Markus Lanthaler", "homepage": "http://www.markus-lanthaler.com/", "image": "http://twitter.com/account/profile_image/markuslanthaler" }
application/ld+json
というメディア・タイプで提供されるJSON-LDドキュメントには、ドキュメントの本文内に、外部コンテキストへの参照を含むすべてのコンテキスト情報がなければならない(MUST)ことに注意してください。このようなドキュメントでは、http://www.w3.org/ns/json-ld#context
というHTTPリンク・ヘッダーを介してリンクされたコンテキストを無視しなければなりません(MUST)。
JSON-LDとして直接解釈できないドキュメントは、JSON-LDが含まれている代替の位置を提供できます。これを提供する方法の1つは、HTTPリンク・ヘッダーでJSON-LDドキュメントを参照することです。これは、例えば、名前空間に関連付けられているURLにはHTMLドキュメントが当然含まれているけれども、そのURLに関連付けられているJSON-LDコンテキストは別の場所にある場合に役立つことがあります。
代替の位置を指定するために、JSONではない資源(つまり、application/json
や派生物以外のメディア・タイプを用いている資源)は、次のリンク・ヘッダーを用いて代替の位置を返すことができます。
rel="alternate"
、およびtype="application/ld+json"
。応答には、type="application/ld+json"
のalternate
リンク関係を用いて複数のHTTPリンク・ヘッダーを含めてはなりません(MUST NOT )。
代替の位置を提供するためのその他のメカニズムを、他のURIスキームに対して記述できます(MAY)。
次の例は、HTTPを介した通常のHTTPドキュメントでの代替の位置の使用を示しています。
GET /index.html HTTP/1.1 Host: example.com Accept: application/ld+json,application/json,*/*;q=0.1 ==================================== HTTP/1.1 200 OK ... Content-Type: text/html Link: <alternate.jsonld>; rel="alternate"; type="application/ld+json" <html> <head> <title>Primary Entrypoint</title> </head> <body> <p>This is the primary entrypoint for a vocabulary</p> </body> </html>
プロセッサは、JSONではない結果に気づくと、リンク・ヘッダーの存在に注目し、代わりにそのドキュメントを読み込むでしょう。
この項では、HTMLスクリプト抽出をサポートしているdocumentLoaderで利用できる機能について説明しています。詳細については、遠隔のドキュメントとコンテキストの取得を参照してください。
JSON-LDコンテンツは、type
属性をapplication/ld+json
に設定してスクリプト要素に置くことにより、HTML[HTML]に容易に組み込むことができます。これにより、データ・ブロックが作成されます。
このようなデータの使用方法の定義は、この仕様の範囲を超えるものです。組み込まれているJSON-LDドキュメントはそのまま抽出されたり、例えば、RDFとして解釈されたりする可能性があります。
JSON-LDコンテンツがRDF[RDF11-CONCEPTS]として抽出される場合は、JSON-LDからRDFへの逆シリアル化アルゴリズム[JSON-LD11-API]を用いて、RDFデータセットに展開しなければなりません(MUST)。特定のスクリプトが対象でない場合は(§ 7.3 特定のJSON-LDスクリプト要素の位置指定を参照)、application/ld+json
というtype
(型)を持つすべてのスクリプト要素を処理し、同等の空白ノード識別子を別のスクリプト要素に含み、それらが1つのドキュメント内にあるかのように扱って、1つのデータセットに統合しなければなりません(MUST)(つまり、空白ノードが様々なJSON-LDスクリプト要素間で共有される)。
base
要素からの基底IRIの継承JSON-LDのスクリプト要素を処理する際に、[HTML]で定義されているように、含まれているHTMLドキュメントのドキュメントの基底URLを用いて、囲まれているJSON-LDコンテンツのデフォルトの基底IRIが確立されます。
HTMLでは、基底URLに対する動的な変更が許されています。この仕様では特定の動作を要求せず、すべてのシステムが基底IRIを同等に処理することを保証するために、作成者は、IRIを用いるか§ 4.1.3 基底IRIの定義のとおりに明示すべきです(SHOULD)。実装(特に[DOM]でネイティブに動作するもの)では、基底URLに対する動的な変更を考慮することができます(MAY)。
script
要素のコンテンツに対する制限この項は非規範的です。
HTMLの<script>
要素のコンテンツに対する制限により、スクリプト要素に含まれるJSON-LDデータにエンコーディングの制限が追加適用されます。
作成者は、コメントの開始(comment-open)、スクリプトの開始(script-open)、コメントの終了(comment-close)、スクリプトの終了(script-close)と混同される可能性がある文字列を、HTMLに組み込まれたスクリプトで用いることを避けるべきです。
&
→ & (アンパサンド、U+0026)<
→ < (不等号(より小)、U+003C)>
→ > (不等号(より大)、U+003E)"
→ " (引用符、U+0022)'
→ ' (アポストロフィ、U+0027)HTMLドキュメント内の特定のスクリプト要素の位置は、URLで指定されるHTMLドキュメント内のスクリプト要素の一意の識別子と一致するフラグメント識別子を用いて指定できます([DOM]を参照)。JSON-LDプロセッサは、指定されたデータ・ブロックの内容のみを抽出し、それを独立したJSON-LDドキュメントとして解析しなければならず(MUST)、その結果を同じHTMLドキュメントからの他のマークアップと統合してはなりません(MUST)。
例えば、http://example.com/document
にあるHTMLドキュメントを想定した場合、「dave」で識別されるスクリプト要素は、http://example.com/document#dave
というURLを用いて対象にすることができます。
JSON-LDは、JSONに基づくリンクト・データのシリアル化形式です。したがって、[RFC8259]のJSONで定義されている構文と、RDFデータ・モデル[RDF11-CONCEPTS]の拡張であるデータ・モデルを区別することが重要です。JSON-LDとRDFデータ・モデルがどのように関係しているかに関する正確な詳細は、§ 10. RDFとの関係で説明しています。
RDFモデルに慣れていない開発者が理解しやすいように、次のとおり、要約を提供します。
#
などのドキュメントに対して相対的なIRIの使用を検討してください。{
"@id": "http://example.org/1"
}
@id
のみが含まれている入れ子でないノード・オブジェクトを事実上禁止しているだけです。1つ以上のプロパティーが定義されているか、ノードが別のノード・オブジェクトから参照されている限り、ドキュメントは、関係付けのないノードを持つことができます。_:
で始まります。xsd:string
という型の型付き値として解釈される)、数値(0でない小数部を持つ数値、つまり、モジュロ‑1演算の結果、または整数として表すには大きすぎるもの([JSON-LD11-API]のデータ・ラウンドトリップを参照)は、xsd:double
という型を持つ型付き値として解釈され、その他のすべての数値は、xsd:integer
という型を持つ型付き値として解釈される)、true
かfalse
(xsd:boolean
という型の型付き値として解釈される)、または言語タグ付き文字列です。JSON-LDドキュメントには、上記で定義したデータ・モデルでは表現できないデータを含むことができます(MAY)。特に明記されていない限り、このようなデータは、JSON-LDドキュメントの処理中に無視されます。この規則の1つの結果として、IRI、空白ノード、またはキーワードにマップされていないプロパティーは無視されます。
さらに、JSONのシリアル化形式は、リスト、マップ、文字列、数値、ブール、およびnullの一般的な概念を用いてJSONドキュメントで表されるデータを記述する、JSON-LD内部表現を用いて内部的に表されます。
この図で説明しているデータセットは、次のように表すことができます。
最も外側のレベルで@graph
を用いて、3つの最上位の資源(そのうちの2つは名前付きグラフ)を記述していることに注意してください。名前付きグラフは、@id
に加えて@graph
を用いて、グラフごとに名前を提供します。
この項では、前の項で説明した構文規則をより形式的に説明します。
[RFC8259]で記述されているように、JSON-LDドキュメントは有効なJSONテキストであるか、有効なJSONテキストと同等のJSON-LD内部表現で表現できる形式でなければなりません(MUST)。
JSON-LDドキュメントは、1つのノード・オブジェクト、@context
および/または@graph
というエントリーのみで構成されるマップ、または0以上のノード・オブジェクトの配列でなければなりません(MUST)。
JSONとは対照的に、JSON-LDでは、オブジェクト内のキーは一意でなければなりません(MUST)。
この文法でキーワードについて論じられている場合は常に、その言説はそのキーワードのエイリアスにも適用されます。
JSON-LDでは、キーワードをエイリアシングすることができます(詳細については、§ 4.1.6 キーワードのエイリアシングを参照)。例えば、アクティブ・コンテキストが@id
という用語を@id
のエイリアスとして定義している場合、そのエイリアスを@id
の代わりとして正当に使用できます。キーワードのエイリアスはコンテキストの処理中には展開されないことに注意してください。
用語は、IRI、空白ノード識別子、またはキーワードに展開される短縮形の文字列です。
用語は、@type
を除き、JSON-LDのキーワードと同じであってはなりません(MUST NOT)。
用語は、短縮IRIで接頭辞として用いる場合は、IRIスキームと混同される接頭辞の潜在的な曖昧さを回避するために、[IANA-URI-SCHEMES]で定義されているURIスキームのリストから取得すべきではありません(SHOULD NOT)。同様に、短縮IRIと用語の間の混同を避けるために、用語にはコロン(:
)を含めるべきではなく(SHOULD NOT)、[RFC3987]で定義されているisegment-nz-nc
の形式に制限すべきです(SHOULD)。
JSON-LDの将来のバージョンで追加のキーワードが導入される可能性があるため、前方互換性の問題を回避するために、用語は、1つ以上のALPHA文字([RFC5234]を参照)のみが後続する@
という文字で始まるべきではありません(SHOULD NOT)。さらに、すべてのプログラミング言語が空のJSONキーを処理できるわけではないため、用語は空の文字列(""
)であってはなりません(MUST NOT)。
IRIへの用語のマッピングに関する詳細な議論ついては、§ 3.1 コンテキストと§ 3.2 IRIを参照してください。
ノード・オブジェクトは、JSON-LDドキュメントによってシリアル化されたグラフ内のノードの0以上のプロパティーを表します。マップは、JSON-LDコンテキストの外部に存在し、かつ次の場合、ノード・オブジェクトです。
@graph
と@context
のみのエントリーで構成されるJSON-LDドキュメントの最上部のマップではない。@value
、@list
、@set
@setキーワードが含まれていない。グラフ内のノードのプロパティーは、ドキュメント内の様々なノード・オブジェクトに分散させることができます。その際には、様々なノード・オブジェクトのキーを統合して、その結果のノードのプロパティーを作成する必要があります。
ノード・オブジェクトはマップでなければなりません(MUST)。IRI、短縮IRI、アクティブ・コンテキストで有効な用語、または下記のキーワード(または、そのようなキーワードのエイリアス)のうちの1つではないすべてのキーは、処理時に無視しなければなりません(MUST)。
@context
、@id
、@included
、@graph
、@nest
、@type
、@reverse
、または@index
ノード・オブジェクトに@context
キーが含まれている場合、その値はnull、IRI参照、コンテキスト定義、またはこれらのいずれかで構成される配列でなければなりません(MUST)。
ノード・オブジェクトに@id
キーが含まれている場合、その値はIRI参照または短縮IRI(空白ノード識別子を含む)でなければなりません(MUST)。@id
という値に関する詳細な議論については、§ 3.3 ノード識別子、§ 4.1.5 短縮IRI、および§ 4.5.1 空白ノードの識別を参照してください。
ノード・オブジェクトに@graph
キーが含まれている場合、その値はノード・オブジェクトまたは0以上のノード・オブジェクトの配列でなければなりません(MUST)。ノード・オブジェクトに@id
キーワードも含まれている場合、その値は名前付きグラフのグラフ名として用いられています。@graph
という値に関する詳細な議論については、§ 4.9 名前付きグラフを参照してください。特殊なケースとして、マップに@graph
と@context
以外のキーが含まれておらず、マップがJSON-LDドキュメントのルートである場合、マップはノード・オブジェクトとして扱われません。これは、接続されたグラフを形成しないノード・オブジェクトを定義する方法として用います。これにより、構成するすべてのノード・オブジェクトで共有されるコンテキストを定義できます。
ノード・オブジェクトに@type
キーが含まれている場合、その値はIRI参照、短縮IRI(空白ノード識別子を含む)、IRIに展開するアクティブ・コンテキストで定義された用語、またはこれらのいずれかの配列でなければなりません(MUST)。@type
という値に関する詳細な議論については、§ 3.5 型の指定を参照してください。
ノード・オブジェクトに@reverse
キーが含まれている場合、その値は逆プロパティーを表すエントリーが含まれているマップでなければなりません(MUST)。そのような逆プロパティーの個々の値は、IRI参照、短縮IRI、空白ノード識別子、ノード・オブジェクト、またはこれらの組み合わせが含まれている配列でなければなりません(MUST)
ノード・オブジェクトに@included
キーが含まれている場合、その値は包含ブロックでなければなりません(MUST)。包含ブロックに関する詳細な議論については、§ 9.13 包含ブロックを参照してください。
ノード・オブジェクトに@index
キーが含まれている場合、その値は文字列でなければなりません(MUST)。@index
という値に関する詳細な議論については、§ 4.6.1 データのインデックス化を参照してください。
ノード・オブジェクトに@nest
キーが含まれている場合、その値はマップまたはマップの配列でなければならず(MUST)、値オブジェクトを含んではなりません(MUST NOT)。@nest
という値に関する詳細な議論については、§ 9.14 プロパティーの入れ子化を参照してください。
キーワードではないノード・オブジェクト内のキーは、アクティブ・コンテキストを用いてIRIに展開できます(MAY)。IRIに展開されるキーに関連付けられる値は、次のうちの1つでなければなりません(MUST)。
true
、false
、フレーム化時には、フレーム・オブジェクトはノード・オブジェクトを拡張して、フレーム化専用のエントリーを可能にします。
@default
の値には、IRIに展開するエントリー・キーの値の文法で許されているその他の値に加えて、@null
という値、または@null
のみが含まれている配列を含むことができます(MAY)。@id
と@type
の値は、空のマップ(ワイルドカード)、空のマップのみが含まれている配列、空の配列(一致しないもの)、IRIの配列でありえます(MAY)。@always
、@once
、および@never
からの任意の値を持つ@embed
キーを持つエントリーを含むことができます(MAY)。@explicit
、@omitDefault
、または@requireAll
のキーを持つエントリーを含めることができます(MAY)。フレーム・オブジェクトの使用方法の説明については、[JSON-LD11-FRAMING]を参照してください。
グラフ・オブジェクトは名前付きグラフを表し、それには明示的なグラフ名を含めることができます(MAY)。マップは、JSON-LDのコンテキストの外部に存在し、@graph
エントリー(またはそのキーワードのエイリアス)を含み、JSON-LDドキュメントの最上部のマップではなく、@graph
、@index
、@id
および@context
のエントリーまたはこれらのキーワードのいずれかのエイリアスのみで構成されている場合、グラフ・オブジェクトです。
グラフ・オブジェクトに@context
キーが含まれている場合、その値はnull、IRI参照、コンテキスト定義、またはこれらのいずれかで構成される配列でなければなりません(MUST)。
グラフ・オブジェクトに@id
キーが含まれている場合、その値は名前付きグラフの識別子(グラフ名)として用いられ、IRI参照または短縮IRI(空白ノード識別子を含む)でなければなりません(MUST)。@id
という値に関する詳細な議論については、§ 3.3 ノード識別子、§ 4.1.5 短縮IRI、および§ 4.5.1 空白ノードの識別を参照してください。
@id
エントリーのないグラフ・オブジェクトもシンプルなグラフ・オブジェクトであり、明示的な識別子のない名前付きグラフを表しますが、データ・モデルにはグラフ名がまだあり、これは暗黙的に割り当てられた空白ノード識別子です。
@graph
キーの値は、ノード・オブジェクトまたは0以上のノード・オブジェクトの配列でなければなりません(MUST)。@graph
という値に関する詳細な議論については、§ 4.9 名前付きグラフを参照してください。
値オブジェクトは、型や言語を値に明示的に関連付けて型付き値または言語タグ付き文字列を作成するため、あるいは基本書字方向を関連付けるために用います。
値オブジェクトは、@value
キーが含まれているマップでなければなりません(MUST)。また、@type
、@language
、@direction
、@index
、@context
のキーを含めることもできますが(MAY)、@type
と、@language
か@direction
のいずれかのキーの両方を同時に含めてはなりません(MUST NOT)。値オブジェクトには、IRIやキーワードに展開されるその他のキーを含めてはなりません(MUST NOT)。
@value
キーに関連付ける値は、文字列、数値、true
、false
、またはnullのいずれかでなければなりません(MUST)。@type
キーに関連付けられている値が@json
である場合、値は配列かオブジェクトのいずれかでありえます(MAY)。
@type
キーに関連付ける値は、用語、IRI、短縮IRI、語彙マッピングを用いてIRIに変換できる文字列、@json
、またはnullでなければなりません(MUST)。
@language
キーに関連付ける値は、[BCP47]で記述されている字句形式か、nullでなければなりません(MUST)。
@direction
キーに関連付ける値は、"ltr"
か"rtl"
のいずれか、またはnullでなければなりません(MUST)。
@index
キーに関連付ける値は文字列でなければなりません(MUST)。
値オブジェクトに関する詳細情報については、§ 4.2.1 型付き値と§ 4.2.4 文字列の国際化を参照してください。
リストは、順序付きの値の集合を表します。集合は、順不同の値の集合を表します。特に指定のない限り、JSON-LDでは配列は順不同です。そのため、@set
キーワードは、JSON-LDドキュメントの本文で用いた場合には、ドキュメントの処理時に最適化によって削除される単なる構文糖衣を表します。しかし、ドキュメントのコンテキスト内で用いると非常に役立ちます。@set
または@list
のコンテナに関連付けられている用語の値は、ドキュメントが処理される際に、常に配列の形式で表されます—そうでない場合に短縮ドキュメントの配列でない形式に最適化される値が1つだけある場合でも。データは常に確定的な形式であるため、データの後処理がシンプルになります。
リスト・オブジェクトは、@list
と@index
以外のIRIやキーワードに展開されるキーが含まれていないマップでなければなりません(MUST)。
集合オブジェクトは、@set
と@index
以外のIRIやキーワードに展開されるキーが含まれていないマップでなければなりません(MUST)。@index
キーは処理時に無視されることに注意してください。
どちらの場合も、@list
と@set
のキーに関連付けられる値は、次の型のうちの1つでなければなりません(MUST)。
集合とリストに関する詳細な議論については、§ 4.3 値の順序付けを参照してください。
言語マップは、プログラムが容易にアクセスできる方法で言語を値に関連付けるために用います。言語マップは、@container
を@language
に設定して用語が定義されている場合、または@language
と@set
の両方が含まれている配列である場合に、ノード・オブジェクト内の用語の値として使用できます。言語マップのキーは、[BCP47]言語タグを表す文字列、@none
というキーワード、または@none
に展開される用語でなければならず(MUST)、値は次の型のいずれかでなければなりません(MUST)。
言語マップに関する詳細な議論については、§ 4.2.4 文字列の国際化を参照してください。
インデックス・マップでは、セマンティックな意味を持たないキーは許されていますが、それでもなお、そのキーは、JSON-LDドキュメントで用いるために保持すべきです。インデックス・マップは、@container
を@index
に設定して用語が定義されている場合、または@index
と@set
の両方が含まれている配列である場合に、ノード・オブジェクト内の用語の値として使用できます。インデックス・マップのエントリーの値は、次の型のうちの1つでなければなりません(MUST)。
true
、false
、このトピックに関する詳細情報については、§ 4.6.1 データのインデックス化 を参照してください。
インデックス・マップは、@graph
と@index
の両方が含まれていて、オプションで@set
が含まれている配列に@container
を設定して用語が定義されている場合に、関連付けられている名前付きグラフにインデックスをマッピングするためにも使用できます。値は、参照キーを用いてインデックス化されている名前付きグラフ内に含まれているノード・オブジェクトで構成され、値に@id
が含まれていない場合はシンプルなグラフ・オブジェクトとして、@id
が含まれている場合は名前付きグラフとして表すことができます。
プロパティー・ベースのインデックス・マップは、インデックスがプロパティー値としてグラフにセマンティック的に保持されているインデックス・マップの変種です。プロパティー・ベースのインデックス・マップは、@container
を@index
に設定して用語が定義されている場合、または@index
と@set
の両方が含まれている配列である場合、そして@index
を文字列に設定して定義されている場合に、ノード・オブジェクト内の用語の値として使用できます。プロパティー・ベースのインデックス・マップの値は、ノード・オブジェクトまたはノード・オブジェクトに展開される文字列でなければなりません(MUST)。
展開時に、@index
の値に対する用語定義がアクティブ・コンテキストに含まれている場合、この用語定義はインデックス・マップのキーを展開するために用いられるでしょう。それ以外の場合は、キーはシンプルな値オブジェクトとして展開されるでしょう。インデックス・マップの展開された値の中の個々のノード・オブジェクトには、追加のプロパティー値が追加され、そのプロパティーは@index
の展開された値であり、その値は展開された参照キーです。
このトピックに関する詳細情報については、§ 4.6.1.1 プロパティー・ベースのデータのインデックス化を参照してください。
idマップは、IRIを値に関連付け、プログラムが容易にアクセスできるようにするために用います。idマップは、@container
を@@id
に設定して用語が定義されている場合、または@id
と@set
の両方が含まれている配列である場合に、ノード・オブジェクト内の用語の値として使用できます。idマップのキーはIRI(IRI参照または短縮IRI(空白ノード識別子を含む))、@none
キーワード、または@none
に展開される用語でなければならず(MUST)、値はノード・オブジェクトでなければなりません(MUST)。
@id
に展開されるプロパティーが値に含まれている場合、その値は参照キーと同等でなければなりません(MUST)。それ以外の場合は、値に由来するプロパティーは、展開時にノード・オブジェクトの値の@id
として用います。
idマップは、@graph
と@id
の両方が含まれていて、オプションで@set
が含まれている配列に@container
を設定して用語が定義されている場合に、その名前付きグラフにグラフ名をマッピングするためにも使用できます。値は、参照キーを用いて名付けられる名前付きグラフ内に含まれるノード・オブジェクトで構成されます。
型マップは、IRIを値に関連付け、プログラムが容易にアクセスできるようにするために用います。型マップは、@container
を@type
に設定して用語が定義されている場合、または@type
と@set
の両方が含まれている配列である場合に、ノード・オブジェクト内の用語の値として使用できます。型マップのキーはIRI(IRI参照または短縮IRI(空白ノード識別子を含む))、用語、または@none
キーワードでなければならず(MUST)、値はノード・オブジェクトまたはノード・オブジェクトに展開される文字列でなければなりません(MUST)。
@type
に展開されるプロパティーが値に含まれており、参照キーと値の両方の適切な展開後の参照キーがその値に含まれている場合、ノード・オブジェクトには既に型が含まれています。それ以外の場合は、値に由来するプロパティーは、展開時にノード・オブジェクトの値の@type
として追加されます。
包含ブロックは、ノード・オブジェクトの集合を提供するために用います。包含ブロックは、@included
のキーか@included
のエイリアスのいずれかを持つノード・オブジェクトのメンバーの値として出現可能です(MAY)。包含ブロックは、ノード・オブジェクトかノード・オブジェクトの配列のいずれかです。
入れ子のプロパティーは、別個のマップ、または値オブジェクトではないマップの配列にノード・オブジェクトのプロパティーを集めるために用います。これはセマンティック的には意識する必要はなく、展開の過程で削除されます。プロパティーの入れ子化は再帰的であり、入れ子のプロパティーのコレクションにさらに入れ子を含めることができます。
セマンティック的には、入れ子は、プロパティーと値が、含んでいるノード・オブジェクト内で直接宣言されているかのように扱われます。
コンテキスト定義は、ノード・オブジェクトのローカル・コンテキストを定義します。
コンテキスト定義は、キーが用語、短縮IRI、IRI、または@base
、@import
、@language
、@propagate
、@protected
、@type
、@version
、@vocab
のキーワードのうちの1つでなければならない(MUST)マップでなければなりません(MUST)。
コンテキスト定義に@base
キーがある場合、その値はIRI参照またはnullでなければなりません(MUST)。
コンテキスト定義に@direction
キーがある場合、その値は"ltr"
か"rtl"
のいずれか、またはnullでなければなりません(MUST)。
コンテキスト定義に@import
キーワードが含まれている場合、その値はIRI参照でなければなりません(MUST)。@import
からの参照として用いる場合、参照されるコンテキスト定義に@import
キー自体を含めてはなりません(MUST NOT)。
コンテキスト定義に@language
キーがある場合、その値は[BCP47]で記述されている字句形式であるか、nullでなければなりません(MUST)。
コンテキスト定義に@propagate
キーがある場合、その値はtrue
かfalse
でなければなりません(MUST)。
コンテキスト定義に@protected
キーがある場合、その値はtrue
かfalse
でなければなりません(MUST)。
コンテキスト定義に@type
キーがある場合、その値は@container
というエントリーのみを@set
に設定し、オプションで@protected
というエントリーを設定したマップでなければなりません(MUST)。
コンテキスト定義に@version
キーがある場合、その値は1.1
という値を持つ数値でなければなりません(MUST)。
コンテキスト定義に@vocab
キーがある場合、その値はIRI参照、短縮IRI、空白ノード識別子、用語、またはnullでなければなりません(MUST)。
キーワードではないキーの値は、IRI、短縮IRI、用語、空白ノード識別子、キーワード、null、または展開用語定義のいずれかでなければなりません(MUST)。
展開用語定義は、用語とその展開された識別子の間のマッピング、およびノード・オブジェクトでキーとして用いたときに用語に関連付けられる値のその他のプロパティーを記述するために用います。
展開用語定義は、@id
、@reverse
、@type
、@language
、@container
、@context
、@prefix
、@propagate
、または@protected
の0以上のキーで構成されるマップでなければなりません(MUST)。展開用語定義には、その他のキーを含めるべきではありません(SHOULD NOT)。
関連付けられている用語が@type
である場合、展開用語定義に@container
と@protected
以外のキーを含めてはなりません(MUST NOT)。@container
の値は、@set
という1つの値に限定されています。
定義されている用語がIRIや短縮IRIでなく、アクティブ・コンテキストに@vocab
マッピングがない場合は、展開用語定義に@id
キーが含まれていなければなりません(MUST)。
IRIまたは短縮IRIの形式のキーを持つ用語定義は、キー自体の展開以外のIRIに展開してはなりません(MUST)。
展開用語定義に@id
キーワードが含まれている場合、その値はnull、IRI、空白ノード識別子、短縮IRI、用語、またはキーワードでなければなりません(MUST)。
展開用語定義に@reverse
エントリーがある場合、@id
または@nest
のエントリーが同時にあってはならず(MUST NOT)、その値はIRI、空白ノード識別子、短縮IRI、または用語でなければなりません(MUST)。@container
エントリーが存在する場合、その値はnull、@set
、または@index
でなければなりません(MUST)。
展開用語定義に@type
キーワードが含まれている場合、その値はIRI、短縮IRI、用語、null、または@id
、@json
、@none
、@vocab
のキーワードのうちの1つでなければなりません(MUST)。
展開用語定義に@language
キーワードが含まれている場合、その値は[BCP47]で記述されている字句形式であるか、nullでなければなりません(MUST)。
展開用語定義に@index
キーワードが含まれている場合、その値はIRI、短縮IRI、または用語でなければなりません(MUST)。
展開用語定義に@container
キーワードが含まれている場合、その値は@list
、@set
、@language
、@index
、@id
、@graph
、@type
のいずれか、またはnullか、これらのキーワードのいずれか1つを厳密に含む配列、または@set
と、任意の順序の@index
、@id
、@graph
、@type
、@language
のいずれかとの組み合わせでなければなりません(MUST)。@container
は、@id
か@index
のいずれかとともに@graph
を含み、オプションで@set
を含む配列でもありえます。値が@language
である場合、用語が@context
の外で用いられているときは、関連付けられている値は言語マップでなければなりません(MUST)。値が@index
である場合、用語が@context
の外で用いられているときは、関連付けられている値はインデックス・マップでなければなりません(MUST)。
展開用語定義に@context
エントリーがある場合、それは有効なcontext definition
(コンテキスト定義)でなければなりません(MUST)。
展開用語定義に@nest
キーワードが含まれている場合、その値は@nest
、または@nest
に展開される用語のいずれかでなければなりません(MUST)。
展開用語定義に@prefix
キーワードが含まれている場合、その値はtrue
かfalse
でなければなりません(MUST)。
展開用語定義に@propagate
キーワードが含まれている場合、その値はtrue
かfalse
でなければなりません(MUST)。
展開用語定義に@protected
キーワードが含まれている場合、その値はtrue
かfalse
でなければなりません(MUST)。
用語は循環的に用いてはなりません(MUST NOT)。つまり、ある用語の定義は、別の用語がその用語に依存している場合、その別の用語の定義に依存することはできません。
コンテキストに関する詳細な議論については、§ 3.1 コンテキストを参照してください。
JSON-LDのキーワードについては、§ 1.7 構文トークンとキーワードで説明しており、この項では、個々のキーワードが様々なJSON-LD構造内のどこに出現するかについて説明します。
ノード・オブジェクト、値オブジェクト、グラフ・オブジェクト、リスト・オブジェクト、集合オブジェクト、および入れ子のプロパティー内では、@context
を除き、対応するキーワードの代わりにキーワードのエイリアスを使用できます(MAY)。@context
キーワードをエイリアス化してはなりません(MUST NOT)。ローカル・コンテキストと展開用語定義内では、キーワードのエイリアスは使用できません(MAY NOT)。
@base
@base
キーワードは、コンテキスト定義でキーとして使用できます(MAY)。その値はIRI参照かnullでなければなりません(MUST)。@container
@container
キーワードは、展開用語定義でキーとして使用できます(MAY)。その値は@list
、@set
、@language
、@index
、@id
、@graph
、@type
のいずれか、またはnullか、これらのキーワードのいずれか1つを厳密に含む配列、または@set
と、任意の順序の@index
、@id
、@graph
、@type
、@language
のいずれかとの組み合わせでなければなりません(MUST)。値は、@id
か@index
のいずれかとともに@graph
を含み、オプションで@set
を含む配列でもありえます。@context
@context
キーワードはエイリアス化してはならず(MUST NOT)、次のオブジェクトでキーとして使用できます(MAY)。
@context
の値は、null、IRI参照、コンテキスト定義、またはこれらのいずれかで構成される配列でなければなりません(MUST)。@direction
@direction
キーワードはエイリアス化でき(MAY)、値オブジェクトでキーとして使用できます(MAY)。その値は"ltr"
か"rtl"
のいずれか、またはnullでなければなりません(MUST)。
エイリアス化されていない@direction
は、コンテキスト定義でキーとして使用できます(MAY)。
詳細な議論については、§ 4.2.4.1 基本書字方向を参照してください。
@graph
@graph
キーワードはエイリアス化でき(MAY)、ノード・オブジェクトまたはグラフ・オブジェクトでキーとして使用でき(MAY)、その値は値オブジェクト、ノード・オブジェクト、または値オブジェクトかノード・オブジェクトのいずれかの配列でなければなりません(MUST)。
エイリアス化されていない@graph
は、展開用語定義内で@container
キーの値として使用できます(MAY)。
§ 4.9 名前付きグラフを参照してください。
@id
@id
キーワードはエイリアス化でき(MAY)、ノード・オブジェクトまたはグラフ・オブジェクトでキーとして使用できます(MAY)。
エイリアス化されていない@id
は、展開用語定義でキーとして、または展開用語定義内で@container
キーの値として使用できます(MAY)。
@id
キーの値は、IRI参照、または短縮IRI(空白ノード識別子を含む)でなければなりません(MUST)。
@id
の値に関する詳細な議論については、§ 3.3 ノード識別子、§ 4.1.5 短縮IRI、および§ 4.5.1 空白ノードの識別を参照してください。
@import
@import
キーワードは、コンテキスト定義で使用できます(MAY)。その値はIRI参照でなければなりません(MUST)。詳細な議論については、§ 4.1.10 インポートされたコンテキストを参照してください。@included
@included
キーワードはエイリアス化でき(MAY)、その値は包含ブロックでなければなりません(MUST)。このキーワードについては、§ 4.7 内包ノードと§ 9.13 包含ブロックで詳細に説明しています。@index
@index
キーワードはエイリアス化でき(MAY)、ノード・オブジェクト、値オブジェクト、グラフ・オブジェクト、集合オブジェクト、またはリスト・オブジェクトでキーとして使用できます(MAY)。その値は文字列でなければなりません(MUST)。
エイリアス化されていない@index
は、展開用語定義内で@container
キーの値として、そして展開用語定義でエントリーとして使用でき(MAY)、その値はIRI、短縮IRI、または用語です。
詳細な議論については、§ 9.9 インデックス・マップと§ 4.6.1.1 プロパティー・ベースのデータのインデックス化を参照してください。
@json
@json
キーワードはエイリアス化でき(MAY)、値オブジェクトまたは展開用語定義内で@type
キーの値として使用できます(MAY)。
§ 4.2.2 JSONリテラルを参照してください。
@language
@language
キーワードはエイリアス化でき(MAY)、値オブジェクトでキーとして使用できます(MAY)。その値は[BCP47]で記述されている字句形式の文字列であるか、nullでなければなりません(MUST)。
エイリアス化されていない@language
は、コンテキスト定義でキーとして、または展開用語定義内で@container
キーの値として使用できます(MAY)。
§ 4.2.4 文字列の国際化、§ 9.8 言語マップを参照してください。
@list
@list
キーワードはエイリアス化でき(MAY)、リスト・オブジェクトでキーとして用いなければなりません(MUST)。エイリアス化されていない@list
は、展開用語定義内で@container
キーの値として使用できます(MAY)。その値は次のうちの1つでなければなりません(MUST)。
集合とリストに関する詳細な議論については、§ 4.3 値の順序付けを参照してください。
@nest
@nest
キーワードはエイリアス化でき(MAY)、ノード・オブジェクトでキーとして使用でき(MAY)、その値はマップでなければなりません。
エイリアス化されていない@nest
は、シンプルな用語定義の値として、または展開用語定義でキーとして使用でき(MAY)、その値は@nest
に展開される文字列でなければなりません(MUST)。
詳細な議論については、§ 9.14 プロパティーの入れ子化を参照してください。
@none
@none
キーワードはエイリアス化でき(MAY)、インデックス・マップ、idマップ、言語マップ、型マップでキーとして使用できます(MAY)。詳細な議論については、§ 4.6.1 データのインデックス化、§ 4.6.2 言語のインデックス化、§ 4.6.3 ノード識別子のインデックス化、§ 4.6.4 ノード型のインデックス化、§ 4.9.3 名前付きグラフのインデックス化、または§ 4.9.2 名前付きグラフのデータのインデックス化を参照してください。@prefix
@prefix
キーワードは、展開用語定義でキーとして使用できます(MAY)。その値はtrue
かfalse
でなければなりません(MUST)。詳細な議論については、§ 4.1.5 短縮IRIと§ 9.15 コンテキスト定義を参照してください。@propagate
@propagate
キーワードは、コンテキスト定義で使用できます(MAY)。その値はtrue
かfalse
でなければなりません(MUST)。詳細な議論については、§ 4.1.9 コンテキストの伝播を参照してください。@protected
@protected
キーワードは、コンテキスト定義、または展開用語定義で使用できます(MAY)。その値はtrue
かfalse
でなければなりません(MUST)。詳細な議論については、§ 4.1.11 保護された用語定義を参照してください。@reverse
@reverse
キーワードはエイリアス化でき(MAY)、ノード・オブジェクトでキーとして使用できます(MAY)。
エイリアス化されていない@reverse
は、展開用語定義でキーとして使用できます(MAY)。
@reverse
キーの値は、IRI参照、または短縮IRI(空白ノード識別子を含む)でなければなりません(MUST)。
詳細な議論については、§ 4.8 逆プロパティーと§ 9.15 コンテキスト定義を参照してください。
@set
@set
キーワードはエイリアス化でき(MAY)、集合オブジェクトでキーとして用いなければなりません(MUST)。その値は次のうちの1つでなければなりません(MUST)。
エイリアス化されていない@set
は、展開用語定義内で@container
キーの値として使用できます(MAY)。
集合とリストに関する詳細な議論については、§ 4.3 値の順序付けを参照してください。
@type
@type
キーワードはエイリアス化でき(MAY)、ノード・オブジェクトまたは値オブジェクトでキーとして使用でき(MAY)、その値は用語、IRI参照、または短縮IRI(空白ノード識別子を含む)でなければなりません(MUST)。
エイリアス化されていない@type
は、展開用語定義でキーとして使用でき(MAY)、その値は@id
または@vocab
のいずれか、または展開用語定義内で@container
キーの値としても使用できます。
コンテキスト内では、@type
は展開用語定義のキーとして使用でき、そのエントリーは@container
と@protected
に限定されています。
このキーワードは、§ 3.5 型の指定と§ 4.2.1 型付き値で詳細に説明しています。
@value
@value
キーワードはエイリアス化でき(MAY)、値オブジェクトでキーとして用いなければなりません(MUST)。その値のキーは、文字列、数値、true
、false
、またはnullのいずれかでなければなりません(MUST)。このキーワードは、§ 9.5 値オブジェクトで詳細に説明しています。@version
@version
キーワードは、コンテキスト定義でキーとして使用できます(MAY)。その値は1.1
という値を持つ数値でなければなりません(MUST)。このキーワードは、§ 9.15 コンテキスト定義で詳細に説明しています。@vocab
@vocab
キーワードは、コンテキスト定義でキーとして、または展開用語定義で@type
の値として使用できます(MAY)。その値はIRI参照、短縮IRI、空白ノード識別子、用語、またはnullでなければなりません(MUST)。このキーワードは、§ 9.15 コンテキスト定義と§ 4.1.2 デフォルトの語彙で詳細に説明しています。JSON-LDは、[RDF11-CONCEPTS]で記述されている具象RDF構文です。したがって、JSON-LDドキュメントはRDFドキュメントでもJSONドキュメントでもあり、それに応じてRDFデータ・モデルのインスタンスを表します。しかし、JSON-LDは、RDFデータ・モデルを拡張して、オプションでJSON-LDが一般化RDFデータセットをシリアル化できるようにもします。RDFデータ・モデルに対するJSON-LDの拡張は次のとおりです。
true
とfalse
もサポートしています。JSON-LD 1.1処理アルゴリズムとAPI仕様[JSON-LD11-API]は、JSONのネイティブなデータ型とRDFの対応するデータ型の間の変換規則を定義して、ラウンドトリップを可能にしています。プロパティーにラベル付けするための空白ノード識別子の使用は廃止されており、一般化RDFデータセットのサポートと同様に、JSON-LDの将来のバージョンでは削除される可能性があります。
要約すると、これらの違いは、JSON-LDがRDFのグラフやデータセットをシリアル化できることを意味し、すべてではないものの、ほとんどのJSON-LDドキュメントは、RDF 1.1概念[RDF11-CONCEPTS]で説明されているように、RDFとして直接解釈できます。
作成者は、空白ノード識別子を用いてプロパティーにラベル付けしないようにすることを強くお勧めします。代わりに、次のいずれかの方法を検討してください。
urn:example:1
などのURN。[URN]を参照、または、JSON-LDをRDFとして解釈し、RDFをJSON-LDとしてシリアル化するための規範的なアルゴリズムは、JSON-LD 1.1処理アルゴリズムとAPI仕様[JSON-LD11-API]で規定されています。
JSON-LDはRDFデータセットをシリアル化しますが、グラフ情報源としても使用できます。その場合、利用者はデフォルト・グラフのみを用い、すべての名前付きグラフを無視しなくてはなりません(MUST)。これにより、サーバーはHTTP内容交渉を用いてTurtleやJSON-LDなどの言語でデータを公開できます。
この項は非規範的です。
JSON-LDとしてのRDFのシリアル化、JSON-LDからRDFへの逆シリアル化の処理は、JSON-LD 1.1処理アルゴリズムとAPI仕様[JSON-LD11-API]のRDFシリアル化-逆シリアル化アルゴリズムで定義されているアルゴリズムの実行に依存します。これらのアルゴリズムに関するこれ以上の詳細な説明は、このドキュメントの範囲を超えていますが、処理について説明するために、必要な操作の概要を提供します。
JSON-LDドキュメントをRDFに逆シリアル化する手順には、次のステップが含まれます。
例えば、次の短縮形式のJSON-LDドキュメントについて考えてみましょう。
{
"@context": {
"name": "http://xmlns.com/foaf/0.1/name",
"knows": "http://xmlns.com/foaf/0.1/knows"
},
"@id": "http://me.markus-lanthaler.com/",
"name": "Markus Lanthaler",
"knows": [
{
"@id": "http://manu.sporny.org/about#manu",
"name": "Manu Sporny"
}, {
"name": "Dave Longley"
}
]
}
上記の例のJSON-LD入力ドキュメントに対してJSON-LDの展開とフラット化のアルゴリズムを実行すると、次の出力が生成されます。
[
{
"@id": "_:b0",
"http://xmlns.com/foaf/0.1/name": "Dave Longley"
}, {
"@id": "http://manu.sporny.org/about#manu",
"http://xmlns.com/foaf/0.1/name": "Manu Sporny"
}, {
"@id": "http://me.markus-lanthaler.com/",
"http://xmlns.com/foaf/0.1/name": "Markus Lanthaler",
"http://xmlns.com/foaf/0.1/knows": [
{ "@id": "http://manu.sporny.org/about#manu" },
{ "@id": "_:b0" }
]
}
]
これをRDFに逆シリアル化することは、各ノード・オブジェクトを1つ以上のトリプルに変換するという簡単な処理となりました。これはTurtleでは次のように表現できます。
@prefix foaf: <http://xmlns.com/foaf/0.1/> .
_:b0 foaf:name "Dave Longley" .
<http://manu.sporny.org/about#manu> foaf:name "Manu Sporny" .
<http://me.markus-lanthaler.com/> foaf:name "Markus Lanthaler" ;
foaf:knows <http://manu.sporny.org/about#manu>, _:b0 .
RDFをJSON-LDとしてシリアル化する処理は、この最後のステップの逆と考えることができ、共通の主語を持っているすべてのトリプルに対する1つのノード・オブジェクトと、共通の述語も持っているそれらのトリプルに対する1つのプロパティーを用いて、RDFからのトリプルに非常に一致した展開されたJSON-LDドキュメントが作成されます。次に、[JSON-LD11-FRAMING]で記述されているフレーム化アルゴリズムを用いて結果をフレーム化し、望ましいオブジェクトの組み込みを作成できます。
rdf:JSON
データ型RDFは、JSONコンテンツをリテラル値になり得るものとして提供します。これにより、リテラル値によるマークアップが可能になります。このようなコンテンツは、データ型をrdf:JSON
に設定したリテラルを用いてグラフで示されます。
rdf:JSON
というデータ型は次のように定義されています。
http://www.w3.org/1999/02/22-rdf-syntax-ns#JSON
です。U+0008
、U+0009
、U+000A
、U+000C
、U+000D
(それぞれ\b
、\t
、\n
、\f
、\r
としてシリアル化すべき(SHOULD))でない限り、小文字の16進Unicode表記法(\uhhhh
)を用いて、U+0000
からU+001F
までのUnicodeコードポイントでシリアル化しなければなりません(MUST)。その他のすべてのUnicode文字は、U+005C
(\
)とU+0022
("
)(それぞれ\\
、\"
としてシリアル化すべき(SHOULD))を除き、「そのまま」シリアル化すべきです(SHOULD)。xsd:string
の値空間とは異なるものと見なされます。JSON.parse
関数を用いて作成された[ECMASCRIPT]の表現と整合性がある内部表現へと解析し、i18n
名前空間この項は非規範的です。
i18n
名前空間は、RDFリテラルの言語タグと基本書字方向の組み合わせを記述するために用います。これは、[BCP47]のRDFリテラルで言語タグと基本書字方向を記述するための代替メカニズム(それ以外の場合はxsd:string
やrdf:langString
のデータ型を用いる)として用います。
この名前空間に基づくデータ型では、基本書字方向を用いたJSON-LDドキュメントのラウンドトリップが可能ですが、この方法は標準化されていません。
JSON-LDからRDFへの逆シリアル化アルゴリズムを、i18n-datatype
に設定したrdfDirectionというオプションとともに用いて、
i18n
ベースを用いてRDFリテラルを生成し、後に下線("_"
)、その後に@direction
の値が続く@language
の値(ある場合は)をhttps://www.w3.org/ns/i18n#
に追加することにより@direction
を含んでいる値オブジェクトから、基本書字方向をオプションの言語タグ(小文字に正規化)とともにエンコードしたIRIを作成することができます。
相互運用性を向上させるために、データ型IRIの作成時に言語タグは小文字に正規化されます。
次の例では、i18n:ar-EG_rtl
というリテラル値を持つ2つのステートメントを示しています。これは、ar-EG
という言語タグと、rtl
という基本書字方向をエンコードしています。
@prefix ex: <http://example.org/> . @prefix i18n: <https://www.w3.org/ns/i18n#> . # Note that this version preserves the base direction using a non-standard datatype. [ ex:title "HTML و CSS: تصميم و إنشاء مواقع الويب"^^i18n:ar-eg_rtl; ex:publisher "مكتبة"^^i18n:ar-eg_rtl ] .
文字列に対する基本書字方向の使用に関する詳細については、§ 4.2.4.1 基本書字方向を参照してください。
rdf:CompoundLiteral
クラスおよびrdf:language
とrdf:direction
のプロパティーこの項は非規範的です。
この仕様はrdf:CompoundLiteral
クラスを定義しており、これは、同じ主語上のrdf:value
の文字列の値に関連付けられる基本書字方向と可能な言語タグが含まれているRDFリテラルの値の記述に用いられるrdf:language
とrdf:direction
の定義域にあります。
rdf:CompoundLiteral
rdf:language
rdfs:Literal
であり、その値は整形式の[BCP47]言語タグでなければなりません(MUST)。プロパティーの定義域はrdf:CompoundLiteral
です。rdf:direction
rdfs:Literal
であり、その値は"ltr"
か"rtl"
のいずれかでなければなりません(MUST)。プロパティーの定義域はrdf:CompoundLiteral
です。JSON-LDからRDFへの逆シリアル化ゴリズムを、compound-literal
に設定したrdfDirectionオプションとともに用いて、これらのプロパティーを用いてRDFリテラルを生成し、@direction
とオプションで@language
を含んでいる値オブジェクトから、基本書字方向とオプションで言語タグ(小文字に正規化)を記述することができます。
相互運用性を向上させるために、データ型IRIの作成時に言語タグは小文字に正規化されます。
次の例は、ar-EG
という言語タグと、rtl
という基本書字方向を持つ文字列を表す複合リテラルが含まれている2つのステートメントを示しています。
@prefix ex: <http://example.org/> . # Note that this version preserves the base direction using a bnode structure. [ ex:title [ rdf:value "HTML و CSS: تصميم و إنشاء مواقع الويب", rdf:language "ar-eg", rdf:direction "rtl" ]; ex:publisher [ rdf:value "مكتبة", rdf:language "ar-eg", rdf:direction "rtl" ] ] .
文字列に対する基本書字方向の使用に関する詳細については、§ 4.2.4.1 基本書字方向を参照してください。
§ C. IANAに関する留意点のセキュリティに関する留意点を参照してください。
外部コンテキストの取得によりJSON-LDプロセッサの操作が公開され、中間ノードが、取得した資源のイントロスペクションを通じてクライアント・アプリケーションのフィンガープリントを行えるようになり([fingerprinting-guidance]を参照)、中間者攻撃の機会をもたらします。これを防ぐには、公開者は将来的な利用のために遠隔のコンテキストをキャッシュすることを検討するか、documentLoaderを用いてそのようなコンテキストのローカルなバージョンを維持すべきです。
JSON-LDはRDFデータ・モデルを用いるため、左から右または右から左の方向の指標を有する文字列であるJSON-LD値を適切に記録する機能は、設計上制限されています。JSON-LDとRDFはいずれも、文字列に関連付けられている言語を指定する方法(言語タグ付き文字列)を提供していますが、文字列の基本書字方向を示す手段は提供しません。
Unicodeは、文字列内の方向を示唆するメカニズムを提供していますが(Unicode双方向アルゴリズム[UAX9]を参照)、文字列に、文字列の先頭では決定できない全体的な基本書字方向がある場合は、[HTML]のdir属性などの外部の指標が必要です。しかし、現在、RDFリテラルにはそれに相当するものはありません。
RDFで基本書字方向を適切に表すという課題は、それが制限であったりコアRDFデータ・モデルであったりするため、このワーキンググループで扱えるものではありません。このワーキンググループは、将来のRDFワーキンググループがこの問題を検討し、言語タグ付き文字列の基本書字方向を指定する機能を追加することを期待しています。
この仕様の将来のバージョンにおいてより包括的な解決策に対応できるようになるまで、公開者は、他の方法では文字列の内容に基づいて文字列の基本書字方向を正しく推測できない文字列を表す際に、この課題について考慮すべきです。ウェブで用いられる文字列の言語と基本書字方向を識別するためのベスト・プラクティスの議論については、[string-meta]を参照してください。
この項は非規範的です。
この項は非規範的です。
この項では、§ 8. データ・モデルのリンクト・データのデータセットの図について説明します。
画像は3つの破線のボックスで構成されており、それぞれ異なるリンクト・データ・グラフを示しています。各ボックスは、リンクト・データの関係を示す矢印でリンク付けされた図形で構成されています。
最初のボックスのタイトルは「default graph: <no name>」(デフォルト・グラフ: <名前なし>)で、http://example.com/people/alice
とhttp://example.com/people/bob
の2つの資源(それぞれ、「Alice」と「Bob」を表している)が記述されており、2つの資源間の既知(knows)の関係を示すschema:knows
というラベルが付いた矢印で接続されています。さらに、「Alice」という資源は、次の3つの異なるリテラルに関連付けられています。
2番目と3番目のボックスは、それぞれ「http://example.com/graphs/1」と「http://example.com/graphs/2」というグラフ名を持つ2つの名前付きグラフを示しています。
2番目のボックスは、schema:parent
という関係によって関連付けられているhttp://example.com/people/alice
とhttp://example.com/people/bob
の2つの資源で構成され、http://example.com/people/bob
を「Bob」と名付けています。
3番目のボックスは、http://example.com/people/bob
という名前の資源と、名前のない資源の2つの資源で構成されています。2つの資源は、schema:sibling
という関係を用いて互いに関連付けられており、2番目の資源は「Mary」と名付けられています。
この項は非規範的です。
下記のJSON-LDの例は、JSON-LDを用いて、Turtle、RDFa、Microdataなどの他のリンクト・データ形式でマークアップしたセマンティックなデータを表現する方法を示しています。これらの項は、様々なリンクト・データのアプローチで表現できる内容に関して、JSON-LDの柔軟性が非常に高いことを示す証拠として提供しているに過ぎません。
この項は非規範的です。
以下は、[Turtle]で表されているRDFをJSON-LDに変換する例です。
JSON-LDのコンテキストには、Turtleの@prefix
宣言に直接相当するのものがあります。
@prefix foaf: <http://xmlns.com/foaf/0.1/> .
<http://manu.sporny.org/about#manu> a foaf:Person;
foaf:name "Manu Sporny";
foaf:homepage <http://manu.sporny.org/> .
{
"@context": {
"foaf": "http://xmlns.com/foaf/0.1/"
},
"@id": "http://manu.sporny.org/about#manu",
"@type": "foaf:Person",
"foaf:name": "Manu Sporny",
"foaf:homepage": { "@id": "http://manu.sporny.org/" }
}
[Turtle]とJSON-LDではどちらも組み込みが可能ですが、[Turtle]では空白ノードの組み込みのみが可能です。
@prefix foaf: <http://xmlns.com/foaf/0.1/> .
<http://manu.sporny.org/about#manu>
a foaf:Person;
foaf:name "Manu Sporny";
foaf:knows [ a foaf:Person; foaf:name "Gregg Kellogg" ] .
{
"@context": {
"foaf": "http://xmlns.com/foaf/0.1/"
},
"@id": "http://manu.sporny.org/about#manu",
"@type": "foaf:Person",
"foaf:name": "Manu Sporny",
"foaf:knows": {
"@type": "foaf:Person",
"foaf:name": "Gregg Kellogg"
}
}
JSON-LDでは、数値とブール値はネイティブなデータ型です。[Turtle]にはそのような値を表現するための省略構文がありますが、RDFの抽象構文では、数値とブール値を型付きリテラルとして表す必要があります。したがって、完全なラウンドトリップを可能にするために、JSON-LD 1.1処理アルゴリズムとAPI仕様[JSON-LD11-API]では、JSON-LDのネイティブなデータ型とRDFの対応するデータ型の間の変換規則を定義しています。小数が含まれていない数値はxsd:integer
という型付きリテラルに、小数が含まれている数値はxsd:double
という型付きリテラルに、true
とfalse
という2つのブール値はxsd:boolean
という型付きリテラルに変換されます。すべての型付きリテラルは、正規字句形式です。
{
"@context": {
"ex": "http://example.com/vocab#"
},
"@id": "http://example.com/",
"ex:numbers": [ 14, 2.78 ],
"ex:booleans": [ true, false ]
}
@prefix ex: <http://example.com/vocab#> .
@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
<http://example.com/>
ex:numbers "14"^^xsd:integer, "2.78E0"^^xsd:double ;
ex:booleans "true"^^xsd:boolean, "false"^^xsd:boolean .
2.78
というリテラルがxsd:decimal
に変換される[Turtle]とは異なることに注意してください。原理は、ほとんどのJSONツールが小数を含む数値を浮動小数点数として解析するため、RDFに戻して表すのにはxsd:double
が最も適切なデータ型であることです。JSON-LDと[Turtle]はどちらも、連続する値のリストを表すことができます。
@prefix foaf: <http://xmlns.com/foaf/0.1/> .
<http://example.org/people#joebob> a foaf:Person;
foaf:name "Joe Bob";
foaf:nick ( "joe" "bob" "jaybee" ) .
{
"@context": {
"foaf": "http://xmlns.com/foaf/0.1/"
},
"@id": "http://example.org/people#joebob",
"@type": "foaf:Person",
"foaf:name": "Joe Bob",
"foaf:nick": {
"@list": [ "joe", "bob", "jaybee" ]
}
}
この項は非規範的です。
次の例は、3人の名前とホームページを個々にRDFa[RDFA-CORE]で記述しています。
<div prefix="foaf: http://xmlns.com/foaf/0.1/"> <ul> <li typeof="foaf:Person"> <a property="foaf:homepage" href="http://example.com/bob/"> <span property="foaf:name">Bob</span> </a> </li> <li typeof="foaf:Person"> <a property="foaf:homepage" href="http://example.com/eve/"> <span property="foaf:name">Eve</span> </a> </li> <li typeof="foaf:Person"> <a property="foaf:homepage" href="http://example.com/manu/"> <span property="foaf:name">Manu</span> </a> </li> </ul> </div>
1つのコンテキストを用いたJSON-LDの実装例を以下に示します。
この項は非規範的です。
下記のHTMLマイクロデータ[MICRODATA]の例は、本の情報をマイクロデータのワーク・アイテムとして表しています。
<dl itemscope
itemtype="http://purl.org/vocab/frbr/core#Work"
itemid="http://purl.oreilly.com/works/45U8QJGZSQKDH8N">
<dt>Title</dt>
<dd><cite itemprop="http://purl.org/dc/elements/1.1/title">Just a Geek</cite></dd>
<dt>By</dt>
<dd><span itemprop="http://purl.org/dc/elements/1.1/creator">Wil Wheaton</span></dd>
<dt>Format</dt>
<dd itemprop="http://purl.org/vocab/frbr/core#realization"
itemscope
itemtype="http://purl.org/vocab/frbr/core#Expression"
itemid="http://purl.oreilly.com/products/9780596007683.BOOK">
<link itemprop="http://purl.org/dc/elements/1.1/type" href="http://purl.oreilly.com/product-types/BOOK">
Print
</dd>
<dd itemprop="http://purl.org/vocab/frbr/core#realization"
itemscope
itemtype="http://purl.org/vocab/frbr/core#Expression"
itemid="http://purl.oreilly.com/products/9780596802189.EBOOK">
<link itemprop="http://purl.org/dc/elements/1.1/type" href="http://purl.oreilly.com/product-types/EBOOK">
Ebook
</dd>
</dl>
マイクロデータ情報のJSON-LD表現は、コンテキストを避け、代わりに完全なIRIによってアイテムを参照したいというマイクロデータ・コミュニティの要望に忠実であることに注意してください。
[
{
"@id": "http://purl.oreilly.com/works/45U8QJGZSQKDH8N",
"@type": "http://purl.org/vocab/frbr/core#Work",
"http://purl.org/dc/elements/1.1/title": "Just a Geek",
"http://purl.org/dc/elements/1.1/creator": "Wil Wheaton",
"http://purl.org/vocab/frbr/core#realization":
[
{"@id": "http://purl.oreilly.com/products/9780596007683.BOOK"},
{"@id": "http://purl.oreilly.com/products/9780596802189.EBOOK"}
]
}, {
"@id": "http://purl.oreilly.com/products/9780596007683.BOOK",
"@type": "http://purl.org/vocab/frbr/core#Expression",
"http://purl.org/dc/elements/1.1/type": {"@id": "http://purl.oreilly.com/product-types/BOOK"}
}, {
"@id": "http://purl.oreilly.com/products/9780596802189.EBOOK",
"@type": "http://purl.org/vocab/frbr/core#Expression",
"http://purl.org/dc/elements/1.1/type": {"@id": "http://purl.oreilly.com/product-types/EBOOK"}
}
]
この項は、IANAでのレビュー、承認、登録のためにIESG(Internet Engineering Steering Group)に提出しています。
profile
[RFC6906]に従ってJSON-LDドキュメントに適用される特定の制約や規定を識別する、スペース区切りのURIの空でないリスト。プロファイルは、プロファイルの知識なしに処理された場合に資源の表現のセマンティクスを変更しないため、プロファイル対象の資源に関して、クライアントが知識を持っていてもいなくても同じ表現を安全に使用できます。profile
パラメータは、クライアントが内容交渉の過程でプレファレンスを表すために使用できます(MAY)。プロファイルのパラメータが指定されていれば、サーバーは、認識したリスト内のプロファイルを尊重するドキュメントを返べきであり(SHOULD)、認識しないリスト内のプロファイルは無視しなければなりません(MUST)。プロファイルのURIは逆参照可能であり、そのURIで有用なドキュメントを提供することをお勧めします(RECOMMENDED)。詳細な情報と背景については、[RFC6906]を参照してください。
この仕様では、profile
パラメータに対して6つの値を定義しています。
http://www.w3.org/ns/json-ld#expanded
http://www.w3.org/ns/json-ld#compacted
http://www.w3.org/ns/json-ld#context
http://www.w3.org/ns/json-ld#flattened
http://www.w3.org/ns/json-ld#frame
http://www.w3.org/ns/json-ld#framed
http://www.w3.org/ns/json-ld
で始まるその他のすべてのURIは、JSON-LD仕様によって将来の使用のために予約されています。
他の仕様では、独自のセマンティクスを定義した追加のprofile
パラメータURIを公開できます。これには、ファイル拡張子をprofile
パラメータに関連付ける機能が含まれます。
HTTP Acceptヘッダー[RFC7231]でメディア・タイプ・パラメータ[RFC4288]として用いる場合、複数のプロファイルURIを組み合わせる場合に必要な空白などの特殊文字が含まれていれば、profile
パラメータの値を引用符("
)で囲まなければなりません(MUST)。
「profile」というメディア・タイプのパラメータを処理する場合、その値にはIRIではなく1つ以上のURIが含まれていることに注意することが重要です。したがって、[RFC3987]の3項 IRIとURIの関係で規定されているように、IRIとURIの変換が必要になる場合があります。
JSON-LDは有向グラフの純粋なデータ交換フォーマットであることを意図しているため、シリアル化は、解析用のJavaScriptのeval()
関数などのコード実行メカニズムを通すべきではありません(SHOULD NOT)。(無効な)ドキュメントには、実行時にシステムのセキュリティを危険にさらす予期しない副作用を引き起こす可能性のあるコードが含まれている場合があります。
JSON-LDドキュメントを処理する場合、通常、遠隔のコンテキストとフレームへのリンクが自動的に辿られるため、その結果、それぞれに対してユーザーの明示的なリクエストがなくてもファイル転送が行われます。遠隔のコンテキストを第三者が提供している場合、プライバシーの懸念につながるような利用パターンなどの情報を収集できる可能性があります。JSON-LD 1.1処理アルゴリズムとAPI仕様[JSON-LD11-API]で定義されているAPIなどの特定の実装では、この動作を制御するためのきめ細かいメカニズムを提供することができます。
HTTPなどの安全でない接続を介してウェブから読み込まれたJSON-LDコンテキストは、攻撃者によって変更される危険性があり、JSON-LDのアクティブ・コンテキストがセキュリティを危険にさらすようなものに変更される可能性があります。極めて重要な目的で遠隔のコンテキストに依存しているアプリケーションは、システムによる利用を許可する前に、その遠隔のコンテキストを検証しキャッシュすることをお勧めします。
JSON-LDでは長いIRIを短い用語に置き換えることができるため、JSON-LDドキュメントが処理時に大幅に展開され、最悪の場合、結果としてデータが受信者の資源をすべて使い切る可能性があります。アプリケーションは、十分な疑念を持ってデータを扱う必要があります。
JSON-LDは使用できるIRIスキームに制限を設けておらず、語彙に対して相対的なIRIはIRI解決ではなく文字列連結を用いるため、逆参照された場合に悪意を持って利用される可能性のあるIRIを構築することが可能です。
application/ld+jsonで用いられるフラグメント識別子は、RDF 1.1概念および抽象構文[RDF11-CONCEPTS]に従って、RDF構文と同様に扱われます。
この登録は、[JSON-LD10]のapplication/ld+jsonに関する元の定義の更新です。
この項は非規範的です。
以下の例は、プロファイルのパラメータを用いて様々な受け入れ可能な応答を記述する様々な方法を示しています。
GET /ordinary-json-document.json HTTP/1.1
Host: example.com
Accept: application/ld+json;profile=http://www.w3.org/ns/json-ld#expanded
リクエストされた資源を展開ドキュメント形式のJSON-LDとして返すようサーバーにリクエストします。
GET /ordinary-json-document.json HTTP/1.1
Host: example.com
Accept: application/ld+json;profile=http://www.w3.org/ns/json-ld#compacted
リクエストされた資源を短縮ドキュメント形式のJSON-LDとして返すようサーバーにリクエストします。明示的なコンテキスト資源が指定されていないため、サーバーはアプリケーション固有のデフォルトのコンテキストを用いて短縮します。
GET /ordinary-json-document.json HTTP/1.1
Host: example.com
Accept: application/ld+json;profile="http://www.w3.org/ns/json-ld#flattened http://www.w3.org/ns/json-ld#compacted"
リクエストされた資源を短縮ドキュメント形式とフラット化ドキュメント形式の両方でJSON-LDとして返すようサーバーにリクエストします。空白は2つのURIを区切るために用いられるため、二重引用符("
)で囲まれていることに注意してください。
この項は非規範的です。
下記は、公開時点で未解決の課題のリストです。
メタデータを用いた参照によるコンテキストの検討
重要な接頭辞の用語定義に対する短縮IRI展開のサポート
言語マップで別個の基本書字方向は許されていない
JSON-LDコア構文の@context
の@default
@prefix
に関する提案
型強制/ノード変換: @coerceキーワード等
この項は非規範的です。
@version
エントリーを持つことができるようになった。@context
プロパティーを持つことができるようになった。これは、そのような用語で識別されるプロパティーの値に用いられるコンテキストを定義する。@container
の値に、idマップと型マップに対応する@id
、@graph
、@type
を含むことができるようになった。@nest
プロパティーを持つことができるようになった。これは、同じ@nest
マッピングを用いてプロパティーを含めるための@nest
に展開する用語を識別する。展開時に、@nest
に展開するプロパティーの値は、それを囲んでいるノード・オブジェクト内に直接含まれているかのように扱われる。@none
キーを持つことができるが、JSON-LD 1.0では文字列キーのみが許されていた。これを@none
キーを許すように更新した。@container
の値は、@set
(@list
ではなく)とともに適切なコンテナ・キーワードを含む配列にすることもできる。これにより、そのようなプロパティー値を常に配列の形式で表現できる。true
の値を持つ@prefix
エントリーが含まれている場合にのみ、短縮時に用語が短縮IRI接頭辞として選択される。1.0のアルゴリズムが更新され、URIのgen-delim文字で終わる値にマッピングされる用語のみを考慮するようになった。@graph
に設定した@container
を持つプロパティーの値は、暗黙的な名前付きグラフとして解釈され、関連付けられているグラフ名は新しい空白ノード識別子から割り当てられる。他の組み合わせには、["@container", "@id"]
、["@container", "@index"]
が含まれ、それぞれに"@set"
を含むことができる。これは、インデックス・マップおよびidマップと同様に、グラフ識別子またはインデックス値からマップを作成する。さらに、§ F. JSON-LDコミュニティグループ最終報告以後の変更を参照してください。
この項は非規範的です。
@type
の値、または@type
のエイリアスは、@container
を@set
に設定して、@type
エントリーを常に確実に配列として表現できるようになった。これにより、@type
に用語を定義することもでき、その値は@container
を@set
に設定したマップでなければならない(MUST)。"@type": "@none"
に対するサポートを用語定義に追加した。rdf:JSON
データ型を定義。application/ld+json;profile=http://www.w3.org/ns/json-ld#frame
という型を用いて識別される。@type
の値にも使用できる。これは、関連付けられている型を含むノード・オブジェクトに用いるコンテキストを定義する。@propagate
エントリーを用いて制御できる。@import
エントリーを含むことができ、これにより、本来はJSON-LD 1.0
用に作成されたコンテキストにJSON-LD 1.1
の機能を追加できる。alternate
リンク関係を用いてJSON-LDドキュメントを取得するための代替の位置を指定できる。@direction
がサポートされるようになった。json-ld-1.0
に明示的に設定していない場合は、処理モードは暗黙的にjson-ld-1.1
になった。"@"1*ALPHA
)の形式の用語に対する前方互換性の課題について警告。i18n
データ型またはrdf:CompoundLiteral
を作成する場合、実装間の相互運用性を向上させるために、言語タグは小文字に正規化される。この項は非規範的です。
"@prefix": false
の動作を記述するように§ 4.1.5 短縮IRIを拡張し、これは短縮IRIの展開と短縮IRIへのIRIの短縮の両方に影響することを注記。@index
キーワードの欠落している規範的な定義を§ 9.15.1 展開用語定義に追加。rdf:JSON
データ型のrdf:JSON
というデータ型の規範的な定義を変更し、規範的な正規化について記述。これは課題323への応答。i18n
名前空間のi18n
ベースのデータ型および§ 10.4 rdf:CompoundLiteral
クラスおよびrdf:language
とrdf:direction
のプロパティーのrdf:CompoundLiteral
クラスの非規範的な定義を更新し、RDFの生成時に言語タグを小文字に正規化。この項は非規範的です。
@embed
キーワードの規範的な記述から意図せずに逸脱していた§ 9.3 フレーム・オブジェクトの誤記を修正。これは、課題358への応答。この項は非規範的です。
編集者は、この仕様の作成と編集に多大な貢献をしてくださった次の方々に特に感謝申し上げます。
さらに、発表時のワーキンググループのメンバーは次の方々でした。
メーリング・リストや週次のテレビ会議による多くの技術的な課題に対する取り組みに関し、JSON-LDコミュニティ・グループの参加者であるChris Webber、David Wood、Drummond Reed、Eleanor Joslin、Fabien Gandon、Herm Fisher、Jamie Pitts、Kim Hamilton Duffy、Niklas Lindstrom、Paolo Ciccarese、Paul Frazze、Paul Warren、Reto Gmur、Rob Trainer、Ted Thibodeau Jr.、Victor Charpenayに厚く御礼申し上げます。