SpecProposalTemplate

Specification Proposal Template

This document is a template for "pre-specification" proposals that Mozilla contributors can use to write up their ideas for consideration. "Copy-paste" of the WikiText used here for the creation of such documents is encouraged.

Ideal use cases might be APIs, formats, protocols or even best practice guidelines that are possible candidates for implementation in Mozilla (or submissions as general documents) but aren't yet submitted to a standards-setting forum (including WHATWG, W3C, ES4, etc.).

Replace the term "Specification Proposal Template" with the title of what you're proposing.

Abstract

Use this section to describe in some short sentences what is specified in the document.

Example: "The XMLHttpRequest Object specification defines an API that provides scripted client functionality for transferring data between a client and a server."

Introduction

Use this section to introduce what you're proposing, and give the background to the problem space. This section consists of optional subsections "Use Cases" and "Terminology" defined below.

Example: "The first main goal of DOMEvents is the design of an event system which allows registration of event listeners and describes event flow through a tree structure.

Another goal is: [ ]"

Use Cases

This subsection should further specify what this proposal addresses by giving examples of how life gets better with the implementation of the proposal.

Example: "Developers have asked for a way to formalize ad-hoc mechanisms such as <script src="invalid.crossdomain.invocation.foo"> and have themselves proposed mechanisms such as JSONRequest which aren't desirable for varied types of web content. Potential use cases include

1. Mashups of data using a browser primitive, e.g. Mashup.com can invoke select data from Flickr.com using Access Control and XMLHttpRequest...

2. "

Terminology

Are you introducing any terminology that's potentially confusing? If so, clarify them in this subsection.

Example: "A browsing context is a collection of one or more Document objects, and one or more views.

At any one time, one of the Documents in a browsing context is the active document. The collection of Documents is the browsing context's session history.

A view is a user agent interface tied to a particular media used for the presentation of Document objects in some media. A view may be interactive. Each view is represented by an AbstractView object. Each view belongs to a browsing context."

Conformance

This section is optional, but recommended. Cut-paste this generally accepted blurb:

"Everything in this specification is normative except for diagrams, examples, notes and sections marked non-normative.

The key words must, must not, should and may in this document are to be interpreted as described in RFC 2119. RFC2119

This specification defines the following classes of products: "

And then mention what kinds of products you want described.

Example:

"Conforming user agent

A user agent MUST behave as described in this specification in order to be considered conformant.

..."

Dependencies

Are there any particular dependencies (e.g. existing specifications or interfaces) that this proposal relies on? List them here, and use subheadings for each one so that the Wiki's table of contents system picks up on them.

Specification Proposal

Now the interesting part! If you are specifying an API, use either XPIDL or Web IDL (when it's ready).

Do this for each interface or object you are defining, so that each appears as its own heading. After defining the interface, show use cases for example usage.

Example:

interface Foo {
  // event handler
           attribute EventListener onreadystatefubar;

  // state
  const unsigned short STATUS = 0;
  .....

Define each method and attribute in detail using <blockquote> and <code> blobs.

Example:

onreadystatefubar is of type EventListener is an attribute that MUST be invoked when a fubar event is called.

Syntax

You can use this optional section if you wish to specify something that is particular about the usage of your proposal, and which is outside the scope of an interface definition.

Create subheadings for each aspect of the syntax that you want specified. Good uses of this are either for HTTP headers or particular uses of syntax outside of interface definitions.

Example below:

Syntax Item 1

"Syntax Item 1 is used during a Request:

Syntax-Item-1: <*>

Some text defining the above."

Syntax Item 2

"Syntax Item 2 is used during a Response:

Syntax-Item-2: 0

Some text defining the above."

Not In This Specification

Are there particular items that are not specified in this proposal? List them here.

References

List your references. Include research on similar proposals that are in the space you want this proposal to exist (e.g. are there other proposals)?

Acknowledgements

List authors/contributors.