Issues

This draft API reflects a good guess at a useful, efficent API for storing user-contributed compatibility data. Some of the guesses are better than others. This section highlights the areas where more experienced opinions are welcome, and areas where more work is expected.

Additions to Browser Compatibility Data Architecture

This spec includes changes to the Browser Compatibility Data Architecture developed around March 2014. These seemed like a good idea to me, based on list threads and thinking how to recreate Browser Compatibility tables live on MDN.

These changes are:

  • browsers
    • slug - human-friendly unique identifier
    • name - converted to localized text.
    • note - added for engine, OS, etc. information
  • versions
    • Was browser-versions, but multi-word resources are problematic.
    • release_day - Day of release
    • retirement_day - Day of “retirement”, or when it was superceeded by a new release.
    • status - One of “retired”, “retired-beta”, “current”, “beta”, “future”
    • relese_notes_uri - For Mozilla releases, as specified in CompatGeckoDesktop.
    • note - added for engine version, etc.
  • features
    • slug - human-friendly unique identifier
    • mdn_uri - MDN page that data was scraped from
    • experimental - True if the feature is considered experimental due to being part of a unratified spec such as CSS Transitions, ES6, or the DOM Living Standard. For example, see the run-in value of Web/CSS/display.
    • standardized - True if the feature is described in a standards-track specification, regardless of the maturity of the specification. Most features are standardized, but some browser-specific features may be non-standard, and some features like the left and right features of Web/CSS/caption-side were part of the CSS2 “wishlist” document that was not standardized.
    • stable - True if the feature is considered stable enough for production usage.
    • obsolete - True if the feature should no longer be used in production code.
    • name - converted to localized text, or a string if the name is canonical
    • sections - replaces spec link
    • parent, children - tree relations for this feature
  • supports
    • Was browser-version-features, but multi-word resources are problematic.
    • prefix - string prefix to enable, or null if no prefix
    • prefix_mandatory - True if the prefix is required
    • alternate_name - An alternate name associated with this feature, such as “RTCPeerConnectionIdentityEvent”
    • alternate_name_mandatory - True if the alternate name is required
    • requires_config - A configuration string required to enable the feature, such as “media.peerconnection.enabled=on”
    • default_config - The configuration string in the shipping browser, such as “media.peerconnection.enabled=off”
    • note - Note, which can be null, but if included, can be translated, and may contain HTML and code samples. Supports extended footnote in use on MDN. MDN inline notes are not supported, and must be converted to footnotes.

There are also additional Resources:

Unresolved Issues

  • We’ve been talking data models. This document talks about APIs. The service will not have a working SQL interface. Features like history require that changes are made through the API. Make sure your use case is supported by the API.

  • overholt wants availability in Web Workers. Is an API enough to support that need?

  • I think Niels Leenheer has good points about browsers being different across operating systems and OS versions - I’m considering adding this to the model: Mapping browsers to 2.2.1 Dictionary Browser Members.

  • How should we support versioning the API? There is no Internet concensus.
    • I expect to break the API as needed while implementing. At some point (late 2014), we’ll call it v1.
    • Additions, such as new attributes and links, will not cause an API bump
    • Some people put the version in the URL (/v1/browsers, /v2/browsers)
    • Some people use a custom header (X-Api-Version: 2)
    • Some people use the Accept header (Accept: application/vnd.api+json;version=2)
    • These people all hate each other. Read a good blog post on the subject.
  • What should be the default permissions for new users? What is the process for upgrading or downgrading permissions?

  • Is Persona a good fit for creating API accounts? There will need to be a process where an MDN user becomes an API user, and a way for an API user to authenticate directly with the API.

  • If we succeed, we’ll have a detailed history of browser support for each feature. For example, the datastore will know that every version of Firefox supported the <h1> tag. How should version history be summarized for the Browser Compatibility table? Should the API pick the “important” versions, and the KumaScript display them all? Or should the API send all known versions, and the KumaScript parse them for the significant versions, with UX for exposing known versions? The view doc proposes one implementation, with a <meta> section for identifying the important bits.

  • Do we want to add more items to versions? Wikipedia has interesting data for Chrome release history and Firefox release history. Some possibly useful additions: release date, retirement date, codename, JS engine version, operating system, notes. It feels like we should import the data from version-specific KumaScripts like CompatGeckoDesktop (versions, release dates, translations, links to release docs).

  • We’ll need additional models for automated browser testing. Things like user agents, test names, test results for a user / user agent. And, we’ll need a bunch of rules for mapping test results to features, required number of tests before we’ll say a browser supports a feature, what to do with test conflicts, etc. It might be easier to move all those wishlist items to a different project, that talks to this API when it’s ready to assert browser support for a feature.

  • We need to decide on the URIs for the API and the developer resources. This is being tracked by Bugzilla 1050458.

  • In browsers, it seems like icon won’t be generally useful. What format should the icon be? What size? It may be more useful to use the slug for deciding between icons designed for the local implementation.

Interesting MDN Pages

These MDN pages represent use cases for compatibility data. They may suggest features to add, or existing features that will be dropped.

Some pages will require manual intervention to get them into the data store. Here’s a sample:

Translating from MDN wiki format

The current compatibility data on developer.mozilla.org in MDN wiki format, a combination of HTML and KumaScript.

A MDN page will be imported as a feature with at least one child feature.

Here’s the MDN wiki version of the Specifications section for Web/CSS/border-image-width:

<h2 id="Specifications" name="Specifications">Specifications</h2>
<table class="standard-table">
  <thead>
    <tr>
      <th scope="col">Specification</th>
      <th scope="col">Status</th>
      <th scope="col">Comment</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>{{SpecName('CSS3 Backgrounds', '#border-image-width', 'border-image-width')}}</td>
      <td>{{Spec2('CSS3 Backgrounds')}}</td>
      <td>Initial specification</td>
    </tr>
  </tbody>
