互換性一覧表とブラウザー互換性データリポジトリ (BCD)

MDN には、オープンなウェブ文書のための互換性一覧表の標準形式があります。これは、すべてのブラウザーにわたって共有される DOM, HTML, CSS, JavaScript, SVG などの技術の文書で使用されます。この記事は、作成した互換性一覧表をデータベースにどのように追加して維持するか、また、一覧表を記事に統合する方法についての「始め方」のガイドです。

より高度なドキュメントや、データを表現するために使用される手続きや JSON スキーマの最新の変更点については、データリポジトリの contributor guide や data guidelines guide をご覧ください。

質問がある場合や問題を発見した場合は、 MDN ディスカッションフォーラムで相談してください。

データリポジトリにアクセスする方法

データは GitHub リポジトリに保存されています - https://github.com/mdn/browser-compat-data を参照してください。アクセスするには GitHub アカウントを取得し、 browser-compat-data を自分のアカウントでフォーク (fork) し、フォークしたものをローカルマシンにクローン (クローン) する必要があります。

データを追加する準備

新しいデータを追加する前に、フォークがメインリポジトリの最新である (同じ内容を含む) ことを確認し、フォーク内に追加を格納するための新しいブランチ (ブランチ) を作成し、そのブランチをローカルのクローンにプルすれば、その中で作業を始めることができます。

フォークが最新であることを、次のように簡単な方法で確認してみましょう。

メインの browser-compat-data リポジトリをリモートとして追加

端末またはコマンドラインでフォークをローカルにクローンした場所へ行き、次のようにしてリモートにメイン (upstream) リポジトリを指すよう追加します (これを行う必要があるのは一度だけです)。

git remote add upstream https://github.com/mdn/browser-compat-data.git

もしこれをしたか不明確であれば、次のようにリポジトリがどのリモートを指しているかを確認することができます。

git remote -v

リモートのコンテンツでフォークを更新する

では、フォークを更新したいときは、次のようにできます。

1. master ブランチにいることを確認します。

   git checkout master

2. 以下のように更新されたリポジトリのコンテンツをフェッチ (fetch) します。

   git fetch upstream

3. ローカルの master の内容をメイン (upstream) リポジトリの master の内容にリベース (rebase) します。

   git rebase upstream/master

4. 以下のようにしてここまでの変更をあなたがフォークしたリモートへ反映します。

   git push

作業用の新しいブランチの作成

次に、自分のリモートフォーク (普通はhttps://github.com/自分のユーザー名/browser-compat-data) へ行き、以下の手順で新しいブランチを作成します。変更したい内容をここに追加していくことになります。

1. "Branch: Master" ボタンをクリックします。
2. 新しいブランチの名前を "Find or create a branch..." と書かれたところに入力します。
3. "Create branch ブランチ名 from Master" と書かれたボタンを押します。

例えば、 WebVR API についてデータを追加したい場合 "webvr" という名前がブランチ名として考えられるでしょう。

新しいブランチへの切り替え

ここから先は作業が端末またはコマンドラインに戻ります。ローカルにクローンしたものを更新して新しく作成したブランチを使えるようにするには、下のコマンドを使います。

git pull

そして以下のように新しく作成したブランチに切り替えます。

git checkout name-of-branch

これでデータを追加するための準備が完了しました！

データの追加

データを追加するには、新たに互換性データを書いたファイルを作成する必要があります。作成する必要があるファイルは、どの技術分野について作業しようとするかによって異なります。

• HTML: HTML の要素ごとに一つのファイルがbrowser-compat-data/html/elementsに格納されています。ファイル名は要素の名前をすべて小文字でつけるべきです。 例) div.json
• CSS: CSS のプロパティないしセレクターごとに一つのファイルが browser-compat-data/css 以下の適切なディレクトリに格納されています。ファイル名はその機能の名前をすべて小文字でつけてください。 例) background-color.json, hover.json
• JS: JavaScriptオブジェクトごとに一つのファイルがbrowser-compat-data/javascript/builtinsに格納されています。ファイル名は大文字小文字を含めて完全にオブジェクト名と一致させてください。 例) Date.json, InternalError.json
• APIs: API のインターフェイスごとに一つのファイルがbrowser-compat-data/apiに格納されています。ファイル名は大文字小文字を含めて完全にインターフェイス名と一致させてください。 例) WebVR API にはVRDisplay.jsonやVRDisplayCapabilities.jsonなどがあります

