This file contains guidelines that are specific to the web API features (api/).
Don't include data for constants in BCD. The rationale for not including them is that they're not known to be a source of any compatibility issues.
For example, although the UI Events specification defines a DOM_KEY_LOCATION_STANDARD constant, we don't include data for it in BCD.
This guideline was proposed in #7936, based in part on previous discussion in #7585.
Dictionaries and enumerations (enums) in Web IDL are used in specifications to define a set of properties that may be reused across various interfaces. For web developers, they aren't observable directly; they act as helpers for web browser engineers to avoid internally repeating API definitions. Add dictionary members and enum values to the appropriate methods and properties when needed.
For example, ScrollToOptions is a dictionary defined in the CSSOM View specification. The properties of this dictionary are available to an argument of various methods, including Element.scroll(), Element.scrollTo(), Window.scrollBy() and more. These properties are added to each of the members as parameter object features.
Interface mixins in Web IDL are used in specifications to define Web APIs. For web developers, they aren't observable directly; they act as helpers for web browser engineers to avoid internally repeating API definitions. Add mixin members directly to the corresponding interface they're exposed on.
For example, HTMLHyperlinkElementUtils is a mixin defined in the HTML specification.
Members of this mixin are available to HTMLAnchorElement and HTMLAreaElement, so that's where BCD exposes them. As such, members of HTMLHyperlinkElementUtils should be added directly to the api/HTMLAnchorElement.json and api/HTMLAreaElement.json files as if they were regular members of these interfaces.
This guideline was proposed in #8929, based in part on previous discussion in #472.
Namespaces in Web IDL are similar to interfaces. A namespace should only be documented in BCD if it contains properties or functions that would normally be documented. For example, the console namespace contains many functions, so it should be documented in BCD. The GPUBufferUsage namespace only contains constants, which should not be documented in BCD; thus, the GPUBufferUsage namespace should not be documented.
Don't add unexposed callbacks as features in api. If needed, represent callbacks as subfeatures of relevant methods or properties.
Callback functions and interfaces (denoted by callback and callback interface in Web IDL) are used in specifications to define Web APIs. Where defined without the [Exposed] attribute, they aren't observable directly to web developers.
For example, addEventListener() is specified as taking an EventListener callback. Since EventListener is specified as an unexposed callback interface EventListener, it would be represented as a subfeature of api.EventTarget.addEventListener.
This guideline is based on a discussion in #3068 and was proposed in #14302.
An API is considered global when it is available for both Window and WorkerGlobalScope. Such APIs are recorded in the api/_globals/ folder.
For example, the fetch() method is global, recorded like this in api/_globals/fetch.json:
{
"api": {
"fetch": {
"__compat": {},
"worker_support": {
"__compat": {
"description": "Available in workers",
"support": {}
}
}
}
}
}All APIs defined on the WindowOrWorkerGlobalScope mixin are considered global.
Note that APIs available on only some types of workers are not considered global. For example:
- The
cookieStoreproperty, available inWindowandServiceWorkerGlobalScope. - The
requestAnimationFrame()function, available inWindowandDedicatedWorkerGlobalScope.
This guideline is based on a discussion in #11518.
Name a constructor for an API feature the same as the parent feature (unless the constructor doesn't share the name of its parent feature) and have a description with text in the form of <code>Name()</code> constructor.
For example, the ImageData constructor, ImageData(), is represented as api.ImageData.ImageData. It has the description <code>ImageData()</code> constructor, like this:
{
"api": {
"ImageData": {
"__compat": {},
"ImageData": {
"__compat": {
"description": "<code>ImageData()</code> constructor",
"support": {}
}
}
}
}
}Add DOM events as features of their target interfaces, using the name eventname_event with the description text set to <code>eventname</code> event. If an event can be sent to multiple interfaces, add the event as a feature of each interface that can receive it.
For example, the feature for a focus event targeting the Element interface would be named focus_event with the description text <code>focus</code> event, like this:
{
"api": {
"Element": {
"__compat": {},
"focus_event": {
"__compat": {
"description": "<code>focus</code> event",
"support": {}
}
}
}
}
}The event handler onfocus is represented by the focus_event entry. Don't create features for on event handler properties. If an implementation doesn't support the event handler property, use partial_implementation with the note "The <code>onfocus</code> event handler property is not supported.". If only the on event handler property is supported and not the event itself, use "version_added": false.
If a specification has two sections (the event handler property and the event name), add both specification links.
This practice emerged through several discussions:
Add Permissions API permissions as subfeatures of api.Permissions using the name permissionname_permission with the description text set to <code>permissionname</code> permission.
For example, the Geolocation permission is named geolocation_permission with the description text <code>geolocation</code> permission, like this:
{
"api": {
"Permissions": {
"__compat": { ... },
"geolocation_permission": {
"__compat": {
"description": "<code>geolocation</code> permission",
"support": { ... }
}
}
}
}
}This guideline was proposed in #6156.
When a method returns a promise in some (but not all) browser releases, use a subfeature named returns_promise with description text Returns a <code>Promise</code> to record when the method returns a promise.
For example, HTMLMediaElement's play() method returns a promise, recorded like this:
{
"api": {
"HTMLMediaElement": {
"__compat": {},
"play": {
"__compat": {},
"returns_promise": {
"__compat": {
"description": "Returns a <code>Promise</code>",
"support": {}
}
}
}
}
}
}This guideline is based on a discussion in #11630.
Use a subfeature named secure_context_required with the description text Secure context required to record data about whether a feature requires HTTPS. For example, the ImageData API requires a secure context, recorded like this:
{
"api": {
"ImageData": {
"__compat": {},
"secure_context_required": {
"__compat": {
"description": "Secure context required",
"support": {}
}
}
}
}
}This convention is discussed in more detail in #190.
Use a subfeature named worker_support with description text Available in workers to record data about an API's support for Web Workers.
For example, the ImageData API has worker support, recorded like this:
{
"api": {
"ImageData": {
"__compat": {},
"worker_support": {
"__compat": {
"description": "Available in workers",
"support": {}
}
}
}
}
}Formerly named available_in_workers, this policy was set in #2362.
Interfaces may have an attribute with a stringifier keyword in its IDL definition. When the stringifier keyword is present on an attribute, a toString() method is generated, which returns the value of that attribute. Record both the attribute and the toString() method.
For example, the MediaList API has a mediaText attribute with the stringifier keyword (stringifier attribute [LegacyNullToEmptyString] CSSOMString mediaText;). Both are recorded like so:
{
"api": {
"MediaList": {
"__compat": { ... },
"mediaText": {
"__compat": { ... }
},
"toString": {
"__compat": { ... }
}
}
}
}Web IDL interfaces (and JavaScript built-in objects) form prototype chains, with one type inheriting from another. For example, AudioContext inherits from BaseAudioContext, and Element inherits from Node.
Some of these interfaces are abstract and never have instances, while most are concrete and can be instantiated. For example, BaseAudioContext and Node are abstract, while AudioContext and Element are concrete.
When attributes and methods are moved between interfaces in specifications and implementations, BCD should make the corresponding change. This guideline covers which versions to use, and whether to use partial_implementation and notes in the resulting compat data.
For interface members, use the version when the member is first supported on any concrete interface, regardless of where in the prototype chain the member is, even if that is earlier than the existence of the current interface. If there are any concrete interfaces where the member wasn't supported before the move, then use partial_implementation and notes.
For interfaces, use the version when the interface itself is first supported. If there are members supported earlier than the interface itself was introduced, then use partial_implementation and notes for that range of versions.
For example, most members of AudioContext have moved to a new BaseAudioContext parent interface. The data was recorded like this:
- The members were removed from
AudioContextand added toBaseAudioContext. - Since some of the members were supported on
AudioContextearlier than onBaseAudioContext,partial_implementationand notes are used forBaseAudioContextfor that range of versions. - Full
BaseAudioContextsupport (withoutpartial_implementation) is recorded as separate entries from the versions when theBaseAudioContextinterface itself is supported.
See #9516 for a part of this data being fixed, and #9479 for another example.
Use the version when the member is first supported on the current interface, regardless of where in the prototype chain the member is. No partial_implementation or notes about the move are needed.
For example, some attributes have moved from Node to Attr and Element. The data was recorded like this:
- The members were removed from
Nodeand added toAttrandElement. - Support is recorded from when the members were first available via
Node, without any notes.
See #9561 for a part of this data being fixed.
This guideline is based on a discussion in #3463.
Always append the suffix _static to static members of an interface and have a description with text in the form of <code>json()</code> static method.
For example, the Response interface has both, a prototype and static method called json(). The static method is represented as api.Response.json_static. It has the description <code>json()</code> static method. The prototype method is represented as api.Response.json without suffix and without description.
{
"api": {
"Response": {
"__compat": {},
"json": {
"__compat": {}
},
"json_static": {
"__compat": {
"description": "<code>json()</code> static method",
"support": {}
}
}
}
}
}This guideline is based on a discussion in #16613.