Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Update description of WebView #5534

Merged
merged 1 commit into from
Jan 23, 2020
Merged

Update description of WebView #5534

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
166 changes: 103 additions & 63 deletions schemas/compat-data-schema.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@
This document helps you to understand how mdn-browser-compat-data is organized and structured.

## Where to find compat data

### The folder structure

Compatibility data is organized in top-level directories for each broad area covered: for example, `http`,
Expand Down Expand Up @@ -32,6 +33,7 @@ JSON files containing the compatibility data.
- [xslt/](https://github.com/mdn/browser-compat-data/tree/master/xslt) contains data for [XSLT](https://developer.mozilla.org/docs/Web/XSLT) elements, attributes, and global attributes.

### File and folder breakdown

The JSON files contain [feature identifiers](#feature-identifiers),
which are relevant for accessing the data. Except for the top-level directories,
the file and sub-folder hierarchies aren't of any meaning for the exports.
Expand All @@ -46,6 +48,7 @@ Each feature is identified by a unique hierarchy of strings.
E.g the `text-align` property is identified by `css.properties.text-align`.

In the JSON file it looks like this:

```json
{
"css": {
Expand Down Expand Up @@ -83,55 +86,59 @@ To add a sub-feature, a new identifier is added below the main feature at the le
See [Data guidelines](/docs/data-guidelines.md) for more information about feature naming conventions and other best practices.

### The `__compat` object

The `__compat` object consists of the following:

* A mandatory `support` property for __compat information__.
An object listing the compatibility information for each browser ([see below](#the-support-object)).
- A mandatory `support` property for **compat information**.
An object listing the compatibility information for each browser ([see below](#the-support-object)).

* An optional `description` property to __describe the feature__.
A string containing a human-readable description of the feature.
It is intended to be used as a caption or title and should be kept short.
The `<code>`, `<kbd>`, `<em>`, and `<strong>` HTML elements may be used.
- An optional `description` property to **describe the feature**.
A string containing a human-readable description of the feature.
It is intended to be used as a caption or title and should be kept short.
The `<code>`, `<kbd>`, `<em>`, and `<strong>` HTML elements may be used.

* An optional `matches` property to __help match the feature to source code__ ([see below](#the-matches-object))
An object that contains a keyword list or regex that can match values or tokens which correspond to the feature.
- An optional `matches` property to **help match the feature to source code** ([see below](#the-matches-object))
An object that contains a keyword list or regex that can match values or tokens which correspond to the feature.

* An optional `status` property for __status information__.
An object containing information about the stability of the feature:
Is it a functionality that is standard? Is it stable? Has it been deprecated and shouldn't be used anymore? ([see below](#status-information))
- An optional `status` property for **status information**.
An object containing information about the stability of the feature:
Is it a functionality that is standard? Is it stable? Has it been deprecated and shouldn't be used anymore? ([see below](#status-information))

* An optional `mdn_url` property which __points to an MDN reference page documenting the feature__.
It needs to be a valid URL, and should be the language-neutral URL (e.g. use `https://developer.mozilla.org/docs/Web/CSS/text-align` instead of `https://developer.mozilla.org/en-US/docs/Web/CSS/text-align`).
- An optional `mdn_url` property which **points to an MDN reference page documenting the feature**.
It needs to be a valid URL, and should be the language-neutral URL (e.g. use `https://developer.mozilla.org/docs/Web/CSS/text-align` instead of `https://developer.mozilla.org/en-US/docs/Web/CSS/text-align`).

* An optional `spec_url` property as a URL or an array of URLs, each of which is for a specific part of a specification in which this feature is defined. Each URL must contain a fragment identifier (e.g. `https://tc39.es/proposal-promise-allSettled/#sec-promise.allsettled`).
- An optional `spec_url` property as a URL or an array of URLs, each of which is for a specific part of a specification in which this feature is defined. Each URL must contain a fragment identifier (e.g. `https://tc39.es/proposal-promise-allSettled/#sec-promise.allsettled`).

### The `support` object

Each `__compat` object contains support information. For each browser identifier, it contains a [`support_statement`](#the-support_statement-object) object with
information about versions, prefixes, or alternate names, as well as notes.

#### Browser identifiers

The currently accepted browser identifiers should be declared in alphabetical order:
* `chrome`, Google Chrome (on desktops)
* `chrome_android`, Google Chrome (on Android)
* `edge`, MS Edge (on Windows), based on the EdgeHTML version
* `firefox`, Mozilla Firefox (on desktops)
* `firefox_android`, Firefox for Android, sometimes nicknamed Fennec
* `ie`, Microsoft Internet Explorer (discontinued)
* `nodejs` Node.js JavaScript runtime built on Chrome's V8 JavaScript engine
* `opera`, the Opera browser (desktop), based on Blink since Opera 15
* `opera_android`, the Opera browser (Android version)
* `qq_android`, the QQ browser (Android version)
* `safari`, Safari on macOS
* `safari_ios`, Safari on iOS, based on the iOS version
* `samsunginternet_android`, the Samsung Internet browser (Android version)
* `uc_android`, UC Browser (Android version)
* `uc_chinese_android`, UC Browser (Chinese Android version)
* `webview_android`, Webview, the former stock browser on Android

- `chrome`, Google Chrome (on desktops)
- `chrome_android`, Google Chrome (on Android)
- `edge`, MS Edge (on Windows), based on the EdgeHTML version
- `firefox`, Mozilla Firefox (on desktops)
- `firefox_android`, Firefox for Android, sometimes nicknamed Fennec
- `ie`, Microsoft Internet Explorer (discontinued)
- `nodejs` Node.js JavaScript runtime built on Chrome's V8 JavaScript engine
- `opera`, the Opera browser (desktop), based on Blink since Opera 15
- `opera_android`, the Opera browser (Android version)
- `qq_android`, the QQ browser (Android version)
- `safari`, Safari on macOS
- `safari_ios`, Safari on iOS, based on the iOS version
- `samsunginternet_android`, the Samsung Internet browser (Android version)
- `uc_android`, UC Browser (Android version)
- `uc_chinese_android`, UC Browser (Chinese Android version)
- `webview_android`, Webview, the built-in browser for Android

Desktop browser identifiers are mandatory, with the `version_added` property set to `null` if support is unknown.

#### The `support_statement` object

The `support_statement` object describes the support provided by a single browser type for the given subfeature.
It is an array of `simple_support_statement` objects, but if there
is only one of them, the array must be omitted.
Expand All @@ -141,6 +148,7 @@ In other words, sort such arrays with entries applying to the most recent browse
If in doubt, reverse-chronological order with respect to the `"version_removed"` and then `"version_added"` values usually works well. For more information on sorting support statements, see [#1596](https://github.com/mdn/browser-compat-data/issues/1596).

Example of a `support` compat object (with an `array_support_statement` containing 2 entries):

```json
"support": {
"firefox": [
Expand All @@ -157,68 +165,83 @@ Example of a `support` compat object (with an `array_support_statement` containi
```

Example of a `support` compat object (with 1 entry, array omitted):

```json
"support": {
"ie": { "version_added": "6.0" }
}
```

### Compat data in support statements

The `simple_support_statement` object is the core object containing the compatibility information for a browser.
It consist of the following properties:

#### `version_added`

This is the only mandatory property and it contains a string with the version
number indicating when a sub-feature has been added (and is therefore supported).
The Boolean values indicate that a sub-feature is supported (`true`, with the
additional meaning that it is unknown in which version support was added) or
not supported (`false`). A value of `null` indicates that support information is
entirely unknown. Examples:

* Support from version 3.5 (inclusive):
- Support from version 3.5 (inclusive):

```json
{
"version_added": "3.5"
"version_added": "3.5"
}
```
* Supported, but version unknown:

- Supported, but version unknown:

```json
{
"version_added": true
}
```
* No support:

- No support:

```json
{
"version_added": false
}
```
* Support unknown (default value, if browser omitted):

- Support unknown (default value, if browser omitted):

```json
{
"version_added": null
}
```

#### `version_removed`

Contains a string with the version number the sub-feature was
removed in. It may also be a Boolean value of (`true` or `false`), or the
`null` value.

Default values:
* If `version_added` is set to `true`, `false`, or a string, `version_removed` defaults to `false`.
* if `version_added` is set to `null`, the default value of `version_removed` is also `null`.

- If `version_added` is set to `true`, `false`, or a string, `version_removed` defaults to `false`.
- if `version_added` is set to `null`, the default value of `version_removed` is also `null`.

Examples:

* Removed in version 10 (added in 3.5):
- Removed in version 10 (added in 3.5):

```json
{
"version_added": "3.5",
"version_removed": "10"
}
```
* Not removed (default if `version_added` is not `null`):

- Not removed (default if `version_added` is not `null`):

```json
{
"version_added": "3.5",
Expand All @@ -233,25 +256,28 @@ Currently, the only allowed ranged version is `"≤37"` for `webview_android`. T

```json
{
"version_added": "≤37",
"version_added": "≤37"
}
```

#### `prefix`

A prefix to add to the sub-feature name (defaults to empty string).
If applicable, leading and trailing `-` must be included.

Examples:

* A CSS property with a standard name of `prop-name` and a vendor-prefixed name of `-moz-prop-name`:
- A CSS property with a standard name of `prop-name` and a vendor-prefixed name of `-moz-prop-name`:

```json
{
"prefix": "-moz-",
"version_added": "3.5"
}
```

* An API with a standard name of `FeatureName` and a vendor-prefixed name of `webkitFeatureName`:
- An API with a standard name of `FeatureName` and a vendor-prefixed name of `webkitFeatureName`:

```json
{
"prefix": "webkit",
Expand All @@ -260,9 +286,11 @@ Examples:
```

#### `alternative_name`

In some cases features are named entirely differently and not just prefixed. Example:

* Prefixed version had a different capitalization
- Prefixed version had a different capitalization

```json
{
"alternative_name": "mozRequestFullScreen",
Expand All @@ -274,18 +302,21 @@ In some cases features are named entirely differently and not just prefixed. Exa
Note that you can’t have both `prefix` and `alternative_name`.

#### `flags`

An optional array of objects describing flags that must be configured for this browser to support this feature. Usually this
array will have one item, but there are cases where two or more flags can be required to activate a feature.
An object in the `flags` array consists of three properties:
* `type` (mandatory): an enum that indicates the flag type:
* `preference` a flag the user can set (like in `about:config` in Firefox).
* `runtime_flag` a flag to be set before starting the browser.
* `name` (mandatory): a string giving the value which the specified flag must be set to for this feature to work.
* `value_to_set` (optional): representing the actual value to set the flag to.
It is a string, that may be converted to the right type
(that is `true` or `false` for Boolean value, or `4` for an integer value). It doesn't need to be enclosed in `<code>` tags.

- `type` (mandatory): an enum that indicates the flag type:
- `preference` a flag the user can set (like in `about:config` in Firefox).
- `runtime_flag` a flag to be set before starting the browser.
- `name` (mandatory): a string giving the value which the specified flag must be set to for this feature to work.
- `value_to_set` (optional): representing the actual value to set the flag to.
It is a string, that may be converted to the right type
(that is `true` or `false` for Boolean value, or `4` for an integer value). It doesn't need to be enclosed in `<code>` tags.

Example for one flag required:

```json
{
"version_added": true,
Expand All @@ -298,7 +329,9 @@ Example for one flag required:
]
}
```

Example for two flags required:

```json
{
"version_added": true,
Expand All @@ -318,19 +351,22 @@ Example for two flags required:
```

#### `partial_implementation`

A `boolean` value indicating whether or not the implementation of the sub-feature
deviates from the specification in a way that may cause significant compatibility problems.
It defaults to `false` (no interoperability problems expected). If set to `true`, it is
recommended that you add a note explaining how it diverges from the standard (such as
that it implements an old version of the standard, for example).

#### `notes`

A string or `array` of strings containing additional information. If there is only one
entry, the value of `notes` must simply be a string instead of an array.

Example:

* Indicating a restriction:
- Indicating a restriction:

```json
{
"version_added": "3.5",
Expand All @@ -340,28 +376,29 @@ Example:
]
}
```
The `<code>`, `<kbd>`, `<em>`, and `<strong>` HTML elements may be used. In addition, `<a>` tags may be used, such as to link to a browser's bug report, or MDN documentation.

The `<code>`, `<kbd>`, `<em>`, and `<strong>` HTML elements may be used. In addition, `<a>` tags may be used, such as to link to a browser's bug report, or MDN documentation.

### The `matches` object

A `matches` object contains hints to help automatically detect whether source code corresponds to a feature, such as a list of keywords or a regular expression. A `matches` object may have one of the following properties (in order of preference):

* `keywords`: an array of one or more literal strings that correspond to the feature.
- `keywords`: an array of one or more literal strings that correspond to the feature.

Examples:

- In CSS selector features, they can be literal selectors. See [`css.selectors.backdrop`](../css/selectors/backdrop.json)).
- In CSS property subfeatures, they can be data type keywords or function keywords. See [`css.properties.transform.3d`](../css/properties/transform.json)).

* `regex_token`: a string containing a regular expression that matches a single token (i.e., text delimited by characters that are excluded from the text to be matched) corresponding to the feature.
- `regex_token`: a string containing a regular expression that matches a single token (i.e., text delimited by characters that are excluded from the text to be matched) corresponding to the feature.

Tests are required for all regular expressions. See [`test-regexes.js`](../tests/test-regexes.js).

Examples:

- In CSS property subfeatures, they can be regular expressions that match component value types. See [`css.properties.color.alpha_hexadecimal_notation`](../css/properties/color.json) and corresponding tests.

* `regex_value`: a string containing a regular expression that matches a complete value corresponding to the feature.
- `regex_value`: a string containing a regular expression that matches a complete value corresponding to the feature.

Tests are required for all regular expressions. See [`test-regexes.js`](../tests/test-regexes.js).

Expand All @@ -370,16 +407,18 @@ A `matches` object contains hints to help automatically detect whether source co
- In CSS property subfeatures, these can be regular expressions that match whole declaration values. See [`css.properties.transform-origin.three_value_syntax`](../css/properties/transform.json) and corresponding tests.

### Status information

The status property contains information about stability of the feature. It is
an optional object named `status` and has three mandatory properties:
* `experimental`: a `boolean` value that indicates this functionality is
intended to be an addition to the Web platform. Some features are added to
conduct tests. Set to `false`, it means the functionality is mature, and no
significant incompatible changes are expected in the future.
* `standard_track`: a `boolean` value indicating if the feature is part of an
active specification or specification process.
* `deprecated`: a `boolean` value that indicates if the feature is no longer recommended.
It might be removed in the future or might only be kept for compatibility purposes. Avoid using this functionality.

- `experimental`: a `boolean` value that indicates this functionality is
intended to be an addition to the Web platform. Some features are added to
conduct tests. Set to `false`, it means the functionality is mature, and no
significant incompatible changes are expected in the future.
- `standard_track`: a `boolean` value indicating if the feature is part of an
active specification or specification process.
- `deprecated`: a `boolean` value that indicates if the feature is no longer recommended.
It might be removed in the future or might only be kept for compatibility purposes. Avoid using this functionality.

```json
"__compat": {
Expand All @@ -392,6 +431,7 @@ It might be removed in the future or might only be kept for compatibility purpos
```

### Localization

We are planning to localize some of this data (e.g. notes, descriptions).
At this point we haven't decided how or when we are going to do that.
See [issue 114](https://github.com/mdn/browser-compat-data/issues/114) for more information.