Specification tables

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

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

Here's an example of what a specification table looks like; this one is for the MouseEvent interface:

Specification Status Comment
Document Object Model (DOM) Level 2 Events Specification Recommendation  
Document Object Model (DOM) Level 3 Events Specification Working Draft  
UI Events Working Draft Extend DOM3
Pointer Lock Working Draft Extend the MouseEvent interface

The table is a standard table with the CSS class spectable.

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 specification to which to link; 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 reader 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 too and 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 listed in the macro, ping an admin, or the dev-mdc mailing list so that it gets added.

{{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. Here again, if the specification you want to link to is not listed in the macro, ping an admin, or the dev-mdc mailing list so that it gets added.

Document Tags and Contributors

Contributors to this page: Sheppy, teoli
Last updated by: Sheppy,
Hide Sidebar