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

この記事は翻訳が完了していません。 この記事の翻訳にご協力ください

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

より高度なドキュメントや、データを表現するために使用される手続きや JSON スキーマの最新の変更点については、データリポジトリの contributor guidedata 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.jsonVRDisplayCapabilities.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 を見てください。

HTML や CSS、 JavaScript のページにおいては、普通一つだけの機能について記述するでしょう。しかし API インターフェイスについては少し事情が異なります。なぜなら常に複数のサブ機能を持つからです (下の Sub-features を参照してください)。

機能内の基本構造

機能の __compat メンバーの中には、以下のメンバーを記述する必要があります。

  • mdn_url: MDN 上のこの機能の参照ページの URL を指定します。これは、ロケールのディレクトリを含めずに記述する必要があることに注意してください。例えば、 /docs/... であり、 /ja/docs/... ではありません。これは、ローカライゼーションのために、データがページに置かれるときにマクロで追加されます。
  • support: 報告したいすべての各ブラウザーにおける、この機能のブラウザーの対応情報を表すメンバーが含まれています。
  • status: この機能の標準化過程の状態を報告するメンバーが含まれています。

ブラウザーメンバーの名前はスキーマで定義されています (Browser identifiers を参照してください)。現在定義されている識別子の完全な一覧のもの使用してください。他のブラウザーを追加したい場合は、広範な影響があり、慎重に考えずに行うべきではありませんので、まず私たちに相談してください。

基本的なブラウザーの compat データファイルでは、ブラウザー識別子のメンバーの中に "version_added" を含めるだけでよいでしょう (詳細は後ほど説明します)。記述することができる値は以下の通りです。

  • バージョン番号: ブラウザーがその機能に対応し始めた正確なバージョンが分かる場合は、その番号を表す文字列を使用してください。例) "47".
  • true: ブラウザがその機能に対応しているが、、正確なバージョン番号がわからない場合は、 true の値を使用してください。
  • false: ブラウザーがその機能に対応していない場合は、 false の値を使用してください。
  • null: ブラウザーがその機能に対応しているかどうかわからない場合は、 null の値を使用してください。

status メンバーの内容には、以下の3つのサブメンバーの記述してください。

  • experimental: この機能が実験的であれば true を設定し、そうでない場合は false を設定してください。
  • standard_track: この機能が何らかの標準化過程 (最も有名なものは W3C/WHATWG ですが、他にも Khronos, TC39, など) にある場合は true を設定し、そうでない場合は false を設定してください。
  • deprecated: この機能が非推奨であれば true に設定し、そうでない場合は false を設定してください。

border-width の機能データ (border-width.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
  }
}

説明の追加

There is a fourth, optional, member that can go inside the __compat member — description. This can be used to include a human-readable description of the feature. You should only include this if it is hard to see what the feature is from glancing at the data. For example, it might not be that obvious what a constructor is from looking at the data structure, so you can include a description like so:

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

      ... etc.
    }
  }
}

サブ機能

In a page where the compat table has more than one row, you'll need multiple subfeatures inside each feature to define the information for each row. This can happen, for example, when you've got the basic support for a feature stored in one row, but then the feature also has a new property or value type that was addded much later in the specification's life and is only supported in a couple of browsers.

As an example, see the compat data and corresponding MDN page for the background-color property. The basic support exists inside the __compat object as explained above, then you have an additional row for browsers' support for "alpha channel for hex values", which contains its own __compat object.

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

For an API, you've got the top two levels defined as api.name-of-the-interface, then a top-level __compat section to define the overall browser compatibility of the interface, then a sub-feature for each of the methods, properties, and constructors contained inside the interface. The basic structure looks like this:

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

      ... etc.
      
    }
  }
}

See VRDisplay.json for a full example.

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

There are some advanced features that you'll want to include in browser compat data. The aim of this section is to list the most common ones, providing an example of each to show how you can implement them in your own compat data.

脚注を含める

Often compat tables will include footnotes related to certain entries that explain useful details or strange behavior that developers will find useful. As an example, the Chrome Android entry for VRDisplay.capabilities (see also VRDisplay.json) (at the time of writing) had a footnote "Currently supported only by Google Daydream." To include this in the capabilities data, we added a "notes" submember inside the relevant "chrome_android" submember; it would look like this:

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

ベンダー接頭辞を含める

If a feature is supported behind a vendor prefix in one or more browsers, you'll want to make that clear in the browser compat data. imagine you had a feature that was supported with a -moz- prefix in Firefox. To specify this in the compat data, you'd need to add a "prefix" submember inside the relevant "firefox" submember. It would look something like this:

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

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

Some features may be supported in a browser, but they are experimental and turned off by default. If a user wants to play with this feature they need to turn it on using a preference/flag.

