Repository files navigation

This repository contains a curated list of technical Web specifications.The list is used in a variety of ways, which include:

• Reffy, which generatesWebref, which is then usedby tools such asReSpec andBikeshed to create terminologyand reference links between Web specifications.
• BCD andweb-features to validatespecification URLs
• Specref to complete the list of specificationsthat can be referenced.
• Analyzers of browser technologies to create reports on test coverage,WebIDL, and specification quality.

The repository is calledbrowser-specs because browsers werehistorically the focus of the list; it is now open to any spec that canreasonably be qualified as a "Web specification".

• Installation and usage

• Spec object
  • url
  • shortname
  • title
  • shortTitle
  • categories
  • standing
  • obsoletedBy
  • formerNames
  • series
    • series.shortname
    • series.currentSpecification
    • series.title
    • series.shortTitle
    • series.releaseUrl
    • series.nightlyUrl
  • seriesVersion
  • seriesComposition
  • seriesPrevious
  • seriesNext
  • forkOf
  • forks
  • organization
  • groups
  • release
    • release.url
    • release.status
    • release.filename
    • release.pages
  • nightly
    • nightly.url
    • nightly.status
    • nightly.alternateUrls
    • nightly.filename
    • nightly.pages
    • nightly.repository
    • nightly.sourcePath
  • tests
    • tests.repository
    • tests.testPaths
    • tests.excludePaths
  • source
• Spec identifiers
• How to add/update/delete a spec
• Versioning
• Spec selection criteria
• Development notes
  • How to generateindex.json manually
  • How to check a new spec
  • Debugging tools
    • Lookup a spec inindex.json
    • Run tests
    • Build a restricted set of specs
  • How to release a new version

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

npm install web-specs

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

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

Alternatively, you can fetchindex.jsonor retrieve the list from theweb-specs@latest branch.

The subset of specs that target web browsers is published in a separatebrowser-specs package. You may retrieve that filtered list from thebrowser-specs@latest branch

Each specification in the list comes with the following properties:

{"url":"https://www.w3.org/TR/css-color-4/","seriesComposition":"full","shortname":"css-color-4","series": {"shortname":"css-color","currentSpecification":"css-color-4","title":"CSS Color","shortTitle":"CSS Color","releaseUrl":"https://www.w3.org/TR/css-color/","nightlyUrl":"https://drafts.csswg.org/css-color/"  },"seriesVersion":"4","seriesNext":"css-color-5","organization":"W3C","groups": [    {"name":"Cascading Style Sheets (CSS) Working Group","url":"https://www.w3.org/Style/CSS/"    }  ],"release": {"url":"https://www.w3.org/TR/css-color-4/","filename":"Overview.html"  },"nightly": {"url":"https://drafts.csswg.org/css-color/","repository":"https://github.com/w3c/csswg-drafts","sourcePath":"css-color-4/Overview.bs","filename":"Overview.html"  },"title":"CSS Color Module Level 4","source":"w3c","shortTitle":"CSS Color 4","categories": ["browser"],"tests": {"repository":"https://github.com/web-platform-tests/wpt","testPaths": ["css/css-color"    ]  }}

The versioned (but not dated) URL for the spec. For W3C specs published asTR documents, this is the TR URL. For WHATWG specs, this is the URL of theliving standard. For specs developed by an organization that does not providea public version of the spec such as ISO, this is the URL of the page thatdescribes the spec on the organization's web site. In other cases, this is theURL of the latest Editor's Draft.

The URL should be relatively stable but may still change over time. SeeSpec identifiers for details.

Theurl property is always set.

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 forhttps://compat.spec.whatwg.org/). For specs developed onGitHub, this is usually the name of repository that holds the spec.

When the spec is a fork (seeforkOf) of a base spec, its shortnamewill start with the shortname of the base spec completed by-fork- and theactual shortname of the fork spec. For instance, given an exception handlingfork of the WebAssembly spec for which the raw shortname would beexception-handling, the actual spec shortname will bewasm-js-api-1-fork-exception-handling.

