Import and export names are how hosts and parent components identify what a component
needs and offers, and are expected to be bound to variable, function and type names in
source languages, so they have a restricted, structured syntax. This page follows
design/mvp/Binary.md and Text.md (“Import and Export Definitions”) in the
component-model repository
(branch main, read 2026-11-18). Marks are the specification’s gates: 🏷️
attributes implements and external-id (shipped in WASI 0.3.1), 🔗
canonical interface names, 🪺 nested namespaces, 📡 getters and setters; see the
status table.
Name and attributes in the binary
Imports, exports and the import and export declarations of component and instance types
begin with nameattributes. Its first byte selects one of three forms; all start
with a u32 length and then that many bytes of the name (an externname,
as below):
| Byte | Encoding after the byte | Meaning | Gate |
|---|---|---|---|
00 | u32 length, name | a name | |
01 | u32 length, name | the same, a redundant form that will be merged with 00 in version 1.0 | |
02 | u32 length, name, vec(attribute) | a name and attributes | 🏷️ / 🔗 |
The length must equal the byte length of the name. Each attribute:
| Code | Encoding | Attribute | Gate |
|---|---|---|---|
00 | u32 length, interfacename | implements | 🏷️ |
01 | u32 length, semversuffix | version-suffix | 🔗 |
02 | a core name (u32 length, UTF-8) | external-id | 🏷️ |
Attributes give extra semantic information about an import or export; they do not identify it, so they are ignored by name-uniqueness checks and by type validation, and tools may interpret them to decide how to supply or call it.
implements🏷️ says an imported or exported instance implements a particular WIT interface, which lets one component import the same interface several times under different names. Validation requires the item to be instance-typed and to have a plain name.external-id🏷️ is an identifier in the host’s own naming scheme, for example a JavaScript module specifier such as a URL, for cases where the restrictedexternnamesyntax is not expressive enough.version-suffix🔗 holds the minor, patch and build part stripped from a canonical interface name. Validation requires it only on instance-typed imports or exports that have animplementsattribute or an interface name; it applies to theimplementsinterface name if present, otherwise to the item’s own.- A list of attributes may contain each kind at most once.
External names
An externname is a plain name or an interface name. The productions below are
lexical rules over characters: there is no whitespace, terminals are literal text.
externname ::= plainname | interfacename
plainname ::= label
| '[get]' label 📡
| '[set]' label 📡
| '[constructor]' label
| '[method]' ('[get]' | '[set]')? label '.' label (the get and set forms 📡)
| '[static]' ('[get]' | '[set]')? label '.' label (the get and set forms 📡)
interfacename ::= namespace words projection interfaceversion?
| namespace+ words projection+ interfaceversion? 🪺
namespace ::= words ':'
words ::= first-word ('-' word)*
projection ::= '/' label
interfaceversion ::= '@' valid-semver
| '@' canonversion 🔗
Labels
label ::= first-fragment ('-' fragment)*
first-fragment ::= first-word | first-acronym
first-word ::= [a-z] [0-9a-z]*
first-acronym ::= [A-Z] [0-9A-Z]*
fragment ::= word | acronym
word ::= [0-9a-z]+
acronym ::= [0-9A-Z]+
A label is kebab case: hyphen-separated words in lower case and acronyms in upper
case. This separates words from acronyms without a Unicode table, so a language binding can
convert it to its own style (is-XML may become isXML,
IsXml, is_XML or is_xml). The first fragment must start
with a letter, so a, a-b-c, a1-2-3, A-B-C,
a11-w0rds and m1x3d-4CR0NYMS are valid and 1-2-3 is not. The
same syntax applies to the labels of records, variants, flags, enums and parameters
(see types).
Plain names
A plain name leaves it to the developer to read the docs. The annotations are hints for
binding generators: [constructor]R is a constructor of resource R,
[method]R.f a method f of resource R and
[static]R.f a static function; with 📡, [get] and [set]
mark property getters and setters, standing alone or in front of the resource form. For
the annotated forms the first label is the resource name and the second the function’s name.
Validation:
- The annotations
[constructor],[method],[static],[get]and[set]only occur on function imports and exports. - For
[constructor],[method]and[static]the first label matches the name of a preceding resource import or export in the same scope (component, component type or instance type). [constructor]Rneeds a function whose result is(own $R)or(result (own $R) (error $E)?).[method]R.fneeds a first parameter(param "self" (borrow $R)).- 📡 A
[get]function has no parameters (onlyselfif also[method]) and a result type; for(result $V? (error $E)?)the result must have a value type. The getter’s property type is its result type, with aresultunwrapped to$V. - 📡 A
[set]name must be preceded in the same scope by the matching name with[get]; the function has exactly one parameter (two with[method], the firstself) of the getter’s property type, and either no result or(result (error $E)?)with no value type. - 🔀/📡 A getter or setter must not be
async.
Interface names
An interface name refers to a WIT interface in a package published in a namespace:
namespace:package/interface, for example wasi:http/handler, with an
optional @version. With the 🪺 gate there may be several namespaces and
projections (nested packages and interfaces). The version is a Semantic Versioning 2.0 version.
The name of a WIT interface compiled into a component has the form namespace:package/interface
(for example local:demo/types) and the wrapping component type exports an instance with
that name.
Canonical interface names 🔗
With 🔗 an interface name is canonical if it has no version or its version matches
canonversion, so that compatible versions can be matched by plain string
comparison:
canonversion ::= [1-9][0-9]* | '0.' [1-9][0-9]* | '0.0.' [1-9][0-9]* | '0.0.0'
| version-core '-' pre-release
semversuffix ::= [0-9A-Za-z.+-]+
A full semantic version is split into the canonversion that goes in the name and a
semversuffix that goes in the version-suffix attribute:
| Rule | Example |
|---|---|
| build metadata is always in the suffix | 0.0.1+sha.5114f85 → 0.0.1 and +sha.5114f85 |
| a pre-release version is not split (apart from build metadata) | 0.0.1-alpha → whole, no suffix |
| otherwise, if major is above 0, split after major | 1.2.3 → 1 and .2.3 |
| otherwise, if minor is above 0, split after minor | 0.2.6 → 0.2 and .6 |
| otherwise the version is already canonical | 0.0.1 |
Validation requires the interface version joined with the suffix to be a valid semantic
version that canonicalises to exactly that split. So a:b/c@1 with suffix .2.3
is valid, a:b/c@1 without a suffix is invalid (1 is not a semantic
version), and a:b/c@1.2 with .3 is invalid. For compatibility, non-canonical
interface names with any semantic version are temporarily allowed; they may warn and will be
rejected at some point.
Strong uniqueness
Names in one scope must not merely differ as strings: they must be strongly unique, so that two names cannot be mapped by a binding generator to the same identifier. The scope is all imports of a component or component type, all exports of a component, instance, component type or instance type, and also the labels of parameters, results, fields, cases and flags in their own list. To compare two names:
- Canonicalise each name: remove all hyphens and lower-case the acronyms (upper-case letters); if the name has the form
[…]*l.lfor annotations and some labell, replace it byl; strip all[…]annotations except[constructor]and 📡[set]. - The names are strongly unique if the canonical strings are different.
These are all strongly unique: foo, foo-bar, [constructor]foo,
[method]foo.bar, [static]foo.baz, foo:bar/baz. Adding
FOO, [method]foo.foo, foo-BAR, foobar,
[constructor]FOO, [static]foo.bar (clashes with [method]foo.bar) or
foo:bar/BAZ would be a validation error. The rule means a method or static function
cannot share the name of its resource type, which leaves the name free for a constructor.
The component-name section
Like the core name section, a custom section (ID 0) can name everything a component can declare. It exists to aid debugging and is not required to be valid: engines should not reject a component whose name section is invalid.
| Item | Encoding | Meaning |
|---|---|---|
| section name | name = component-name | The custom section’s name. |
| component name | optional subsection 00, u32 size, a name | The name of the component. |
| sort names | any number of subsections 01, u32 size, a sort and a namemap | Names for the entries of one index space. |
| namemap | vec(nameassoc) | Each association is a u32 index and a name. |
Each subsection is its ID byte, a u32 size that must equal the length of its
contents, and the contents. The sort in a sort-names subsection is the
sort encoding (so a core sort takes
two bytes), and a particular sort should appear only once in a name section: component
instances, for example, can be named only once. The component name subsection comes first;
the grammar has it optional. A namemap is as in the core name section; the core module
pages describe its ordering (sorted by index, no duplicates).
Sources
design/mvp/Binary.md (“Import and Export Definitions”, “Name Section”) and
design/mvp/Text.md (“Import and Export Definitions”, “Name Uniqueness”,
“Canonical Interface Name”) and design/mvp/WIT.md (the component encoding of
interfaces) in
github.com/WebAssembly/component-model,
raw files read 2026-11-18.