A MDN possui um formato padrão para tabelas de compatibilidade para nossa documentação da Web aberta; isto é, documentação de tecnologias como DOM, HTML, CSS, JavaScript, SVG etc., compartilhadas em todos os navegadores. Este artigo é um guia de "introdução" sobre como adicionar, manter o banco de dados a partir do qual as tabelas de compatibilidade são geradas e como integrar as tabelas em artigos.

Para obter uma documentação mais avançada, bem como as alterações mais recentes nos processos e esquemas JSON usados para representar os dados, consulte o guia do colaborador do repositório de dados e o guia de diretrizes de dados.

Como acessar o repositório de dados

Os dados são armazenados em um repositório do GitHub — consulte https://github.com/mdn/browser-compat-data. Para acessá-lo, você precisa obter uma conta do GitHub, bifurcar (fork) o repositório de dados compatível com o navegador em sua própria conta e, em seguida, clonar seu fork na sua máquina local.

Preparando para adicionar os dados

Antes de adicionar dados novos, verifique que o fork criado tenha o mesmo conteúdo que o repositório principal. Após isso, crie uma nova branch, dentro do fork criado, para conter as mudanças e adições a serem realizadas, em seguida, faça um pull dessa branch no clone local, para então começar a contribuir com o projeto.

Uma forma simples para ter certeza que o seu fork tem o mesmo conteúdo, e está tão atualizado quanto o repositório principal, é descrita abaixo:

Adicionando o repositório principal browser-compat-data como um controle remoto

Vá para o clone local do seu fork no seu terminal/linha de comando e adicione um controle remoto apontando para o repositório principal (upstream) assim (você só precisa fazer isso uma vez):

Se não tiver certeza se fez isso, verifique os controles remotos que seu repositório está usando

Atualizando seu fork com o conteúdo do controle remoto

Criando um novo branch (ramo) para fazer o seu trabalho

Em seguida, vá à sua bifurcação remota (será em https://github.com/seu-nome-de-usuario/browser-compat-data) e crie um novo ramo para guardar suas mudanças de adição de conteúdo. Isso pode ser feito em:

Por exemplo, se você quisesse adicionar informações sobre WebVR API, você criaria um ramno chamado algo como "webvr".

Mudando para o novo branch (ramo)

Agora,volte para o seu terminal/linha de comando, e atualize seu clone local da sua bifurcação para incluir o seu novo ramo usando o seguinte comando:

Adicionando os dados

To add the data, you need to create a new file or files to store your compat data in. The files you need to create differ, depending on what technology you are working on:

Each file you create has to follow the pattern defined in the schema contained within our repo; you can see the detailed schema description here.

Estrutura de dados de compatibilidade básica

Let's look at an example. CSS property JSON files for example need the following basic structure:

You have the css object, inside of which is a properties object. Inside the properties object, you need one member for each of the specific features you want to define the compat data for. Each of these members has a __compat member, inside of which the actual data goes.

In HTML, CSS, and JS pages, you'll normally only need one feature. API interfaces work slightly differently — they always have multiple sub-features (see {{anch("Sub-features")}}, below).

Estrutura básica dentro de um recurso

Inside a feature __compat member, you need to include the following members:

mdn_url: Contains the URL of the reference page for this feature on MDN. Note that this needs to be written without the locale directory inside, e.g. /docs/... not /docs/en-US/... (or whatever). This is added in by the macro when the data is put on the page, for localization purposes.
support: Contains members representing the browser support information for this feature in all the different browsers we want to report.
status: Contains members reporting the standards track status of this feature.

The names of the browser members are defined in the schema (see Browser identifiers). You should use the full list of currently defined identifiers. If you wish to add another browser, talk to us first, as this could have a wide-ranging impact and should not be done without careful thought.

In a basic browser compat data file, you'll only need to include "version_added" inside the browser identifier members (we'll cover {{anch("Advanced cases")}} later on). The different values you might want to include are as follows:

A version number: If you know the exact version in which a browser started to support your feature, use a string representing the number, e.g. "47".
true: If a browser supports a feature but you don't know the exact version number, use the value true. This equivalent to the \{{CompatVersionUnknown}} macro call in the old manual tables.
false: If a browser does not support a feature, use the value false. This is equivalent to the the \{{CompatNo}} macro call in the old manual tables.
null: If you don't know whether a browser supports a feature or not, use the value null. This is equivalent to the \{{CompatUnknown}} macro call in the old manual tables.

Inside the status member, you'll include three submembers:

"experimental": This should be set to true if the feature is experimental, or false otherwise.
"standard_track": This should be set to true if a feature is on some kind of standards track (most commonly W3C/WHATWG, but there are also other standards efforts such as Khronos, TC39, etc.) or false otherwise.
"deprecated": This should be set to true if the feature is deprecated, or false otherwise.

The feature data for border-width (also see border-width.json) is shown below as an example:

"__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
  }
}

Adicionando uma descrição

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

Sub-recursos

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.

Adicionando dados: Casos avançados

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.

Incluindo uma nota de rodapé

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 {{domxref("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:

Incluindo um prefixo de fornecedor

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:

Incluindo preferências ou sinalizadores do navegador

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:

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

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

Incluindo uma versão em que o suporte foi removido

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:

Incluindo vários pontos de suporte para a mesma entrada do navegador

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

As an example, the {{cssxref("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:

Incluindo um nome alternativo

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.

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

Empurrando uma mudança de volta para o repositório principal

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

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:

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.

Inserindo os dados em páginas 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:

As an example, on the {{httpheader("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 {{domxref("VRDisplay.capabilities")}} property is generated using \{{Compat("api.VRDisplay.capabilities")}}. The macro call generates the following table (and corresponding set of notes):