Home - News ( United States | United Kingdom | Italy | Germany ) - Football scores

Showing content from https://www.asahi-net.or.jp/~ax2s-kmtn/internet/lod/REC-json-ld11-framing-20200716.html below:

JSON-LD 1.1フレーム化

【注意】 このドキュメントは、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日

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 1.1
• JSON-LD 1.1処理アルゴリズムとAPI
• JSON-LD 1.1フレーム化

1. 1. はじめに
   1. 1.1 このドキュメントの読み方
   2. 1.2 貢献
   3. 1.3 表記上の規定
   4. 1.4 用語
      1. 1.4.1 アルゴリズムの用語
   5. 1.5 構文トークンとキーワード
2. 2. 機能
   1. 2.1 フレーム化
      1. 2.1.1 プロパティーによるマッチング
      2. 2.1.2 ワイルドカード・マッチング
      3. 2.1.3 プロパティーの不在によるマッチング
      4. 2.1.4 値によるマッチング
      5. 2.1.5 @idによるマッチング
      6. 2.1.6 空のフレーム
   2. 2.2 デフォルトのコンテンツ
   3. 2.3 フレーム化のフラグ
      1. 2.3.1 オブジェクト組み込みフラグ
      2. 2.3.2 明示的な包含フラグ
      3. 2.3.3 デフォルト省略フラグ
      4. 2.3.4 グラフ省略フラグ
      5. 2.3.5 すべて必要フラグ
   4. 2.4 逆フレーム化
   5. 2.5 名前付きグラフのフレーム化
3. 3. 適合性
4. 4. フレーム化
   1. 4.1 フレーム化アルゴリズム
      1. 4.1.1 概要
      2. 4.1.2 アルゴリズム
   2. 4.2 フレーム・マッチング・アルゴリズム
   3. 4.3 値パターン・マッチング・アルゴリズム
5. 5. API
   1. 5.1 JsonLdProcessor
   2. 5.2 エラー処理
   3. 5.3 データ構造
      1. 5.3.1 JsonLdContext
      2. 5.3.2 JsonLdOptions
6. 6. セキュリティに関する留意点
7. 7. プライバシーに関する留意点
8. 8. 国際化に関する留意点
9. A. IANAに関する留意点
10. B. IDL索引
11. C. 未解決の課題
12. D. 2012年8月30日の1.0草案以後の変更
13. E. JSON-LDコミュニティ・グループ最終レポート以後の変更
14. F. 2019年12月12日の候補リリース以降の変更
15. G. 2020年5月7日の勧告案リリース以後の変更
16. H. 謝辞
17. I. 参考文献
    1. I.1 規範的な参考文献
    2. I.2 参考情報の参考文献

この項は非規範的です。

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ドキュメントにクエリを行い、特定のユースケースに適した表現を作成したい著者。
• JSON-LD用のプロセッサとAPIを実装したいソフトウェア開発者。

関連ドキュメントである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バージョン以降の変更点を強調表示できます。変更のを選択してください。

この項は非規範的です。

この仕様の開発に参加していただける方法がいくつかあります。

• 通常、技術的な議論は公開メーリング・リストであるpublic-json-ld-wg@w3.orgで行われます。
• ワーキンググループは、irc.w3.org上のリアルタイムな議論に利用できる#json-ld IRCチャネルを用いています。
• irc.freenode.net上のリアルタイムな議論にも#json-ld IRCチャネルを利用できます。

この項は非規範的です。

この仕様では、表記に関して次の規定を用いています。

マークアップ

マークアップ(要素、属性、プロパティー)、機械が処理可能な値(文字列、文字、メディア・タイプ)、プロパティー名、またはファイル名は、赤橙色の等幅フォントです。

変数

疑似コードやアルゴリズムの記述内の変数は、イタリック体です。

定義

この仕様や他の仕様の他の場所で用いられている用語の定義は、太字のイタリック体です。

定義の参照

このドキュメント内の定義への参照は下線付きで表しており、それは定義自体へのアクティブ・リンクでもあります。

定義の参照のマークアップ

このドキュメント内の定義への参照は、参照自体がマークアップでもある場合は、下線付きの赤橙色の等幅フォントで表しており、それは定義自体へのアクティブ・リンクでもあります。

外部定義の参照

別ドキュメント内の定義への参照は、下線付きのイタリック体で表しており、それは定義自体へのアクティブ・リンクでもあります。

外部定義の参照のマークアップ

別ドキュメント内の定義への参照は、参照自体がマークアップでもある場合は、下線付きのイタリック体の赤橙色の等幅フォントで表しており、それは定義自体へのアクティブ・リンクでもあります。

ハイパーリンク

ハイパーリンクは、下線付きの青色です。

[参考文献]

ドキュメントの参考文献(規範的または参考情報)は角括弧で囲み、参考文献の項にリンクしています。

勧告以後の変更

以前の勧告から変更した項や表現は、§ 1.1 このドキュメントの読み方の機能を用いて強調表示できます。

注

注は、緑色の左枠線と緑色の「注」という見出しが付いた薄緑色のボックスに入っています。注は常に参考情報です。

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固有の用語も定義しています。

次の用語を特定のアルゴリズム内で用います。

active property(アクティブ・プロパティー)

プロセッサが処理時に用いるべき現在アクティブなプロパティーやキーワード。アクティブ・プロパティーは、元の字句形式で表され、アクティブ・コンテキストで強制マッピングを見つけるために用います。

explicit inclusion flag(明示的な包含フラグ)

出力に含めるべきプロパティーを指定するフラグ。マッチングを行うフレームで明示的に宣言しなければなりません。

framing state(フレーム化の状態)

オブジェクト組み込みフラグ、すべて必要フラグ、オブジェクトの組み込みが適切かどうかを判断するために内部的に用いる組み込みフラグ、明示的な包含フラグ、デフォルト省略フラグの値が含まれているマップ。

input frame(入力フレーム)

フレーム化アルゴリズムに提供される初期フレーム。

IRI compacting(IRI短縮)

active contextを直接指定するか、この用語を用いてアルゴリズムのステップの範囲から取得するかのいずれかの方法で、様々なアルゴリズム内でマクロとして用いて、IRIやキーワードを表す文字列であるvarの短縮プロセスを記述するために用いる言語を削減します。明示的に指定されている場合は、オプションのvalueを用います。特に指定がなければ、vocabフラグはデフォルトでtrueに、reverseフラグはデフォルトでfalseに設定されます。

1. active context、var、(提供されていれば)value、vocab、resultを渡し、IRI短縮アルゴリズムを用いた結果を返します。

JSON-LD input(JSON-LD入力)

アルゴリズムへの入力として提供されるJSON-LDデータ構造。

map of flattened subjects(フラット化された主語のマップ)

ノード・マップ生成アルゴリズムの結果である主語のマップ。

object embed flag(オブジェクト組み込みフラグ)

ノード・オブジェクトをIRIで参照するのではなく、直接出力に組み込むべきであることを指定するフラグ。

omit default flag(デフォルト省略フラグ)

JSON-LD入力にはないが、入力フレームには存在するプロパティーを出力から省略すべきであることを指定するフラグ。

omit graph flag(グラフ省略フラグ)

フレーム化の出力を常に@graphエントリー内に含めるのか、それとも複数のノード・オブジェクトを表す必要がある場合にのみ含めるのかを決定するフラグ。

require all flag(すべて必要フラグ)

フレームがマッチするためには、入力フレームに存在するすべてのプロパティーが、デフォルト値を持っているか、JSON-LD入力に存在しているかのいずれかでなければならないことを指定するフラグ。

