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:

The table is a standard table with the CSS class spectable. The code looks as follows:

<table class="spectable standard-table">
 <tbody>
  <tr>
   <th scope="col">Specification</th>
   <th scope="col">Status</th>
   <th scope="col">Comment</th>
  </tr>
  <tr>
   <td>{{SpecName('DOM2 Events','#Events-MouseEvent','MouseEvent')}}</td>
   <td>{{Spec2('DOM2 Events')}}</td>
   <td> </td>
  </tr>
  <tr>
   <td>{{SpecName('DOM3 Events','#events-mouseevents','MouseEvent')}}</td>
   <td>{{Spec2('DOM3 Events')}}</td>
   <td> </td>
  </tr>
  <tr>
   <td>{{SpecName('UI Events','#constructor-mouseevent','MouseEvent')}}</td>
   <td>{{Spec2('UI Events')}}</td>
   <td>Extend DOM3</td>
  </tr>
  <tr>
   <td>{{SpecName('Pointer Lock','#extensions-to-the-mouseevent-interface','MouseEvent')}}</td>
   <td>{{Spec2('Pointer Lock')}}</td>
   <td>Extend the <code>MouseEvent</code> interface</td>
  </tr>
 </tbody>
</table>

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 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 MDN discussion forum so that it gets added.