構造化データの使用方法

MDNは可能な限り、明確に定義された構造でデータを格納されます。この情報は一元化され、一度の更新で多くの場所で使用することができます。

このようなファイルがいくつかあり、この記事ではそれらの目的、構造、メンテナンスプロセスについて記述しています。

GroupData: API の論理的なグループ化

GroupData は Web API の情報を集めた JSON ファイルです。 API のグループ分けはやや曖昧です。どんなインターフェイス、メソッド、プロパティも複数の API の一部になり得ます。ある名前の下にグループ化された API の設定は、機能についてのコミュニケーションに使用する慣習であり、技術的な強制力はありません。

しかし、 MDN は適切なリファレンスページ、ガイド、概要記事を持つ首尾一貫した Web-API サイドバー（{{APIRef}} マクロなど）を作成するためにこの情報を必要としています。

GroupData はまさにそれを行います。それぞれの API について、インターフェイス、プロパティ、メソッド、ガイド、概要ページを掲載しています。過去には、辞書やコールバックも掲載されていました。しかし、まだ対応しているとはいえ、この使用は非推奨です。将来的には除去される予定です。

GroupData の構造

警告: このファイルに掲載されている存在しないファイルは無視されます（en-US では）。

GroupData.json の項目は次のような構造です。

json

"API_の名前": {
  "overview": ["概要ページの名前"],
  "guides": [
    "ガイド_1_の名前",
    (…)
  ],
  "interfaces": [
    "インターフェイス_1_の名前",
    (…)
  ],
  "methods": [
    "追加メソッド_1_の名前",
    (…)
  ],
  "properties": [
    "追加プロパティ_1_の名前",
    (…)
  ],
  "events": [
    "追加イベント_1_の名前",
    (…)
  ]
}

…ここで、

"API_の名前": このキーは {{APIRef("API_の名前")}} のようなサイドバーマクロで使用する ID であり、サイドバー自体に表示される名前でもあります。賢く選んでください。

警告: サイドバーに表示される名前を変更したい場合は、その名前を表示しているすべてのページを編集する必要があります。
"overview": これは 1 つのページ、概要ページを格納するリストです。 "API_の名前" テキストのリンクとして使用します。値はページのタイトルで、ページは web/api/ ディレクトリーになければなりません。
"guides": 指定された順序でサイドバーに表示するガイドのリストです。値は /docs/ から始まるページへのパスです。
"interfaces": API の一部であるインターフェイスを掲載します。
"methods": API の一部であるメソッドを掲載します。

メモ: "interfaces" に掲載されているインターフェイスのメソッドは、ここに挙げてはいけません。そのページの page-type キーが web-api-static-method または web-api-instance-method の場合、自動的にサイドバーに追加されます。
"properties": API の一部である他のインターフェイスのプロパティを掲載します。例えば navigator.xr （WebXR API が navigator オブジェクトに追加するプロパティ）です。

メモ: "interfaces" に掲載されているインターフェイスのプロパティは、ここに挙げてはいけません。そのページの page-type キーが web-api-static-property または web-api-instance-property の場合、自動的にサイドバーに追加されます。
"events": API の一部である他のインターフェイスのイベントを掲載します。値はページのタイトルです（Web/Events 以下になければなりません）。

メモ: "interfaces" に掲載されているインターフェイスのプロパティは、ここに挙げてはいけません。そのページの page-type キーが web-api-event の場合、自動的にサイドバーに追加されます。

他の 2 つのキー、 "dictionaries" と "callbacks" がありますが、同じ原理で処理します。これらのエンティティを自分自身のページで文書化しなくなりましたので、これらの使用は非推奨です。また、新しい項目を追加するべきではありません（少しずつ除去していきます）。

メモ: また、どのキーも必須ではありません。非推奨でないものは省略するのではなく、空リストで追加するのがよい習慣です（これを強制する予定です）。これは、値がないことが意識的な選択であることを示すものです。

GroupData の更新プロセス

このファイルは、サイドバーに影響する変更が起こったのと同じPRで更新されるべきです。そうすれば、サイドバーは常に最新の状態になります。レビュアーはこのファイルを採用していない PR をマージすべきではありません。

あなたの変更をテストするには、 PR 内のファイルのサイドバーがすべての項目を正しく表示しているか調べてください。

GroupData.json ファイルは GitHub でここにあります。

InterfaceData: インターフェイスの継承の記録

メモ: 将来的には、 w3c/webref で利用できるデータからこのファイルを自動生成したいと思っています。

InterfaceData はインターフェイスの階層構造を記述しています。継承が掲載されています。以前は、それぞれのインターフェイスで実装されているミックスインも掲載されていました。しかし、この使い方は非推奨です。 MDN が更新されるのと同じペースで、このファイルからミックスインを除去します。

この継承データは API サイドバーを構築する際や、インターフェイスページの {{InheritanceDiagram}} で使用します。

InterfaceData の構造

InterfaceData.json の項目は次のような構造です。

json

"インターフェイスの名前": {
  "inh": "親インターフェイスの名前",
  "impl": []
}

メモ: ミックスインは非推奨です。新しいインターフェイスでは、 "impl" はすべて空リストでなければなりません。

"親インターフェイスの名前" の値はリストではなく単一の項目で、必須です。他のインターフェイスを継承していないインターフェイスを掲載してはいけません。

InterfaceData の更新プロセス

他のインターフェイスを継承する新しいインターフェイスを追加する PR は、このファイルを更新しなければなりません。レビュアーはそうしない PR をマージすべきではありません。

変更をテストするには、 P Rで編集した各インターフェイスのサイドバーが継承を正しく表示しているか調べてください。

InterfaceData.json ファイルは GitHub でここにあります。

SpecData: 仕様書情報

警告: SpecData.json ファイルは保守されなくなりました。正規の仕様書情報は w3c/browser-spec と mdn/browser-compat-data の features の spec_url キーに保存されます。

除去している {{SpecName}} と {{Spec2}} マクロは SpecData.json ファイルを使用しています。代わりに、 {{Specifications}} マクロを使用して仕様表を挿入するか、仕様への（良い）リンクをハードコーディングしてください。たいていの場合、「仕様書」セクションの外で仕様書に言及したり、リンクを張ったりすることは、 MDN で適切に文書化されていないことの表れであることに注意してください。

SpecData.json ファイルは GitHub でここにあります。