この仕様では、JSON-LD 1.1構文仕様[JSON-LD11]で定義されているものにいくつかのキーワード(フレーム化キーワード)を追加しています。

@default

フレーム化されたノード・オブジェクトに出力プロパティーが含まれていない場合に、出力プロパティーのデフォルト値を設定するためにフレーム化で用います。

@embed

特定のフレーム内のオブジェクト組み込みフラグの値を上書きするためにフレーム化で用います。@embedで有効な値は次のとおりです。

@always

循環参照が発生しない限り、常にノード・オブジェクトをプロパティー値として組み込みます。

@once

特定のノード・オブジェクト内の1つの値のみを組み込むべきであり、他のプロパティーのその他の値はノード参照を用います。@embedもオブジェクト組み込みフラグも指定されていない場合は、これがデフォルト値です。

注

組み込むことを選ばれる特定の

ノード・オブジェクト

ã¯ã€é †åºã«ã‚ˆã£ã¦ç•°ãªã‚Šã¾ã™ã€‚

ordered

フラグが

true

であれば、それは、最初に検出される

ノード・オブジェクト

ã«ãªã‚‹ã§ã—ã‚‡ã†ã—ã€ãã†ã§ãªã„å ´åˆã¯ã€ä»»æ„ã®ãƒŽãƒ¼ãƒ‰ãƒ»ã‚ªãƒ–ã‚¸ã‚§ã‚¯ãƒˆã«ãªã‚Šãˆã¾ã™ã€‚

@never

マッチする値をシリアル化する際に、常にノード参照を用います。

@embedに対するその他の値は無効であり、invalid @embed valueというエラーが検出されたことを示し、処理が中止されます。

@explicit

特定のフレーム内の明示的な包含フラグの値を上書きするためにフレーム化で用います。

@null

nullの値を返すべきである場合にフレーム化で用います。そうでない場合は、短縮時に削除されます。

@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"
  }]
}

フレーム・アルゴリズムにより、フレームの構造に従った新しいドキュメントを作成できます。

{
  "@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"
    }
  }
}

処理モードが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で選択した場合と同じフレーム化の結果が生成されます。

{
  "@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"
    }
  }
}

すべてを含むノード・オブジェクトのマッチングなのか、このようなリスト化されたプロパティーのマッチングなのかのマッチングの制限方法については、§ 2.3.5 すべて必要フラグを参照してください。

この項は非規範的です。

空のマップ({})をwildcardとして用います。それにより、特定の値に関係なく、ターゲットのノード・オブジェクトにプロパティーが存在していればマッチします。

例えば、次のフレームは、@typeではなく、プロパティーのワイルドカードに基づいてオブジェクトを選択します。

{
  "@context": {"@vocab": "http://example.org/"},
  "location": {},
  "contains": {
    "creator": {},
    "contains": {
      "description": {}
    }
  }
}

マッチするプロパティーは各ノード・オブジェクトに固有のものであるため、これにより、@typeで選択した場合と同じフレーム化の結果が生成されます。

{
  "@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"
    }
  }
}

この項は非規範的です。

空の配列([])をmatch noneに用います。それにより、プロパティーがターゲットのノード・オブジェクトに存在しない場合にのみノード・オブジェクトにマッチします。

例えば、次のフレームは、@typeではなく、プロパティーの不在に基づいてオブジェクトを選択します。

{
  "@context": {"@vocab": "http://example.org/"},
  "creator": [],
  "title": [],
  "contains": {
    "location": [],
    "description": [],
    "contains": {
      "location": []
    }
  }
}

これにより、@typeを選択した場合と同じフレーム化の結果が生成され、除外されたプロパティーは各ノード・オブジェクトを一意に識別します。明示的に除外されたプロパティーには、nullという値のプロパティーが追加されることに注意してください。

{
  "@context": {"@vocab": "http://example.org/"},
  "@id": "http://example.org/library",
  "@type": "Library",
  "location": "Athens",
  "creator": null, 
  "title": null, 
  "contains": {
    "@id": "http://example.org/library/the-republic",
    "@type": "Book",
    "creator": "Plato",
    "description": null, 
    "location": null, 
    "title": "The Republic",
    "contains": {
      "@id": "http://example.org/library/the-republic#introduction",
      "@type": "Chapter",
      "description": "An introductory chapter on The Republic.",
      "location": null, 
      "title": "The Introduction"
    }
  }
}

この項は非規範的です。

フレームは、特定のプロパティー値の存在に基づいてマッチさせることができます。この値自体は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"
    }
  }
}

これにより、次のフレーム化の結果が生成されます。

{
  "@context": {"@vocab": "http://example.org/"},
  "@id": "http://example.org/library",
  "@type": "Library",
  "location": {"@value": "Athina", "@language": "el-Latn"},
  "contains": {
    "@id": "http://example.org/library/the-republic",
    "@type": "Book",
    "creator": {"@value": "Plátōn", "@language": "el-Latn"},
    "title": {"@value": "Res Publica", "@language": "el-Latn"},
    "contains": {
      "@id": "http://example.org/library/the-republic#introduction",
      "@type": "Chapter",
      "description": "An introductory chapter on The Republic.",
      "title": "The Introduction"
    }
  }
}

この項は非規範的です。

フレームは、特定の識別子(@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"
    }
  }
}

これにより、次のフレーム化の結果が生成されます。

{
  "@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"
    }
  }
}

フレームは、識別子の配列からマッチさせることもできます。フレーム内では、@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/"},
  "@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"
    }
  }
}

この項は非規範的です。

空のフレームは、そのオブジェクトが他の場所で組み込まれていても、任意のノード・オブジェクトとマッチするため、最上位でシリアル化されます。

{
  "@context": {"@vocab": "http://example.org/"}
}

これにより、次のフレーム化の結果が生成されます。

{
  "@context": {"@vocab": "http://example.org/"},
  "@graph": [{
    "@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"
      }
    }
  }, {
    "@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"
    }
  }, {
    "@id": "http://example.org/library/the-republic#introduction",
    "@type": "Chapter",
    "description": "An introductory chapter on The Republic.",
    "title": "The Introduction"
  }]
}

この項は非規範的です。

フレームは、入力ファイルに存在しないプロパティーを指定できます。明示的な包含フラグが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"
    }
  }
}

{
  "@context": {"@vocab": "http://example.org/"},
  "@id": "http://example.org/library",
  "@type": "Library",
  "description": null,
  "location": "Athens",
  "contains": {
    "@id": "http://example.org/library/the-republic",
    "@type": "Book",
    "creator": "Plato",
    "description": "A great book.",
    "title": "The Republic",
    "contains": {
      "@id": "http://example.org/library/the-republic#introduction",
      "@type": "Chapter",
      "description": "An introductory chapter on The Republic.",
      "title": "The Introduction"
    }
  }
}

他のプロパティーと同様に、デフォルト値を@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"
  }]
}

{
  "@context": {"@vocab": "http://example.org/"},
  "@graph": [{
    "@id": "http://example.org/library",
    "@type": "Library",
    "contains": {
      "@id": "http://example.org/library/the-republic",
      "@type": "Book",
      "contains": {
        "@id": "http://example.org/library/the-republic#introduction",
        "@type": "Chapter",
        "description": "An introductory chapter on The Republic.",
        "title": "The Introduction"
      },
      "creator": "Plato",
      "description": "A great book.",
      "title": "The Republic"
    }
  }]
}

この項は非規範的です。

フレーム化は、APIのオプションを用いるか、§ 1.5 構文トークンとキーワードで記述されているようにフレーム内にフレーム化キーワードを追加することで制御できます。

