Introduction
A WebAssembly component is a .wasm file that packages core
WebAssembly modules together with the instructions for
linking them and the types of everything that crosses their boundary. The
component model explainer
compares a component to a module as an ELF executable or an OCI container is to machine
code: the module is the code, the component says how pieces of code link together and
talk to the outside world. Imports and exports have high-level types (strings, lists,
records, variants, resources) rather than just numbers, and a generated
canonical ABI layer converts those values to and from the linear memory of the
modules inside.
The file uses the same extension and the same first four bytes as a core module. It is
told apart by the next four bytes: 0D 00 01 00 (version 0x0d,
layer 0x01) instead of 01 00 00 00. It is a separate format with
its own binary grammar, so it has its own pages; see
the module pages for the other one.
The interface description language WIT is a text format. The WIT specification says WIT has no package format of its own: a WIT package is packaged as a component binary, with each interface and world encoded as a component type, so a compiled WIT package is a file of this format. How is described in WIT packages below.
Status: what is stable and what is gated
The component model is a WebAssembly proposal at phase 1 (“Feature
Proposal”, champion Luke Wagner) in the
proposals list. It has no
formal specification yet: the repository’s spec/ folder is a placeholder, and
Binary.md says it does not completely define decoding and validation, only
enough “to create a prototype”. The version field 0x0d is pre-standard: it
will be bumped upwards as the proposal changes and set to 0x1 once
standardised, so the bytes in this format will change before then.
In practice the format is used in production through the WASI developer-preview
releases, which keep the features they enable stable for tools. According to the
repository readme and Text.md (“Gated Features”):
| Group | What it covers |
|---|---|
| Stable, WASI 0.2 | Everything that has no emoji mark in the grammar files: core modules, core instances, components and instances, aliases, the type grammar without the gated types, lift and lower with the string, memory, realloc and post-return options, the three resource built-ins, imports and exports with plain and interface names, and the component-name section. |
| Shipped in later WASI releases, not open to breaking change | 🔀 native concurrency (async functions, stream, future and the built-ins for them; WASI 0.3.0), 🗺️ the map type and 🏷️ the implements and external-id attributes (WASI 0.3.1). |
| Gated: in progress, off by default, may change | 🪙 value imports and exports, value section and component-level start; 🪺 nested namespaces and packages in names; 🚝 more canonical options on async built-ins; 🚟 stackful async lift without a callback; 🧵 threading built-ins (and 🧵② those based on shared-everything threads); 🔧 fixed-length lists; 📝 the error-context type; 🔗 canonical interface names and the version-suffix attribute; 🐘 64-bit memories; 📡 getters and setters; ➡️ stream.forward and future.forward. |
The reference pages describe every encoding in Binary.md, gated ones
included, and mark each gated item with its emoji. A parser for today’s files needs the
unmarked parts; the marked parts are listed so that a file using them can be read, not
because they are settled. Only the emoji legend is in Text.md: where the
binary file does not mark a production (for example the async function type
0x43) the page says so.
Structure
A component is an 8-byte preamble followed by sections. Each section is a one-byte ID, a size as unsigned LEB128 and its contents, the same frame as in a core module. Unlike a module there is no fixed section order and any kind of section may appear several times: a component is a sequence of definitions, each of which may refer only to definitions before it. The sections are custom, core module, core instance, core type, component, instance, alias, type, canon, start, import, export and value. The core module and component sections hold complete embedded modules and components, each with its own preamble, so a component is a tree.
0magic00 61 73 6D4 bytes4version0D 002 bytes6layer01 002 bytes8sections, in any order, any number of eachvaries+0id: 0 custom, 1 core module, 2 core instance, 3 core type, 4 component, 5 instance, 6 alias, 7 type, 8 canon, 9 start, 10 import, 11 export, 12 value1 byte+1size of the contents, LEB1281 to 5 bytes…contents, usually a vector of definitionssize bytes
The pages in this reference:
- Preamble and sections – the preamble, how to tell a component from a module, every section ID, the sorts and index spaces, instances, aliases, start, imports, exports and the value section
- Types – core types and module types, the component value types, function, resource, component and instance types
- Canonical definitions –
lift,lower, every built-in and every canonical option - Names – the name forms of imports and exports, attributes, interface names and the
component-namesection
WIT packages
Source: design/mvp/WIT.md, “Package Format” (component-model repository, branch
main, raw, read 2026-11-19). “Each top-level WIT definition can be compiled into a single
canonical Component Model type definition that captures the result of performing the type resolution”;
these types are exported by a component, “allowing a single component to package both runtime
functionality and development-time WIT interfaces. Thus, WIT does not need its own separate package
format; WIT can be packaged as a component binary.” The document gives these advantages: the binary format
(the type encoding in particular) is reused; downstream tools do not have to repeat the resolution logic
or know the resolution environment (directories, registries, paths); the WIT syntax can evolve without
breaking tools; WIT interfaces and worlds can be published with the same tooling and named with the same
namespace:package/export scheme as components; and one package can hold an implementation and
the interface and world definitions it imports. The text-format examples below are
the document’s; in the binary each is a type definition (section 7) exported through the export section.
An interface
- Each top-level WIT definition becomes a type export of the same kebab-case name (the
interface
typesin packagelocal:demois exported astypes). - Each interface becomes a component type that exports an instance named with
the fully qualified interface name (
local:demo/types). The nesting lets one component both define and implement a WIT interface without a name clash. - The wrapping component type has an import for every
usein the interface, bringing the used types into scope so they can be aliased inside the instance type. It can be read as parameterising the instance type (“∀T.{instance type}”). There is always an outer wrapping component type, even with nouse. - A resource
filebecomes an exported(sub resource)type, and its functions are exported under the names[method]file.read,[constructor]…and so on, with the receiver as a first parameterselfof type(borrow $file); a function that returns a resource returns(own $file).
(component
(type (export "types") (component
(export "local:demo/types" (instance
(export $file "file" (type (sub resource)))
(export "[method]file.read" (func
(param "self" (borrow $file)) (param "off" u32) (param "n" u32)
(result (list u8))))))))
(type (export "namespace") (component
(import "local:demo/types" (instance $types
(export "file" (type (sub resource)))))
(alias export $types "file" (type $file))
(export "local:demo/namespace" (instance
(export "open" (func (param "name" string) (result (own $file)))))))))
(That is the document’s example for interface types and interface namespace,
shortened to one method.) Every top-level definition is self-contained and valid by itself, so packages can
be split or united. When a component holding WIT definitions is published to a registry, the registry is
expected to check that the interface names inside agree with the package name it assigns: this example is
valid only as package local:demo. A reference to another package (use
wasi:http/types.{request}) is encoded the same way: an import of the instance
wasi:http/types in the wrapping component type, whose definition is simply not in the file.
A world
- A world is encoded like an interface, but the inner exported instance is replaced by an inner exported
component named with the qualified world name (
local:demo/the-world). That inner component holds the world’s imports and exports. In the current WIT version the outer wrapping component type holds a single export, only to separate the kebab-case name from the inner qualified name. - When a world imports or exports an interface, the interface’s compiled instance type is copied into the world’s component type, so a compiled world is self-contained and can be used to build a component without further type information.
- 🏷️ When a world imports or exports a named interface under a custom plain name
(
import one: store;), the import or export carries an(implements "local:demo/store")annotation (and an(external-id "…")from an@external-idattribute) saying which interface that instance implements. Each such copy is a separate instance, so a resource type of the interface is duplicated per copy unless it is moved to a separate interface that the othersuse: then the world imports that interface’s resource once, aliases it, and the copies refer to it with an(eq $b)type bound. - Inside a concrete world, the interfaces that it imports are not “parameterised”: there is no wrapping
component type, and every
useis replaced by an alias of an earlier type import, as decided by the WIT resolution.
(component
(type (export "the-world") (component
(export "local:demo/the-world" (component
(export "test" (func))
(export "run" (func)))))))
Feature gates
The WIT @since and @unstable gates are not represented in the
binary: they act as macros, in place of keeping two copies of a WIT document. The target version and the set
of explicitly enabled features decide, when a collection of documents is encoded, whether each gated item is
included. For package ns:p@1.1.0 with a function f and a function g
marked @since(version = 1.1.0), a target version of 1.0.0 gives an instance named
ns:p/i@1.0.0 with only f; 1.1.0 gives ns:p/i@1.1.0 with f and
g. The gates are source-level tooling, not part of the run-time semantics of components.
The WIT language itself (syntax, name resolution, the file layout) is not described here; see
WIT.md.
Planned changes before 1.0
Binary.md, “Binary Format Warts to Fix in a 1.0 Release”, lists six changes. None is fixed
yet.
- The opcodes (for types, canonical built-ins and so on) should be re-sorted.
- The two
listtype codes should be merged into one with an optional immediate, and similarly forfunc. - The redundant
00and01opcodes ofnameattributeswill be merged. - The vestigial
00in thethread.*andwaitable-set.*built-ins may be removed. - Most built-ins should have a
canonopt*immediate instead of an ad hoc subset ofcanonopts. - An optional
sharedimmediate should be added to all canonical definitions (explicitly or throughcanonopt) when shared-everything threads (🧵②) are added.
Separately, in the notes on core types, Binary.md says the module type, whose code
50 overlaps the core sub code, will get a new non-overlapping opcode by the 1.0
release (see Types). The version field will become
0x1 when the specification is final.
Not described
Known, not yet covered
- Reference: not covered (runtime behaviour, not file contents): the algorithms of the Canonical ABI in
CanonicalABI.md, that is how values are loaded, stored, lifted and lowered, and the runtime state (handle tables, tasks, waitable sets, buffers). The canonical definitions page lists every encoding, option and core signature but not these algorithms. The static parts, flattening, alignment and element size, are on the canonical definitions page, and the static validation rules of each built-in are in its validation table. - Reference: not covered (the concurrency model): what the 🔀 and 🧵 built-ins do at run time beyond their signatures and a one-line purpose.
Concurrency.mdwas not read for these pages. - Reference: not covered (type-checking rules): the subtyping, instantiation and resource-generativity rules in the “Type Checking” section of
Text.md. The pages list the validation rules thatBinary.mdstates for each production. - Reference: not covered (text format and WIT): the text format
Text.mdbeyond what the binary needs, the WIT language inWIT.mdand the JavaScript embedding. Only the way WIT is packaged as a component is described, in WIT packages. - Viewer: inside a component the tree shows an embedded core module only as its preamble and section frames; its contents (types, code) are read by opening the module as a file of its own, which the viewer offers as an entry (the module viewer reads it). The index-space, type and canonical tabs are lists of the top-level component; a nested component’s own lists are read by opening it too.
- Viewer: not checked: whether an instantiation argument has a type that matches the import beyond its name, sort and, for functions, its type (the subtyping and substitution rules are not applied, so an abstract imported type is treated as matching any resource type); the generativity of resource types; that every record, variant, enum and flags type has an export name (“external visibility”: only locally defined resources are checked); and what the code of the embedded core modules does (a lifted function is checked against the types of the module’s exports, from a light read of its type, import, function, memory, table and export sections; a core module with global initialisers or a type it cannot follow leaves what depends on it unchecked, shown as “not known”).
- Viewer: the gates (🔀 🧵 📝 🪙 🔧 🗺️ 🏷️ 🔗 🪺 📡 🐘) are not enforced: every encoding of
Binary.mdis read whether or not a tool enables its feature, and a gated item is labelled with its mark. A component that has a sort named twice in itscomponent-namesection (three of the jco fixtures do) shows a soft problem, because the page says a sort “should” appear once. Part of the component model that has no binary encoding on these pages, such as the custom sections of the tool conventions at component level (producersis decoded; others are shown as bytes), is not decoded. - Viewer: tested on 15 public components (jco’s test fixtures for WASI 0.2 and 0.3, wit-bindgen’s
wasi-cli@0.2.0package, a wasm-tools test file), which read with no problem (a sixteenth file, a wasm-tools test with a wrong version on purpose, is correctly not taken for a component), on components built by hand for every section, type form and canonical definition, and on damaged ones; nowasm-toolswas available to cross-check a verdict.
Unknown
- Note (cannot be known yet, does not block the reference): the final 1.0 binary encoding. The six changes
Binary.mdplans, and the module-type opcode, are listed under planned changes, but none is fixed, and the version will change to0x1. - Note (source-read, annotated in place): the type-index encoding of a
valtype(signed 33-bit LEB128 inwasmparser) is on the Types page, and the component-level custom sections (decoded by name, as for modules) on the sections page, each marked as read from decoder source and not a rule of the specification. They were not run on a file for the pages; the viewer’s tests later read the type-index encoding in 15 public components without a problem (producersandcomponent-nameare decoded there; three of the jco test fixtures name the sortinstancetwice in theircomponent-namesection, which the page’s “a sort should appear once” does not allow, so the viewer reports it as a soft problem).
Also used for
- WebAssembly module – Portable bytecode for browsers and runtimes, in numbered sections.
Links
Software
Developers
- wasm-tools – command-line tools and the
wasmparserandwasm-encodercrates, which read and write components (Rust) - wit-bindgen – generates language bindings for components from WIT (Rust)
Reference
- Component Model binary format – the grammar of the binary format (
Binary.md) - Component Model text format – the AST, names, validation and the gated-features legend (
Text.md) - Canonical ABI – lifting, lowering and the built-ins (
CanonicalABI.md) - WIT – the interface description language and its component encoding (
WIT.md) - Component Model documentation – the Bytecode Alliance’s user-focused guide
- WebAssembly proposals – the phase table that lists the component model at phase 1
Sources for these pages
All pages are written from the files README.md,
design/mvp/Binary.md, Text.md, Explainer.md,
WIT.md and CanonicalABI.md of
github.com/WebAssembly/component-model
(branch main) and README.md of
github.com/WebAssembly/proposals,
fetched as raw files on 2026-11-18 and again on 2026-11-19 (the validation, flattening and WIT package
sections). The two decoder notes on the types and sections pages are from types.rs and
custom.rs of crates/wasmparser in
bytecodealliance/wasm-tools (main branch,
raw, 2026-11-19). The binary files themselves were not examined for these pages; the viewer built from them afterwards was
tried on 15 public component files (see Not described).