Specs/howto

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.

See also Advice for people writing specs.

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.

Organization

Each specification includes these top-level sections:

• Introduction — Gives an overview of the technology defined.
• Conformance — References RFC 2119 and/or explains how conformance is determined in this specification. Lists the conformance classes that apply to this specification. See http://www.w3.org/TR/qaframe-spec/
• Terminology — Defines where the terms in the specification originate from and sometimes provides a few novel definitions that do not fit within the main prose of the specification.
• … content …
• References
• Acknowledgments

See e.g. Progress Events and XMLHttpRequest.

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

See also Hixie's blog post on the subject: http://ln.hixie.ch/?start=1140242962&count=1

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:

• Interfaces: InterfaceName; e.g. interface Document { …
• Interface members: dom-InterfaceName-attributeOrMethodName; e.g. the URL</code> attribute must …
• Events: event-eventname
• Elements: elementname
• Attributes: attr-elementname-attributename
• Concepts: concept-word; e.g. <dfn title=concept-node>node</dfn>

You reference a definition using either the span or code element. Anolis takes care of linking back to the definition.

IDL

The structure of an API is defined using Web IDL. An interface can be defined as follows:

<pre class=idl>interface <dfn>ProcessingInstruction</dfn> : <span>Node</span> {
  readonly attribute DOMString <span title=dom-ProcessingInstruction-target>target</span>;
           attribute DOMString <span title=dom-ProcessingInstruction-data>data</span>;
};</pre>

(See also ProcessingInstruction in DOM Core.)

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.

Defining a method

Defining a simple method can be done as follows:

The <dfn><code>timesTwo(<var>num</var>)</code></dfn> method must return <var>num</var> × 2.

If the method is more complicated (or you feel like being more verbose) a list of steps can be used instead:

<p>The <dfn><code>add(<var>num1</var>, <var>num2</var>)</code></dfn> method must run these steps:
<ol>
 <li><p>Let <var>result</var> be <var>num1</var> + <var>num2</var>.
 <li><p>Return <var>result</var>.
</ol>

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.

<pre class=idl>[Constructor(DOMString <var>type</var>, optional <span>PonyEventInit</span> <var>eventInitDict</var>)]
interface <dfn>PonyEvent</dfn> : <span data-anolis-spec=dom>Event</span> {
  readonly attribute DOMString <span title=dom-PonyEvent-hairColor>hairColor</span>;
};

dictionary <dfn>PonyEventInit</dfn> {
  DOMString hairColor;
};</pre>

<p>The <dfn title=dom-PonyEvent-hairColor><code>hairColor</code></dfn> attribute must
return the value it was initialized to. When an 
<span data-anolis-spec=dom title=concept-event>event</span> is created it must be
initialized to "<code>rainbow</code>".

Defining the constructor is "magically" taken care of by the constructing events chapter of DOM. Dispatching an event implementing its own interface requires a bit more wording as well. See the "fire a progress event named e" for an example.

Event handler attributes

HTML defines event handlers. Introducing these on objects upon which events are dispatched is common practice. Excluding markup, the IDL for adding a "colorchange" event's handler would be:

  attribute EventHandler oncolorchange;

In prose you use the following language (replacing "Pony" with the name of the interface and "colorchange" with the name of the event):

<p>The following are the <span data-anolis-spec=html>event handlers</span> (and their corresponding 
<span data-anolis-spec=html title="event handler event type">event handler event types</span>) that must 
be supported on objects implementing the <code>Pony</code> interface:

<table>
 <thead>
  <tr>
   <th><span data-anolis-spec=html title="event handler">event handler</span>
   <th><span data-anolis-spec=html>event handler event type</span>
 <tbody>
  <tr>
   <td><dfn title="event-colorchange"><code>oncolorchange</code></dfn>
   <td><code>colorchange</code>
…

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.
• Also useful: HTML Design Principles. It's always good to keep the Big Picture in mind.

More

Here are some links to sources that might be helpful in expanding the above:

• http://lists.whatwg.org/htdig.cgi/whatwg-whatwg.org/2011-July/032361.html

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.