注

キーワードを用いて設定されたフレーム化のフラグは、それが出現するフレームと、フレーム・オブジェクトが存在しないオブジェクト用に作成された暗黙的なフレームに対してのみ有効です。

この項は非規範的です。

オブジェクト組み込みフラグは、参照されているノード・オブジェクトを参照オブジェクトのプロパティー値として組み込むか、ノード参照として保持するかを決定します。オブジェクト組み込みフラグの初期値は、embedオプションを用いて設定します。オブジェクト組み込みフラグのデフォルトの@once値に基づく次のフレームについて考えてみてください。

{
  "@context": {"@vocab": "http://example.org/"},
  "@type": "Library"
}

{
  "@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"
    }
  }
}

(明示的な包含フラグがfalseであることに加えて)オブジェクト組み込みフラグのデフォルトは@onceであるため、列挙されていないプロパティーが出力に追加され、デフォルトの空のフレームを用いて暗黙的に組み込まれます。その結果、orderedフラグがtrueであると仮定すると、上記のフレーム化されたライブラリー・オブジェクで用いられているものと同じ出力が生成されます。

しかし、@embedプロパティーを@neverの値で明示的に追加すれば、BookとChapterの値は除外されます。

{
  "@context": {"@vocab": "http://example.org/"},
  "@type": "Library",
  "contains": {
    "@type": "Book",
    "@embed": "@never"
  }
}

{
  "@context": {"@vocab": "http://example.org/"},
  "@id": "http://example.org/library",
  "@type": "Library",
  "location": "Athens",
  "contains": {
    "@id": "http://example.org/library/the-republic"
  }
}

@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"
  }]
}

{
  "@context": {"@vocab": "http://example.org/"},
  "@id": "http://example.org/library",
  "@type": "Library",
  "contains": {"@id": "http://example.org/library/the-republic"},
  "books": {
    "@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"
    }
  }
}

@onceというデフォルトの@embedで、同じフレームを用いてフレーム化した場合、orderedフラグがtrueであれば、"books"プロパティーのみがコンテンツを持ち、"contains"プロパティーは参照を用います。

"@embed": "@always"を用いたフレームを用いれば、両方のプロパティーには展開された値が含まれます。

{
  "@context": {"@vocab": "http://example.org/"},
  "@type": "Library",
  "@embed": "@always"
}

{
  "@context": {"@vocab": "http://example.org/"},
  "@id": "http://example.org/library",
  "@type": "Library",
  "books": {
    "@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"
    }
  },
  "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"
    }
  }
}

この項は非規範的です。

出力ドキュメントに含まれるプロパティーを決定するために用いる明示的な包含フラグ。デフォルト値はfalseで、これは、関連付けられているフレーム内にはない入力ノード・オブジェクトに存在するプロパティーが出力オブジェクトに含まれることを意味します。trueの場合は、入力フレームに存在するプロパティーのみが出力に配置されます。明示的な包含フラグの初期値は、explicitオプションを用いて設定します。

例えば、入力からの一部のプロパティーは含まれているけれども、その他のプロパティーは省略されているライブラリー・フレームの展開バージョンについて考えてみてください。

{
  "@context": {"@vocab": "http://example.org/"},
  "@type": "Library",
  "description": {},
  "contains": {
    "@type": "Book",
    "@explicit": true,
    "title": {},
    "contains": {
      "@type": "Chapter"
    }
  }
}

結果として得られる出力では、フレーム・オブジェクトに明示的に列挙されていないBookのプロパティーが除外されます。

{
  "@context": {"@vocab": "http://example.org/"},
  "@id": "http://example.org/library",
  "@type": "Library",
  "description": null ,
  "location": "Athens",
  "contains": {
    "@id": "http://example.org/library/the-republic",
    "@type": "Book",
    
    "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オブジェクトにnullというdescriptionプロパティーが含まれていますが、これは、"description": {}を用いてフレーム内で明示的に呼び出されているためであることに注意してください。creatorプロパティーは、明示的ではないため、出力には存在しません。

この項は非規範的です。

デフォルト省略フラグは、フレームに記述されているプロパティーが入力ドキュメントに存在しない場合に、フレーム化が出力を生成する方法を変更します。デフォルト省略フラグの初期値は、omitDefaultオプションを用いて設定します。詳細については、§ 2.2 デフォルトのコンテンツを参照してください。

次の入力ドキュメントについて考えてみてください。

{
  "@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の「子」プロパティーが含まれますが、これは必ずしも望ましいものではありません。

{
  "@context": {
    "@vocab": "http://example.org/",
    "child": {"@type": "@id"}
  },
  "@graph": [{
    "@id": "http://example.org#John",
    "@type": "Person",
    "name": "John",
    "child": {
      "@id": "http://example.org#Jane",
      "@type": "Person",
      "name": "Jane"
    }
  }, {
    "@id": "http://example.org#Jane",
    "@type": "Person",
    "name": "Jane",
    "child": null
  }]
}

"@embed": "@always"というオプションが子プロパティーの下のフレームで指定されているため、その"child": nullが、そのプロパティーを持たないマッチングに対する出力に出現しますが、これは望ましくない場合があることに注意してください。このデフォルトのnullの出力が発生しないようにするには、次のように@omitDefaultをtrueに設定できます。

{
  "@context": {
    "@vocab": "http://example.org/",
    "child": {"@type": "@id"}
  },
  "@type": "Person",
  "child": {
    "@embed": "@always",
    "@omitDefault": true
  }
}

これにより、次の(望ましい)出力が得られます。

{
  "@context": {
    "@vocab": "http://example.org/",
    "child": {"@type": "@id"}
  },
  "@graph": [{
    "@id": "http://example.org#John",
    "@type": "Person",
    "name": "John",
    "child": {
      "@id": "http://example.org#Jane",
      "@type": "Person",
      "name": "Jane"
    }
  }, {
    "@id": "http://example.org#Jane",
    "@type": "Person",
    "name": "Jane"
    
  }]
}

この項は非規範的です。

グラフ省略フラグは、1つのノード・オブジェクトを含んでいるフレーム化された出力を@graph内に含むかどうかを決定します。グラフ省略フラグの初期値は、omitGraphというオプションを用いるか、処理モードに基づいて設定されます。処理モードがjson-ld-1.0であれば、出力には常に@graphエントリーが含まれ、そうでない場合は、@graphエントリーは、短縮と整合的に、複数のノード・オブジェクトを記述するためにのみ用いられます。詳細については、§ 4.1 フレーム化アルゴリズムを参照してください。

結果は元のフラット化したライブラリー・オブジェクトの例と同じですが、最上位に@graphがあります。例5は、グラフ省略フラグをtrueに設定した結果を示しており、これは、処理モードがデフォルトのjson-ld-1.1に設定されている場合のデフォルト値です。処理モードをjson-ld-1.0に設定するか、グラフ省略フラグをfalseに設定することで、最上位のオブジェクトを@graphで囲むことができます。

{
  "@context": {"@vocab": "http://example.org/"},
  "@graph": [{
    "@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"
      }
    }
  }]
}

この項は非規範的です。

すべて必要フラグは、どのような場合に入力ドキュメントのノード・オブジェクトがフレームとマッチするかを決定するためにフレームのマッチングで用います。マッチング時に、オブジェクトには@typeなどのプロパティーが含まれている場合があり、すべて必要フラグの値がfalse(デフォルト)であれば、オブジェクト内の任意のプロパティー値がフレーム・オブジェクト内のnode patternとマッチした場合にマッチングが成立します。フラグの値がtrueであれば、ノードがマッチするためには、フレーム・オブジェクト内のすべてのプロパティーがノード・オブジェクトに存在していなければなりません。

次のフレームは、プロパティーの不在を含む複数のプロパティーでマッチします。フラット化されたライブラリー・オブジェクトの例を用いると、タイトルと内容記述の両方またはタイトルと作成者のプロパティーを含むオブジェクトでマッチングを行うことができます。falseに設定した@requireAllを用いると、すべてのプロパティーの存在ではなく、任意のプロパティーの存在に基づいてマッチングを行うことができます。

{
  "@context": {"@vocab": "http://example.org/"},
  "@type": "Library",
  "contains": {
    "@requireAll": true,
    "creator": {},
    "title": {},
    "contains": {
      "@requireAll": true,
      "description": {},
      "title": {}
    }
  }
}

これにより、再び望ましいフレーム化された出力が再生されます。

{
  "@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"
    }
  }
}

