WebIDL Guide

WebIDL Guide

To specify an interface using WebIDL, you define a <pre class="idl"> block.

<pre class="idl">
interface Request {
  readonly attribute ByteString method;
  readonly attribute USVString url;
};
</pre>

Ideal linking setup

The recommended pattern is a <section data-dfn-for="InterfaceName"> that groups the IDL block with prose definitions for each member:

<section data-dfn-for="Fetch">
  <h2>The <code>Fetch</code> interface</h2>
  <pre class="idl">
  [Exposed=Window]
  interface Fetch {
    constructor(USVString url);
    readonly attribute USVString url;
    undefined send();
  };
  </pre>
  <section>
    <h2>Constructors</h2>
    <p>The <dfn constructor for="Fetch">constructor(url)</dfn> steps are:</p>
    <ol class="algorithm">
      <li>Set [=this=]'s {{Fetch/url}} to |url|.</li>
    </ol>
  </section>
  <section>
    <h2>Attributes</h2>
    <p>The <dfn attribute>url</dfn> attribute steps are to return [=this=]'s url.</p>
  </section>
  <section>
    <h2>Methods</h2>
    <p>The <dfn method>send()</dfn> method steps are:</p>
    <ol class="algorithm">
      <li>...</li>
    </ol>
  </section>
</section>

Using data-dfn-for

data-dfn-for on a <section> sets the default interface context for all <dfn> elements within it. This saves repeating the interface name on every definition:

<section data-dfn-for="Request">
  <p>The <dfn>url</dfn> attribute of {{Request}}.</p>
  <p>The <dfn>clone()</dfn> method.</p>
  <!-- Both dfns are automatically "for Request" -->
</section>

Without data-dfn-for, use explicit for= attributes on individual <dfn> elements.

Constructors

Define constructors with <dfn constructor for="InterfaceName">:

<p>The <dfn constructor for="Widget">constructor(name, options)</dfn> steps are:</p>
<ol class="algorithm">
  <li>Let |w:Widget| be a new {{Widget}} object.</li>
  <li>Set |w|'s {{Widget/name}} to |name|.</li>
  <li>Return |w|.</li>
</ol>

Link to the constructor from prose: {{Widget/constructor(name, options)}}.

Enums

Enum values defined in the IDL block are automatically linked. To add prose descriptions, define them explicitly using data-dfn-type="enum-value" and data-dfn-for:

<pre class="idl">
enum RequestMode { "navigate", "cors", "no-cors", "same-origin" };
</pre>

<p>The <dfn data-dfn-type="enum-value" data-dfn-for="RequestMode">"cors"</dfn>
mode means cross-origin requests are sent with CORS headers.</p>

<p>The <dfn data-dfn-type="enum-value" data-dfn-for="RequestMode">"navigate"</dfn>
mode is used for top-level navigation.</p>

Link to enum values in prose: {{RequestMode/"cors"}}.

Dictionaries

Dictionary members defined in IDL are automatically linked. Reference them in prose as {{DictionaryName/memberName}}:

<pre class="idl">
dictionary RequestInit {
  ByteString method = "GET";
  boolean keepalive = false;
};
</pre>

<p>If |init|'s {{RequestInit/method}} is not a [=method=], throw a {{TypeError}}.</p>

Multiple interfaces with same attributes/methods

If two interfaces share attribute or method names, use data-dfn-for to distinguish them:

<section data-dfn-for="Request">
  <p>The <dfn>url</dfn> attribute of {{Request}}.</p>
</section>

<section data-dfn-for="Response">
  <p>The <dfn>url</dfn> attribute of {{Response}}.</p>
</section>

Dfn types for IDL members

When defining IDL members as prose <dfn> elements, you can omit data-dfn-type when data-dfn-for is set on the containing section — ReSpec infers the type from the IDL. For explicit control:

Pattern	Type inferred
<dfn attribute>url</dfn>	attribute
<dfn method>send()</dfn>	method
<dfn constructor for="Foo">constructor()</dfn>	constructor
<dfn data-dfn-type="dict-member">method</dfn>	dict-member

Notes

• The <pre class="idl"> block is syntax-highlighted and validated by ReSpec
• IDL terms are automatically added to the terms index and IDL index
• Use class="exclude" on a <pre class="idl"> to keep it out of the IDL index: <pre class="idl exclude">
• See data-dfn-type for the full list of definition types