To represent this in the compat data, you need to add the "flags" submember inside the relevant browser identifier submember. The value of "flags" is an array of objects each of which contains of three members:

  • type: The type of flag or pref this is. The most common value is "preference", which is set inside the browser (for example, using about:config in Firefox, or chrome://flags in Chrome), but you might also sometimes use a value of "compile_flag", which is a preference set when the browser build is compiled.
  • name: This is a string representing the name of the preference that needs to have a value set on it. For example, "Enable Experimental Web Platform Features" is a preference that exists in Chrome, found in chrome://flags.
  • value_to_set: This is a string representing the value that needs to be set on the preference, for example "true".

So to add a preference/flag to the Chrome support for a feature, you'd do something like this:

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

If a feature is behind two or more flags, you can add additional objects to the "flags" array, like in this case, for example:

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

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

Sometimes a feature will be added in a certain browser version, but then removed again as the feature is deprecated. This can be easily represented using the "version_removed" submember, which takes as its value a string representing the version number it was removed on. For example:

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

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

Sometimes you'll want to add multiple support data points for the same browser inside the same feature.

As an example, the text-align-last property (see also text-align-last.json) was added to Chrome in version 35, supported behind a pref.

The support mentioned above was then removed in version 47; also in version 47, support was added for text-align-last enabled by default.

To include both of these data points, you can make the value of the "chrome" submember an array containing two support information objects, rather than just a single support information object:

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

Note: You should put the most current or important support point first in the array — this makes the data easier to read for people who just want to scan it for the latest info.

別名を含める

Occasionally browsers will support a feature under a different name to the name defined in its specification. This might be for example because a browser added experimental support for a feature early, and then the name changed before the spec stabilized.

To include such a case in the browser compat data, you can include a support information point that specifies the alternative name inside an "alternative_name" member.

Note: The alternative name might not be an exact alias — it might have differing behaviour to the standard version.

Let's look at an example. The border-top-right-radius property (see also border-top-right-radius.json) was supported in Firefox:

  • From version 4 onwards with the standard name border-top-right-radius.
  • From version 49 onwards with a -webkit- prefix, for browser compatibility purposes.
  • From version 1 onwards with the alternative name -moz-border-radius-topright. Support for this alias was removed in version 12.

To represent this in the data, we used the following 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"
  }
],

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

Once you are finished with adding your compat data, you should first test it using the following commands:

  • npm run lint — tests all the compat data to make sure the JSON is valid, and is written in the correct style, for example correct indentation, no missing commas, etc. It will print out a long list of file names and test results; if an error is found, the linter will throw an error on the file it is found in, giving you useful debugging info like line number, error message, etc.
  • npm run show-errors — validates the JSON against the data schema, and highlights errors such as invalid browser version numbers being used.

If it is looking OK, you then need to commit it and push it back up to your remote fork on GitHub. You can do this easily with terminal commands like this:

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

Now go to your remote fork (i.e. https://github.com/your-username/browser-compat-data) and you should see information about your push at the top of the files list (under "Your recently pushed branches"). You can create a pull request (starting the process of pushing this to the main repo) by pressing the "Compare & pull request" button, then following the simple prompts on the subsequent screen.

At this point, you just need to wait. A reviewer will review your pull request, and merge it with the main repo, OR request that you make changes. If changes are needed, make the changes and submit again until the PR is accepted.

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

Once your new data has been included in the main repo, you can start dynamically generating browser compat tables based on that data on MDN pages using the Compat macro. This takes a single parameter, the dot notation required to walk down the JSON data and find the object representing the feature you want to generate the compat table for.

Above the macro call, to help other contributors finding their way, you should add a hidden text that is only visible in MDN contributors in edit mode:

<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>

As an example, on the Accept-Charset HTTP header page, the macro call looks like this: {{Compat("http.headers.Accept-Charset")}}. If you look at the accept-charset.json file in the repo, you'll see how this is reflected in the JSON data.

As another example, The compat table for the VRDisplay.capabilities property is generated using {{Compat("api.VRDisplay.capabilities")}}. The macro call generates the following table (and corresponding set of notes):


Update compatibility data on GitHub
デスクトップモバイル
ChromeEdgeFirefoxInternet ExplorerOperaSafariAndroid webviewAndroid 版 ChromeAndroid 版 FirefoxAndroid 版 OperaiOSのSafariSamsung Internet
capabilities
実験的非推奨
Chrome 未対応 なしEdge 未対応 15 — 79Firefox 完全対応 55
補足
完全対応 55
補足
補足 Windows support was enabled in Firefox 55.
完全対応 64
補足
補足 macOS support was enabled in Firefox 64.
IE 未対応 なしOpera ? Safari 未対応 なしWebView Android 未対応 なしChrome Android 未対応 56 — 80
補足 無効
未対応 56 — 80
補足 無効
補足 Only works in an experimental version of Chrome. (Other builds won't return any devices when Navigator.getVRDisplays() is invoked.)
補足 Daydream View supported in Chrome 56.
補足 Google Cardboard supported in Chrome 57.
無効 From version 56 until version 80 (exclusive): this feature is behind the WebVR preference. To change preferences in Chrome, visit chrome://flags.
Firefox Android 完全対応 55Opera Android ? Safari iOS ? Samsung Internet Android 完全対応 6.0
補足
完全対応 6.0
補足
補足 Google Cardboard supported in Samsung Internet 7.0.

凡例

完全対応  
完全対応
未対応  
未対応
実装状況不明  
実装状況不明
実験的。動作が変更される可能性があります。
実験的。動作が変更される可能性があります。
非推奨。新しいウェブサイトでは使用しないでください。
非推奨。新しいウェブサイトでは使用しないでください。
実装ノートを参照してください。
実装ノートを参照してください。
ユーザーが明示的にこの機能を有効にしなければなりません。
ユーザーが明示的にこの機能を有効にしなければなりません。

Note: The filenames often match the labels given to the interfaces inside the JSON structures, but it is not always the case. When the macro calls generate the tables, they walk through all the files until they find the relevant JSON to use, so the filenames are not critical. Saying that, you should always name them as intuitively as possible.