Conceptio › Archive › ECMA International

ECMA Internationalopen access

ECMA-429 — Minimum common web API (December 2025)

ECMA International · ECMA International

ECMA International · Standards · License: Open Access

Open Source ↗Direct PDF ↓

api common ecma ecmainternational minimum web

ecma, standard, ecma international, specification, ecma-429, ecma 429, 429, minimum, common, web, api

ECMA-429 1

Edition / December 2025

Minimum common web API

is the registered trademark of Ecma International

Contents

Page

Scope . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

Conformance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

Normative references . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

Terms and definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

5 5.1 5.2 5.3

Common API index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 Common interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 Common methods & properties. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 Web workers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

The global scope . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

Requirements for default User-Agent value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

Annex A (informative) Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 A.1 Terms defined by this specification. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 A.2 Terms defined by reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 Bibliography . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

Introduction There is a wide base of ECMAScript runtime environments being used beyond web browsers, specifically in web server and edge platforms. A major benefit to this approach is the ability to use a single programming language across multiple contexts, reducing specialisation and allowing for reuse of code across the server and client side. Since code running in web browsers makes up the vast majority of ECMAScript code, runtimes are incentivised to support the same APIs as web browsers. However, without a specification of which web platform APIs to be implemented, the resulting landscape provides poor interoperability across such environments. As such, this Ecma Standard defines the Minimum common web API specification, which defines a subset of Web Platform APIs for server runtimes to implement for interoperability with the web. This is the first edition of the standard, corresponding to the 2025 snapshot. As the web platform and web server runtimes grow and evolve, the committee will aim to publish with an annual cadence.

Contributing to this Specification This version: https://min-common-api.proposal.wintertc.org/ Issue Tracking: GitHub Editor: James M Snell (Cloudflare)

This Ecma Standard was developed by Technical Committee 55 and was adopted by the General Assembly of December 2025.

iii

ALTERNATIVE COPYRIGHT NOTICE AND COPYRIGHT LICENSE © 2025 Ecma International By obtaining and/or copying this work, you (the licensee) agree that you have read, understood, and will comply with the following terms and conditions. Permission under Ecma’s copyright to copy, modify, prepare derivative works of, and distribute this work, with or without modification, for any purpose and without fee or royalty is hereby granted, provided that you include the following on ALL copies of the work or portions thereof, including modifications: (i) The full text of this COPYRIGHT NOTICE AND COPYRIGHT LICENSE in a location viewable to users of the redistributed or derivative work. (ii) Any pre-existing intellectual property disclaimers, notices, or terms and conditions. If none exist, the Ecma alternative copyright notice should be included. (iii) Notice of any changes or modifications, through a copyright statement on the document such as “This document includes material copied from or derived from Minimum common web API. Copyright © Ecma International.” Disclaimers THIS WORK IS PROVIDED “AS IS,” AND COPYRIGHT HOLDERS MAKE NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, WARRANTIES OF MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR PURPOSE OR THAT THE USE OF THE DOCUMENT WILL NOT INFRINGE ANY THIRD PARTY PATENTS, COPYRIGHTS, TRADEMARKS OR OTHER RIGHTS. COPYRIGHT HOLDERS WILL NOT BE LIABLE FOR ANY DIRECT, INDIRECT, SPECIAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF ANY USE OF THE DOCUMENT. The name and trademarks of copyright holders may NOT be used in advertising or publicity pertaining to the work without specific, written prior permission. Title to copyright in this work will at all times remain with copyright holders.

Minimum common web API 1 Scope This Standard defines the 2025 snapshot of the Minimum common web API, a curated subset of APIs defined by web platform standards from W3C and WHATWG, which is intended to define a minimum set of capabilities common to browser and web server runtime environments based on ECMAScript. The intended audience for this Standard is for web server runtime environments that want to be interoperable with the web platform. However, the set of APIs it describes may be implemented by any ECMAScript-based runtime environment that aims to be web-interoperable, even if its primary purpose is unrelated to web servers.

2 Conformance A conforming implementation of this Standard shall provide the interfaces and properties listed in this specification, according to their definition in the corresponding W3C or WHATWG standard. A conforming implementation shall also conform to ECMA-262. Runtime-specific extensions to any Web Platform API may be implemented by conforming runtimes. Such extensions shall be defined so that their use neither contradicts, nor causes the non-conformance of, normative functionality of any Web Platform API. Extending API surface, even without modifying existing API behaviours, should be avoided as it can reduce interoperability and portability of code across runtimes. Runtimes may implement Web Platform APIs beyond those listed in this Standard. NOTE For example, the Performance API could be extended with additional methods or properties beyond those defined in the High Resolution Time specifications, such as those defined in the Performance Timeline or User Timing Level 3 specifications.