この項は非規範的です。

フレームには、@reverse、または@reverseを用いて定義した用語の値を含めて、出力オブジェクトの関係を反転させることができます。例えば、ライブラリーの例は、次のフレームを用いて反転できます。

{
  "@context": {
    "@vocab": "http://example.org/",
    "within": {"@reverse": "contains"}
  },
  "@type": "Chapter",
  "within": {
    "@type": "Book",
    "within": {
      "@type": "Library"
    }
  }
}

上記のフラット化されたライブラリーの例を用いると、次のような結果になります。

{
  "@context": {
    "@vocab": "http://example.org/",
    "within": {"@reverse": "contains"}
  },
  "@id": "http://example.org/library/the-republic#introduction",
  "@type": "Chapter",
  "description": "An introductory chapter on The Republic.",
  "title": "The Introduction",
  "within": {
    "@id": "http://example.org/library/the-republic",
    "@type": "Book",
    "contains": {"@id": "http://example.org/library/the-republic#introduction"},
    "creator": "Plato",
    "title": "The Republic",
    "within": {
      "@id": "http://example.org/library",
      "@type": "Library",
      "location": "Athens",
      "contains": {"@id": "http://example.org/library/the-republic"}
    }
  }
}

注

通常のプロパティーと逆のプロパティーの間には非対称性が存在します。通常、ノード・オブジェクトをフレーム化する場合、明示的な包含フラグが設定されていなければ、ノードのすべてのプロパティーが出力に含まれますが、逆プロパティーは、実際にはノードのプロパティーではないため、含まれません。

出力に逆プロパティーを含めるためには、それをフレームに明示的に追加します。逆の関係が存在しない場合は、シンプルに出力から除外されることに注意してください。

この項は非規範的です。

フレームに@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"
}]

{
  "@context": {"@vocab": "http://example.org/"},
  "@id": "http://example.org/library",
  "@type": "Library",
  "name": "Library",
  "contains": {
    "@id": "http://example.org/graphs/books",
    "@graph": {
      "@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"
      }
    }
  }
}

非規範的と記している項と同じく、この仕様のすべての作成ガイドライン、図、例、注は、非規範的です。この仕様のその他の部分はすべて規範的です。

このドキュメントの「することができる／してもよい(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]で定義されている文法を次のように拡張しています。

• フレーム化により、ノード・オブジェクトのエントリーとして使用できるフレーム化キーワードが追加され、これは、展開時に保存しなくてはなりません(MUST)。
• キーワードではないフレーム・オブジェクトのエントリーの値には、デフォルト・オブジェクトも含むことができます(MAY)。@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)ことに注意してください。

1. frameが配列であれば、frameを配列の値に設定し、これは有効なフレームでなければなりません(MUST)。frameが無効であると判断されれば、invalid frameエラーが検出され、処理が中止されます。
   1. Frameはマップでなければなりません(MUST)。
   2. frameに@idエントリーがあれば、その値は、1つの空のマップが値として含まれている配列、有効なIRI、すべての値が有効なIRIである配列のいずれかでなければなりません(MUST)。
   3. frameに@typeエントリーがあれば、その値は、1つの空のマップが値として含まれている配列、キーが@defaultであるエントリーを持つマップが含まれている配列、有効なIRI、すべての値が有効なIRIである配列のいずれかでなければなりません(MUST)。