The shortname should be relatively stable but may still change over time. SeeSpec identifiers for details.

Theshortname property is always set.

The title of the spec. The title is either retrieved from an official source(theW3C API for W3C specs, theworkstreams database forWHATWG specs, etc.), or from the spec itself. Thesource propertydetails the actual provenance.

Thetitle property is always set.

The short title of the spec. In most cases, the short title is generated fromtitle by dropping terms such as "Module", "Level", or "Standard". In somecases, the short title is set manually.

TheshortTitle property is always set. When there is no meaningful shorttitle, the property is set to the actual (possibly long) title of the spec.

An array that contains the list of categories that the spec belongs to. The onlypossible value so far is"browser", which means that the spec targets webbrowsers.

Thecategories property is always set. Value may be an empty array for some ofthe specs in theweb-specs package. Value always contains"browser" forspecs in thebrowser-specs package.

A rough approximation of whether the spec is in good standing, meaning that,regardless of its current status, it should be regarded as a spec that gets somelove from targeted implementers and as a spec that has some well-defined scope,whether the spec has not yet matured enough or should only be viewed as acollection of interesting ideas for now, or whether development of the spec hasbeen discontinued.

Specs for which the status is "Unofficial Proposal Draft" or "A Collection ofInteresting Ideas" typically have a standing set to"pending" (but there maybe exceptions).

Specs whose status is "Discontinued Draft" typically have a standing set to"discontinued".

Thestanding property is always set. Value may either be"good","pending"or"discontinued". Value is always"good" for specs in thebrowser-specspackage.

An array that contains the list of shortnames of specs that replace or otherwiseobsolete the contents of a discontinued spec.

TheobsoletedBy property is only set whenstanding is"discontinued",provided that there are indeed specs that replace the contents of the spec.

An array that contains the list of shortnames that were used to identify thespec in the past. The property is not meant to provide an exhaustive list of allthe shortnames that a spec ever had, but just a list of the shortnames that thespec used to havein browser-specs.

By definition, shortnames listed informerNames properties are notcurrentshortnames. They can be used in projects that consume the list of specs to tracka specification over time.

TheformerNames property is only set for specs that used to be known under adifferentshortname in browser-specs.

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

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

Theseries property is always set.

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

Theshortname property is always set.

The shortname of the spec that should be regarded as the current level orversion in the series. The current spec in a series is up to the group whodevelops the series. In most cases, the current spec is the latest level orversion in the series that is a "full" spec (seeseriesComposition).

ThecurrentSpecification property is always set.

The version-less version of the title of the spec which can be used to refer toall specs in the series. The title is either retrieved from theW3C API for W3C specs, or derived from thespec'stitle.

Thetitle property is always set.

The short title of the series title. In most cases, the short title is generatedfromseries.title by dropping terms such as "Module", "Level",or "Standard". In some cases, the short title is set manually.

TheshortTitle property is always set. When there is no meaningful shorttitle, the property is set to the actual (possibly long) series title.

The URL of the latest published snapshot for the spec series. For leveled specs(those that create a series), this matches the unversioned URL. In most cases,that unversioned URL will return the specification identified by thecurrentSpecification property. It may returnan earlier level though, e.g. when the current specification has not yet beenpublished as a TR document.

For instance, this property will be set tohttps://www.w3.org/TR/css-fonts/for all specifications in the CSS Fonts series.

For non-leveled specs, this matches theurl property.

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

For leveled specs (those that create a series), this matches the unversioned URLthat allows to access the latest Editor's Draft of the current specification inthe series. That unversioned URL should return the specification identified bythecurrentSpecification property.

For instance, this property will be set tohttps://drafts.csswg.org/css-fonts/for all specifications in the CSS Fonts series.