3 Normative references The following documents are referred to in the text in such a way that some or all of their content constitutes requirements of this document. For dated references, only the edition cited applies. For undated references, the latest edition of the referenced document (including any amendments) applies. ECMA-262, ECMAScript Language Specification https://tc39.es/ecma262/multipage/ IETF RFC 9110, HTTP Semantics. June 2022. https://httpwg.org/specs/rfc9110.html W3C File API https://w3c.github.io/FileAPI/ W3C High Resolution Time https://w3c.github.io/hr-time/ W3C WebAssembly JavaScript Interface https://webassembly.github.io/spec/js-api/ W3C WebAssembly Web API https://webassembly.github.io/spec/web-api/

W3C Web Cryptography Level 2 https://w3c.github.io/webcrypto/ WHATWG Compression Standard https://compression.spec.whatwg.org/ WHATWG Console Standard https://console.spec.whatwg.org/ WHATWG DOM Standard https://dom.spec.whatwg.org/ WHATWG Encoding Standard https://encoding.spec.whatwg.org/ WHATWG Fetch Standard https://fetch.spec.whatwg.org/ WHATWG HTML Standard https://html.spec.whatwg.org/multipage/ WHATWG Streams Standard https://streams.spec.whatwg.org/ WHATWG URL Standard https://url.spec.whatwg.org/ WHATWG URL Pattern Standard https://urlpattern.spec.whatwg.org/ WHATWG Web IDL Standard https://webidl.spec.whatwg.org/ WHATWG XMLHttpRequest Standard https://xhr.spec.whatwg.org/

4 Terms and definitions For the purposes of this document, the terms and definitions given in ECMA-262, Compression Standard, Console Standard, DOM Standard, Encoding Standard, Fetch Standard, File API, High-Resolution Time, HTML Standard, Streams Standard, URL Standard, URL Pattern Standard, WebAssembly JavaScript Interface, WebAssembly Web API, W3C Web Cryptography Level 2, and the following apply. Externally-defined terms are mapped to source in Annex A. 4.1 web platform combination of technology standards defined by organizations such as the W3C, the WHATWG, and others as implemented by Web Browsers 4.2 web-interoperable runtime ECMAScript-based runtime environment that implements this Standard NOTE Web Browsers are Web-interoperable Runtimes. The term "Web-interoperable Runtime" is intentionally broad. The primary focus of this Standard is web server runtimes.

5 Common API index All Web-interoperable Runtimes conforming to this Standard shall implement each of the following Web Platform APIs. These should be implemented in accordance with their normative requirements except as specified in Clause 6, the global scope. Where any runtime environment must diverge from a normative requirement for technical or structural reasons, clear documentation shall be provided. Documentation shall include both explanation and impact of deviation. NOTE For example, since web server runtimes do not have an origin concept, they must violate Fetch Standard’s requirement of appending an Origin header to network requests.

5.1 Common interfaces All of the following interfaces shall be exposed on the global object accessible through globalThis. Interfaces defined in DOM Standard: • • • •

AbortController AbortSignal Event EventTarget

Interfaces defined in HTML Standard: • • • • • •

CustomEvent ErrorEvent MessageChannel MessageEvent MessagePort PromiseRejectionEvent

Interfaces defined in Web IDL Standard: • DOMException Interfaces defined in Fetch Standard: • Headers • Request • Response Interfaces defined in XMLHttpRequest Standard: • FormData NOTE The FormData constructor takes optional arguments of the types HTMLFormElement and HTMLElement, which are web API interfaces not included in the common API list in this Standard. Since both of these arguments are optional, the behavior when both are undefined or not given is always welldefined. The behavior in other cases for runtimes that do not implement such APIs is not well-defined by this Standard; future editions will provide greater clarity. Interfaces defined in File API: • Blob

• File Interfaces defined in Compression Standard: • CompressionStream • DecompressionStream Interfaces defined in Streams Standard: • • • • • • • • • • • • •

ByteLengthQueuingStrategy CountQueuingStrategy ReadableByteStreamController ReadableStream ReadableStreamBYOBReader ReadableStreamBYOBRequest ReadableStreamDefaultController ReadableStreamDefaultReader TransformStream TransformStreamDefaultController WritableStream WritableStreamDefaultController WritableStreamDefaultWriter

