【注意】 このドキュメントは、W3CのJSON-LD 1.1 Framing : An Extension to the Application Programming Interface for the JSON-LD Syntax W3C Recommendation 16 July 2020の和訳です。
このドキュメントの正式版はW3Cのサイト上にある英語版であり、このドキュメントには翻訳に起因する誤りがありえます。誤訳、誤植などのご指摘は、訳者までお願い致します。
First Update: 2021年8月3日
公開以後に報告されたエラーや問題がないか正誤表を確認してください。
翻訳版も参照してください。
このドキュメントは、規範以外の形式でも入手できます: EPUB
Copyright © 2010-2020 W3C® (MIT, ERCIM, Keio, Beihang). W3C liability, trademark and permissive document license rules apply.
JSON-LDフレーム化により、開発者は例を用いてクエリを実行し、JSON-LDドキュメントに特定のツリー・レイアウトを適用させることができます。
この仕様で記述しているのは、JSON-LDフレーム化1.0[JSON-LD10-FRAMING]で定義している機能の上位集合であり、特に明記していない限り、この仕様のアルゴリズムは、以前のコミュニティ標準を用いて作成されたドキュメントと完全に互換性があります。
この項は、このドキュメントの公開時のステータスについて記述しています。他のドキュメントがこのドキュメントに取って代わることがありえます。現行のW3Cの刊行物およびこの技術報告の最新の改訂版のリストは、https://www.w3.org/TR/のW3C技術報告インデックスにあります。
このドキュメントは、JSON-LDワーキンググループによって開発され、JSON-LDコミュニティ・グループの最終レポートから派生したものです。
このドキュメントで記述している機能を実証できる実演型JSON-LDプレイグラウンドがあります。
このドキュメントは、JSON-LDワーキンググループによって勧告として公開されました。
この仕様の議論にはGitHub Issuesをお勧めします。または、メーリング・リストにコメントを送信することもできます。コメントはpublic-json-ld-wg@w3.org(アーカイブ)に送信してください。
ワーキンググループの実装報告書を参照してください。
このドキュメントは、W3Cメンバー、ソフトウェア開発者、他のW3Cグループ、および他の利害関係者によりレビューされ、W3C勧告として管理者の協賛を得ました。これは確定済みドキュメントであり、参考資料として用いたり、別のドキュメントで引用することができます。勧告の作成におけるW3Cの役割は、仕様に注意を引き付け、広範囲な開発を促進することです。これによってウェブの機能性および相互運用性が増強されます。
このドキュメントは、W3C特許方針の下で活動しているグループによって作成されました。W3Cは、このグループの成果物に関連するあらゆる特許の開示の公開リストを維持し、このページには特許の開示に関する指示も含まれています。不可欠な請求権(Essential Claim(s))を含んでいると思われる特許に関して実際に知っている人は、W3C特許方針の6項に従って情報を開示しなければなりません。
このドキュメントは、2019年3月1日のW3Cプロセス・ドキュメントによって管理されています。
このドキュメントは、JSON-LDワーキンググループが作成した次の3つのJSON-LD 1.1勧告うちの1つです。
この項は非規範的です。
JSON-LDは、JSON[RFC8259]でリンクト・データ[LINKED-DATA]をシリアル化するための軽い構文です。その設計により、既存のJSONを最小限の変更でリンクト・データとして解釈できるようになります。有向グラフを記述する他のリンクト・データの表現と同様に、1つの有向グラフは、まったく同じ情報を表す多くの異なるシリアル化になりえます。開発者は通常、JSONオブジェクトとして表されるツリーで操作を行います。グラフをツリーにマッピングすることはできますが、最終結果のレイアウトを事前に指定する必要があります。フレームを用いると、開発者は、JSON-LDドキュメント上で、グラフの確定的なレイアウトを指定することができます。
データのチャンクの前後に区切り記号を用いることを「フレーム化」といいます。JSON-LDでは、{と}などのJSONの区切り記号を用いて、特定の主語に関するステートメントを区切ります。JSON-LDでは、主語は、文字列として表された識別子を用いて他の主語を参照することもできます。
しかし、JSON-LDは1つ以上の情報のグラフを表すため、いくつかの関連する主語に関するステートメントをまとめて1つのドキュメントにフレーム化する方法は複数あります。実際、情報のグラフは、まったく束ねられていない独立した長いステートメント(別名、トリプル)のリストと考えることができます。
JSON-LDフレーム化APIにより、開発者は、特定の主語に関するステートメントを{と}で区切って束ねたり、関連する主語を、アプリケーションが期待するものと一致する特定のツリー構造に「入れ子」にするなど、データのフレーム化方法を正確に指定できます。
この項は非規範的です。
このドキュメントは、リンクト・データをJSONでシリアル化するための詳細仕様です。このドキュメントは、主に次の読者を対象としています。
関連ドキュメントであるJSON-LD 1.1仕様[JSON-LD11]は、JSON-LDドキュメントの文法を規定しています。
この仕様の基本を理解するためには、まず、[RFC8259]で詳細に説明されているJSONに精通していなければなりません。また、このドキュメントのすべてのアルゴリズムで用いている基本構文であるJSON-LD 1.1構文仕様[JSON-LD11]とJSON-LD 1.1 API [JSON-LD11-API]も理解していなければなりません。APIと、それがプログラミング環境でどのように動作することを目指しているのかを理解するためには、JavaScriptプログラミング言語[ECMASCRIPT]とWebIDL[WEBIDL]の実用的な知識があると便利です。JSON-LDをRDFにマッピングする方法を理解するためには、基本的なRDFの概念[RDF11-CONCEPTS]に精通していると役立ちます。
このドキュメントでは、JSON-LD 1.0バージョン以降の変更点を強調表示できます。変更のを選択してください。
この項は非規範的です。
この仕様の開発に参加していただける方法がいくつかあります。
この項は非規範的です。
この仕様では、表記に関して次の規定を用いています。
マークアップ定義の参照のマークアップ外部定義の参照のマークアップ注は、緑色の左枠線と緑色の「注」という見出しが付いた薄緑色のボックスに入っています。注は常に参考情報です。
Examples are in light khaki boxes, with khaki left border, and with a numbered "Example" header in khaki. Examples are always informative. The content of the example is in monospace font and may be syntax colored. Examples may have tabbed navigation buttons to show the results of transforming an example into other representations.
このドキュメントでは、外部仕様で定義されている次の用語を用いるとともに、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のコンテキスト定義の項を参照してください。@defaultキーを持つマップです。trueかfalse、型付き値、または言語タグ付き文字列です。これは、RDFリテラルを表します。@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)を定義します。@valueエントリーを持つマップです。規範的な記述については、JSON-LD 1.1の値オブジェクトの項を参照してください。nullでなければならない@vocabキーを用いてコンテキスト内で設定されます。規範的な記述については、JSON-LD 1.1のコンテキスト定義の項を参照してください。次の用語を特定のアルゴリズム内で用います。
trueに、reverseフラグはデフォルトでfalseに設定されます。
@graphエントリー内に含めるのか、それとも複数のノード・オブジェクトを表す必要がある場合にのみ含めるのかを決定するフラグ。この仕様では、JSON-LD 1.1構文仕様[JSON-LD11]で定義されているものにいくつかのキーワード(フレーム化キーワード)を追加しています。
@default@embed@embedで有効な値は次のとおりです。
@always@once@embedもオブジェクト組み込みフラグも指定されていない場合は、これがデフォルト値です。
orderedtrueであれば、それは、最初に検出されるノード・オブジェクトになるでしょうし、そうでない場合は、任意のノード・オブジェクトになりえます。@never@embedに対するその他の値は無効であり、invalid @embed valueというエラーが検出されたことを示し、処理が中止されます。
@explicit@nullnullの値を返すべきである場合にフレーム化で用います。そうでない場合は、短縮時に削除されます。@omitDefault@requireAllすべてのJSON-LDのトークンとキーワードは、大文字と小文字を区別します。
この項は非規範的です。
JSON-LD 1.1では、JSON-LD 1.0[JSON-LD10]と互換性のある新機能を導入していますが、JSON-LD 1.0プロセッサで処理すると、異なる結果が作成される可能性があります。プロセッサは、processingMode APIのオプションが明示的にjson-ld-1.0に設定されていない限り、json-ld-1.1にデフォルト設定されます。公開者は、JSON-LD1.0プロセッサがJSON-LD 1.1の機能を誤って解釈しないように、1.1に設定されたコンテキスト内で@versionマップ・エントリーを用いることをお勧めします。
この項は非規範的です。
JSON-LDドキュメントのデータを整形するために、フレーム化を用い、フラット化されたデータをマッチさせるためと、結果として得られるデータの整形方法の例を示すための両方にフレーム・ドキュメントの例を用います。マッチングは、フレーム内に存在するプロパティーを用いて、共通の値を共有するデータ内のオブジェクトを見つけることによって行なわれます。マッチングは、フレーム内に存在するすべてのプロパティーを用いるか、フレーム内の任意のプロパティーを用いるかのいずれかで行うことができます。マッチしたプロパティー値を用いてオブジェクトを連鎖させることで、オブジェクトを互いに組み込むことができます。
フレームにはコンテキストも含まれ、これは、結果として得られるフレーム化した出力を短縮するために用います。
例えば、次のJSON-LDフレームを想定してみましょう。
{
"@context": {"@vocab": "http://example.org/"},
"@type": "Library",
"contains": {
"@type": "Book",
"contains": {
"@type": "Chapter"
}
}
}このフレーム・ドキュメントでは、Libraryという型のオブジェクトを上部に配置し、containsプロパティーを用いてライブラリー・オブジェクトにリンクしたBookという型のオブジェクトをプロパティー値として組み込んだ組み込み構造を記述しています。また、参照しているBookオブジェクト内に、Chapterという型のオブジェクトを、Bookオブジェクトの組み込み値として配置しています。
フレーム要素にマッチするフラット化されたオブジェクトの集合を用いる場合は、次のとおりです。
{
"@context": {
"@vocab": "http://example.org/",
"contains": {"@type": "@id"}
},
"@graph": [{
"@id": "http://example.org/library",
"@type": "Library",
"location": "Athens",
"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-1.0でない場合や、グラフ省略フラグがtrueである場合は、最上位の@graphエントリーを省略できます。
{
"@context": {"@vocab": "http://example.org/"},
"@id": "http://example.org/library",
"@type": "Library",
"location": "Athens",
"contains": {
"@id": "http://example.org/library/the-republic",
"@type": "Book",
"creator": "Plato",
"title": "The Republic",
"contains": {
"@id": "http://example.org/library/the-republic#introduction",
"@type": "Chapter",
"description": "An introductory chapter on The Republic.",
"title": "The Introduction"
}
}
}フレーム化アルゴリズムは、最初に入力フレームとドキュメントの両方を展開することによってこれを行います。次に、フラット化された主語のマップを作成します。フレーム内の最も外側のノード・オブジェクトは、マップ内のオブジェクトをマッチさせるために用います。このケースでは、Libraryという@typeを持ち、そのプロパティーの値をマッチさせるために別のフレームを用いるcontainsプロパティーを持つノード・オブジェクトを探します。入力ドキュメントには、そのようなノード・オブジェクトがきっかり1つだけ含まれています。containsの値にはノード・オブジェクトもあり、これは、Libraryオブジェクトのcontainsという値である主語の集合にマッチするフレームなどとして扱われます。
この項は非規範的です。
型でのマッチングに加えて、フレームは1つ以上のプロパティーでもマッチングを行えます。
例えば、次のフレームは、@typeではなくプロパティー値に基づいてオブジェクトを選択します。
{
"@context": {"@vocab": "http://example.org/"},
"location": "Athens",
"contains": {
"title": "The Republic",
"contains": {
"title": "The Introduction"
}
}
}
プロパティー値はノード・オブジェクトごとに異なるため、これにより、@typeで選択した場合と同じフレーム化の結果が生成されます。
すべてを含むノード・オブジェクトのマッチングなのか、このようなリスト化されたプロパティーのマッチングなのかのマッチングの制限方法については、§ 2.3.5 すべて必要フラグを参照してください。
この項は非規範的です。
空のマップ({})をwildcardとして用います。それにより、特定の値に関係なく、ターゲットのノード・オブジェクトにプロパティーが存在していればマッチします。
例えば、次のフレームは、@typeではなく、プロパティーのワイルドカードに基づいてオブジェクトを選択します。
{
"@context": {"@vocab": "http://example.org/"},
"location": {},
"contains": {
"creator": {},
"contains": {
"description": {}
}
}
}
マッチするプロパティーは各ノード・オブジェクトに固有のものであるため、これにより、@typeで選択した場合と同じフレーム化の結果が生成されます。
この項は非規範的です。
空の配列([])をmatch noneに用います。それにより、プロパティーがターゲットのノード・オブジェクトに存在しない場合にのみノード・オブジェクトにマッチします。
例えば、次のフレームは、@typeではなく、プロパティーの不在に基づいてオブジェクトを選択します。
{
"@context": {"@vocab": "http://example.org/"},
"creator": [],
"title": [],
"contains": {
"location": [],
"description": [],
"contains": {
"location": []
}
}
}
これにより、@typeを選択した場合と同じフレーム化の結果が生成され、除外されたプロパティーは各ノード・オブジェクトを一意に識別します。明示的に除外されたプロパティーには、nullという値のプロパティーが追加されることに注意してください。
この項は非規範的です。
フレームは、特定のプロパティー値の存在に基づいてマッチさせることができます。この値自体はwildcardsを用いて、特定または一連の値、言語タグ、型、基本書字方向でマッチさせることができます。
例として、より複雑な値の表現を持つ多言語バージョンのライブラリーの例を用います。
{
"@context": {
"@vocab": "http://example.org/",
"contains": {"@type": "@id"}
},
"@graph": [{
"@id": "http://example.org/library",
"@type": "Library",
"location": [
{"@value": "Athens", "@language": "en"},
{"@value": "Αθήνα", "@language": "grc"},
{"@value": "Athina", "@language": "el-Latn"}
],
"contains": "http://example.org/library/the-republic"
}, {
"@id": "http://example.org/library/the-republic",
"@type": "Book",
"creator": [
{"@value": "Plato", "@language": "en"},
{"@value": "Πλάτων", "@language": "grc"},
{"@value": "Plátōn", "@language": "el-Latn"}
],
"title": [
{"@value": "The Republic", "@language": "en"},
{"@value": "Πολιτεία", "@language": "grc"},
{"@value": "Res Publica", "@language": "el-Latn"}
],
"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"
}]
}値の属性でマッチングを行うことで、その属性を持つフレームをマッチさせ、マッチしたプロパティー値に結果を限定できます。このケースでは、ラテン字化したギリシャ語(el-Latn)になっている値のみでLibraryとBookのオブジェクトをフレーム化します。
{
"@context": {"@vocab": "http://example.org/"},
"location": {"@value": {}, "@language": "el-Latn"},
"contains": {
"creator": {"@value": {}, "@language": "el-Latn"},
"title": {"@value": {}, "@language": "el-Latn"},
"contains": {
"title": "The Introduction"
}
}
}
これにより、次のフレーム化の結果が生成されます。
@idによるマッチングこの項は非規範的です。
フレームは、特定の識別子(@id)と一致した場合に、マッチさせることができます。これは、特定の@id値にマッチするフレームを用いた、元のフラット化されたライブラリー・オブジェクトの入力で例示できます。
{
"@context": {"@vocab": "http://example.org/"},
"@id": "http://example.org/library",
"contains": {
"@id": "http://example.org/library/the-republic",
"contains": {
"@id": "http://example.org/library/the-republic#introduction"
}
}
}
これにより、次のフレーム化の結果が生成されます。
フレームは、識別子の配列からマッチさせることもできます。フレーム内では、@idは配列値を持つことが許されています。その場合、個々の値はIRIとして扱われます。
{
"@context": {"@vocab": "http://example.org/"},
"@id": ["http://example.org/home", "http://example.org/library"],
"contains": {
"@id": ["http://example.org/library/the-republic"],
"contains": {
"@id": ["http://example.org/library/the-republic#introduction"]
}
}
}
これにより、次のフレーム化の結果が生成されます。
この項は非規範的です。
空のフレームは、そのオブジェクトが他の場所で組み込まれていても、任意のノード・オブジェクトとマッチするため、最上位でシリアル化されます。
{
"@context": {"@vocab": "http://example.org/"}
}
これにより、次のフレーム化の結果が生成されます。
この項は非規範的です。
フレームは、入力ファイルに存在しないプロパティーを指定できます。明示的な包含フラグがfalseであれば、フレーム化アルゴリズムは結果にプロパティーと値を追加します。ノード・オブジェクトや値オブジェクト、または@typeの値としての@defaultプロパティーは、結果として得られる出力ドキュメントで用いるデフォルト値を提供します。@defaultという値がなければ、プロパティーはnullという値で出力されます。(これを回避する方法については、§ 2.3.3 デフォルト省略フラグを参照してください)。
フレーム内のプロパティーの値は、それ以外には出力ドキュメントで用いられません。その目的は、フレームのマッチングとデフォルト値の発見です。次の例のLibraryのdescriptionの値に注目してください。
{
"@context": {"@vocab": "http://example.org/"},
"@type": "Library",
"description": "A great Library.",
"contains": {
"@type": "Book",
"description": {"@default": "A great book."},
"contains": {
"@type": "Chapter"
}
}
}
他のプロパティーと同様に、デフォルト値を@typeに用いることもできます。このケースでは、@typeなしにマッチしたノード・オブジェクトは、フレームからデフォルト・オブジェクトの値を取得します。デフォルト・オブジェクトは、1つのIRIである値を持ちます。複数のIRIが指定されている場合は、最初のIRIのみがデフォルトの型として用いられます。
フレームは特定のプロパティー値を持つオブジェクトとマッチし、マッチしたオブジェクトに@typeのデフォルトを提供します。
{
"@context": {"@vocab": "http://example.org/"},
"@type": "Library",
"contains": {
"@type": {"@default": "Book"},
"creator": "Plato",
"contains": {
"@type": {"@default": "Chapter"},
"description": "An introductory chapter on The Republic."
}
}
}
@typeに特定の値が欠落しているが、他のプロパティー値に基づいてマッチするデータ。
{
"@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",
"creator": "Plato",
"title": "The Republic",
"contains": "http://example.org/library/the-republic#introduction"
}, {
"@id": "http://example.org/library/the-republic#introduction",
"description": "An introductory chapter on The Republic.",
"title": "The Introduction"
}]
}この項は非規範的です。
フレーム化は、APIのオプションを用いるか、§ 1.5 構文トークンとキーワードで記述されているようにフレーム内にフレーム化キーワードを追加することで制御できます。
キーワードを用いて設定されたフレーム化のフラグは、それが出現するフレームと、フレーム・オブジェクトが存在しないオブジェクト用に作成された暗黙的なフレームに対してのみ有効です。
この項は非規範的です。
オブジェクト組み込みフラグは、参照されているノード・オブジェクトを参照オブジェクトのプロパティー値として組み込むか、ノード参照として保持するかを決定します。オブジェクト組み込みフラグの初期値は、embed@once値に基づく次のフレームについて考えてみてください。
{
"@context": {"@vocab": "http://example.org/"},
"@type": "Library"
}(明示的な包含フラグがfalseであることに加えて)オブジェクト組み込みフラグのデフォルトは@onceであるため、列挙されていないプロパティーが出力に追加され、デフォルトの空のフレームを用いて暗黙的に組み込まれます。その結果、orderedtrueであると仮定すると、上記のフレーム化されたライブラリー・オブジェクで用いられているものと同じ出力が生成されます。
しかし、@embedプロパティーを@neverの値で明示的に追加すれば、BookとChapterの値は除外されます。
{
"@context": {"@vocab": "http://example.org/"},
"@type": "Library",
"contains": {
"@type": "Book",
"@embed": "@never"
}
}
@onceが値を展開しないケースを例示するために、本が二重にインデックス化されている別のライブラリーの例について考えてみてください。
{
"@context": {
"@vocab": "http://example.org/",
"books": {"@type": "@id"},
"contains": {"@type": "@id"}
},
"@graph": [{
"@id": "http://example.org/library",
"@type": "Library",
"books": "http://example.org/library/the-republic",
"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"
}]
}@onceというデフォルトの@embedで、同じフレームを用いてフレーム化した場合、orderedtrueであれば、"books"プロパティーのみがコンテンツを持ち、"contains"プロパティーは参照を用います。
"@embed": "@always"を用いたフレームを用いれば、両方のプロパティーには展開された値が含まれます。
{
"@context": {"@vocab": "http://example.org/"},
"@type": "Library",
"@embed": "@always"
}
この項は非規範的です。
出力ドキュメントに含まれるプロパティーを決定するために用いる明示的な包含フラグ。デフォルト値はfalseで、これは、関連付けられているフレーム内にはない入力ノード・オブジェクトに存在するプロパティーが出力オブジェクトに含まれることを意味します。trueの場合は、入力フレームに存在するプロパティーのみが出力に配置されます。明示的な包含フラグの初期値は、explicit
例えば、入力からの一部のプロパティーは含まれているけれども、その他のプロパティーは省略されているライブラリー・フレームの展開バージョンについて考えてみてください。
{
"@context": {"@vocab": "http://example.org/"},
"@type": "Library",
"description": {},
"contains": {
"@type": "Book",
"@explicit": true,
"title": {},
"contains": {
"@type": "Chapter"
}
}
}
結果として得られる出力では、フレーム・オブジェクトに明示的に列挙されていないBookのプロパティーが除外されます。
Libraryオブジェクトにnullというdescriptionプロパティーが含まれていますが、これは、"description": {}を用いてフレーム内で明示的に呼び出されているためであることに注意してください。creatorプロパティーは、明示的ではないため、出力には存在しません。
この項は非規範的です。
デフォルト省略フラグは、フレームに記述されているプロパティーが入力ドキュメントに存在しない場合に、フレーム化が出力を生成する方法を変更します。デフォルト省略フラグの初期値は、omitDefault
次の入力ドキュメントについて考えてみてください。
{
"@context": {
"@vocab": "http://example.org/",
"child": {"@type": "@id"}
},
"@graph": [{
"@id": "http://example.org#John",
"@type": "Person",
"name": "John",
"child": "http://example.org#Jane"
}, {
"@id": "http://example.org#Jane",
"@type": "Person",
"name": "Jane"
}]
}
デフォルト省略フラグが有用な場合を例示するために、@omitDefaultを用いない次のフレームについて考えてみてください。
{
"@context": {
"@vocab": "http://example.org/",
"child": {"@type": "@id"}
},
"@type": "Person",
"child": {
"@embed": "@always"
}
}
結果として得られる出力には、値がnullの「子」プロパティーが含まれますが、これは必ずしも望ましいものではありません。
"@embed": "@always"というオプションが子プロパティーの下のフレームで指定されているため、その"child": nullが、そのプロパティーを持たないマッチングに対する出力に出現しますが、これは望ましくない場合があることに注意してください。このデフォルトのnullの出力が発生しないようにするには、次のように@omitDefaultをtrueに設定できます。
{
"@context": {
"@vocab": "http://example.org/",
"child": {"@type": "@id"}
},
"@type": "Person",
"child": {
"@embed": "@always",
"@omitDefault": true
}
}
これにより、次の(望ましい)出力が得られます。
この項は非規範的です。
グラフ省略フラグは、1つのノード・オブジェクトを含んでいるフレーム化された出力を@graph内に含むかどうかを決定します。グラフ省略フラグの初期値は、omitGraphjson-ld-1.0であれば、出力には常に@graphエントリーが含まれ、そうでない場合は、@graphエントリーは、短縮と整合的に、複数のノード・オブジェクトを記述するためにのみ用いられます。詳細については、§ 4.1 フレーム化アルゴリズムを参照してください。
結果は元のフラット化したライブラリー・オブジェクトの例と同じですが、最上位に@graphがあります。例5は、グラフ省略フラグをtrueに設定した結果を示しており、これは、処理モードがデフォルトのjson-ld-1.1に設定されている場合のデフォルト値です。処理モードをjson-ld-1.0に設定するか、グラフ省略フラグをfalseに設定することで、最上位のオブジェクトを@graphで囲むことができます。
この項は非規範的です。
すべて必要フラグは、どのような場合に入力ドキュメントのノード・オブジェクトがフレームとマッチするかを決定するためにフレームのマッチングで用います。マッチング時に、オブジェクトには@typeなどのプロパティーが含まれている場合があり、すべて必要フラグの値がfalse(デフォルト)であれば、オブジェクト内の任意のプロパティー値がフレーム・オブジェクト内のnode patternとマッチした場合にマッチングが成立します。フラグの値がtrueであれば、ノードがマッチするためには、フレーム・オブジェクト内のすべてのプロパティーがノード・オブジェクトに存在していなければなりません。
次のフレームは、プロパティーの不在を含む複数のプロパティーでマッチします。フラット化されたライブラリー・オブジェクトの例を用いると、タイトルと内容記述の両方またはタイトルと作成者のプロパティーを含むオブジェクトでマッチングを行うことができます。falseに設定した@requireAllを用いると、すべてのプロパティーの存在ではなく、任意のプロパティーの存在に基づいてマッチングを行うことができます。
{
"@context": {"@vocab": "http://example.org/"},
"@type": "Library",
"contains": {
"@requireAll": true,
"creator": {},
"title": {},
"contains": {
"@requireAll": true,
"description": {},
"title": {}
}
}
}
これにより、再び望ましいフレーム化された出力が再生されます。
この項は非規範的です。
フレームには、@reverse、または@reverseを用いて定義した用語の値を含めて、出力オブジェクトの関係を反転させることができます。例えば、ライブラリーの例は、次のフレームを用いて反転できます。
{
"@context": {
"@vocab": "http://example.org/",
"within": {"@reverse": "contains"}
},
"@type": "Chapter",
"within": {
"@type": "Book",
"within": {
"@type": "Library"
}
}
}
上記のフラット化されたライブラリーの例を用いると、次のような結果になります。
通常のプロパティーと逆のプロパティーの間には非対称性が存在します。通常、ノード・オブジェクトをフレーム化する場合、明示的な包含フラグが設定されていなければ、ノードのすべてのプロパティーが出力に含まれますが、逆プロパティーは、実際にはノードのプロパティーではないため、含まれません。
出力に逆プロパティーを含めるためには、それをフレームに明示的に追加します。逆の関係が存在しない場合は、シンプルに出力から除外されることに注意してください。
この項は非規範的です。
フレームに@graphを含めることができ、これにより、JSON-LDドキュメント内に含まれる名前付きグラフの情報を適切なグラフのコンテキスト内で公開できます。デフォルトでは、フレーム化は、入力内のすべてのグラフのすべてのノード・オブジェクトで構成されるmerged graph(統合グラフ)を用います。フレーム内で@graphを用いることにより、入力ドキュメント内に含まれている名前付きグラフの情報を出力ドキュメントに明確に含めることができます。
次の例では、ライブラリーのテーマのバリエーションを用いており、デフォルトのグラフとhttp://example.org/graphs/booksという名前のグラフとに情報を分割しています。
{
"@context": {"@vocab": "http://example.org/"},
"@type": "Library",
"contains": {
"@id": "http://example.org/graphs/books",
"@graph": {
"@type": "Book"
}
}
}
[{
"@context": {"@vocab": "http://example.org/"},
"@id": "http://example.org/graphs/books",
"@graph": [{
"@id": "http://example.org/library/the-republic",
"@type": "http://example.org/Book",
"http://example.org/contains": {
"@id": "http://example.org/library/the-republic#introduction"
},
"http://example.org/creator": "Plato",
"http://example.org/title": "The Republic"
}, {
"@id": "http://example.org/library/the-republic#introduction",
"@type": "http://example.org/Chapter",
"http://example.org/description": "An introductory chapter on The Republic.",
"http://example.org/title": "The Introduction"
}]
}, {
"@context": {"@vocab": "http://example.org/"},
"@id": "http://example.org/library",
"@type": "http://example.org/Library",
"http://example.org/contains": {"@id": "http://example.org/graphs/books"},
"http://example.org/name": "Library"
}]非規範的と記している項と同じく、この仕様のすべての作成ガイドライン、図、例、注は、非規範的です。この仕様のその他の部分はすべて規範的です。
このドキュメントの「することができる／してもよい(MAY)」、「しなければならない(MUST)」、「してはならない(MUST NOT)」、「すべきである／する必要がある(SHOULD)」、「すべきでない／する必要がない(SHOULD NOT)」というキーワードは、ここで示しているように、すべて大文字で表示されている場合にのみ、BCP 14[RFC2119] [RFC8174]で記述されているように解釈されるべきです。
この仕様への適合性を主張できるレベルの成果物が1つあります: JSON-LDプロセッサ
適合JSON-LDプロセッサは、この仕様で定義しているアルゴリズムと整合性のある方法でフレーム化の操作を実行できるシステムです。
JSON-LDプロセッサは、不正な形式のIRIや言語タグを修正しようとしてはなりません(MUST NOT)が、妥当性に関する警告を出すことができます(MAY)。IRIには、相対IRIと絶対IRIの間の変換以外の変更は行われません。
processingMode APIのオプションを用いて指定されていない限り、処理モードはローカル・コンテキストの@versionエントリーを用いて設定され、展開や短縮などのアルゴリズムの動作に影響を与えます。一度設定すれば、異なる処理モードに変更しようとするとエラーになり、プロセッサはprocessing mode conflictエラーを生成して、それ以降の処理は中止しなければなりません(MUST)。
この仕様のアルゴリズムは概して、効率よりも明確さを重視して記述しています。したがって、JSON-LDプロセッサは、最終的な結果が仕様のアルゴリズムによって得られる結果と区別がつかないものである限り、この仕様で指定しているアルゴリズムを任意の望ましい方法で実装できます(MAY)。
キーワードの操作を記述するアルゴリズムのステップでは、このステップはキーワードのエイリアスにも適用されます。
実装者は、JSON-LDフレーム化テスト・スイートのテスト・ケースに合格することで、この仕様への適合レベルを部分的に確認できます。しかし、テスト・スイートのすべてのテストに合格しても、この仕様に完全に準拠しているとは限らないことに注意してください。それは、実装がテスト・スイートでテストを行った側面に準拠していることを意味するだけです。
以下の項では、JSON-LDドキュメントをフレーム化するためのアルゴリズムについて説明します。フレーム化は、情報のグラフを表すJSON-LDドキュメントを取得し、(フレームと呼ばれる)特定のグラフ・レイアウトを適用するプロセスです。
フレーム化は、ノード・マップ生成アルゴリズムを用いて、JSON-LDドキュメントで定義されている各オブジェクトをフラット化された主語のマップに配置し、フレーム化アルゴリズムで操作できるようにします。
この項で記述しているすべてのアルゴリズムは、言語本来のデータ構造で動作することを意図しています。つまり、テキスト・ベースのJSONドキュメントへのシリアル化は、これらのアルゴリズムへの入力や出力としては必要ありません。
JSONデータ構造への参照は、アルゴリズムを記述する目的のために、内部表現を用いて解釈されます。
有効なJSON-LDフレームは、有効なJSON-LDドキュメントの上位集合であり、それによって追加のコンテンツが可能となり、展開を通じて保存されます。JSON-LD 1.1構文仕様[JSON-LD11]で定義されている文法を次のように拡張しています。
@defaultの値には、IRIに展開されるエントリ・キーの値の文法で許されているその他の値に加えて、@nullという値、または@nullのみが含まれている配列を含むことができます(MAY)。プロセッサは、展開時にこの値を保存しなければなりません(MUST)。デフォルト・オブジェクトの他のエントリーはすべて無視しなければなりません(MUST)。@idと@typeの値は、空のマップ、IRI参照、空のマップのみが含まれている配列、またはIRI参照の配列でもありえます。@typeの値は、@defaultエントリーを持つマップでもありえ(MAY)、その値はIRIによって制限されます。プロセッサは、展開時にこの値を保存しなければなりません(MUST)。@graphエントリーが含まれているかどうかに応じて、入力ドキュメントに含まれている統合されたノード定義か、デフォルト・グラフのいずれかで動作します。フレーム・オブジェクトに@graphが含まれている場合、名前付きグラフでもある主語を持つノードは、関連付けられている名前付きグラフからノード・オブジェクトにフレーム化を拡張します。フレーム化アルゴリズムは、5つの必須の入力変数と1つのオプションの入力変数を取ります。必須の入力は、フレーム化の状態(state)、フレーム化するsubjectsのリスト、入力フレーム(expanded frame)、部分的なフレーム結果の収集に用いるparent、そして、active propertyです。オプションの入力変数はordered
アルゴリズムは、要素が配列の場合はparentに要素を追加する、または要素がマップの場合はparentのactive propertyに関連付けられている配列に要素を追加するのいずれかにより、要素をparentに追加します。parentが配列であればactive propertyはnullでなければならず(MUST)、マップであればnullであってはならない(MUST NOT)ことに注意してください。
invalid frameエラーが検出され、処理が中止されます。
@embed、@explicit、@requireAllの任意のプロパティー値から上書きします。orderedtrueであれば、idで辞書順に並べます。
@idとidを用いてoutputを新しいマップに初期化します。falseで、state内のgraph nameとidに関連付けられているparentに既存の組み込みノードがあれば、このnodeには追加の処理を行いません。trueで、embedが@neverであるか、組み込みによって循環参照が作成されるかのいずれかであれば、outputをparentに追加し、このnodeには追加の処理を行いません。trueで、embedが@onceで、state内のgraph nameとidに関連付けられているparentに既存の組み込みノードがあれば、outputをparentに追加し、このnodeには追加の処理を行いません。@includedエントリーがあれば、組み込みフラグの値をfalseに、subjects、frame、outputをparentとして、@includedをactive propertyとして設定したstateのコピーを用いてアルゴリズムを呼び出します。orderedtrueであれば、propertyで辞書順に並べます。
trueであれば、
プロセッサはpropertyの値をoutputに追加してはならず(MUST NOT)、次のステップはスキップします。@listプロパティーを持つマップであれば、リスト内の各listitemは順に処理され、出力の新しいリストのマップに追加されます。
trueに、listitemの@idの値を新しいsubjects配列の唯一のアイテムとして、frame内の@listの最初の値をframeとして、listをparentとして、@listをactive propertyとして設定したstateのコピーを用いてアルゴリズムを呼び出します。frameが存在していなければ、embed、explicit、requireAllから取得した@embed、@explicit、@requireAllに対するプロパティーを持つ新しいマップを用いて新しいframeを作成します。@listに追加します。trueに、itemの@idの値を新しいsubjects配列の唯一のアイテムとして、frame内のpropertyの最初の値をframeとして、outputをparentとして、propertyをactive propertyとして設定したstateのコピーを用いてアルゴリズムを呼び出します。frameが存在していなければ、embed、explicit、requireAllから取得した@embed、@explicit、@requireAllに対するプロパティーを持つ新しいマップを用いて新しいframeを作成します。trueである@omitDefaultが含まれているか、@omitDefaultが含まれておらず、state内のデフォルト省略フラグの値がtrueであれば、propertyとproperty frameをスキップします。@preserveプロパティーと、存在する場合はframe内の@defaultの値のコピーである値、または、そうでない場合は@nullという文字列を持つ新しいマップを用いて、propertyをoutputに追加します。@reverseプロパティーがあれば、frame内の@reverseの値であるreverse propertyとsub frameごとに、
@reverseプロパティーを作成します。@idであるノード参照が含まれているreverse propertyプロパティーを持つフラット化された主語のマップ内のreverse idとnodeごとに、
フレーム・マッチング・アルゴリズムは、特定のノード・オブジェクトがフレームで設定されている基準にマッチするかどうかを判断するためにフレーム化アルゴリズムの一部として用います。一般的に、ノード・オブジェクトは、@type、@idでのマッチングを満たせば、または、いくつかの異なるプロパティーの1つにマッチすれば、フレームにマッチします。すべて必要フラグがtrueであれば、すべてのプロパティーには、フレームがマッチするデフォルトやマッチングがなければなりません。
展開されたノード・オブジェクトでマッチングが実行されるため、すべての値は配列の形式になります。
ノード・マッチングでは、JSON構成子の組み合わせを用いて、任意の値、ゼロ、またはいくつかの特定の値にマッチングを行います。
[] (match none)[frame object] (node pattern)[IRI+]@typeと@idでのマッチングに用いる、IRI形式の1つ以上の文字列。これにより、列挙されているIRIのいずれかとのマッチングが可能になります。[value object] (value pattern)@value、@type、@languageの値は、1つ以上の文字列の値の配列でもありえ、@languageの値は大文字と小文字を区別せずに比較されます。{} (wildcard)フレーム・マッチング・アルゴリズムは、フレーム化の状態(state)、フラット化された主語のマップからマッチングを行う主語のリスト(subjects)、マッチング対象のフレーム(frame)、およびrequireAllフラグを取り、下記のとおり、subjectsの各nodeをフィルタリングすることでマッチした主語のリストを返します。
@idと@typeを含むすべてのプロパティー。ただし、フレームのマッチング時に他のキーワードは考慮されません。
@idであれば、
@idプロパティーにvalues内のIRIが含まれていれば、propertyはマッチします。@typeプロパティーがwildcardmatch none@idプロパティーを確実に持つようになります。したがって、"@id": []というパターンは、どのノード・オブジェクトともマッチしません。"@id": [{}]というパターンは、任意のノード・オブジェクトにマッチし、frameで@idプロパティーをまったく指定しないのと同等です。@typeであれば、
@typeプロパティーにvalues内のIRIが含まれていれば、propertyはマッチします。@typeプロパティーがwildcard@typeプロパティーがmatch none@typeプロパティーがデフォルト・オブジェクトであれば、propertyはマッチします。@idか@typeで、マッチしなければ、nodeはマッチせず、処理は終了します。@defaultエントリーのみが含まれているマップであり、node内のその他のプロパティーにはデフォルトでないマッチングがあります。match nonewildcardvalue pattern(value pattern)であれば、プロパティーのマッチングは、値マッチング・アルゴリズムを用いて決定されます。値パターン・マッチング・アルゴリズムは、フレーム化およびフレーム・マッチングアルゴリズムの一部として用います。特定の値が、値オブジェクトのプロパティーごとに配列形式を用いて定義された値の集合とマッチングできるようにすることに加えて、値オブジェクトは、@value、@type、@languageでmatch nonewildcard
アルゴリズムは、value pattern(pattern)と値オブジェクト(value)をパラメーターとして取ります。値は、次のアルゴリズムを用いてパターンとマッチします。
@value、@type、@languageの値とし、なにも存在していなければnullとします。その場合、@languageの値は小文字に正規化します。@value、@type、@languageの値とし、なにも存在していなければnullとします。その場合、@languageの文字列の値は小文字に正規化します。wildcardwildcardwildcardnullでありt2がnullかmatch nonewildcardnullでありl2がnullかmatch noneこのAPI(Application Programming Interface)は、開発者がJSON-LDデータを様々なプログラミング言語で容易に扱える様々な出力形式に変換できるようにするクリーンな仕組みを提供します。JSON-LD APIをプログラミング環境で提供する場合は、次のAPIの全体を実装しなければなりません(MUST)。
JSON-LD APIは、Promisesを用いて、様々な遅延演算の結果を表します。Promisesは[ECMASCRIPT]で定義されています。仕様内での一般的な使用方法は、[promises-guide]にあります。実装は、一般的に同じメソッド、引数、オプションを用い、同じ結果を返す限り、ネイティブな環境に適した方法で実装することを選択できます(MAY)。
インターフェイスには[Exposed=JsonLd]と記述され、それによってグローバルなインターフェイスが作成されます。JSON-LDにおけるWebIDLの使用は、ブラウザー内での使用には適していますが、そのような使用に限定されてはいません。
JSON-LDプロセッサのインターフェイスは、開発者がJSON-LD変換メソッドにアクセスするために用いるハイレベルなプログラミング構造です。下記の定義は、JSON-LD 1.1 API[JSON-LD11-API]で定義されているインターフェースを実験的に拡張したものです。
実装が入力パラメーターを変更しないことを強調することは重要です。エラーが検出されれば、Promiseは適切なcodeJsonLdFramingErrorで拒否され、処理が停止します。
WebIDL/* * JsonLdインターフェースは、JsonLdProcessorインターフェースを公開するために作成されます。 */ [Global=JsonLd, Exposed=JsonLd] interfaceJsonLd{}; [Exposed=JsonLd] interfaceJsonLdProcessor{constructor(); static Promise<JsonLdRecord>frame(JsonLdInputinput,JsonLdInputframe, optionalJsonLdOptionsoptions = {}); };
JsonLdProcessorインターフェイスのframe()メソッドは、次のフレーム化アルゴリズムのステップに従って、フレームを用いて指定されたinputをフレーム化します。
Promiseであるpromiseを作成し、それを返します。その後、次のステップが非同期で実行されます。orderedfalseに設定したオプションに対してremote documentがなければ、expanded inputをremote documentか入力のいずれかの展開メソッドを用いた結果に設定します。trueに設定し、orderedfalseに設定した入力オプションにremote frameがなければ、expanded frameをremote frameかframeのいずれかの展開メソッドを用いた結果に設定します。@contextの値に、そうでない場合は、新しい空のコンテキストに設定します。documentUrlに、そうでない場合は、オプションからのbaseに設定します。nullに設定します。@graphに展開される最上位のプロパティーがフレームにあれば、frameDefaulttrueであるオプションに設定します。@onceであるembedfalseに設定します。falseであるexplicitfalseであるrequireAllfalseであるomitDefaultframeDefaulttrueであれば、state内のgraph nameを@defaultに設定するか、そうでない場合はfalseに設定します。@mergedであれば、graph map内の@mergedのエントリーを、ノード・マップ統合アルゴリズムがgraph mapを渡した結果に追加します。nullをactive propertyとして渡します。json-ld-1.0でなければ、エントリーの値が、結果内のプロパティー値に1回だけ現れる空白ノード識別子である、results内の各ノード・オブジェクトの@idエントリーを削除します。@preserveである結果のすべての エントリーを、そのエントリーの最初の値に置き換えます。
@preserveを含むマップが効果的にその値に置き換えられます。null、elementとしてのresults、オプションからのcompactArraysとorderedcompactメソッドを用いた結果に設定します。
@nullという値をnullに置き換えます。置換後に、配列にnullという値のみが含まれていれば、その値を削除して、空の配列を残します。omitGraphfalseで、compacted resultsに最上位の@graphエントリーがない、またはその値が配列でない場合は、compacted resultsの@contextでないエントリーを、@graphの配列の値に含まれているマップに配置するように変更します。omitGraphtrueであれば、最上位の@graphエントリーは、複数のノード・オブジェクトを含むためにのみ用いられます。inputのデータを再配置するときに用いるフレーム。マップ形式かIRIとしてのいずれか。JsonLdOptionsWebIDLtypedef record<USVString, any> JsonLdRecord;
JsonLdRecordは、JSONオブジェクトの解析結果である任意のマップ・エントリーを含むために用いるマップの定義です。
WebIDLtypedef (JsonLdRecordor sequence<JsonLdRecord> or USVString or RemoteDocument)JsonLdInput;
JsonLdInputインターフェースは、JsonLdRecord、JsonLdRecordsのsequence、有効なJSONドキュメントを取得するために逆参照できるIRIを表す文字列、またはすでに逆参照されているRemoteDocumentなどの入力値を参照するために用います。
値がJsonLdRecord またはJsonLdRecordsのシーケンスである場合、その値は同等の内部表現の値と見なされ、その場合、JsonLdRecordはマップと同等であり、JsonLdRecordsのシーケンスはマップの配列と同等です。マップ・エントリーは、[INFRA]でそれと同等のものに変換されます。
処理エラーを報告するためにJsonLdFramingError型を用います。
WebIDLdictionaryJsonLdFramingError{JsonLdFramingErrorCodecode; USVString?message= null; }; enumJsonLdFramingErrorCode{ "invalid frame", "invalid @embed value" };
JSON-LDフレーム化は、JSON-LD 1.1処理アルゴリズムとAPI[JSON-LD11-API]で定義されているエラーのインターフェイスとコードを拡張しています。
codemessageJsonLdFramingErrorCode は、有効なJSON-LDフレーム化エラー・コードのコレクションを表します。
invalid @embed value@embedの値は、オブジェクト組み込みフラグに対して認識される値ではありません。invalid frameこの項では、JSON-LDAPI内で用いるデータ型の定義について説明します。
JsonLdContext型は、マップ、IRIを表す文字列、またはマップと文字列の配列でありえる値を参照するために用います。
JSON-LD 1.1 API[JSON-LD11-API]のJsonLdContextの定義を参照してください。
JsonLdOptions型は、様々なオプションをJsonLdProcessorメソッドに渡すために用います。
WebIDLdictionaryJsonLdOptions{ (JsonLdEmbedor boolean)embed= "@once"; booleanexplicit= false; booleanomitDefault= false; booleanomitGraph; booleanrequireAll= false; booleanframeDefault= false; booleanordered= false; }; enumJsonLdEmbed{ "@always", "@once", "@never" };
JSON-LD 1.1 API[JSON-LD11-API]で定義されているオプションに加えて、フレーム化では次の追加オプションを定義しています。
embedtrueというブール値は、フラグを@onceに設定し、falseという値はフラグを@neverに設定します。explicitframeDefaultomitDefaultomitGraphjson-ld-1.0の場合はfalseに、そうでない場合はtrueに設定されます。orderedtrueに設定されていれば、指示されている特定のアルゴリズム処理ステップは辞書順になります。falseであれば、処理において順序は考慮されません。requireAllJsonLdEmbedは、次のembed
@always@never@once@embedとオブジェクト組み込みフラグのいずれも指定されていなければ、これがデフォルト値です。JSON-LD 1.1 API[JSON-LD11-API]のJsonLdOptions定義を参照してください。
§ A. IANAに関する留意点のセキュリティに関する留意点を参照してください。
[JSON-LD11]のプライバシーに関する留意点を参照してください。
[JSON-LD11]の国際化に関する留意点を参照してください。
この項は、標準コミュニティのレビューのためだけに含まれており、この仕様がW3C勧告になれば、インターネット技術運営委員会に提出されます。
JSON-LDフレームは、[JSON-LD11]で記述されているものと同じMIMEメディア・タイプと、必須profileパラメータを用います。
profile資源をJSON-LDフレームとして識別する1つのURI。プロファイルは、プロファイルの知識なしに処理された場合に資源の表現のセマンティクスを変更しないため、プロファイル対象の資源に関してクライアントが知識を持っていてもいなくても同じ表現を安全に使用できます。
http://www.w3.org/ns/json-ld#framedJSON-LDフレーム・ドキュメントを提供およびリクエストする際には、http://www.w3.org/ns/json-ld#framedを用いるべきです(SHOULD)。
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構文と同様に扱われます。
この項は非規範的です。
WebIDL/* * The JsonLd interface is created to expose the JsonLdProcessor interface. */ [Global=JsonLd, Exposed=JsonLd] interfaceJsonLd{}; [Exposed=JsonLd] interfaceJsonLdProcessor{constructor(); static Promise<JsonLdRecord>frame(JsonLdInputinput,JsonLdInputframe, optionalJsonLdOptionsoptions = {}); }; typedef record<USVString, any>JsonLdRecord; typedef (JsonLdRecordor sequence<JsonLdRecord> or USVString or RemoteDocument)JsonLdInput; dictionaryJsonLdFramingError{JsonLdFramingErrorCodecode; USVString?message= null; }; enumJsonLdFramingErrorCode{ "invalid frame", "invalid @embed value" }; dictionaryJsonLdOptions{ (JsonLdEmbedor boolean)embed= "@once"; booleanexplicit= false; booleanomitDefault= false; booleanomitGraph; booleanrequireAll= false; booleanframeDefault= false; booleanordered= false; }; enumJsonLdEmbed{ "@always", "@once", "@never" };
この項は非規範的です。
下記は、公開時点で未解決の課題のリストです。
クラスを範囲としたフレーム化を許可
同じフレーム・ドキュメント内に複数のフレーム?
リフレーム化関係
この項は非規範的です。
@embed)が様々な値を取ることができるようになった。wildcardmatch none@value、@type、@languageの値は、wildcardmatch none@reverseをサポートするようになった。@idに1つ以上の値を用いて、フレーム内の特定のオブジェクトにマッチングを行えるようになった。json-ld-1.0でなければ、その@idにのみ用いられるブランク・ノード識別子を持つ@idエントリーは削除されるようになった。@linkとメモリ内のオブジェクト・リンクのサポートを削除。omitDefaultfalseのordered@reverseを用いた逆プロパティー、または@reverseで定義された用語を含むことができ、これにより、フレームの対象となっているノードを参照しているノードに、逆参照が作成される可能性がある。この項は非規範的です。
falseのorderedapplication/ld-frame+jsonからapplication/ld+jsonに変更し、profileパラメータを必須にした。@idや@typeを含むすべてのプロパティーの存在が必須となった。@onceを優先して、オブジェクト組み込みフラグの@firstと@lastの値を削除。json-ld-1.0に設定されていない限り、処理モードは暗黙的にjson-ld-1.1になった。@typeはデフォルト値を持つことができるが、これはフレーム・マッチングの目的には用いられない。この項は非規範的です。
JsonLdProcessorこの項は非規範的です。
[Exposed=(Window,Worker)] を[Exposed=JsonLd]に変更。これは、レビューの提案に対処するために、ブラウザー以外で用いるJsonLdProcessorこの項は非規範的です。
編集者は、この仕様の作成と編集に多大な貢献をしてくださった次の方々に特に感謝申し上げます。
さらに、発表時のワーキンググループのメンバーは次の方々でした。
メーリング・リストや週次のテレビ会議による多くの技術的な課題に対する取り組みに関し、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に厚く御礼申し上げます。