Minimum Common Web Platform API

Draft Community Group Report,

This version:
https://common-min-api.proposal.wintercg.org/
Issue Tracking:
GitHub
Inline In Spec
Editor:
(Cloudflare)

Abstract

Minimum Common Web Platform API for Non-Browser EcmaScript-based runtimes.

Status of this document

This specification was published by the Web-interoperable Runtimes Community Group. It is not a W3C Standard nor is it on the W3C Standards Track. Please note that under the W3C Community Contributor License Agreement (CLA) there is a limited opt-out and other conditions apply. Learn more about W3C Community and Business Groups.

1. Introduction

This section is non-normative.

The Minimum Common Web Platform API is a curated subset of standardized Web Platform APIs intended to define a minimum set of capabilities common to Browser and Non-Browser JavaScript-based runtime environments.

2. Terminology

The Web Platform is the combination of technology standards defined by organizations such as the W3C, the WHATWG, and others as implemented by Web Browsers.

A Web Platform API is a ... TBD.

A Web-interoperable Runtime is any EcmaScript-based application runtime environment that implements the subset of Web Platform APIs outlined in this specification. This term is intentionally broad to also encompass Web Browsers.

3. Common API Index

All Web-interoperable Runtimes conforming to this specification SHALL fully implement each of the following Web Platform APIs in accordance to their normative standard requirements except where modified here. Where any conforming runtime environment chooses (either by necessity or otherwise) to diverge from a normative requirement of the specification, clear explanations of such divergence MUST be made clearly and readily available in documentation.

Interfaces:

Global methods / properties:

4. The Global Scope

The exact type of the globalScope can vary across runtimes. Most Web Platform APIs are defined in terms that assume Web Browser environments that specifically expose types like Window, Worker, WorkerGlobalScope, and so forth. To simplify conformance, all Interfaces, methods, and properties defined by this specification MUST be exposed on the runtime’s relevant global scope (e,g., globalThis.crypto, globalThis.ReadableStream, etc).

Likewise, 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 defined global properties using the readonly attribute. To avoid introducing breaking changes, runtimes conforming to this specification MAY choose to ignore the readonly attribute for properties being added to the global scope.

5. Extensions

Runtime-specific extensions to any Web Platform API MAY be implemented by conforming runtimes. Such extensions must be defined so that their use neither contradicts nor causes the non-conformance of normative functionality of any Web Platform API.

Application use of such extensions must be carefully considered, as doing so reduces interoperability and portability of code across runtimes.

6. Open Questions

Remove this section before publishing.

Should window also be included here as an alias for globalThis?

Should globalThis be required to extend from EventTarget?

Many of the globals defined as Web Platform APIs are marked as readonly on the global scope. This, however, causes a number of backwards compatibility issues in many runtimes whenever a new global is added (this has been a challenge in Node.js and Cloudflare Workers, for instance). We likely need to allow for standard globals to be implemented without the readonly attribute enforced.

Conformance

Document conventions

Conformance requirements are expressed with a combination of descriptive assertions and RFC 2119 terminology. The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in the normative parts of this document are to be interpreted as described in RFC 2119. However, for readability, these words do not appear in all uppercase letters in this specification.

All of the text of this specification is normative except sections explicitly marked as non-normative, examples, and notes. [RFC2119]

Examples in this specification are introduced with the words “for example” or are set apart from the normative text with class="example", like this:

This is an example of an informative example.

Informative notes begin with the word “Note” and are set apart from the normative text with class="note", like this:

Note, this is an informative note.

Conformant Algorithms

Requirements phrased in the imperative as part of algorithms (such as "strip any leading space characters" or "return false and abort these steps") are to be interpreted with the meaning of the key word ("must", "should", "may", etc) used in introducing the algorithm.

Conformance requirements phrased as algorithms or specific steps can be implemented in any manner, so long as the end result is equivalent. In particular, the algorithms defined in this specification are intended to be easy to understand and are not intended to be performant. Implementers are encouraged to optimize.

Index

Terms defined by this specification

Terms defined by reference

References

Normative References

[CONSOLE]
Dominic Farolino; Robert Kowalski; Terin Stock. Console Standard. Living Standard. URL: https://console.spec.whatwg.org/
[DOM]
Anne van Kesteren. DOM Standard. Living Standard. URL: https://dom.spec.whatwg.org/
[ENCODING]
Anne van Kesteren. Encoding Standard. Living Standard. URL: https://encoding.spec.whatwg.org/
[HTML]
Anne van Kesteren; et al. HTML Standard. Living Standard. URL: https://html.spec.whatwg.org/multipage/
[RFC2119]
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL: https://datatracker.ietf.org/doc/html/rfc2119
[STREAMS]
Adam Rice; et al. Streams Standard. Living Standard. URL: https://streams.spec.whatwg.org/
[URL]
Anne van Kesteren. URL Standard. Living Standard. URL: https://url.spec.whatwg.org/
[WebCryptoAPI]
Mark Watson. Web Cryptography API. 26 January 2017. REC. URL: https://www.w3.org/TR/WebCryptoAPI/
[WEBIDL]
Edgar Chen; Timothy Gu. Web IDL Standard. Living Standard. URL: https://webidl.spec.whatwg.org/

Issues Index

Should window also be included here as an alias for globalThis?
Should globalThis be required to extend from EventTarget?
Many of the globals defined as Web Platform APIs are marked as readonly on the global scope. This, however, causes a number of backwards compatibility issues in many runtimes whenever a new global is added (this has been a challenge in Node.js and Cloudflare Workers, for instance). We likely need to allow for standard globals to be implemented without the readonly attribute enforced.