</table>

The elements of this table are converted into API data:

  • Body row, first column - Format is SpecName('KEY', 'PATH', 'NAME'). KEY is the specification.mdn_key, PATH is section.subpath, in the page language, and NAME is section.name, in the page language. The macro SpecName has additional lookups on KEY for specification.name and specification.uri (en language only).
  • Body row, second column - Format is Spec2('KEY'). KEY is the specification.mdn_key, and should match the one from column one. The macro Spec2 has additional lookups on KEY for maturity.mdn_key, and maturity.name (multiple languages).
  • Body row, third column - Format is a text fragment which may include HTML markup, becomes the section.name associated with this feature.

and here’s the Browser compatibility section:

<h2 id="Browser_compatibility">Browser compatibility</h2>
<div>{{CompatibilityTable}}</div>
  <div id="compat-desktop">
    <table class="compat-table">
      <tbody>
        <tr>
          <th>Feature</th>
          <th>Chrome</th>
          <th>Firefox (Gecko)</th>
          <th>Internet Explorer</th>
          <th>Opera</th>
          <th>Safari</th>
        </tr>
        <tr>
          <td>Basic support</td>
          <td>15.0</td>
          <td>{{CompatGeckoDesktop("13.0")}}</td>
          <td>11</td>
          <td>15</td>
          <td>6</td>
        </tr>
      </tbody>
    </table>
  </div>
  <div id="compat-mobile">
    <table class="compat-table">
      <tbody>
        <tr>
          <th>Feature</th>
          <th>Android</th>
          <th>Firefox Mobile (Gecko)</th>
          <th>IE Phone</th>
          <th>Opera Mobile</th>
          <th>Safari Mobile</th>
        </tr>
        <tr>
          <td>Basic support</td>
          <td>{{CompatUnknown}}</td>
          <td>{{CompatGeckoMobile("13.0")}}</td>
          <td>{{CompatNo}}</td>
          <td>{{CompatUnknown}}</td>
          <td>{{CompatUnknown}}</td>
        </tr>
      </tbody>
    </table>
  </div>
</div>

This will be converted to API resources:

  • Table class - one of "compat-desktop" or "compat-mobile". Representation in API is TBD.

  • Header row, all but the first column - format is either Browser Name (Engine Name) or Browser Name. Used for browser.name, engine name is discarded. Other formats or KumaScript halt import.

  • Non-header rows, first column - If the format is <code>some text</code>, then feature.canonical=true and the string is the canonical name. If the format is text w/o KumaScript, it is the non-canonocial name. If there is also KumaScript, it varies. TODO: doc KumaScript.

  • Non-header rows, remaining columns - Usually Kumascript:
    • {{CompatUnknown}} - version.version is null, and support.support is "unknown"
    • {{CompatVersionUnknown}} - version.version and are null, and support.support in "yes"
    • {{CompatNo}} - version.version and are null, and support.support is "no"
    • {{CompatGeckoDesktop("VAL")}} - version.version is set to "VAL", support.support is "yes". and version.release_day is set by logic in CompatGeckoDesktop.
    • {{CompatGeckoMobile("VAL")}} - version.version is set to "VAL", support.support is "yes". is set by logic in CompatGeckoMobile.
    • Numeric string, such as 6, 15.0. This becomes the version.version, and support.support is "yes".
  • Content after table - This is usually formatted as a paragraph, containing HTML. If it resembles a footnote, it will be converted to supports.notes.

Once the initial conversion has been done for a page, it may be useful to perform additional steps:

  1. Split large features into smaller ones. For example, here’s one way to reorganize Web/CSS/display:
Reorganization of Web/CSS/display

Data sources for browser versions

The version model currently supports a release date and a retirement date, as well as other version data. Some sources for this data include:

To Do

  • Add multi-get to browser doc, after deciding on GET /versions/1,2,3,4 vs. GET /browser/1/versions

  • Look at additional MDN content for items in common use

  • Move to developers.mozilla.org subpath, auth changes

  • Jeremie’s suggested changes (italics are done)
    • Add browsers.notes, localized, to note things like engine, applicable OS, execution contexts (web workers, XUL, etc.).
    • Drop browsers.engine attribute. Not important for searching or filtering, instead free text in browsers.notes
    • Add versions.notes, localized, to note things like OS, devices, engines, etc.
    • Drop versions.engine-version, not important for searching or sorting.
    • Drop versions.status. Doesn’t think the MDN team will be able to keep up with browser releases. Will instead rely on users figuring out if a browser version is the current release.
    • Drop feature.canonical. Instead, name=”string” means it is canonical, and name={“lang”: “translation”} means it is non-canonical.
    • Feature-sets is a cloud, not a heirarchy. “color=red” is the same feature as “background-color=red”, so needs to be multiply assigned.
    • A feature-set can either have sub-feature sets (middle of cloud), or features (edge of cloud). - Note - implemented by merging features and feature sets.
    • Add support-sets, to make positive assertions about a version supporting a feature-set. Only negative assertions can be made based on features. - Note - implemented by merging features and feature sets
    • Drop order of features by feature set. Client will alpha-sort.
    • supports.support, drop “prefixed” status. If prefixed, support = ‘yes’, and prefix is set.
    • Add examples of filtering (browser versions in 2010, firefox versions before version X).
  • Holly’s suggestions
    • Nail down the data, so she has something solid to build a UX on.
    • sheppy or jms will have experience with how users use tables and contribute to them, how frequently.
  • Add history resources for specifications, etc.

  • Add empty resource for deleted items?