For specs that are not part of a series of specs, this matches thenightly.url property.

ThenightlyUrl property is always set when thenightly propertyis set.

The level or version of the spec, represented as anx,x.y orx.y.z stringwithx,y andz numbers, andx always greater than or equal to1. Forinstance, this property will have the value1.2 (as a string, so enclosedin") for the WAI-ARIA 1.2 spec.

TheseriesVersion property is only set for specs that have a level or versionnumber.

Whether the spec is a standalone spec, whether it is a delta spec over theprevious level or version in the series, or whether it is a temporary fork ofanother spec. Possible values arefull,delta, orfork.

TheseriesComposition property is always set.

Theshortname of the previous spec in the series.

TheseriesPrevious property is only set where there is a previous level orversion.

Theshortname of the next spec in the series.

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

The shortname of the spec that this spec is a fork of.

TheforkOf property is only set when the spec is a fork of another one. TheseriesComposition property is always"fork" when theforkOf property is set.

A forked specs is supposed to be temporary by nature. It will be removed fromthe list as soon as it gets merged into the main spec, or as soon as it getsabandoned.

An array that lists shortnames of known forks of the spec in the list.

Theforks property is only set when there exists at least one fork of thespec in the list, in other words when there is an entry in the list that has aforkOf property set to the spec's shortname.

The name of the standardization organization that owns the spec such asW3C,WHATWG,IETF,Ecma International,Khronos Group.

Theorganization property is always set.

The list the groups that develop (or developed) the spec. Each item in the arrayis an object with aname property that contains the human-readable name of thegroup and aurl property that targets the homepage of the group.

Thegroups property is always set. In most cases, a spec is developed by oneand only one group.

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

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

The URL of the latest published snapshot of the spec. Matches the versionedURL (seeurl).

Theurl property is always set.

The status of the latest published snapshot of the spec. SeeDocuments published at W3C for possiblevalues, e.g. "Recommendation", "Candidate Recommendation Draft", "DraftRegistry" or "Working Draft".

Thestatus property is always set.

The filename of the resource that gets served when the default URL is fetched.For instance, the filename forhttps://www.w3.org/TR/presentation-api/ isOverview.html, meaning that the specification could also be retrieved fromhttps://www.w3.org/TR/presentation-api/Overview.html. The filename may beuseful to distinguish links to self in a spec.

Thefilename property is always set.

The list of absolute page URLs when the spec is a multipage spec.

Thepages property is only set for specs identified as multipage specs.

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

Thenightly property is always set unless the spec does not have a publicversion available through a URL. For instance, ISO specs are not publiclyavailable.

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

The URL is either retrieved from an official source (theW3C API for W3C specs, theworkstreams database forWHATWG specs, etc.) when possible. The document at the versioned URL isconsidered to be the latest Editor's Draft otherwise. Thesourceproperty details the actual provenance.

The URL should be relatively stable but may still change over time. SeeSpec identifiers for details.

Theurl property is always set.

The status of the nightly version of the spec. This is typically "Editor'sDraft" or "Living Standard", but can also be "Draft Community Group Report"for Community Group drafts, "Unofficial Proposal Draft" for some unofficialCSS specifications, "Internet Standard" for IETF specifications, etc.

Thestatus property is always set.

A list of alternate URLs for the Editor's Draft or the living standard.

The list typically contains URLs that external sources may use to reference thespec, be it because the canonical URL evolved over time and sources still useold URLs (e.g. when the spec was incubated in a Community Group and transitionedto a Working Group), or because the canonical URL is unstable for some reasonand external sources decided to use a workaround (e.g. CSS drafts).

Alternate URLs should only be used to ease mapping between external sources andspecs inbrowser-specs. The canonical URL innightly.urlshould be preferred to reference a spec otherwise.

Alternate URLs are only set when needed, in other words when an alternate URL iseffectively in use in some external source and when the external source cannoteasily be updated to use the canonical URL. In particular, the list is not meantto be exhaustive.

ThealternateUrls property is always set and is often an empty array.

The filename of the resource that gets served when the default URL is fetched.For instance, the filename forhttps://w3c.github.io/presentation-api/ isindex.html, meaning that the specification could also be retrieved fromhttps://w3c.github.io/presentation-api/index.html. The filename may beuseful to distinguish links to self in a spec.

Thefilename property is always set.

The list of absolute page URLs when the spec is a multipage spec.

Thepages property is only set for specs identified as multipage specs.

The URL of the repository that contains the source of the Editor's Draft or ofthe living standard.

The URL is computed fromnightly.url.

Therepository property is always set except for IETF specs where such a repo does not always exist.

The relative path to the filename that contains the source of the Editor's Draftor of the living standard at the HEAD of the default branch of the repository.

That path is computed by parsing the contents of the repository for commonpatterns. The info must be specified inspecs.json for specifications that donot follow a common pattern.

ThesourcePath property is always set whenrepository is set... except inrare cases where the source of the spec is not in the default branch of therepository.

Note: The path is relative to the root of the repository, and only valid inthe default branch of the repository. If needed, the source may be fetched fromthe absolute HTTPS URL${nightly.repository}/blob/HEAD/${nightly.sourcePath}.

An object that links the specification with its test suite when it has one.

The URL of the repository that contains the test suite of the specification,typicallyhttps://github.com/web-platform-tests/wpt.

Therepository property is always set when thetests object is present.

The list of relative paths to the actual tests at the HEAD of the default branchof the test repository.

For test suites withinWeb PlatformTests, the list is determined bylooking atMETA.yml files within each folder.

ThetestPaths array typically only contains one entry, but tests of a givenspec are sometimes spread over multiple folders. For instance, that is the casefor DOM and HTML tests.

ThetestPaths property is usually set when thetests object is present. Whenabsent, that means that the entire repository is the test suite.

The list of relative sub-paths of paths listed in thetestPaths property thatdo not contain tests for the underlying spec. For instance, tests for theWebXR Device API are under thewebxr folder,but several folders underwebxr actually contain test suites for WebXR modulespecs and as such need to be excluded from the test suite of the WebXR DeviceAPI spec.

TheexcludePaths property is seldom set.

The provenance for thetitle andnightly property values. Can be one of:

• w3c: information retrieved from theW3C API
• whatwg: information retrieved fromWHATWG
• ietf: information retrieved from theIETF datatracker
• iso: information retrieved from theISO Open Data datasetsiso_deliverables_metadata andiso_technical_committees, licensed under theODC Attribution License
• spec: information retrieved from the spec itself

Thesource property is always set.

An entry in browser-specs contains properties that can be viewed asidentifiers:shortname,url, andnightly.url. Please note that these identifiers are not fullystable.

Theshortname property should remain mostly stable over time. Theshortnamemay still change though, for instance when a W3C specification starts beingpublished as a TR document with a shortname that is different from the one usedduring incubation, or when an IETF specification gets published as an RFC.Starting in July 2023, when theshortname of a specification changes inbrowser-specs, the previousshortname gets added to aformerNames property. This makes it possible to track aspecification entry over time in browser-specs.

Theurl property contains a URL of the specification that can be regarded ascanonical and mostly stable too, but that URL will typically change when aspecification starts getting published as a formal technical document, or whena specification transitions from one organization or group to another one.

Thenightly.url property is the least stable identifier of a specification.That URL may be under the control of an individual or group, who may decide tochange the URL at any time. Or it may be affected by a change of status. Forinstance, thenightly.url property will change when a W3C spec incubated inthe Web Platform Incubator Community Group (WICG) transitions to a WorkingGroup, or when a new version of an IETF draft gets published.

If your project tracks specifications over time and relies on browser-specs togather information about these specifications, you will need to record theshortname of the specifications you're tracking, and apply the followingalgorithm to find the relevant specification entry in browser-specs:

1. Look for an entry in browser-specs whoseshortname matches the recordedshortname. If one is found, that is the relevant specification entry.
2. Look for entries in browser-specs that have the recorded shortname in itsformerNames property. If one is found, that is the relevant specificationentry.
3. If you found more than one entry in the previous step, that looks like a bugin browser-specs, pleaseraise anissue.
4. If you're still looking for a relevant specification entry at this pointwhereas the recorded shortname used to exist in browser-specs, that looks likea bug in browser-specs too, pleaseraise anissue.

Shortname changes may occur in major and minor releases of npm packages but notin patch releases.

If you believe that a spec should be added to the list, check theselectioncriteria below and use the"New spec" issuetemplate.

For other types of changes, please checkcontributinginstructions.

This repository contains a curated list of technical Web specifications that aredeemed relevant for the Web platform. Roughly speaking, this list should matchthe list of web specs actively developed by W3C, the WHATWG and a few otherorganizations.

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

1. The spec is stable or in development. Superseded and abandoned specs will notappear in the list. For instance, the list contains the HTML LS spec, but notHTML 4.01 or HTML 5).
2. The spec is being developed by a well-known standardization orpre-standardization group. Today, this means a W3C Working Group or CommunityGroup, the WHATWG, the IETF, the TC39 group, the Khronos Group, the Alliance for Open Media (AOM), or ISO.
3. The spec sits at the application layer or is "close to it". For instance,most IETF specs are likely out of scope, but some that are exposed to Web developers are in scope.
4. The spec defines normative content (terms, CSS, IDL), or it containsinformative content that other specs often need to refer to (e.g. guidelinesfrom horizontal activities such as accessibility, internationalization, privacyand security).