あなたが作成するファイルは、このリポジトリに含まれているスキーマで定義されている構造に従わなければなりません。詳細なスキーマの説明はこちらで見ることができます。

基本的な互換性データの構造

では例を見ていきましょう。例として CSS プロパティの JSON ファイルに求められる基本構造を次に示します。

{
  "css": {
    "properties": {
      "border-width": {
        "__compat": {
          ...
        }
      }
    }
  }
}

まず css オブジェクトがあります。その中に properties オブジェクトがあります。 properties オブジェクトの中には、互換性データとして定義したい特定の機能につき一つのメンバーが必要です。それぞれのメンバーは __compat をメンバーに持ち、この中に実際のデータを記述します。

上記のデータは border-width.json にあります。 MDN で表示された border-width の表と見比べてみてください。

他の種類の機能についても同様ですが、ただしオブエジェクトの名前が異なります。

• CSS セレクターは CSS プロパティと基本的に同様ですが、最上位のオブジェクト構造が css.properties ではなく css.selectors になります。例として cue.json を見てください。
• HTML についても基本的に同様ですが、最上位のオブジェクト構造が html.elements です。例として article.json を見てください。
• JavaScript の組込みオブジェクトについての最上位のオブジェクト構造は javascript.builtins です。例として Array.json を見てください。

"__compat": {
  "mdn_url": "https://developer.mozilla.org/docs/Web/CSS/border-width",
  "support": {
    "chrome": {
      "version_added": "1"
    },
    "webview_android": {
      "version_added": "2"
    },
    "edge": {
      "version_added": true
    },
    "edge_mobile": {
      "version_added": true
    },
    "firefox": {
      "version_added": "1"
    },
    "firefox_android": {
      "version_added": "1"
    },
    "ie": {
      "version_added": "4"
    },
    "ie_mobile": {
      "version_added": "6"
    },
    "opera": {
      "version_added": "3.5"
    },
    "opera_android": {
      "version_added": "11"
    },
    "safari": {
      "version_added": "1"
    },
    "safari_ios": {
      "version_added": "3"
    }
  },
  "status": {
    "experimental": false,
    "standard_track": true,
    "deprecated": false
  }
}

{
  "api": {
    "AbortController": {
      "__compat": {
        ...
      },
      "AbortController": {
        "__compat": {
          "mdn_url": "https://developer.mozilla.org/docs/Web/API/AbortController/AbortController",
          "description": "<code>AbortController()</code> constructor",
          "support": {
            ...
          }
        }
      }

      ... etc.
    }
  }
}

{
  "css": {
    "properties": {
      "background-color": {
        "__compat": {
          ...
        },
        "alpha_ch_for_hex": {
          "__compat": {
            ...
          },
        }
      }
    }
  }
}

{
  "api": {
    "VRDisplay": {
      "__compat": {
        ...
      },
      "cancelAnimationFrame": {
        "__compat": {
          ...
        }
      },
      "capabilities": {
        "__compat": {
          ...
        }
      },

      ... etc.
      
    }
  }
}

データの追加: 高度な場合

ブラウザの互換性データには、いくつかの高度な機能があります。このセクションの目的は、最も一般的なものをリストアップし、それぞれの例を提供して、あなた自身の互換性データにそれらを実装する方法を示すことです。

脚注を含める

しばしば互換性一覧表には、有益な詳細や、開発者にとって有用な奇妙な動作を説明する、特定のエントリに関連した脚注が含まれています。例として、VRDisplay.capabilities (VRDisplay.jsonも参照) の Chrome Android エントリには、(執筆時点では)"現在はGoogle Daydreamのみでサポートされています "という脚注がありました。これを互換性データに含めるために、関連する "chrome_android "サブメンバーの中に "notes "サブメンバーを追加しました。これはこのようになります。

