CDDL

CDDL

ReSpec parses, syntax-highlights, and auto-links CDDL (Concise Data Definition Language, RFC 8610) inside <pre class="cddl"> blocks.

CDDL describes the shape of data: which fields a message carries, their types, and which are optional. Specs use it the way browser specs use WebIDL, but for wire formats and JSON or CBOR payloads rather than for JavaScript APIs. If your spec defines messages rather than interfaces, CDDL is probably what you want. RFC 8610 teaches the language itself; this page covers only what ReSpec does with it.

You get CDDL support automatically if your spec loads respec-w3c.js, which almost every W3C spec does.

Quick example

<pre class="cddl">
  delivery = {
    address: tstr,
    zip: uint,
  }
</pre>
<p>Each {^delivery^} has an {^delivery/address^} and a {^delivery/zip^}.</p>

delivery becomes a definition you can link to. address and zip become member-key definitions scoped to delivery. tstr and uint auto-link to RFC 8610.

Authoring blocks

Wrap CDDL in <pre class="cddl">. References resolve across all blocks — a type used in one block can be defined in a later one.

To skip processing for a single block, add a data-no-cddl attribute to its <pre>.

Modules

Group blocks with data-cddl-module="<name>". Useful for protocols with distinct ends (for example, WebDriver BiDi's "local end" and "remote end"). The module name appears in the CDDL Index.

<pre class="cddl" data-cddl-module="local end">
  Command = { id: uint, method: tstr, params: any }
</pre>
<pre class="cddl" data-cddl-module="remote end">
  CommandResponse = { id: uint, result: any }
</pre>

What becomes a definition

Pattern in your CDDL	Becomes
Rule LHS — name = …	A linkable type
Rule extension — name /= … or //= …	Links to the existing definition (no duplicate)
Bareword map key — key:	A linkable key, scoped to its enclosing rule
String literal in a type choice — "value"	A linkable value, scoped to its enclosing rule

All definitions are exported, so other specs can reference them via xref.

Prelude types

The standard RFC 8610 prelude types (tstr, uint, int, bool, bytes, etc.) are recognised and auto-link to RFC 8610 Appendix D. No setup needed.

Linking from prose

Use {^…^} to link to a CDDL definition from the prose of your spec.

Shorthand	Links to	Example
{^name^}	A type	{^delivery^}
{^type/key^}	A key on a type	{^delivery/address^}
{^type/"value"^}	A literal value on a type	{^attire/"bow tie"^}

The quotes are significant — they distinguish a key name from a literal value.

If a {^…^} reference can't be resolved, ReSpec emits a warning and renders the link as plain text.

CDDL Index

Add <section id="cddl-index"> and ReSpec fills it with every CDDL definition in the document.

<section id="cddl-index"></section>

To exclude a block from the index, add class="exclude" to it. Blocks inside informative sections are excluded automatically. When you use data-cddl-module, the index groups by module.

Errors and warnings

• Invalid CDDL syntax — error. Fix the syntax in the offending block.
• Type referenced but never defined — warning. Likely a typo.
• {^…^} with no matching definition — warning. Check spelling, the for scope, or that the definition exists in some <pre class="cddl">.

Related

• Shorthands-Guide — ReSpec's full inline shorthand reference (including {^…^})
• WebIDL-Guide — the WebIDL equivalent for browser API surfaces