This file contains recommendations to help you record data in a consistent and understandable way. It covers the project's preferences for the way features should be represented, rather than hard requirements encoded in the schema definitions or linter logic.
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": {}
}
}
}
}
}This rule applies to the event features themselves, not the features for the event handlers. For example, focus_event and onfocus are two separate features.
This practice emerged through several discussions:
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.
If a browser recognizes an API name, but the API doesn’t have any discernable behavior, use "partial_implementation": true instead of "version_added": false, as if the feature has non-standard support, rather than no support.
For example, suppose there is some specification for a Web API NewFeature.method(). Running typeof NewFeature.method in some browser returns function (not undefined), but the method, when called, returns null instead of an expected value. For that feature, set "partial_implementation": true and write a note describing the feature’s misbehavior.
See #3904 for additional background (and nuance).
Use version numbers to reflect which release line (major or minor but not patch-level releases) first supported a feature, rather than absolute version numbers.
Typically, BCD does not record absolute version numbers (such as Chrome 76.0.3809.46; instead BCD records significant releases (such as Chrome 76). Use the earliest applicable release line for recording support for a given feature, even when that support change was backported to a previous release of the browser.
For example, if the current release of browser X is version 10.2, but a new feature was backported to previous versions including a new 9.7.1 release, then the supported version is 9.7 (not 10.2 or 9.7.1).
This decision was made in #3953, under the expectation that most users are likely to run the latest minor version of their browser, but not necessarily the latest version overall.
For Safari for iOS, use the iOS version number, not the Safari version number or WebKit version number.
This versioning scheme came at Apple's request, in #2006.