"chrome_android": {
  "version_added": true,
  "notes": "Currently supported only by Google Daydream."
}

ベンダープレフィックスを含める

ある機能が、あるブラウザでベンダープレフィックス付きでサポートされている場合、ブラウザの互換性データでそのことを明確にしたいと思うでしょう。Firefoxにおいて、 -moz- プレフィックスによりサポートされている機能を想像してください。互換性データでこれを指定するには、該当する "firefox" サブメンバーの中に "prefix" サブメンバーを追加する必要があります。これは次のようになります。

"firefox": {
  "version_added": true,
  "prefix": "-moz-"
}

ブラウザーの設定やフラグを含める

いくつかの機能はブラウザでサポートされているかもしれませんが、それらは実験的なものであり、デフォルトではオフになっています。ユーザがこの機能を使いたい場合は、環境設定/フラグを使ってオンにする必要があります。

互換性データでこれを表現するには、関連するブラウザ識別子サブメンバーの中に "flags" サブメンバーを追加する必要があります。flags" の値は、3つのメンバを含むオブジェクトの配列です。

• type: フラグやプリファレンスのタイプ。最も一般的な値は "preference"で、これはブラウザ内部で設定されます(例えば、Firefoxではabout:config、Chromeではchrome://flagsを使用します)が、時には "compile_flag "という、ブラウザのビルドがコンパイルされるときに設定される値を使用することもあります。
• name: これは、値を設定する必要がある設定の名前を表す文字列です。例えば、"Enable Experimental Web Platform Features" はChromeに存在する環境設定で、Chromeではchrome://flagsにあります。
• value_to_set: 設定する値を表す文字列で、例えば "true "などです。

つまり、ある機能のChromeのサポートに環境設定/フラグを追加するには、次のようにします。

"chrome": {
  "version_added": "50",
  "flags": [
    {
      "type": "preference",
      "name": "Enable Experimental Web Platform Features",
      "value_to_set": "true"
    }
  ]
},

もしその機能が2つ以上のフラグの元にある場合、この例のように "flags"配列にオブジェクトを追加することができます。

"firefox": {
  "version_added": "57",
  "flags": [
    {
      "type": "preference",
      "name": "dom.streams.enabled",
      "value_to_set": "true"
    },
    {
      "type": "preference",
      "name": "javascript.options.streams",
      "value_to_set": "true"
    }
  ]
},

対応が削除されたバージョンを含める

あるブラウザのバージョンで追加された機能が、非推奨となったために再び削除されることがあります。これは、削除されたバージョン番号を表す文字列を値として受けとる、"version_removed" サブメンバーを使えば簡単に表現できます。例えば、以下のようになります。

"firefox": {
  "version_added": "35",
  "version_removed": "47",
},

同じブラウザーの項目に複数の対応ポイントを含む

同じブラウザの複数のサポートデータポイントを、同じ機能の中に追加したい場合もあるでしょう。

例えば、 text-align-last プロパティ（text-align-last.jsonも参照）は、バージョン35でChromeに追加され、プレフィックス付きでサポートされました。

上記のサポートはバージョン 47 で削除されましたが、バージョン 47 でもデフォルトで text-align-last が有効になるようにサポートが追加されました。

これらのデータポイントの両方を含めるために、"chrome "サブメンバーの値を、単一のサポート情報オブジェクトではなく、2つのサポート情報オブジェクトを含む配列にすることができます。

"chrome": [
  {
    "version_added": "47"
  },
  {
    "version_added": "35",
    "version_removed": "47",
    "flags": [
      {
        "type": "preference",
        "name": "Enable Experimental Web Platform Features",
        "value_to_set": "true"
      }
    ]
  }
],

別名を含める

時々、ブラウザが仕様とは異なる名前で機能をサポートすることがあります。これは例えば、あるブラウザがある機能の実験的なサポートを早くから追加していて、仕様が安定する前に名前が変わってしまったというような場合が考えられます。

このようなケースをブラウザの互換性データに含めるには、"alternative_name"メンバの中に代替名を指定するサポート情報ポイントを含めます。

では例を見てみましょう。border-top-right-radius プロパティ（border-top-right-radius.jsonも参照）のFirefoxでのサポートは以下の通りです。

• バージョン 4 以降では border-top-right-radius という標準的な名前でサポートされています。
• バージョン 49 以降では、ブラウザの互換性を考慮し、-webkit-プレフィクスと共に使用されます。
• バージョン 1 以降では -moz-border-radius-topright という代替名を使用しています。このエイリアスのサポートはバージョン12で削除されました。

これをデータで表現するために、以下のJSONを使用しました。

"firefox": [
  {
    "version_added": "4",
    "notes": "Prior to Firefox 50.0, border styles of rounded corners were always rendered as if <code>border-style</code> was solid. This has been fixed in Firefox 50.0."
  },
  {
    "prefix": "-webkit-",
    "version_added": "49",
    "notes": "From Firefox 44 to 48, the <code>-webkit-</code> prefix was available with the <code>layout.css.prefixes.webkit</code> preference. Starting with Firefox 49, the preference defaults to <code>true</code>."
  },
  {
    "alternative_name": "-moz-border-radius-topright",
    "version_added": "1",
    "version_removed": "12"
  }
],

変更のメインリポジトリへの反映

互換性データの追加が終わったら、まず以下のコマンドを使ってテストしてみてください。

• npm run lint — すべての互換性データをテストして、JSONが有効であること、正しいスタイルで書かれていること、例えば正しいインデント、カンマの欠落がないことなどを確認します。ファイル名とテスト結果の長いリストが表示されます。エラーが見つかった場合、リンターは見つかったファイルに対してエラーをスローし、行番号やエラーメッセージなどのデバッグに役立つ情報を表示します。
• npm run show-errors — JSON をデータスキーマと照らし合わせて検証し、無効なブラウザのバージョン番号が使用されているなどのエラーをハイライトします。

問題がなさそうであれば、コミットして、GitHub上のあなたのリモートフォークにプッシュする必要があります。これは、以下のようなターミナルコマンドで簡単に行うことができます。

git add .
git commit -m 'adding compat data for name-of-feature'
git push

リモートフォーク (URLの例: https://github.com/your-username/browser-compat-data) に行くと、ファイルリストの一番上 (「最近プッシュしたブランチ」の下) にあなたのプッシュに関する情報が表示されているはずです。プルリクエスト（あなたのリモートフォークをメインリポジトリに取り込むための、最初の過程のことです）を作成するには、"Compare & pull request" ボタンを押して、続く画面の簡単なプロンプトに従ってください。

これが終われば、ただ待つのみです。レビュアーがあなたのプルリクエストをレビューし、メインリポジトリにマージします。そうでない場合は、変更を依頼します。変更が必要な場合は、変更を加えて、プルリクエストが受理されるまで再度投稿してください。

MDN ページへのデータの挿入

一度あなたの新しいデータがメインリポジトリに含められたら、Compat マクロを使って、MDNページ上でそのデータに基づいてブラウザの互換性一覧表を動的に生成することができます。これは、JSONデータを探索して、互換性一覧表を生成したい機能を表すオブジェクトを見つけるために必要なドット記法を唯一のパラメータとして受け取ります。

マクロ呼び出しの上に、他のコントリビューターにとって使いやすくするために、編集モードのMDNでコントリビューターにのみ表示される隠しテキストを追加します。

<div class="hidden">
The compatibility table on this page is generated from structured data. 
If you'd like to contribute to the data, please check out 
<a href="https://github.com/mdn/browser-compat-data">https://github.com/mdn/browser-compat-data</a> 
and send us a pull request.
</div>

例として、HTTPヘッダーに関するページである Accept-Charset では、マクロの呼び出しは次のようになっています。 {{Compat("http.headers.Accept-Charset")}}リポジトリ内のaccept-charset.jsonファイルを見ると、これが JSON データにどのように反映されているかがわかると思います。

別の例として、VRDisplay.capabilities プロパティの互換性一覧表は、 {{Compat("api.VRDisplay.capabilities")}}を使用して生成されます。マクロ呼び出しにより、以下の表（および対応する一連の注釈）が生成されます。