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-interoperable Runtime is any EcmaScript-based application runtime environment that implements the subset of Web Platform APIs outlined in this specification.
While this term is intentionally broad to also encompass Web Browsers, the primary focus here is on outlining expectations for non-browser runtimes.
3. Common API Index
All Web-interoperable Runtimes conforming to this specification SHALL implement each of the following Web Platform APIs in accordance to their normative 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.
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).
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 specification MAY choose to ignore the readonly attribute for properties being added to the global scope.
5. Requirements for navigator.userAgent
The globalThis.navigator.userAgent property is provided such that application code can reliably identify the runtime within which it is running.
The value of the property is a string conforming to the the User-Agent construction in RFC 7231:
While runtimes that implement globalThis.navigator.userAgent MUST provide a value that is conformant with the structure defined by RFC 7231, the value SHOULD be treated 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. For instance, navigator.userAgent = 'MyRuntime'. The value SHOULD NOT include any comment components.
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.
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
This is an example of an informative example.
Informative notes begin with the word “Note”
and are set apart from the normative text
Note, this is an informative note.
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.