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.
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
Update to new schema #86
Changes from all commits
3b8fdb5
f860087
e38302a
c1d84ef
5d12bfb
c42ad5d
685978e
cc1d810
b29712f
01db98b
1317abb
ef8d62e
4ccd3af
2145c9e
707a417
1f1f826
34b8028
769a044
20146c7
725f5d8
a14effe
85b674c
c602697
c63dfbe
2472d5b
396d3d2
9577f98
eab3453
b64a8df
0c07e40
7f805e7
de51413
c7aa52a
95f18e1
8d83f02
6d679d3
5b643e5
8c236d5
e81bbe5
5bb0571
f511ac4
c354fa3
e86320b
11760e1
f5b860c
15ef262
adfa4b7
18468c6
d4b807f
548687b
67bc692
b20b442
4f4f48e
1e5ec93
e5806f1
7185d9e
1406ddb
ca77435
47a68c3
004ec10
d722129
3ca0d70
a42e18a
95dff43
df2f5ff
8b8d17b
e2020e3
922ea40
a328eff
0cbd0ed
7ebb45d
73122bd
5acc0ca
5517f54
35604b2
23703ee
55b86fd
3e9bfee
89ad765
639b5b2
b542bac
28be392
387ebe1
27a3287
549d4a9
d0ee326
590a0b9
1f058df
89c8105
43f36a6
48cc7de
e807b98
606a0ce
d26842a
285361c
6a56b48
f477c52
719b5c6
371e475
755c7af
c699e59
b35f00b
f4bfb12
4f779be
8a1829c
bec5612
f795ddd
f62c6ed
946d5db
e7ffee0
52df0ea
104a4ee
c028916
afc7407
7b76c50
fbf3403
583cb30
38038a4
7e12b55
8b99064
e92a54e
0c4deee
86be332
6e87662
38c3be4
85fb617
336763b
ede86e2
a083b51
fe99dcb
4426de7
43c21d1
d7cadeb
b106970
89038f4
7d9f035
c80be00
8f07c46
8224a05
00e0aba
976fadf
f57f52f
1931ccb
7efde21
2585308
eb3a004
e6f1a51
3d24bf7
5940a08
e73b16d
701eed1
1d4b5f6
4c64ed3
145b54b
0b369fd
e11db65
df9fe42
78c85c6
cbcde3b
a6bdd84
40b0030
eb5fee6
6c06ead
e51a09f
c7ec7bc
692b6cb
7db156b
9a589b8
cb89270
516f19b
47638fc
6537825
5795df0
2d1227e
9fe482e
c3ddcda
5a1130f
a88f1eb
9a86677
684d16b
8aee506
a6c8392
26e9a6a
45fb3f0
06d12e1
2f9358b
847c7c1
e161af7
d281444
21172f0
d54dc71
9a86c18
3ebc4ac
b694175
057f297
2f22bce
f1945f9
6178040
6fd3c8e
77abd28
45205e5
a3450d4
172d4e6
7ea9ba6
a9527ad
0b7d189
9b6d60a
5544c81
886f501
a39a68c
281392d
6901fe9
8bce56b
784e35a
6c7c08f
54e4bf5
b4ac9c3
98935ee
352bb22
ff0d1f5
f12f69a
d199dec
bb068af
175c2e2
0fb253a
862297a
ac009d2
3a2b970
3aa348f
0b7aa74
7907172
5aa7539
9542eb6
956fb63
af307d1
7f92648
803deb6
fac052e
b2b82f5
f8c5388
efd1dcd
2319685
4c8ebe9
a73e7a3
084ba1c
664e56d
f23c5eb
1730321
68f3d3c
9862548
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,365 @@ | ||
# The browser-compat-data JSON format | ||
|
||
Maintained by the [MDN team at Mozilla](https://wiki.mozilla.org/MDN). | ||
|
||
## Browser compatibility information | ||
MDN needs the compatibility information for each feature of the Web platform. In | ||
order to make it easier to maintain and easy to reuse by third-party tool, we | ||
decided to store this data into a set of JSON files, stored in a git repository. | ||
|
||
In order to ensure the coherence of the data, we define a JSON schema that | ||
describes the content of the JSON files storing the info. Before accepting a | ||
PR, we validate the changes against this schema with _travis-ci_. | ||
|
||
This document describes the format in lay-man terms so that a human can create | ||
a JSON browser-compat-data file without having to decrypt the schema from | ||
scratch. | ||
|
||
__Note:__ The schema tries to capture as many constraints and rules about the | ||
browser-compat-data JSON format. Nevertheless there are constraints that cannot | ||
be described inside a schema, and won't be checked by automated tests. We tried | ||
to mark such cases in the following text with a __Not enforced by the | ||
schema__ notice. | ||
|
||
## The JSON format | ||
|
||
### Division in files | ||
The browser-compat-data schema has been designed so the division in files doesn't | ||
convey any meaning. That means that browser compatibility information about features | ||
can be stored in one single large files or being divided in smaller files. | ||
|
||
The division in separate files, themselves in different directories is guided | ||
by making it easy to maintain by humans. | ||
|
||
### Schema versioning | ||
There one single information that is tied to each file, and is mandatory. It is | ||
the version of schema used inside the file. | ||
|
||
{ | ||
"version": "1.0.0", | ||
"data": { | ||
… | ||
} | ||
} | ||
|
||
We are using semantic versioning, so the version is a `string` containing three | ||
integers separate by a dot (`.`). No whitespace or additional characters are | ||
allowed. To see detail of the meaing fo the 3 integers, see the | ||
[Semantic Versioning 2.0.0 specification](http://semver.org/). | ||
|
||
The "data" contains a list of _features_, with their identifier, their description, | ||
their support status, and thir status. | ||
|
||
__Note:__ You cannot mix two schemas in the same file. `"version"` is unique in | ||
a given file. | ||
|
||
### Feature identifier | ||
A _feature_ is a functionality of the platform. It is an entity that can be used | ||
independently. A _sub-feature_ is a specific value or behavior of a feature. The | ||
division is a bit arbitrary, but matches the way developers perceive features of | ||
a platform | ||
|
||
* For CSS, an entity like a property, a pseudo-class, a pseudo-element, an | ||
at-rule, or a descriptor is a feature. A value, a new syntax change, or a | ||
specific behavior, like if a property applies to a set of elements or another | ||
are sub-features. | ||
|
||
* For HTML, an element or an attribute are features, while specific values of an | ||
attribute are sub-features. | ||
|
||
* For Web APIs or JavaScript, an interface, a method, a property, a constructor | ||
are features, while arguments or special values of an enumerated type are | ||
sub-features. | ||
|
||
Each feature is identified by a unique hierarchy of strings. E.g the | ||
`text-align` property is identified by `css.properties.text-align`. | ||
|
||
The strings of an identifier are not intended to be displayed and are therefore | ||
not translatable. | ||
|
||
In JSON, this gives: | ||
|
||
"data": { | ||
"css": { | ||
"properties": { | ||
"text-align": {…}, | ||
… | ||
}, | ||
… | ||
}, | ||
… | ||
} | ||
|
||
That way, each feature is uniquely identifier, independently of the file it is | ||
defined in. | ||
|
||
The hierarchy of identifiers is not defined inside the schema. It is a | ||
convention of the project using the schema. | ||
|
||
In the MDN browser-compat case, it is: | ||
|
||
_Note: this list will evolve as we migrate our data_ | ||
|
||
"data": { | ||
"css": { | ||
"properties": {…} | ||
"pseudo-classes": {…} | ||
"pseudo-elements": {…} | ||
"at-rules": {…} | ||
}, | ||
"html": { | ||
"elements": { | ||
…, | ||
"<element-name>": { | ||
…, | ||
"<attribute-name>": {…}, | ||
… | ||
} | ||
} | ||
"global_attributes": {…} | ||
} | ||
} | ||
|
||
### Feature description | ||
|
||
A feature is represented by an identifier containing the `"__compat"` property. | ||
In this compat property, you'll find the list of sub-features associated to the | ||
feature. | ||
|
||
A feature has at least one sub-feature, representing the basic support. It is | ||
always named `"basic_support"`. | ||
|
||
The basic support feature represents the minimal set of functionality included | ||
when a feature is qualified of 'supported'. What this represents depends of the | ||
evolution of the feature over time, both in term of specification and of browser | ||
support. Another way of seeing it is to consider `"basic_support"` as representing all | ||
the functionality of the feature that doesn't have its own sub-feature(s). | ||
|
||
### Sub-feature | ||
|
||
A sub-feature is the basic entity having browser compatibility information. As | ||
explained in the previous paragraph, any feature has at least one sub-feature | ||
called `'basic_support'`, but it may many more. | ||
|
||
A sub-feature may have three properties. | ||
|
||
* __Sub-feature description__ contained in the `"desc"` property. It is a | ||
`string` that contains a human-readable description of the sub-feature. As it is | ||
intended to be used as a kind of caption or title for the feature, keep it short. | ||
the `<code>` and `<a>`, as well as the macros `{{cssxref}}`, `{{HTMLElement}}`, | ||
`{{htmlattrxref}}`, and `{{domxref}}` can be used. See the localization section | ||
below for an explanation about how this string will be localized. | ||
* __Compat information__ contained in the `"support"` property. It contains an | ||
object listing the compat information for each browser. (See the description | ||
below.) | ||
* __Status information__ contained in the `"status"` object. It contains the | ||
information about the stability of the sub-feature: Is it a functionality that | ||
is standard? Is it stable? Has it been deprecated and shouldn't be used anymore | ||
(See the description below.) | ||
|
||
### The `"support"` object | ||
Each sub-feature has support information. For each browser identifier, it | ||
contains a compat object with the information about versions, prefixes or | ||
alternate names, as well as notes. | ||
|
||
The currently accepted browser identifiers are: | ||
* `"webview_android"`, Webview, the former stock browser on Android, | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Actually, it's the browser bundled with Android for use in native and hybrid apps. Since Android 4.4 (KitKat) it has been based on the Chromium open source project, the same project on which Chrome is built. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Hey @jpmedley. I suggested that we should validate version numbers, here: #86 (review), and Florian just filed an issue for it: #168. I'm sure it would be great to get your input into what the format should be for Chrome. |
||
* `"chrome"`, Google Chrome (on desktops), | ||
* `"chrome_android"`, Google Chrome (on Android), | ||
* `"edge"`, MS Edge (on Windows), | ||
* `"edge_mobile"`, MS Edge, the mobile version, | ||
* `"firefox`", Mozilla Firefox (on desktops), | ||
* `"firefox_android"`, Firefox for Android, sometimes nicknamed Fennec, | ||
* `"ie_mobile"`, Microsoft Internet Explorer, the mobile version, | ||
* `"ie"`, Microsoft Internet Explorer (discontinued) | ||
* `"opera"`, the Opera browser (desktop), based on Blink since Opera 15, | ||
* `"opera_android"`, the Opera browser (Android version) | ||
* `"safari"`, Apple Safari, on Mac OS, | ||
* `"safari_ios"`, Apple Safari, on iOS, | ||
* `"servo"`, the experimental Mozilla engine. | ||
|
||
No value is mandatory. | ||
|
||
Each of these properties contains a `support-statement` object with the | ||
practical compatibility information for this sub-feature and this browser. | ||
|
||
### The `support-statement` object | ||
This object is the key element of each browser compat information. It is a | ||
support-statement object. It is an array of `support` objects, but if there | ||
are only one of them, the array can be ommitted | ||
|
||
|
||
Example of an `support` compat object (with 2 entries): | ||
|
||
{ | ||
"support": [ | ||
{ | ||
"version_added": "6.0" | ||
}, | ||
{ | ||
"prefix": "-moz-", | ||
"version_added": "3.5", | ||
"version_removed": "9.0" | ||
} | ||
|
||
] | ||
} | ||
|
||
Example of a `support` compat object (with 1 entry, array ommitted): | ||
|
||
{ | ||
"support": { "version_added": "6.0" } | ||
} | ||
|
||
### Compat information in a `"support"` field. | ||
Compatibility information is stored in a `"support"` field. It may consist of the | ||
following properties: | ||
|
||
#### `"version_added"` | ||
Contains a string with the version number the sub-feature has | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. This is an extra suggestion, but I think we should define and enforce, for each runtime, what the version syntax must be. I'm thinking here of something like: mdn/kumascript#131 - are Edge versions like "12.34567", or "34567" or "12"? If we don't define this, then we'll end up with a mix, and it will become really hard to work with the data. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I think it is an interesting idea: I quite like it, though it may may be complex to define and maintain. I think we should do, or at least study, this in a follow-up. Could you open an issue so that this is tracked? There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. You'd also need to have uniform data to begin with. When I started contributing to MDN, all the reference to Chrome version numbers were 3 digits ("39.0"). Chrome doesn't do it that way and as far as I can tell never did. I've been trying to correct to 2 digits ("39") wherever I can, but right now it's a mix. |
||
been added (and is therefore supported), the Boolean values to indicate the | ||
sub-feature is supported (`true`, with the additional meaning that the we don't | ||
know in which version) or not (`false`). A value of `null` indicates that we | ||
don't have support information for it. | ||
|
||
* Support from version 3.5 (included) | ||
|
||
{ | ||
"version_added": "3.5" | ||
} | ||
|
||
* Support, but version unknown | ||
|
||
{ | ||
"version_added": true | ||
} | ||
|
||
* No support | ||
|
||
{ | ||
"version_added": false | ||
} | ||
|
||
* Support unknown (default value) | ||
|
||
{ | ||
"version_added" : null | ||
} | ||
|
||
#### `"version_removed"` | ||
Contains a string with the version number the sub-feature | ||
stopped to be supported. It may be a Boolean value of (`true` or `false`), or the | ||
`null` value. If `"version_added"` is set to a Boolean or a `string`, `"version_removed"` | ||
default value is `false`; if it is `null`, the default value of `"version_removed"` | ||
is `null` too. | ||
|
||
* Removed in version 10 (start in 3.5): | ||
|
||
{ | ||
"version_added": "3.5", | ||
"version_removed": "10" | ||
} | ||
|
||
* Not removed (default if `"version_added"` is not `null`): | ||
|
||
{ | ||
"version_added": "3.5", | ||
"version_removed": false | ||
} | ||
|
||
|
||
#### `"prefix"` | ||
Contains the prefix to add to the sub-feature name (default to the empty | ||
string). Note that leading and trailing `-` must be included. | ||
|
||
* Prefixed sub-feature: | ||
|
||
{ | ||
"prefix": "-moz-", | ||
"version_added": "3.5" | ||
} | ||
|
||
#### `"alternative_name"` | ||
For the cases when prefixing is not enough, contains the whole name of the sub-feature. ( A | ||
sub-feature may have a completely different name in some older version. | ||
|
||
* Prefixed version had a different capitalization | ||
|
||
{ | ||
"alternative_name": "mozRequestFullScreen", | ||
"version_added": "true", | ||
"version_removed": "9.0" | ||
} | ||
|
||
#### `"flags"` | ||
Is a specific object indicating what kind of flags must be set for this feature | ||
to work. It consists of three values: | ||
* `"type"`, an enum that indicates what kind of flag it is: `"preference"` represents | ||
a flag that the user can set himself on its browser, like in `about:config` on Firefox; | ||
or `"compile_flag"` that is a flag that has to be set before the compilation of the browser. | ||
* `"name"`, a `string` representing the flag or preference to modify. | ||
* `"value_to_set"` representing the actual 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 valuie). | ||
|
||
#### `partial_implementation` | ||
Is a `boolean` value indicating if the implementation of the subfeature follows the current | ||
spec close enough not to create major interoperability problem. It defaults to `false` (no | ||
interoperability problem expected). If set `true`, it is recommended to add a note indicating | ||
how it diverges from the standard (implement an old version of the standard, …) | ||
|
||
#### `"notes"` | ||
Is an `array` of zero or more translatable `string` containing | ||
additional pertinent information. If there are only 1 entry in the array, | ||
the array can be ommitted | ||
|
||
* Indication of an experimental support behind a flag | ||
|
||
{ | ||
"version_added" : false, | ||
"notes": "Experimental implementation available when <code>layout.css.text-align</code> is set to <code>true</code>." | ||
} | ||
|
||
* Linking to a bug and indicating a restriction | ||
|
||
{ | ||
"version_added": "3.5", | ||
"notes": ["See <a href='https://bugzil.la/123456'>bug 123456</a>.", | ||
"Do not work on {{cssxref('::first-letter)}} pseudo-elements."] | ||
} | ||
|
||
Each `string` that contains a human-readable description of the sub-feature. The | ||
`<code>` and `<a>`, as well as the macros `{{cssxref}}`, `{{HTMLElement}}`, | ||
`{{htmlattrxref}}`, and `{{domxref}}` can be used. See the localization section | ||
below for an explanation about how this string will be localized. | ||
|
||
### Status information | ||
The status indicates the stability of the feature. It is an object named | ||
`"status"` and has four 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 is expected in the future. | ||
* `"standard_track"`, a `boolean` value indicating if the feature is in a | ||
standard track. | ||
* `"obsolete`", a `"boolean"` value that indicates if the functionality is only | ||
kept for compatibility purpose and shouldn't be used anymore. It may be removed | ||
from the Web platform in the future. | ||
|
||
## Localization | ||
There is no localization happening inside the .json files themselves; l10n is | ||
handled separately in order to take advantage of existing toolchains. | ||
|
||
In the case of MDN, .po files with the translated string will be created. We | ||
will work on them once the prototype validating the structure of the json will | ||
be done. | ||
|
||
The plan is: | ||
|
||
1. Define all source strings as English in the spec, as well as which data elements are plain text, HTML, etc. Avoiding HTML is a good idea, but being clear about it is necessary if you can't avoid it. | ||
2. Create a script to extract strings into the standard gettext format | ||
3. Manage translation using gettext conventions, like Kuma, perhaps even using Pontoon to translate the strings. With gettext, you get fuzzy translations, notifications of changed strings, etc. etc. for free. | ||
4. Create a second script to export gettext-formatted files to a JSON data structure. | ||
5. Implement a gettext-like translation in KumaScript (I'm pretty sure this is already done, and multiple times). | ||
|
||
1. is done in this document. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
It seems like "version" could easily be the name of an identifier. For example manifest.json has a
version
key that will appear as an identifier in the data (not at the top-level, but we could imagine this happening).Should we call it
__compat_version
? Alternatively we could shift the data down a level, and have the top-level look like:That seems less hacky, but introduces another level of nesting, and we already have a lot of that.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This is a good point. I don't like "__*" even if we are using it once, so I like the "data" idea. It also allows to extend this in the feature (if needed). I will apply this.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Done.