There are and there will be exceptions to the rule. Besides, some of thesecriteria 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.

This project adheres toSemantic Versioningwith the following increment rules given amajor.minor.patch version:

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

To re-generate theindex.json file locally, run:

npm run build

Important: The generation process will try to retrieve information about W3Cspecification from the W3C API. For that to work, the code requires the presenceof aconfig.json file in the root folder with aGH_TOKEN fieldset to a validGitHub Personal Token(default read permissions are enough).

Generation takes several minutes. SeeBuild a restricted set of specs below forincremental tools.

To check whether a new spec can be added to the list, run:

npx browser-specs build [url]

See the command help for details:

npx browser-specs --helpnpx browser-specs build --help

Theindex.js module can be used as a command-line interface (CLI) to quicklylook at a given spec in theindex.json file. The command outputs the spec orlist of specs that match the provided token as a formatted JSON string.

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

node index.jsnode index.js compatnode index.js mediaqueries-5node index.js deltanode index.js https://w3c.github.io/presentation-api/

Note: Theindex.js CLI is not part of released packages, which onlycontain the actual list of specifications.

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

npmtestnpmtest test/compute-shortname

Tests are run automatically on pull requests.

Thenpx browser-specs build command can be used to build a spec, or a seriesof changes made tospecs.json, see the command help for details:

npx browser-specs --helpnpx browser-specs build --help

The command will report the changes toindex.json that the tested updates would trigger, for instance (output truncated to better show the outline):

{"added": [    {"url":"https://dom.spec.whatwg.org/","seriesComposition":"full","shortname":"dom","...":"..."    }  ],"updated": [    {"url":"https://compat.spec.whatwg.org/","seriesComposition":"full","shortname":"compat","...":"..."    }  ],"deleted": [    {"url":"https://console.spec.whatwg.org/","seriesComposition":"full","shortname":"console","...":"..."    }  ]}

Releases are semi-automated through GitHub workflows. Whenever the list of specsis updated on the main branch, pre-release pull requests are created with thediff to release as description. Merging these pull requests releases the newversion of NPM packages.