2. state内のオブジェクト組み込みフラグ、明示的な包含フラグ、すべて必要フラグからembed、explicit、requireAllのフラグを初期化し、frame内の@embed、@explicit、@requireAllの任意のプロパティー値から上書きします。
3. state、subjects、frame、requireAllでフレーム・マッチング・アルゴリズムを用いてframeに対してsubjectsをフィルタリングすることにより、マッチした主語のリストを作成します。
4. マッチした主語の集合のidおよび関連するノード・オブジェクトのノードごとに、オプションのorderedフラグがtrueであれば、idで辞書順に並べます。
   1. @idとidを用いてoutputを新しいマップに初期化します。
   2. state内の組み込みフラグがfalseで、state内のgraph nameとidに関連付けられているparentに既存の組み込みノードがあれば、このnodeには追加の処理を行いません。
   3. そうでない場合、state内の組み込みフラグがtrueで、embedが@neverであるか、組み込みによって循環参照が作成されるかのいずれかであれば、outputをparentに追加し、このnodeには追加の処理を行いません。
   4. そうでない場合、state内の組み込みフラグがtrueで、embedが@onceで、state内のgraph nameとidに関連付けられているparentに既存の組み込みノードがあれば、outputをparentに追加し、このnodeには追加の処理を行いません。
   5. state内のgraph mapにidのエントリーがあれば、
      1. frameに@graphエントリーがなければ、state内のgraph nameが@mergedでない場合にrecurseをtrueに設定し、subframeを新しい空のマップに設定します。
      2. そうでない場合、subframeをframe内の@graphの最初のエントリーか、それが存在していない場合は新しい空のマップに設定し、idが@mergedか@defaultでなれば、recurseをtrueに設定します。
      3. recurseがtrueであれば、
         1. state内のgraph nameの値をidに設定します。
         2. state内の組み込みフラグの値をfalseに設定します。
         3. graph nameの値をidに設定し、組み込みフラグの値をfalseに、idに関連付けられたstate内のgraph mapからのキーをsubjectsとして、subframeをframeとして、outputをparentとして、@graphをactive propertyとして設定したstateのコピーを用いてアルゴリズムを呼び出します。
   6. frameに@includedエントリーがあれば、組み込みフラグの値をfalseに、subjects、frame、outputをparentとして、@includedをactive propertyとして設定したstateのコピーを用いてアルゴリズムを呼び出します。
   7. node内のpropertyとobjectsごとに、オプションのorderedフラグがtrueであれば、propertyで辞書順に並べます。
      1. propertyがキーワードであれば、propertyとobjectsをoutputに追加します。
      2. そうでない場合、propertyがframe内になく、explicitがtrueであれば、 プロセッサはpropertyの値をoutputに追加してはならず(MUST NOT)、次のステップはスキップします。
      3. objects内のitemごとに、
         1. itemが@listプロパティーを持つマップであれば、リスト内の各listitemは順に処理され、出力の新しいリストのマップに追加されます。
            1. listitemがノード参照であれば、組み込みフラグの値をtrueに、listitemの@idの値を新しいsubjects配列の唯一のアイテムとして、frame内の@listの最初の値をframeとして、listをparentとして、@listをactive propertyとして設定したstateのコピーを用いてアルゴリズムを呼び出します。frameが存在していなければ、embed、explicit、requireAllから取得した@embed、@explicit、@requireAllに対するプロパティーを持つ新しいマップを用いて新しいframeを作成します。
            2. そうでない場合、listitemのコピーをlistの@listに追加します。
         2. itemがノード参照であれば、組み込みフラグの値をtrueに、itemの@idの値を新しいsubjects配列の唯一のアイテムとして、frame内のpropertyの最初の値をframeとして、outputをparentとして、propertyをactive propertyとして設定したstateのコピーを用いてアルゴリズムを呼び出します。frameが存在していなければ、embed、explicit、requireAllから取得した@embed、@explicit、@requireAllに対するプロパティーを持つ新しいマップを用いて新しいframeを作成します。
         3. そうでない場合、itemのコピーをoutputのアクティブ・プロパティーに追加します。
      4. outputにないframe内のキーワードでないpropertyとobjects(`@type以外)ごとに、
         1. itemをobjectsの最初の値とします。これはフレーム・オブジェクトでなければなりません(MUST)。
         2. property frameをobjectsの最初の値に設定するか、値がobjectsであれば新しく作成されたフレーム・オブジェクトに設定します。property frameはマップでなければなりません(MUST)。
         3. property frameに値がtrueである@omitDefaultが含まれているか、@omitDefaultが含まれておらず、state内のデフォルト省略フラグの値がtrueであれば、propertyとproperty frameをスキップします。
         4. @preserveプロパティーと、存在する場合はframe内の@defaultの値のコピーである値、または、そうでない場合は@nullという文字列を持つ新しいマップを用いて、propertyをoutputに追加します。
      5. frameに@reverseプロパティーがあれば、frame内の@reverseの値であるreverse propertyとsub frameごとに、
         1. 新しいマップであるreverse dictを値として用いて、outputに@reverseプロパティーを作成します。
         2. idが@idであるノード参照が含まれているreverse propertyプロパティーを持つフラット化された主語のマップ内のreverse idとnodeごとに、
            1. 新しい空の配列を値として用いて、reverse propertyをreverse dictに追加します。
            2. 組み込みフラグの値をtrueに、reverse idを新しいsubjects配列の唯一のアイテムとして、sub frameをframeとして、nullをactive propertyとして、reverse dict内のreverse propertyの配列の値をparentとして設定したstateのコピーを用いてアルゴリズムを呼び出します。
      6. 前のステップで必要な出力が設定されたら、outputをparentに追加します。

フレーム・マッチング・アルゴリズムは、特定のノード・オブジェクトがフレームで設定されている基準にマッチするかどうかを判断するためにフレーム化アルゴリズムの一部として用います。一般的に、ノード・オブジェクトは、@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を含むすべてのプロパティー。ただし、フレームのマッチング時に他のキーワードは考慮されません。

1. フレームにプロパティーがなければ、nodeがマッチします。
2. requireAllがtrueであれば、frame内のすべてのプロパティー(property)が次のいずれかの条件にマッチする場合にnodeがマッチします。または、requireAllがfalseであれば、フレーム内のプロパティー(property)のいずれかが次のいずれかの条件にマッチする場合。nodeのframeからの各propertyのvaluesでは、
   1. propertyが@idであれば、
      1. フレーム内の@idプロパティーにvalues内のIRIが含まれていれば、propertyはマッチします。
      2. そうでない場合、frame内の@typeプロパティーがwildcardかmatch noneであれば、プロパティーはマッチします。

      注

      フレーム化は

      フラット化された主語のマップ

      で機能し、フラット化を行うことによって、すべての主語が

      @id

      プãƒãƒ‘ティーを確実に持つようになります。したがって、

      "@id": []

      というパターンは、どの

      ノード・オブジェクト

      ともマッチしません。

      "@id": [{}]

      というパターンは、任意の

      ノード・オブジェクト

      にマッチし、

      frame

      で

      @id

      プãƒãƒ‘ティーをまったく指定しないのと同ç‰ã§ã™ã€‚

   2. そうでない場合、propertyが@typeであれば、
      1. フレーム内の@typeプロパティーにvalues内のIRIが含まれていれば、propertyはマッチします。
      2. そうでない場合、valuesが空でなく、frame内の@typeプロパティーがwildcardであれば、propertyはマッチします。
      3. そうでない場合、valuesが空で、frame内の@typeプロパティーがmatch noneであれば、propertyはマッチします。
      4. そうでない場合、フレーム内の@typeプロパティーがデフォルト・オブジェクトであれば、propertyはマッチします。
      5. そうでない場合、propertyはマッチしません。
   3. propertyが@idか@typeで、マッチしなければ、nodeはマッチせず、処理は終了します。
   4. そうでない場合、frame内のpropertyの値は空であるか、有効なフレームが含まれている配列でなければなりません(MUST)。
   5. valuesが空または存在しない場合、propertyはマッチし、frame内のpropertyの値は、任意の値を持つ@defaultエントリーのみが含まれているマップであり、node内のその他のプロパティーにはデフォルトでないマッチングがあります。
   6. valuesが空でなく、frame内のpropertyの値がmatch noneであれば、nodeはマッチせず、それ以降のマッチングは中止されます。
   7. そうでない場合、valuesが空でなく、frame内のpropertyの値がwildcardであれば、propertyはマッチします。
   8. そうでない場合、frame内のpropertyの値がvalue pattern(value pattern)であれば、プロパティーのマッチングは、値マッチング・アルゴリズムを用いて決定されます。
   9. そうでない場合、frame内のpropertyの値の1つであるノード・パターン(node pattern)では、
      1. value subjectsを、valuesからのノード・オブジェクトの値とマッチングしたフラット化された主語のマップからの主語のリストとします。
      2. matched subjectsを、state、subjectsに対するvalue subjects、frameに対するnode pattern、およびrequireAllフラグを用いてこのアルゴリズムを再帰的に呼び出した結果とします。
      3. matched subjectsが空でなければ、propertyはマッチします。
   10. そうでない場合、propertyはマッチしません。

値パターン・マッチング・アルゴリズムは、フレーム化およびフレーム・マッチングアルゴリズムの一部として用います。特定の値が、値オブジェクトのプロパティーごとに配列形式を用いて定義された値の集合とマッチングできるようにすることに加えて、値オブジェクトは、@value、@type、@languageでmatch noneとwildcardを用いて値パターンとマッチします。

アルゴリズムは、value pattern(pattern)と値オブジェクト(value)をパラメーターとして取ります。値は、次のアルゴリズムを用いてパターンとマッチします。

1. v1、t1、l1をvalue内の@value、@type、@languageの値とし、なにも存在していなければnullとします。その場合、@languageの値は小文字に正規化します。
2. v2、t2、l2をvalue pattern内の@value、@type、@languageの値とし、なにも存在していなければnullとします。その場合、@languageの文字列の値は小文字に正規化します。
3. patternがwildcardであれば、valueはpatternとマッチします。または、
   1. v1がv2にあるか、v1がnullでなく、v2がwildcardであり、
   2. t1がt2にあるか、t1がnullではなくt2がwildcardであるか、nullであるか、t1がnullでありt2がnullかmatch noneであり、
   3. l1がl2にあるか、l1がnullではなくl2がwildcardであるか、nullであるか、l1がnullであり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は適切なcodeを持つJsonLdFramingErrorで拒否され、処理が停止します。

[Global=JsonLd, Exposed=JsonLd]
interface JsonLd {};

[Exposed=JsonLd]
interface JsonLdProcessor {
  constructor();
  static Promise<JsonLdRecord> frame(
    JsonLdInput input,
    JsonLdInput frame,
    optional JsonLdOptions options = {});
};

JsonLdProcessorインターフェイスのframe()メソッドは、次のフレーム化アルゴリズムのステップに従って、フレームを用いて指定されたinputをフレーム化します。

1. 新しいPromiseであるpromiseを作成し、それを返します。その後、次のステップが非同期で実行されます。
2. 提供された入力がRemoteDocumentであれば、remote documentを入力に初期化します。
3. そうでない場合、提供された入力がリモート・ドキュメントのIRIを表す文字列であれば、待機してLoadDocumentCallbackを用いてremote documentとしてそれを逆参照し、url用に入力を渡し、オプションからのextractAllScriptsのオプションをextractAllScriptsに渡します。
4. 入力およびorderedをfalseに設定したオプションに対してremote documentがなければ、expanded inputをremote documentか入力のいずれかの展開メソッドを用いた結果に設定します。
5. 提供されたフレームがRemoteDocumentであれば、remote frameをフレームに初期化します。
6. そうでない場合、提供されたフレームがリモート・ドキュメントのIRIを表す文字列であれば、待機してLoadDocumentCallbackを用いてremote frameとしてそれを逆参照し、url用にフレームを渡し、オプションからのextractAllScriptsのオプションをextractAllScriptsに渡します。
7. frameExpansionオプションをtrueに設定し、orderedをfalseに設定した入力オプションにremote frameがなければ、expanded frameをremote frameかframeのいずれかの展開メソッドを用いた結果に設定します。
8. contextを、remote frameかframeが存在していれば、それからの@contextの値に、そうでない場合は、新しい空のコンテキストに設定します。
9. context baseを、利用できる場合は、remote frameからのdocumentUrlに、そうでない場合は、オプションからのbaseに設定します。
10. 新しい空のコンテキストをactive contextとして、contextをlocal contextとして、context baseをbase URLとして渡し、active contextをコンテキスト処理アルゴリズムの結果に初期化します。
11. contextを用いてアクティブ・コンテキストを初期化します。基底IRIは、設定されていれば、オプションからの基底オプションに設定されます。そうでない場合、compactToRelativeというオプションがtrueであれば、利用できる場合は、現在処理中のドキュメントのIRIに、そうでない場合はnullに設定します。
12. inverse contextを、逆コンテキスト作成アルゴリズムを実行した結果に初期化します。
13. @graphに展開される最上位のプロパティーがフレームにあれば、frameDefaultというオプションを値がtrueであるオプションに設定します。
14. 新しいフレーム化の状態(state)を空のマップに初期化します。
    1. state内のオブジェクト組み込みフラグを、デフォルト値が@onceであるembedに設定します。
    2. state内の組み込みフラグをfalseに設定します。
    3. state内の明示的な包含フラグを、デフォルト値がfalseであるexplicitに設定します。
    4. state内のすべて必要フラグを、デフォルト値がfalseであるrequireAllに設定します。
    5. state内のデフォルト省略フラグを、デフォルト値がfalseであるomitDefaultに設定します。
    6. frameDefaultがtrueであれば、state内のgraph nameを@defaultに設定するか、そうでない場合はfalseに設定します。
    7. state内のgraph mapを、expanded inputでノード・マップ生成アルゴリズムを実行した結果に設定します。
       1. state内のgraph nameが@mergedであれば、graph map内の@mergedのエントリーを、ノード・マップ統合アルゴリズムがgraph mapを渡した結果に追加します。
    8. state内のsubject mapを、graph map内のgraph nameの値であるフラット化された主語のマップに設定します。
15. resultsを空の配列として初期化します。
16. フレーム化アルゴリズムを呼び出し、state、subjectsのstate内のsubject mapからのキー、expanded frame、parentのresults、nullをactive propertyとして渡します。
17. 処理モードがjson-ld-1.0でなければ、エントリーの値が、結果内のプロパティー値に1回だけ現れる空白ノード識別子である、results内の各ノード・オブジェクトの@idエントリーを削除します。
18. 再帰的に、キーが@preserveである結果のすべての エントリーを、そのエントリーの最初の値に置き換えます。

    注

    エントリーの値は、1つの値を持つ配列になるでしょう。これにより、@preserveを含むマップが効果的にその値に置き換えられます。

19. compacted resultsを、active context、inverse context、active propertyにnull、elementとしてのresults、オプションからのcompactArraysとorderedフラグを用いてcompactメソッドを用いた結果に設定します。
    1. compacted resultsが空の配列であれば、新しいマップに置き換えます。
    2. そうでない場合、compacted resultsが配列であれば、キーが@graphのIRI短縮の結果であり、値がcompacted resultsである1つのエントリーを持つ新しいマップに置き換えます。
    3. @contextエントリーをcompacted resultsに追加し、その値を提供されたcontextに設定します。
20. 再帰的に、compacted resultsのすべての@nullという値をnullに置き換えます。置換後に、配列にnullという値のみが含まれていれば、その値を削除して、空の配列を残します。
21. omitGraphがfalseで、compacted resultsに最上位の@graphエントリーがない、またはその値が配列でない場合は、compacted resultsの@contextでないエントリーを、@graphの配列の値に含まれているマップに配置するように変更します。omitGraphがtrueであれば、最上位の@graphエントリーは、複数のノード・オブジェクトを含むためにのみ用いられます。
22. compacted resultsを内部表現からJSONシリアル化に変換して、compacted resultsでpromiseを解決します。

input(入力)

フレーム化を実行するJSON-LDオブジェクトまたはJSON-LDオブジェクトの配列、またはフレーム化するJSON-LDドキュメントを参照するIRI。

frame(フレーム)

inputのデータを再配置するときに用いるフレーム。マップ形式かIRIとしてのいずれか。

options(オプション)

入力ドキュメントの基底IRIなど、フレーム化アルゴリズムに影響を与える可能性のある(MAY)一連のオプション。JsonLdOptionsという型は、デフォルトのオプションの値を定義します。

typedef record<USVString, any> JsonLdRecord;

JsonLdRecordは、JSONオブジェクトの解析結果である任意のマップ・エントリーを含むために用いるマップの定義です。

typedef (JsonLdRecord or sequence<JsonLdRecord> or USVString or RemoteDocument) JsonLdInput;

JsonLdInputインターフェースは、JsonLdRecord、JsonLdRecordsのsequence、有効なJSONドキュメントを取得するために逆参照できるIRIを表す文字列、またはすでに逆参照されているRemoteDocumentなどの入力値を参照するために用います。

値がJsonLdRecord またはJsonLdRecordsのシーケンスである場合、その値は同等の内部表現の値と見なされ、その場合、JsonLdRecordはマップと同等であり、JsonLdRecordsのシーケンスはマップの配列と同等です。マップ・エントリーは、[INFRA]でそれと同等のものに変換されます。

処理エラーを報告するためにJsonLdFramingError型を用います。

dictionary JsonLdFramingError {
  JsonLdFramingErrorCode code;
  USVString? message = null;
};
enum JsonLdFramingErrorCode {
  "invalid frame",
  "invalid @embed value"
};

JSON-LDフレーム化は、JSON-LD 1.1処理アルゴリズムとAPI[JSON-LD11-API]で定義されているエラーのインターフェイスとコードを拡張しています。

code

このドキュメントにおいて様々なアルゴリズムで記述している、特定のエラーの型を表す文字列。

message

追加のデバッグ情報が含まれているオプションのエラー・メッセージ。エラー・メッセージの具体的な内容は、この仕様の範囲外です。

JsonLdFramingErrorCode は、有効なJSON-LDフレーム化エラー・コードのコレクションを表します。

invalid @embed value

@embedの値は、オブジェクト組み込みフラグに対して認識される値ではありません。

invalid frame

フレームが無効です。

この項では、JSON-LDAPI内で用いるデータ型の定義について説明します。

JsonLdContext型は、マップ、IRIを表す文字列、またはマップと文字列の配列でありえる値を参照するために用います。

JSON-LD 1.1 API[JSON-LD11-API]のJsonLdContextの定義を参照してください。

JsonLdOptions型は、様々なオプションをJsonLdProcessorメソッドに渡すために用います。

dictionary JsonLdOptions {
  (JsonLdEmbed or boolean)  embed         = "@once";
  boolean                   explicit      = false;
  boolean                   omitDefault   = false;
  boolean                   omitGraph;
  boolean                   requireAll    = false;
  boolean                   frameDefault  = false;
  boolean                   ordered       = false;
};

enum JsonLdEmbed {
  "@always",
  "@once",
  "@never"
};

JSON-LD 1.1 API[JSON-LD11-API]で定義されているオプションに加えて、フレーム化では次の追加オプションを定義しています。

embed

フレーム化アルゴリズムで用いるオブジェクト組み込みフラグの値を設定します。trueというブール値は、フラグを@onceに設定し、falseという値はフラグを@neverに設定します。

explicit

フレーム化アルゴリズムで用いる明示的な包含フラグの値を設定します。

frameDefault

merged graphをフレーム化する代わりに、デフォルト・グラフのみをフレーム化します。

omitDefault

フレーム化アルゴリズムで用いるデフォルト省略フラグの値を設定します。

omitGraph

フレーム化アルゴリズムで用いるグラフ省略フラグの値を設定します。明示的に設定されていなければ、処理モードがjson-ld-1.0の場合はfalseに、そうでない場合はtrueに設定されます。

ordered

trueに設定されていれば、指示されている特定のアルゴリズム処理ステップは辞書順になります。falseであれば、処理において順序は考慮されません。

requireAll

フレーム化アルゴリズムで用いるすべて必要フラグの値を設定します。

JsonLdEmbedは、次のembedオプションの値を列挙します。

@always

循環参照が発生しない限り、常にノード・オブジェクトをプロパティー値として組み込みます。

@never

マッチする値をシリアル化するときに、常にノード参照を用います。

@once

特定のノード・オブジェクト内の1つの値のみを組み込むべきであり、他のプロパティーのその他の値ではノード参照を用います。@embedとオブジェクト組み込みフラグのいずれも指定されていなければ、これがデフォルト値です。

JSON-LD 1.1 API[JSON-LD11-API]のJsonLdOptions定義を参照してください。

§ A. IANAに関する留意点のセキュリティに関する留意点を参照してください。

[JSON-LD11]のプライバシーに関する留意点を参照してください。

[JSON-LD11]の国際化に関する留意点を参照してください。

この項は、標準コミュニティのレビューのためだけに含まれており、この仕様がW3C勧告になれば、インターネット技術運営委員会に提出されます。

JSON-LDフレームは、[JSON-LD11]で記述されているものと同じMIMEメディア・タイプと、必須profileパラメータを用います。

タイプ名:

application

サブタイプ名:

ld+json

必須パラメータ:

なし

任意のパラメータ:

profile

資源をJSON-LDフレームとして識別する1つのURI。プロファイルは、プロファイルの知識なしに処理された場合に資源の表現のセマンティクスを変更しないため、プロファイル対象の資源に関してクライアントが知識を持っていてもいなくても同じ表現を安全に使用できます。

http://www.w3.org/ns/json-ld#framed

JSON-LDのフレームを指定します。

JSON-LDフレーム・ドキュメントを提供およびリクエストする際には、http://www.w3.org/ns/json-ld#framedを用いるべきです(SHOULD)。

コード化に関する留意点:

RFC 8259の11項を参照

セキュリティに関する留意点:

RFC 8259の12項 [RFC8259]を参照

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を構築することが可能です。

互換性に関する留意点:

n/a

公開済み仕様書:

https://www.w3.org/TR/json-ld11-framing

このメディア・タイプを使用するアプリケーション:

有向グラフの交換を必要とするプログラミング環境。JSON-LDの実装は、JavaScript、Python、Ruby、PHP、C++用に作成されています。

追加情報:

マジック・ナンバー:

n/a

ファイル拡張子:

.jsonld

マッキントッシュ・ファイル・タイプ・コード:

TEXT

詳細情報に関する連絡先:

Ivan Herman <ivan@w3.org>

意図する使途:

汎用

使用上の制限:

なし

著者:

Manu Sporny、Gregg Kellogg、Markus Lanthaler、Dave Longley

改版管理者:

W3C

application/ld+jsonで用いられるフラグメント識別子は、RDF 1.1概念および抽象構文[RDF11-CONCEPTS]に従って、RDF構文と同様に扱われます。

この項は非規範的です。

[Global=JsonLd, Exposed=JsonLd]
interface JsonLd {};

[Exposed=JsonLd]
interface JsonLdProcessor {
  constructor();
  static Promise<JsonLdRecord> frame(
    JsonLdInput input,
    JsonLdInput frame,
    optional JsonLdOptions options = {});
};

typedef record<USVString, any> JsonLdRecord;

typedef (JsonLdRecord or sequence<JsonLdRecord> or USVString or RemoteDocument) JsonLdInput;

dictionary JsonLdFramingError {
  JsonLdFramingErrorCode code;
  USVString? message = null;
};
enum JsonLdFramingErrorCode {
  "invalid frame",
  "invalid @embed value"
};

dictionary JsonLdOptions {
  (JsonLdEmbed or boolean)  embed         = "@once";
  boolean                   explicit      = false;
  boolean                   omitDefault   = false;
  boolean                   omitGraph;
  boolean                   requireAll    = false;
  boolean                   frameDefault  = false;
  boolean                   ordered       = false;
};

enum JsonLdEmbed {
  "@always",
  "@once",
  "@never"
};

この項は非規範的です。

下記は、公開時点で未解決の課題のリストです。

クラスを範囲としたフレーム化を許可

同じフレーム・ドキュメント内に複数のフレーム?

この項は非規範的です。

• 一般的な用語定義の項の使用に加え、JSON-LDとJSON-LD-APIの1.0勧告との整合化を目的とした多数のフォーマットと用語の変更がある。
• オブジェクトの組み込みをより適切に制御するために、オブジェクト組み込みフラグ(@embed)が様々な値を取ることができるようになった。
• フレーム化は、より具体的なフレーム・マッチングをサポートし、一般的なwildcardとmatch noneを型とプロパティー値に使用できるようになった。
• フレーム・マッチングは、値オブジェクト・マッチングもサポートし、@value、@type、@languageの値は、wildcardとmatch noneを使用でき、特定の文字列の集合(例えば、特定の言語の集合)を用いてマッチさせることもできるようになった。
• フレーム化により、特定のグラフをマッチさせることができ、最も外側のフレームは、統合されたグラフまたはデフォルト・グラフのいずれかから取得できるようになった。
• フレーム化が、@reverseをサポートするようになった。
• 範囲付きコンテキストを用いることにより、フレームの一部を、最も外側のオブジェクトに用いるものとは異なるコンテキストを用いて短縮できるようになった。
• フレームは、@idに1つ以上の値を用いて、フレーム内の特定のオブジェクトにマッチングを行えるようになった。
• 処理モードがjson-ld-1.0でなければ、その@idにのみ用いられるブランク・ノード識別子を持つ@idエントリーは削除されるようになった。
• JSON構文は、JSONと機能的に同等な他のシリアル化形式を可能とするために、内部表現へと抽象化された。
• 保存された値は、参照する用語のプロパティーを用いて短縮される。
• @linkとメモリ内のオブジェクト・リンクのサポートを削除。
• omitDefault APIオプションや現在の処理モードで制御されるデフォルト省略フラグを追加。
• デフォルトがfalseのorderedオプションをAPIに追加。これは、マップ・エントリー・キーの反復を制御するためにアルゴリズムで用いる。以前は、このアルゴリズムには、そのような順序が常に必要だった。これに伴い、試験結果の評価方法を更新した。
• フレームには、@reverseを用いた逆プロパティー、または@reverseで定義された用語を含むことができ、これにより、フレームの対象となっているノードを参照しているノードに、逆参照が作成される可能性がある。

この項は非規範的です。

• デフォルトがfalseのorderedオプションをAPIに追加。これは、マップ・エントリー・キーの反復を制御するためにアルゴリズムで用いる。以前は、このアルゴリズムには、そのような順序が常に必要だった。これに伴い、試験結果の評価方法を更新した。
• IANA登録をapplication/ld-frame+jsonからapplication/ld+jsonに変更し、profileパラメータを必須にした。
• すべて必要フラグでは、@idや@typeを含むすべてのプロパティーの存在が必須となった。
• @onceを優先して、オブジェクト組み込みフラグの@firstと@lastの値を削除。
• 明示的にjson-ld-1.0に設定されていない限り、処理モードは暗黙的にjson-ld-1.1になった。
• フレームでは、@typeはデフォルト値を持つことができるが、これはフレーム・マッチングの目的には用いられない。

この項は非規範的です。

• 重複していた§ 1.1 このドキュメントの読み方を削除。これは課題92への応答。
• § 4.1 フレーム化アルゴリズムのアルゴリズムを改善。
• 非再帰部分のアルゴリズムをJsonLdProcessorの処理ステップに移動。
• フレーム化の状態からgraph stackを不要なものとして削除。

この項は非規範的です。

• [Exposed=(Window,Worker)] を[Exposed=JsonLd]に変更。これは、レビューの提案に対処するために、ブラウザー以外で用いるJsonLdProcessorインターフェイスを公開するためにグローバル・インターフェイスとして宣言される。

この項は非規範的です。

編集者は、この仕様の作成と編集に多大な貢献をしてくださった次の方々に特に感謝申し上げます。

• Timothy Cole (University of Illinois at Urbana-Champaign)
• Gregory Todd Williams (J. Paul Getty Trust)
• Ivan Herman (W3C Staff)
• Jeff Mixter (OCLC (Online Computer Library Center, Inc.))
• David Lehn (Digital Bazaar)
• David Newbury (J. Paul Getty Trust)
• Robert Sanderson (J. Paul Getty Trust, chair)
• Harold Solbrig (Johns Hopkins Institute for Clinical and Translational Research)
• Simon Steyskal (WU (Wirschaftsuniversitat Wien) - Vienna University of Economics and Business)
• A Soroka (Apache Software Foundation)
• Ruben Taelman (Imec vzw)
• Benjamin Young (Wiley, chair)

さらに、発表時のワーキンググループのメンバーは次の方々でした。

• Steve Blackmon (Apache Software Foundation)
• Dan Brickley (Google, Inc.)
• Newton Calegari (NIC.br - Brazilian Network Information Center)
• Victor Charpenay (Siemens AG)
• Sebastian Kabisch (Siemens AG)
• Axel Polleres (WU (Wirschaftsuniversitat Wien) - Vienna University of Economics and Business)
• Leonard Rosenthol (Adobe)
• Jean-Yves ROSSI (CANTON CONSULTING)
• Antoine Roulin (CANTON CONSULTING)
• Manu Sporny (Digital Bazaar)
• Clement Warnier de Wailly (CANTON CONSULTING)

メーリング・リストや週次のテレビ会議による多くの技術的な課題に対する取り組みに関し、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に厚く御礼申し上げます。

[BCP47]

Tags for Identifying Languages. A. Phillips; M. Davis. IETF. September 2009. IETF Best Current Practice. URL: https://tools.ietf.org/html/bcp47

[ECMASCRIPT]

ECMAScript Language Specification. Ecma International. URL: https://tc39.es/ecma262/

[INFRA]

Infra Standard. Anne van Kesteren; Domenic Denicola. WHATWG. Living Standard. URL: https://infra.spec.whatwg.org/

[JSON-LD10]

JSON-LD 1.0. Manu Sporny; Gregg Kellogg; Marcus Langhaler. W3C. 16 January 2014. W3C Recommendation. URL: https://www.w3.org/TR/2014/REC-json-ld-20140116/

[JSON-LD11]

JSON-LD 1.1. Gregg Kellogg; Pierre-Antoine Champin; Dave Longley. W3C. 7 May 2020. W3C Proposed Recommendation. URL: https://www.w3.org/TR/json-ld11/

[JSON-LD11-API]

JSON-LD 1.1 Processing Algorithms and API. Gregg Kellogg; Dave Longley; Pierre-Antoine Champin. W3C. 7 May 2020. W3C Proposed Recommendation. URL: https://www.w3.org/TR/json-ld11-api/

[LINKED-DATA]

Linked Data Design Issues. Tim Berners-Lee. W3C. 27 July 2006. W3C-Internal Document. URL: https://www.w3.org/DesignIssues/LinkedData.html

[promises-guide]

Writing Promise-Using Specifications. Domenic Denicola. W3C. 9 November 2018. TAG Finding. URL: https://www.w3.org/2001/tag/doc/promises-guide

[RDF-SCHEMA]

RDF Schema 1.1. Dan Brickley; Ramanathan Guha. W3C. 25 February 2014. W3C Recommendation. URL: https://www.w3.org/TR/rdf-schema/

[RDF11-CONCEPTS]

RDF 1.1 Concepts and Abstract Syntax. Richard Cyganiak; David Wood; Markus Lanthaler. W3C. 25 February 2014. W3C Recommendation. URL: https://www.w3.org/TR/rdf11-concepts/

[RFC2119]

Key words for use in RFCs to Indicate Requirement Levels. S. Bradner. IETF. March 1997. Best Current Practice. URL: https://tools.ietf.org/html/rfc2119

[RFC3987]

Internationalized Resource Identifiers (IRIs). M. Duerst; M. Suignard. IETF. January 2005. Proposed Standard. URL: https://tools.ietf.org/html/rfc3987

[RFC8174]

Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words. B. Leiba. IETF. May 2017. Best Current Practice. URL: https://tools.ietf.org/html/rfc8174

[RFC8259]

The JavaScript Object Notation (JSON) Data Interchange Format. T. Bray, Ed.. IETF. December 2017. Internet Standard. URL: https://tools.ietf.org/html/rfc8259

[WEBIDL]

Web IDL. Boris Zbarsky. W3C. 15 December 2016. W3C Editor's Draft. URL: https://heycam.github.io/webidl/

[JSON-LD10-FRAMING]

JSON-LD Framing 1.0. Manu Sporny; Gregg Kellogg; David Longley; Marcus Langhaler. W3C. 30 August 2012. Unofficial Draft. URL: https://json-ld.org/spec/ED/json-ld-framing/20120830/

↑

RetroSearch is an open source project built by @garambo | Open a GitHub Issue

Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo

HTML: 3.2 | Encoding: UTF-8 | Version: 0.7.3