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

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.

APIs

APIs are defined using Web IDL. An interface for instance 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>

The name of the interface is within a dfn element whereas everything else is referenced as term and defined elsewhere. (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. (See other specifications for examples.)

Language

Refer to the RFC2119 for the definitive use of verbs such as "must", "should", and "may". If you use the verb "must", the implementor must be able to write a test case for this requirement. The verb "may" merely grants permission and is used rarely. Do not use "may not." Do not use RFC2119 keywords in non-normative text such as notes, examples, or statements of facts (use words like "can" or "is" instead). Normal lowercase is preferred for readability.

Patterns

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

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.
<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-type>type</span>;
};

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

<p>The <dfn title=dom-PonyEvent-type><code>type</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.

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

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.