This folder contains guidelines to help you record data in a consistent and understandable way. It covers the project's requirements for the way features should be represented, including requirements that are not coded into the linter or schema. This file contains general guidelines that apply to all features added to BCD. For guidelines that apply to specific categories of data, check out their respective files within this folder.
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. The only exception to this is Bun (see below).
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. For example, if a feature was not added in Chrome 76.0.3700.43, but added in Chrome 76.0.3809.46, then the supported version is 76. Likewise, if a feature was not available in Safari 10.1.1, but added in Safari 10.1.3, then the supported version is 10.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.
Some browsers have backport releases, where a feature is added or removed in two or more versions at once that do not follow a linear semantic versioning bump (ex. Safari 6.0 was released, then Safari 7.0, and then Safari 6.1). If not otherwise covered by this guideline, use the earliest applicable version (as described in the Choosing a version number guideline). In some cases, however, you must set the version number to the following major version. For example, if a new feature was added in Safari 7.0 and in Safari 6.1, then the supported version is 7.0 (not 6 or 6.1).
| If the browser and its version is... | then set the version to... |
|---|---|
| Safari 4.1 | Safari 5.0 |
| Safari 6.1 | Safari 7.0 |
| Safari 6.2 | Safari 8.0 |
| Safari 7.1 | Safari 8.0 |
Note: Since NodeJS follows a different release cycle and features are commonly backported to older major versions (ex. a feature was implemented in 17.0.0, and then included in a new 16.17.0 release), this guideline does not apply to NodeJS.
This decision was made in #4679 and #9423.
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.
Since Bun upgrades the WebKit version also in patch releases, which may include new features, BCD tracks patch releases for Bun.
"preview" valuesUse "preview" as values for version_added and version_removed when the future stable version number is unknown or uncertain. Use "preview" when:
You can't be sure a feature will progress (informally, “ride the train”) to a numbered stable release.
For example, use "preview" when a feature is explicitly limited to Chrome Canary builds, is supported in the current version of Canary, and is not supported in the same numbered beta and stable versions.
The next version number is unknown to BCD.
For example, a feature is supported in Safari Technology Preview only and is expected in the next release of Safari, but Apple has not announced the version number for the next release of Safari.
Do not use "preview" for planned but not yet implemented support changes. In other words, if you can't test or use a feature in the current development version of the browser, then use false, not "preview".
This guideline was adopted to protect the quality of stable data in the face of schedule uncertainty. To learn more about the adoption of "preview" values, see #12344 and #10334.
"partial_implementation" general usage guidelines[!NOTE] This guideline was added in August 2025 and feedback is welcome. If you have questions or concerns about how to apply it, file an issue.
You must set "partial_implementation": true when all of the following conditions are met:
This list only covers cases where "partial_implementation": true is required. "partial_implementation": true may apply in unusual situations not covered by this guideline, such as significant changes in a single-implementation feature's behavior before standardization.
Here are some example situations:
"partial_implementation": false: All implementing browsers ignore part of a feature's specified behavior in the same way. This behavior is consistent and is a de facto complete implementation.
"partial_implementation": false: All implementing browsers provide a form control user interface, but the specification gives the implementer discretion over its look and feel. A developer complains that one browser's user interface lacks some desired quality that other browsers implement; they want it to be marked as partially implemented. Use a note or non-standard behavioral subfeature instead.
"partial_implementation": false: An implementing browser fails a web platform test against a corner case. No web developers have reported the bug and it's unlikely that there are real-world applications that would attempt to use the corner case. Use a note instead.
"partial_implementation": true: CSS.supports() returns true for a property name and value, but the value has no behavior. See also: Non-functional defined names imply "partial_implementation".
"partial_implementation": true: One browser exposes a constructor, Example(), but it always throws an error. Other browsers implement the constructor's intended behavior. This confuses feature detection because typeof Example === "function" returns true, even though the constructor does not work.
This guideline was proposed and adopted in #26780.
"partial_implementation" requires a noteIf you set "partial_implementation": true, then write a note describing how the implementation is incomplete.
This guideline was proposed in #7332.
"partial_implementation"If a browser recognizes an API name, but the API doesn’t have any discernible 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).
"partial_implementation"If a browser or engine is available on more than one operating system and a feature is only implemented on a subset of those operating systems, then the support statement should set "partial_implementation": true. For example, if a browser supports both Windows and Linux, but only implements a feature on Windows, then a support statement for that feature should set "partial_implementation": true (and a note).
However, this guideline does not apply to features where the browser‘s expected behavior is conditional on the behavior of the operating system itself. For example, a browser can fully implement a CSS media query even if an underlying operating system can never satisfy the media query’s condition because it does not support the requisite hardware.
This guideline was proposed in #6906.
Features can be removed from BCD if it is considered irrelevant. A feature can be considered irrelevant if any of these conditions are met:
This guideline was proposed in #6018 and updated in #10619 and #21521.
Flag data is helpful for developers who may wish to test features before they are included in a stable release. However, once a feature has landed in a stable browser release, the flag data quickly becomes irrelevant and may be removed from BCD. To be considered irrelevant, the flag support statement must meet any of these conditions:
These conditions represent minimum requirements for the removal of valid flag data; other considerations may result in flag data continuing to be relevant, even after the guideline conditions are met.
This guideline was proposed in #6670 and revised in #16637.
Browser features that have not been implemented (or planned to be implemented) in any browser, should not be added to BCD. A feature should not be added if all of the following conditions are met:
Some features may already be added to BCD that do not have any browser support. These features will be removed over time.
This guideline was proposed in #10619.
The following guidelines will help you determine when to set certain statuses for features.
webextensions features do not have status blocksWeb extensions are not governed by any specifications and are up to the browser vendors to design and implement. As such, the status blocks would be identical for all web extensions features. Do not add status blocks to the webextensions folder.
This guideline was adopted since the beginning of the project.
experimentalGenerally, when a feature is supported by one and only one browser engine, set experimental to true. When a feature is supported by two or more engines, then set experimental to false. Some exceptions apply, however, for long-standing features and features behind flags and prefixes.
If a feature is supported behind flags only, no matter how many engines, then set experimental to true.
If a feature is supported behind incompatible prefixes only (such as -webkit- in one engine and -moz- in another), no matter how many engines support the feature overall, then set experimental to true. If two or more engines support a feature behind a common prefix (such as -webkit- only), then set experimental to false.
A single-engine feature's experimental status may expire and switch to false when the following conditions are met:
| Example | Experimental |
|---|---|
| An API supported in Chrome and Firefox, without flags or prefixes. | No |
A CSS property supported in Chrome and Firefox, with the -webkit- prefix. | No |
| An HTTP header supported in Chrome and Firefox, behind flags. | Yes |
| A CSS property value supported in Safari, released last week. | Yes |
| An API supported in Firefox, released three years ago. | No |
This guideline was proposed in #6905 and adopted in #9933.
deprecatedSet deprecated to true to show that a feature has been authoritatively discouraged from use.
The deprecated status captures the many ways standards organizations (and, for non-standard features, vendors) mark features as disfavored. This includes features that are on the path to removal or features that are discouraged from use despite their retention for backwards compatibility.
Evidence for setting deprecated to true includes:
Do not set deprecated to true for features that are merely old or unpopular, no matter how many considered harmful blog posts they may have garnered. For example, although web developers may prefer fetch over XMLHttpRequest, XMLHttpRequest is not deprecated.
This guideline was proposed in #15703. See mdn/content#5549 and #10490 for further discussion on the use of “deprecated.”
[!NOTE] This guideline was added in August 2025 and feedback is welcome. If you have questions or concerns about how to apply it, file an issue.
A behavioral subfeature records support for some facet, nuance, or evolution of a parent feature, where the behavior doesn't have a natural identifier (like CSS properties, API methods, or HTTP headers do). Due to the lack of a natural identifier, a behavioral subfeature must have a description.
If a more specific guideline applies, follow that guideline instead of this one. See:
Behavioral subfeatures are rare. Do not create a subfeature when the behavioral subfeature's support data would be the same, across all browsers, as the parent feature. For serious bugs affecting a single engine, consider using partial_implementation instead.
You may create a behavioral subfeature for the following types of browser behaviors:
A contextual support condition that is not readily feature detectable. This type of behavioral subfeature typically describes the applicability of a feature to specific context.
Behavioral evolution that is not readily feature detectable. This type of behavioral subfeature typically describes consequences of specification changes that appeared after the feature first shipped in one or more browsers or user interface changes that appeared after implementers learned more about the specification.
Here are some example situations:
A CSS property may depend on the layout context. The CSS property gap has different support histories in flex and grid layouts, so it has the behavioral subfeatures of css.properties.gap.flex_context and css.properties.gap.grid_context. See css.properties.gap.
An API exposure may depend on an execution context. The setTimeout() method has different support histories for worker support, so it has the behavioral subfeatures of api.setTimeout.worker_support. See the guideline for worker_support for further guidance.
An API's specified behavior may change after a feature ships in one or more browsers. The play() method of the HTMLMediaElement interface originally consumed a callback instead of returning a promise, so it has the behavioral subfeature of api.HTMLMediaElement.play.returns_promise. See the guideline for returns_promise for further guidance.
User interface behavior may evolve with better understanding of a specification. The inert HTML attribute marks elements as non-interactive but this did not originally affect find-in-page search, so it has the behavioral subfeature of html.global_attributes.inert.ignores_find_in_page.
This guideline was proposed and adopted in #26781.
Sometimes it's useful to represent support for specific parameters (also known as arguments) of a function or method, as a subfeature of the function itself. To record data about whether a specific parameter is supported by a function or method, use the following naming conventions:
For named parameters, use a subfeature named paramname_parameter with description text `paramname` parameter. Where paramname is the name of the parameter as it appears on the corresponding function's MDN page (or specification, if no MDN page is available).
For example, to represent support for the firstName parameter of a method hello(firstName, familyName), use a subfeature of hello named firstName_parameter with the description text `firstName` parameter.
For unnamed parameters, use a subfeature named ordinal_parameter with description text ordinal parameter where ordinal is the ordinal number position of the parameter.
For example, to represent support for the second parameter of a method count(), use a subfeature of count named second_parameter and description text Second parameter.
For properties of parameter objects, use a subfeature named paramname_prop_parameter with description text `paramname.prop` parameter, where paramname is the name of the parameter object and prop is the name of the property.
For example, to represent support for the year property of the date parameter to a method schedule(date) (as in schedule({"year": 1970 })), use a subfeature of schedule named date_year_parameter with description text `date.year` parameter.
For existing data which does not follow this guideline, you may modify it to conform with this data, if you are you otherwise updating the data (or data related to it).
This guideline was proposed and adopted in #10509.