Skip to content

Latest commit

 

History

History
180 lines (132 loc) · 7.7 KB

data-guidelines.md

File metadata and controls

180 lines (132 loc) · 7.7 KB
Raw

Data guidelines

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.

Constructors

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": {}
        }
      }
    }
  }
}

DOM events (eventname_event)

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:

Secure context required (secure_context_required)

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.

Web Workers (worker_support)

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.

Permissions API permissions (permissionname_permission)

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.

Non-functional defined names imply partial_implementation

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).

Release lines and backported features

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.

Safari for iOS versioning

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.

Removal of irrelevant features

Features can be removed from BCD if it is considered irrelevant. A feature can be considered irrelevant if any of these conditions are met:

  • a feature was never implemented in any browser and the specification has been abandoned.
  • a feature was implemented and has since been removed from all browsers dating back two or more years ago.
  • a feature is unsupported in all releases in the past five years.

This guideline was proposed in #6018.