Specification tables - The MDN project 编辑

Every reference page on MDN should provide information about the specification or specifications in which that API or technology was defined. This article demonstrates what these tables look like and explains how to construct them.

These tables are similar in some respects to the compatibility tables (which should also be present on any page that has a specification table).

Format

A specification table has traditionally consisted of three columns:

Specification

The name of and link to the specification in which the technology is defined.

Status

The specification's status (for example, whether it's an editor's draft or a candidate recommendation).

Comment

Any additional information that may be relevant. This can be particularly helpful when an API is defined across multiple specifications, so that you can explain briefly what parts of the API come from each one.

Most of the tables you'll find on MDN consist of the above described columns, however, there are plans afoot to update the structure, so you might find some different structures here and there, and the eventual aim is to store spec definition links in our browser compat data repo, and auto-generate them from there. You can find a public discussion document at Improving MDN Specification tables.

Which specs should be included?

Each row in the table describes one specification on which the API or technology is based.

Which specs to include in each table depends on what features are being discussed on the reference page in question.

• If it is just a single feature of a spec, you usually just need to include a single line that details the latest spec the feature is defined in. See the AudioContext.close() Specifications, for example.
• If it is a landing page for an API where different parts of the API (e.g. extensions) are defined in different specs, you may need multiple lines referencing different specs. See the Gamepad API Specifications for a simple clear example.

Different types of specs

For technologies defined in "living specs" (for example HTML, or DOM), you'll probably only need to link to a single spec as that is the single canonical place where the technology will be defined.

Other specs (normally WebAPI specs) will tend to have a single URL that always points to the latest editor's draft, whichever spec that is (not always the same spec). In such cases, it is usually better to link to the latest editor's draft so that as the latest spec changes, the link will stay correct — the latest editor's draft is where all the latest features are defined and what browser vendors usually work from. This is therefore the most interesting place to link to, which is most likely to be up-to-date. Examples of this include the IndexedDB draft, Web Audio API draft, etc. You can find the latest draft link at the top of each specification.

Other specs will have the core functionality defined in one spec, but then other specs will extend that functionality, for example The Credential Management spec is extended by the Web Authentication spec (see the spec table).

With CSS specs, it is not that simple — CSS specs are generally broken up into different Levels, which introduce new functionality — for example Media Queries Level 4 and Media Queries Level 5. You'll often have to link to multiple specs to show where all the functionality of a feature is defined.

When adding specs to MDN (see how below), keep the above ideas in mind. Represent living standards as just the name of the technology (e.g. "HTML"). Represent latest spec drafts as WebAPI name draft (e.g. "IndexedDB draft"). Where multiple specs are required, use the exact name of the spec.

What not to include

There are a number of spec tables on MDN where we've included all the specs that define a feature, back to ancient times. For example, the CSS color property spec table. This goes all the way back to CSS level 1, but you probably don't need the bottom three rows of the table. Everything is defined in Level 4, except for the part about colors being animatable.

You especially don't need to refer to specs that are marked as obsolete. They aren't helpful.

Also, the W3C agreed to stop publishing snapshots of technology specs also covered by WHATWG living standards — for technologies covered by both, you can just list the WHATWG spec.

Macros

To help construct these tables in a standard format, with appropriate styling, we use KumaScript macros. There are two of these you need to know how to use.

{{SpecName}}

The SpecName macro is used to create the contents of the "Specification" column. It accepts three parameters:

1. The name of the specification.
2. An optional anchor within the linked specification; this lets you link to a particular section in a specification that defines multiple objects or interfaces, for example. Note that even if this parameter optional, it is strongly recommended: when the readers click on the generated link, they expect to reach the precise place in the spec where the concept is defined.
3. The property or entity name to use in the tooltip; this, too, is used when linking to specific interfaces within a specification. Although this parameter is also optional, it is strongly recommended to add it and it should be set to the name of the concept.

The names you may specify for specifications can be seen by looking at the specList object in the macro. If the specification you want to link to is not supported by the macro, propose a pull request that updates the SpecData file.

{{Spec2}}

The spec2 macro creates and inserts a widget indicating the status of a specification into the "Status" column, given the name of a specification. It also gets its data from the SpecData file. Again, if the specification you want to link to is not supported by the macro, propose a pull request.