About this document

This document explains basic guidelines for writing a specification for the web platform. HTML and DOM among others follow these guidelines. You are encouraged to study those specifications and follow the patterns and style they establish.

Audience

This document focuses primarily on specifications aimed at browser implementors. The content of these specifications focuses on API calls that browsers implement and the required browser behavior under all possible cases. Specifications for user interface design and for authored content are not addressed here.

Content

Content in a specification falls into two general categories: normative and informative. Normative content includes the requirements and definitions and uses verbs such as must, should, and may. Refer to RFC 2119 for their definitions. If a normative statement uses the verb must (and applies to UAs), the browser implementor should be able to write a test case for it. (If it is not possible to write a test case for the statement, do not use the word must.) The verb "may" merely grants permission and is used rarely. Do not use "may not". Normal lowercase is preferred for readability.

Informative content is everything that is not normative. Informative (non-normative) content includes diagrams and code examples—very useful content, but supportive in nature to the actual browser requirements. Informative content must not include RFC 2119 keywords (use words like "can" or "is" instead).

Definitions

Elements, attributes, members of an object, algorithms, are all marked up using the dfn element. The title attribute of the element or its contents if there is no such attribute represents the name used for cross references. These are the conventions:

The interface members are described both in a non-normative and a normative way. Non-normatively using a <dl class=domintro> construct. Normatively as described in the following sections.

Defining an attribute

A readonly attribute is defined as follows:

The <dfn><code>novel</code></dfn> attribute must return "<code>Hear the Wind Sing</code>".

An attribute whose value can be set is typically defined as two distinct definitions:

The <dfn><code>pinball</code></dfn> attribute must return its value. Initially its value must be null.

Setting the <code>pinball</code> attribute must set its value to the given value.

Sometimes it gets a little bit more complicated and you need to use steps:

<p>Setting the <code>pinball</code> attribute must run these steps:
<ol>
<li><p>If the <span>readonly flag</span> is set, terminate these steps.
<li><p>Set the attribute to the given value.
</ol>

Keep this in mind:

Include requirements for setting the attribute to any value, not just to valid values. For example, an attribute that requires a float value must also prescribe what the browser does when the value is set to values of Infinity, zero, or NaN (not a number), unless that is already defined by IDL.

You can omit the "must" statement here for each step (as in the example above) if your conformance section says it is implied. The HTML spec, for example, says in its conformance section that "Requirements phrased in the imperative as part of algorithms (such as "strip any leading space characters" or "return false and abort these steps") are to be interpreted with the meaning of the key word ("must", "should", "may", etc) used in introducing the algorithm".

Attributes that return objects should always return the same object. Having an attribute that returns a new object each time it is accessed can make seemingly innocuous scripts perform a lot of expensive operations — for example, if such an attribute is used in a loop, every single iteration of the loop would involve allocating and initialising a new object.

Using steps helps implementors and QA making sure they have covered all the requirements.

Dealing with exceptions

Sometimes a method needs to throw an exception:

<p>The <dfn><code>isCuteAnimal(<var>animal</var>)</code></dfn> method must run these steps:
<ol>
<li><p>If <var>animal</var> is not "<code>cat</code>",
<span data-anolis-spec=dom title=concept-throw>throw</span> an "<code>UnknownAnimalError</code>" exception
and terminate these steps.

It is important to state whether the algorithm should be terminate when the exception is thrown or not; in some cases, an algorithm will continue even after an exception is thrown (e.g. to do some cleanup).

Events

Just dispatching an event is rather trivial:

<li><p><span data-anolis-spec=dom>Fire an event</span> named <code>tralala</code>
at the <span data-anolis-spec=dom title=concept-document>document</span>.

However, often the situation is more complicated. Events may need to be dispatched from within a task (see asynchronous below), listeners for the event can change the environment, events may need their own event object (to expose certain attributes), etc.

Asynchronous events

In certain circumstances the method returns "early", but the algorithm keeps going. This is done to ensure that the user interface does not lock up while running potentially expensive operations:

<li><p>Return, but continue running these steps asynchronouusly.
<li><p>Let <var>visible</var> be the number of cute animals in the user's surroundings.
<li><p>If <var>visible</var> is zero, terminate these steps.
<li><p><span data-anolis-spec=html>Queue</span> a <span data-anolis-spec=html>task</span>
to <span data-anolis-spec=dom>fire an event</span> named <code>spotted</code> at the
<span>context object</span>.

To still let the developer know of the effects of the method an event has to be dispatched. This is done using the "fire an event" concept from the DOM. As it cannot be dispatched synchronously since it happens in an operation running asynchronously from JavaScript's perspective, the event loop has to be used (queuing a task).

"Cancelable" events

Certain events are dispatched as part of an operation and allow the developer to choose whether to continue running the operation. These are often referred to as "cancelable events" (although actually the operation is cancelable). You can integrate these as follows:

<li><p><span data-anolis-spec=dom>Fire an event</span> named <code>hanginthere</code>
at the <span>context object</span>.
<li><p>If the event's <span>canceled flag</span> is set, terminate these steps.
<li><p>… eat all the things …

Events implementing their own interface

Often events are not just about notification, but also carry additional information. To make that work you will need to define your own event interface.

Callbacks

<p>The <dfn><code>getInspiration(<var>callback</var>)</code></dfn> method must run these steps:
<ol>
<li><p>Return, but continue running these steps asynchronously.
<li><p>Let <var>result</var> be the result of running <span>magic</span>.
<li><p><span data-anolis-spec=html>Queue</span> a <span data-anolis-spec=html>task</span>
to invoke <var>callback</var> with <var>result</var> as argument and <span>context object</span>
as <span>callback this value</span>.

Note that here we define the object the method was invoked upon as the callback this value. If you want the callback object itself to the this value you do not have to specify it, as that is the default.

When dealing with the event loop (task queuing) the task source also needs to be clear. See <canvas>'s toBlob() method for an example.

References

The following references provide useful information about specification writing and tools to aid the process of writing and producing a specification.

Language and terminology:RFC2119. This document explains when and why to use those spec'y verbs like must, may, and should.

Interface definitions:Web IDL. This document defines an interface definition language (IDL) that is useful for describing interfaces intended to be implemented in web browsers. It defines how to write the IDL blocks, how to overload methods, and the basics of common JavaScript bindings. This standard format helps to streamline the definitions for common script objects and allows the spec to focus on defining the unique aspects of the requirements.

Formatting tool: Anolis. This irreverently named tool defines special markup elements that are processed by a Python script that adds the proper spec numbering, cross references, and table of contents. It's magic! This page demonstrates use of the prescribed markup elements.

More

Legacy DOM-style

The old DOM specifications had a particular style of defining methods and attributes that is strongly discouraged (the separation of method definition from arguments, exceptions, and return value). Unfortunately ReSpec.js uses this style by default (consider using Anolis). E.g. the adoptNode() method in DOM Level 3 Core does not define which exception would be thrown first and more importantently it is not clear at all what the processing model is as you have to piece it together from various independent pieces of information. Therefore please follow the patterns outlined above as demonstrated by the adoptNode() method in DOM.