browser-specs

Web browser specifications

This repository contains a curated list of technical Web specifications that are directly implemented or that will be implemented by Web browsers (see Spec selection criteria).

This list is meant to be an up-to-date input source for projects that run analyses on browser technologies to create reports on test coverage, cross-references, WebIDL, quality, etc.

Table of Contents

• Installation and usage
• Spec object
  • url
  • shortname
  • title
  • series
    • series.shortname
    • series.currentSpecification
  • seriesVersion
  • seriesComposition
  • seriesPrevious
  • seriesNext
  • release
    • release.url
  • nightly
    • nightly.url
  • source
• How to add/update/delete a spec
• Spec selection criteria
• Versioning
• Development notes
  • How to generate index.json manually
  • Debugging tool
  • Tests
  • How to release a new version

Installation and usage

The list is distributed as an NPM package. To incorporate it to your project, run:

npm install browser-specs

You can then retrieve the list from your Node.js program:

const specs = require("browser-specs");
console.log(JSON.stringify(specs, null, 2));

Alternatively, you can either retrieve the latest release or fetch index.json.

Note: If you choose to fetch the index.json file directly, keep in mind that it may contain (possibly incorrect) updates that have not yet been included in the NPM package and the latest GitHub release (see also #38).

Spec object

Each specification in the list comes with the following properties:

{
  "url": "https://www.w3.org/TR/css-color-4/",
  "shortname": "css-color-4",
  "title": "CSS Color Module Level 4",
  "series": {
    "shortname": "css-color",
    "currentSpecification": "css-color-4"
  },
  "seriesVersion": "4",
  "seriesComposition": "full",
  "seriesPrevious": "css-color-3",
  "seriesNext": "css-color-5",
  "release": {
    "url": "https://www.w3.org/TR/css-color-4/"
  },
  "nightly": {
    "url": "https://drafts.csswg.org/css-color/"
  },
  "source": "w3c"
}

url

The versioned (but not dated) URL for the spec. For W3C specs published as TR documents, this is the TR URL. For WHATWG specs, this is the URL of the living standard. In other cases, this is the URL of the latest Editor's Draft.

The url property is always set.

shortname

A shortname that uniquely identifies the spec in the list. The value matches the "well-known" shortname of the spec, that usually appears in the versioned URL. For instance, for W3C specs published as TR documents, this is the TR shortname. For WHATWG specs, this is the shortname that appears at the beginning of the URL (e.g. compat for https://compat.spec.whatwg.org/). For specs developed on GitHub, this is usually the name of repository that holds the spec.

The shortname property is always set.

title

The title of the spec. The title is either retrieved from the W3C API for W3C specs, Specref or from the spec itself. The source property details the actual provenance.

The title property is always set.

series

An object that describes the series that the spec is part of. A series includes existing levels/versions of the spec. For instance, CSS Color Module Level 4 belongs to the same series as CSS Color Module Level 3 and CSS Color Module Level 5.

Please note that the list only contains specs that are deemed to be of interest. In particular, the list does not contain levels and versions that have been fully superseded, and may not contain early drafts of new levels and versions either.

The series property is always set.

series.shortname

A shortname that uniquely identifies the series. In most cases, the shortname is the shortname of the spec without the level or version number. For instance, the series' shortname for css-color-5 is css-color. When a specification is not versioned, the series' shortname is identical to the spec's shortname.

The shortname property is always set.

series.currentSpecification

The shortname of the spec that should be regarded as the current level or version in the series. The current spec in a series is up to the group who develops the series. In most cases, the current spec is the latest level or version in the series that is a "full" spec (see seriesComposition).

The currentSpecification property is always set.

seriesVersion

The level or version of the spec, represented as an x, x.y or x.y.z string with x, y and z numbers, and x always greater than or equal to 1. For instance, this property will have the value 1.2 (as a string, so enclosed in ") for the WAI-ARIA 1.2 spec.

The seriesVersion property is only set for specs that have a level or version number.

seriesComposition

Whether the spec is a standalone spec, or whether it is a delta spec over the previous level or version in the series. Possible values are full or delta.

The seriesComposition property is always set.

seriesPrevious

The shortname of the previous spec in the series.

The seriesPrevious property is only set where there is a previous level or version.

seriesNext

The shortname of the next spec in the series.

The seriesNext property is only set where there is a next level or version.

release

An object that represents the latest published snapshot of the spec, when it exists.

The release property is only set for W3C specs published as TR documents.

release.url

The URL of the latest published snapshot of the spec. Matches the versioned URL (see url).

The url property is always set.

nightly

An object that represents the latest Editor's Draft of the spec, or the living standard when the concept of Editor's Draft does not exist.

The nightly property is always set.

nightly.url

The URL of the latest Editor's Draft or of the living standard.

The URL is either retrieved from the W3C API for W3C specs, or Specref. The document at the versioned URL is considered to be the latest Editor's Draft if the spec does neither exist in the W3C API nor in Specref. The source property details the actual provenance.

The url property is always set.

source

The provenance for the title and nightly property values. Can be one of:

• w3c: information retrieved from the W3C API
• specref: information retrieved from Specref
• spec: information retrieved from the spec itself

The source property is always set.

How to add/update/delete a spec

If you believe that a spec should be added, modified, or removed from the list, or if you would like to otherwise contribute to this project, please check contributing instructions.

Spec selection criteria

This repository contains a curated list of technical Web specifications that are deemed relevant for Web browsers. Roughly speaking, this list should match the list of specs that appear in projects such as Web Platform Tests or MDN.

To try to make things more concrete, the following criteria are used to assess whether a spec should a priori appear in the list:

1. The spec is stable or in development. Superseded and abandoned specs will not appear in the list. For instance, the list contains the HTML LS spec, but not HTML 4.01 or HTML 5).
2. The spec is being developed by a well-known standardization or pre-standardization group. Today, this means a W3C Working Group or Community Group, the WHATWG, or the Khronos Group.
3. Web browsers expressed some level of support for the spec, e.g. through a public intent to implement.
4. The spec sits at the application layer or is "close to it". For instance, IETF specs are essentially out of scope, at least for now.
5. The spec defines normative content (terms, CSS, IDL), or it contains informative content that other specs often need to refer to (e.g. guidelines from horizontal activities such as accessibility, internationalization, privacy and security).

There are and there will be exceptions to the rule. Besides, some of these criteria remain fuzzy and/or arbitrary, and we expect them to evolve over time, typically driven by needs expressed by projects that may want to use the list.

Versioning

This project adheres to Semantic Versioning with the following increment rules given a major.minor.patch version:

• major: A property disappeared, its meaning has changed, or some other incompatible API change was made. When the major number gets incremented, code that parses the list likely needs to be updated.
• minor: A new property was added, the list of specs changed (a new spec added, or a spec was removed). Code that parses the list should continue to work undisturbed, but please note that there is no guarantee that a spec that was present in the previous version will continue to appear in the new version. Situations where a spec gets dropped should remain scarce. If you believe that removal of a spec should rather trigger a major update, please raise an issue and explain how it affects your project.
• patch: Info about one or more specs changed. Minor updates were made to the code that don't affect the list.

Development notes

How to generate index.json manually

To re-generate the index.json file locally, run:

npm run build

Tests

To run all tests or to test a given module locally, use one of:

npm test
npm test test/compute-shortname

Tests are run automatically on pull requests.

Debugging tool

The index.js module can be used as a command-line interface (CLI) to quickly look at a given spec in the index.json file. The command outputs the spec or list of specs that match the provided token as a formatted JSON string.

For instance, to retrieve all specs, the Compatibility Standard spec, the CSS Media Queries Module Level 5 spec, all delta specs, and a spec identified by its URL, run:

node index.js
node index.js compat
node index.js mediaqueries-5
node index.js delta
node index.js https://w3c.github.io/presentation-api/

Note: The index.js CLI is not part of the released package, which only contains the actual list of specifications.

How to release a new version

Provided that you have the appropriate admin rights and that a GITHUB_TOKEN environment variable is set to a GitHub Personal Token with repo rights, you may release a new version through the following command, to be run from an up-to-date local master branch:

npm run release

The release command should take care of everything including incrementing the version number, updating the changelog, creating a GitHub Release, and publishing a new NPM package. The command is interactive and will ask you to confirm the different steps. Please check the versioning rules to select the right version part to increment!