Interfaces defined in Encoding Standard: • • • •

TextDecoder TextDecoderStream TextEncoder TextEncoderStream

Interfaces defined in URL Standard: • URL • URLSearchParams Interfaces defined in URL Pattern Standard: • URLPattern Interfaces defined in Web Cryptography Level 2: • Crypto • CryptoKey • SubtleCrypto Interfaces defined in High Resolution Time: • Performance Interfaces defined in WebAssembly JavaScript Interface: • • • • •

WebAssembly.Global WebAssembly.Instance WebAssembly.Memory WebAssembly.Module WebAssembly.Table

• • • • •

WebAssembly.Tag WebAssembly.Exception WebAssembly.CompileError WebAssembly.LinkError WebAssembly.RuntimeError

5.2 Common methods and properties All of the following methods and properties shall be exposed on the global object accessible through globalThis, except as specified in Clause 6, the global scope. • globalThis (as defined in ECMAScript Language Specification) Methods and properties defined in HTML Standard: • • • • • • • • • • • • • •

globalThis.atob() globalThis.btoa() globalThis.clearTimeout() globalThis.clearInterval() globalThis.navigator.userAgent globalThis.onerror globalThis.onunhandledrejection globalThis.onrejectionhandled globalThis.queueMicrotask() globalThis.reportError() globalThis.self globalThis.setTimeout() globalThis.setInterval() globalThis.structuredClone()

Methods and properties defined in Fetch Standard: • globalThis.fetch() Methods and properties defined in Console Standard: • globalThis.console Methods and properties defined in Web Cryptography Level 2: • globalThis.crypto Methods and properties defined in High Resolution Time: • globalThis.performance Methods and properties defined in WebAssembly JavaScript Interface: • • • • • •

globalThis.WebAssembly.compile() globalThis.WebAssembly.compileStreaming() globalThis.WebAssembly.instantiate() globalThis.WebAssembly.instantiateStreaming() globalThis.WebAssembly.JSTag globalThis.WebAssembly.validate()

5.3 Web workers This Standard does not require runtimes to support web workers. However, if a runtime has global scopes that map to WorkerGlobalScope (see Clause 6, the global scope), then the global object shall also expose the following event handlers and attributes as defined in HTML Standard, except as specified in Clause 6, the global scope. • • • •

onerror onunhandledrejection onrejectionhandled self

6 The global scope The exact type of the global scope (globalThis) can vary across runtimes. Most Web Platform APIs are defined in terms that assume Web Browser environments that specifically expose types like Window, WorkerGlobalScope, and so forth. To simplify conformance, this Standard does not require such global scope interfaces to be supported, but each global scope in a relevant runtime may be mapped to a global scope interface defined in web specifications. All interfaces, methods, and properties defined by this Standard which are required by web specifications to be exposed in a global scope interface shall be exposed on all of the runtime’s corresponding global scopes (e.g., globalThis.crypto, globalThis.ReadableStream, etc). NOTE A runtime’s main global scope should map to Window, web worker global scope should map to WorkerGlobalScope, etc. Global scopes that do not map to a specifically defined global interface can only implement web APIs defined as [Exposed=*]. With many runtimes, adding a new global-scoped property can introduce breaking changes when the new global conflicts with existing application code. Many Web Platform APIs define global properties using the readonly attribute. To avoid introducing breaking changes, runtimes conforming to this Standard may omit the readonly attribute for properties being added to the global scope. This allows users of these runtimes to delete or overwrite these properties if they conflict with existing application code. Whenever the global object corresponds to the Window or WorkerGlobalScope global interfaces, it should be an instance of EventTarget. Web-interoperable runtimes should follow the report an exception algorithm, and the JavaScript HostPromiseRejectionTracker host hook, as defined in HTML Standard. This includes firing the error, unhandledrejection and rejectionhandled events on the global object. In cases where it is not possible to have such global objects be an instance of EventTarget due to legacy reasons, the relevant events shall still be fired through a suitable alternative mechanism available at the global scope. This mechanism shall provide at least the same information that is provided by the relevant event interfaces if the global object were to be an EventTarget. Such runtimes shall not support the onerror, onunhandledrejection and onrejectionhandled global properties. Such runtimes are not required to implement the ErrorEvent and PromiseRejectionEvent interfaces. NOTE For example, in Node.js the global object does not implement EventTarget, and the relevant events are fired on the globalThis.process object with the names uncaughtException, unhandledRejection and rejectionHandled, respectively.

7 Requirements for default User-Agent value The default User-Agent value is provided such that application code can reliably identify the runtime within which it is running. The value shall be a string conforming to the User-Agent construction in HTTP Semantics: User-Agent = product *( RWS ( product / comment ) ) product = token ["/" product-version] product-version = token The default User-Agent value should be treated by application code as a single, complete, opaque, unstructured value. It is recommended that the value be limited to a single product token excluding the optional product-version. The value should not include any comment components. NOTE

For instance, navigator.userAgent could be set to 'MyRuntime'.

Annex A (informative) Index A.1 Terms defined by this specification • Web-interoperable Runtime, in 4.2 • Web Platform, in 4.1

A.2 Terms defined by reference • Compression Standard defines the following terms: ◦ CompressionStream ◦ DecompressionStream • Console Standard defines the following terms: ◦ console • DOM Standard defines the following terms: ◦ AbortController ◦ AbortSignal ◦ CustomEvent ◦ Event ◦ EventTarget ◦ origin • ECMAScript Language Specification defines the following terms: ◦ globalThis • Encoding Standard defines the following terms: ◦ TextDecoder ◦ TextDecoderStream ◦ TextEncoder ◦ TextEncoderStream • Fetch Standard defines the following terms: ◦ Headers ◦ Request ◦ Response ◦ default User-Agent value ◦ fetch(input) • File API defines the following terms: ◦ Blob ◦ File • High Resolution Time defines the following terms: ◦ Performance ◦ performance • HTML Standard defines the following terms: ◦ ErrorEvent ◦ MessageChannel ◦ MessageEvent

◦ ◦ ◦ ◦ ◦ ◦ ◦ ◦ ◦ ◦ ◦ ◦ ◦ ◦ ◦ ◦ ◦ ◦ ◦ ◦ ◦ ◦ ◦ ◦ ◦ ◦ ◦ ◦

MessagePort PromiseRejectionEvent Window WorkerGlobalScope atob(data) btoa(data) clearInterval(id) clearTimeout(id) error navigator onerror (for GlobalEventHandlers) onerror (for WorkerGlobalScope) onrejectionhandled (for WindowEventHandlers) onrejectionhandled (for WorkerGlobalScope) onunhandledrejection (for WindowEventHandlers) onunhandledrejection (for WorkerGlobalScope) queueMicrotask(callback) rejectionhandled report an exception reportError(e) self (for Window) self (for WorkerGlobalScope) setInterval(handler, timeout, ...arguments) setTimeout(handler, timeout, ...arguments) structuredClone(value, options) unhandledrejection userAgent web worker

• Streams Standard defines the following terms: ◦ ByteLengthQueuingStrategy ◦ CountQueuingStrategy ◦ ReadableByteStreamController ◦ ReadableStream ◦ ReadableStreamBYOBReader ◦ ReadableStreamBYOBRequest ◦ ReadableStreamDefaultController ◦ ReadableStreamDefaultReader ◦ TransformStream ◦ TransformStreamDefaultController ◦ WritableStream ◦ WritableStreamDefaultController ◦ WritableStreamDefaultWriter • URL Standard defines the following terms: ◦ URL ◦ URLSearchParams • URL Pattern Standard defines the following terms: ◦ URLPattern • WebAssembly JavaScript Interface defines the following terms: ◦ CompileError ◦ Exception ◦ Global ◦ Instance ◦ JSTag ◦ LinkError ◦ Memory ◦ Module ◦ RuntimeError

◦ ◦ ◦ ◦ ◦ ◦

Table Tag WebAssembly compile(bytes) instantiate(bytes) validate(bytes)

• WebAssembly Web API defines the following terms: ◦ compileStreaming(source) ◦ instantiateStreaming(source) • Web Cryptography Level 2 defines the following terms: ◦ Crypto ◦ CryptoKey ◦ SubtleCrypto ◦ crypto • Web IDL Standard defines the following terms: ◦ DOMException ◦ Exposed ◦ read only • XMLHttpRequest Standard defines the following terms: ◦ FormData

Bibliography [1] W3C Performance Timeline https://w3c.github.io/performance-timeline/ [2] W3C User Timing Level 3 https://w3c.github.io/user-timing/

ECMA-429 — Minimum common web API (December 2025)

Related documents