# Browser compatibility tables for API overviews

**URL:** <https://discourse.mozilla.org/t/browser-compatibility-tables-for-api-overviews/33832>\
**Category:** MDN\
**Created:** [November 29, 2018, 12:25am UTC](https://discourse.mozilla.org/t/browser-compatibility-tables-for-api-overviews/33832 "2018-11-29T00:25:26Z")\
**Posts on this page:** 11\
**Page:** 1

<div class="post-metadata">

**Author:** ![sheppy](https://sea1.discourse-cdn.com/flex001/user_avatar/discourse.mozilla.org/sheppy/32/20903_2.png) [@sheppy](https://discourse.mozilla.org/u/sheppy)\
**Post date:** [November 29, 2018, 12:25am UTC](https://discourse.mozilla.org/t/browser-compatibility-tables-for-api-overviews/33832/1 "2018-11-29T00:25:26Z")

</div>

Ideally, our API overview pages ought to have a specification table box on them, and in many cases we have them. The problem is that because we don’t have a concept of “this API overall” in BCD, you have to compromise, often by picking an important or the most important thing in the API and using that.

It would be nice to have a way to state the compatibility in general this way for overview pages, either as a simple “it’s there in this browser and this one but not that one” sort of way or as a more intricate set of supported vs. unsupported subfeatures. I don’t really know which is best (and really am not all that strongly aligned one way or another), but having a responsible and standard way to do compat tables on overviews would be helpful.

---

<div class="post-metadata">

**Author:** ![chrisdavidmills](https://sea1.discourse-cdn.com/flex001/user_avatar/discourse.mozilla.org/chrisdavidmills/32/21688_2.png) [@chrisdavidmills](https://discourse.mozilla.org/u/chrisdavidmills)\
**Post date:** [November 29, 2018, 9:22am UTC](https://discourse.mozilla.org/t/browser-compatibility-tables-for-api-overviews/33832/2 "2018-11-29T09:22:39Z")

</div>

This is an interesting point. I’ve started recommending that people just write a general summary of where the API is at, for example

- [https://developer.mozilla.org/en-US/docs/Web/CSS/CSS\_Logical\_Properties#Browser\_compatibility](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Logical_Properties#Browser_compatibility)
- [https://developer.mozilla.org/en-US/docs/Web/Web\_Components#Browser\_compatibility](https://developer.mozilla.org/en-US/docs/Web/Web_Components#Browser_compatibility)

But it would be nice to have some kind of more formal way to do this.

---

<div class="post-metadata">

**Author:** ![connorshea](https://sea1.discourse-cdn.com/flex001/user_avatar/discourse.mozilla.org/connorshea/32/23616_2.png) [@connorshea](https://discourse.mozilla.org/u/connorshea)\
**Post date:** [November 29, 2018, 4:48pm UTC](https://discourse.mozilla.org/t/browser-compatibility-tables-for-api-overviews/33832/3 "2018-11-29T16:48:27Z")

</div>

That doesn’t seem like it’d scale very well, and wouldn’t it probably lead to outdated info?

---

<div class="post-metadata">

**Author:** ![sheppy](https://sea1.discourse-cdn.com/flex001/user_avatar/discourse.mozilla.org/sheppy/32/20903_2.png) [@sheppy](https://discourse.mozilla.org/u/sheppy)\
**Post date:** [November 29, 2018, 5:24pm UTC](https://discourse.mozilla.org/t/browser-compatibility-tables-for-api-overviews/33832/4 "2018-11-29T17:24:21Z")

</div>

> [@connorshea](#):
>
> That doesn’t seem like it’d scale very well, and wouldn’t it probably lead to outdated info?

I agree; that seems like it’s just begging for content to go obsolete quickly and without notice. A way to handle this using BCD would be helpful. Maybe adding an `APISupport.json` file containing an array of objects, each of which is labeled with one of our spec names (as in `GroupData.json`), and with each record containing an array of browsers and their support overview data.

I could see this file being either maintained manually **or** generated periodically using a script that uses the list of things in `GroupData.json` for that spec to look at each interface and for each item in that interface’s BCD JSON file, compute the percentage of the entries that are supported for the browser. Use that to generate the support status for that API.

A similar algorithm could be used for the compat bar, of course, when we get to that.

Either way, once we have the data, we can update the `Compat` macro so it can generate an appropriate “overall support” table for an API, given the API’s name.

---

<div class="post-metadata">

**Author:** ![wbamberg](https://sea1.discourse-cdn.com/flex001/user_avatar/discourse.mozilla.org/wbamberg/32/30597_2.png) [@wbamberg](https://discourse.mozilla.org/u/wbamberg)\
**Post date:** [November 29, 2018, 6:44pm UTC](https://discourse.mozilla.org/t/browser-compatibility-tables-for-api-overviews/33832/5 "2018-11-29T18:44:41Z")

</div>

Yes, I agree with Connor. A big original motivation for moving compat info into data is to avoid having compat info in more than one place. Another is to enable aggregate views of the data.

There are a couple of options at the moment.

- If your “overview” maps cleanly onto the BCD hierarchy, you can point the macro at the relevant node in the hierarchy. For example: [https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto#Browser\_compatibility](https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto#Browser_compatibility)

- If it doesn’t, but it consists of a few different pieces that do, you can include more than one table. For example, for the Web Components page, I would handle this by including tables for:

Otherwise, if you want to have an “overview” for a thing that isn’t represented at all in the BCD structure (such as a CSS module) then yes, as @sheppy says, you need something that describes which individual things comprise that overall thing. This is the approach taken by the CompatGroup macro ([https://github.com/mdn/kumascript/pull/650](https://github.com/mdn/kumascript/pull/650)) which @ddbeck and @eduardoboucas wrote in Paris, that never got merged :(.

It does seem like in general: if you want custom BCD overview tables, you need a maintainable single place you can say “this big thing maps onto all those little things” - and this sounds like it’s not BCD-specific - you might need it for things like sidebars or even to build indexes of links to the little things in the page, or lists of the specifications that define the little things.

In our present situation I’d be wary of handling this by adding a bunch of extra metadata and KS macros to process it though, without having some idea of what this might look like in a future version of Kuma.

---

<div class="post-metadata">

**Author:** ![sheppy](https://sea1.discourse-cdn.com/flex001/user_avatar/discourse.mozilla.org/sheppy/32/20903_2.png) [@sheppy](https://discourse.mozilla.org/u/sheppy)\
**Post date:** [November 29, 2018, 9:32pm UTC](https://discourse.mozilla.org/t/browser-compatibility-tables-for-api-overviews/33832/6 "2018-11-29T21:32:44Z")

</div>

> [@wbamberg](#):
>
> In our present situation I’d be wary of handling this by adding a bunch of extra metadata and KS macros to process it though, without having some idea of what this might look like in a future version of Kuma.

Yes, certainly that would need to be kept in mind.

---

<div class="post-metadata">

**Author:** ![exe-boss](https://sea1.discourse-cdn.com/flex001/user_avatar/discourse.mozilla.org/exe-boss/32/43293_2.png) [@exe-boss](https://discourse.mozilla.org/u/exe-boss)\
**Post date:** [November 30, 2018, 6:02am UTC](https://discourse.mozilla.org/t/browser-compatibility-tables-for-api-overviews/33832/7 "2018-11-30T06:02:47Z")

</div>

I’d like to point towards:

> <https://github.com/mdn/browser-compat-data/issues/1243>
>
> This macro would work by supplying it references to the APIs that belong to that… overview page, eg.:
> \`\`\`
> {{CompatOverview("api.Body","api.FetchEvent","api.Headers","api.Request","api.Response")}}
> \`\`\`
> Which would render as:
> \<table\>
> \<thead\>
> \<tr\>
> \<th rowspan="2"\>\</th\>
> \<th colspan="6"\>Desktop\</th\>
> \<th colspan="7"\>Mobile\</th\>
> \</tr\>
> \<tr\>
> 			
> \<th\>Chrome\</th\>
> \<th\>Edge\</th\>
> \<th\>Firefox\</th\>
> \<th\>IE\</th\>
> \<th\>Opera\</th\>
> \<th\>Safari\</th\>
> 			
> \<th\>Android Webview\</th\>
> \<th\>Chrome for Android\</th\>
> \<th\>Edge Mobile\</th\>
> \<th\>Firefox for Android\</th\>
> \<th\>Opera for Android\</th\>
> \<th\>iOS Safari\</th\>
> \<th\>Samsung Internet\</th\>
> \</tr\>
> \</thead\>
> \<tbody\>
> \<tr\>
> \<th\>\<a href="https://developer.mozilla.org/docs/Web/API/Body"\>\<code\>Body\</code\>\</a\>\</th\>
> 			
> \<td\>42\</td\>
> \<td\>Yes\</td\>
> \<td\>39\</td\>
> \<td\>No\</td\>
> \<td\>29\</td\>
> \<td\>No\</td\>
> 			
> \<td\>42\</td\>
> \<td\>42\</td\>
> \<td\>?\</td\>
> \<td\>44\</td\>
> \<td\>Yes\</td\>
> \<td\>No\</td\>
> \<td\>?\</td\>
> \</tr\>
> \<tr\>
> \<th\>\<a href="https://developer.mozilla.org/docs/Web/API/FetchEvent"\>\<code\>FetchEvent\</code\>\</a\>\</th\>
> 			
> \<td\>40\</td\>
> \<td\>Yes\</td\>
> \<td\>44\</td\>
> \<td\>No\</td\>
> \<td\>27\</td\>
> \<td\>No\</td\>
> 			
> \<td\>40\</td\>
> \<td\>40\</td\>
> \<td\>?\</td\>
> \<td\>44\</td\>
> \<td\>27\</td\>
> \<td\>No\</td\>
> \<td\>?\</td\>
> \</tr\>
> \<tr\>
> \<th\>\<a href="https://developer.mozilla.org/docs/Web/API/Headers"\>\<code\>Headers\</code\>\</a\>\</th\>
> 			
> \<td\>42\</td\>
> \<td\>Yes\</td\>
> \<td\>39\</td\>
> \<td\>No\</td\>
> \<td\>29\</td\>
> \<td\>10.1\</td\>
> 			
> \<td\>42\</td\>
> \<td\>42\</td\>
> \<td\>?\</td\>
> \<td\>44\</td\>
> \<td\>29\</td\>
> \<td\>No\</td\>
> \<td\>?\</td\>
> \</tr\>
> \<tr\>
> \<th\>\<a href="https://developer.mozilla.org/docs/Web/API/Request"\>\<code\>Request\</code\>\</a\>\</th\>
> 			
> \<td\>42\</td\>
> \<td\>Yes\</td\>
> \<td\>39\</td\>
> \<td\>No\</td\>
> \<td\>28\</td\>
> \<td\>No\</td\>
> 			
> \<td\>42\</td\>
> \<td\>42\</td\>
> \<td\>Yes\</td\>
> \<td\>Yes\</td\>
> \<td\>28\</td\>
> \<td\>No\</td\>
> \<td\>?\</td\>
> \</tr\>
> \<tr\>
> \<th\>\<a href="https://developer.mozilla.org/docs/Web/API/Response"\>\<code\>Response\</code\>\</a\>\</th\>
> 			
> \<td\>42\</td\>
> \<td\>Yes\</td\>
> \<td\>39\</td\>
> \<td\>No\</td\>
> \<td\>29\</td\>
> \<td\>10.1\</td\>
> 			
> \<td\>42\</td\>
> \<td\>42\</td\>
> \<td\>Yes\</td\>
> \<td\>Yes\</td\>
> \<td\>29\</td\>
> \<td\>10.1\</td\>
> \<td\>?\</td\>
> \</tr\>
> \</tbody\>
> \</table\>
> 
> \## See also:
> \- #1163

> <https://github.com/mdn/kumascript/pull/650>
>
> This PR adds a new macro \`CompatGroup\`. This macro takes as an argument the name… of a CSS module (e.g. "CSS Animations"). It uses https://github.com/mdn/data/blob/master/css/properties.json to fetch the properties in that group, and renders a table containing JSON data for those properties. This enables us to embed a single table in pages like https://developer.mozilla.org/en-US/docs/Web/CSS/CSS\_Grid\_Layout that gives an overview of browser support for that area.
> 
> To do this is also splits the existing \`CompatBeta\` macro. At the moment this macro takes a path through the compat data object as an argument, resolves that into an array of JSON compat objects, then renders those objects.
> 
> To enable \`CompatGroup\` to share the rendering code (which is most of the work) this PR also splits out the rendering work from \`CompatBeta\` into a new macro \`CompatRender\`.
> 
> So now we have:
> 
> 1. \`CompatRender\`: given an array of JSON objects, one for each table row, render a table
> 2. \`CompatBeta\`: given a path through the JSON data, get the JSON objects, flattening them if needed, then call \`CompatRender\`
> 3. \`CompatGroup\`: given the name of a CSS module, get the JSON objects for the properties it contains, then call \`CompatRender\`
> 
> The macro is called \`CompatGroup\` even though it's much more specific than this, currently only dealing with CSS modules. Maybe in future it could do a similar trick with JS and Web APIs, but we'd need solid metadata first.
> 
> I've done some manual testing to try to confirm that we haven't regressed the existing \`Compat\` macro with this change.

---

<div class="post-metadata">

**Author:** ![chrisdavidmills](https://sea1.discourse-cdn.com/flex001/user_avatar/discourse.mozilla.org/chrisdavidmills/32/21688_2.png) [@chrisdavidmills](https://discourse.mozilla.org/u/chrisdavidmills)\
**Post date:** [November 30, 2018, 6:28am UTC](https://discourse.mozilla.org/t/browser-compatibility-tables-for-api-overviews/33832/8 "2018-11-30T06:28:35Z")

</div>

I agree that what I’m doing isn’t great. But for web components doing what Will suggested would be _really_ messy; I suppose maybe it would work to just include a couple of tables to indicate the support level of the two most central pieces (e.g. custom elements and shadow dom)?

For the CSS logical properties page, I’m not sure what you’d do; there are about 80 properties, and the level of support is not very obviously split.

---

<div class="post-metadata">

**Author:** ![exe-boss](https://sea1.discourse-cdn.com/flex001/user_avatar/discourse.mozilla.org/exe-boss/32/43293_2.png) [@exe-boss](https://discourse.mozilla.org/u/exe-boss)\
**Post date:** [November 30, 2018, 7:38am UTC](https://discourse.mozilla.org/t/browser-compatibility-tables-for-api-overviews/33832/9 "2018-11-30T07:38:59Z")

</div>

Well, you could use a similar algorithm to what the CSSRef macro does to determine which CSS properties belong to which group, but that will require extracting the compat macro rendering code from the `{{Compat}}` macro, which depends&nbsp;on:

> <https://github.com/mdn/kumascript/pull/1010>
>
> \## Split&nbsp;into:
> \- Fix&nbsp;typos and&nbsp;whitespace: https://github.com/md…n/kumascript/pull/1084 (merged)
> \- Improve \`mdn\_url\` handling: https://github.com/mdn/kumascript/pull/1085
> \- Fix stray closing \`\</tr\>\` tag: https://github.com/mdn/kumascript/pull/1086
> \- Rewrite \`writeFlagsNote(…)\` function: https://github.com/mdn/kumascript/pull/1087
> 
> \---
> 
> This PR imports the following \[browser-compat-toolkit\](https://github.com/mdn/browser-compat-toolkit) changes that I made:
> 
> \- \[x\] https://github.com/mdn/browser-compat-toolkit/pull/7 (moved&nbsp;to https://github.com/mdn/kumascript/pull/1086)
> \- \[x\] https://github.com/mdn/browser-compat-toolkit/pull/5 (moved&nbsp;to https://github.com/mdn/kumascript/pull/1085)
> \- \[x\] https://github.com/mdn/browser-compat-toolkit/pull/15 (moved&nbsp;to https://github.com/mdn/kumascript/pull/1087)
> 
> \## Features blocked by&nbsp;this:
> \- \[x\] Unhard&#x2011;code preferences using \`pref\_url\` (https://github.com/mdn/browser-compat-data/pull/3407; moved&nbsp;to https://github.com/mdn/kumascript/pull/1087)
> \- \[\] Add support for \`\<=\`&nbsp;syntax (https://github.com/mdn/browser-compat-data/issues/3021)
> 
> \## See also:
> \- https://github.com/mdn/browser-compat-data/issues/2354
> 
> \---
> 
> review?(@a2sheppy, @chrisdavidmills, @davidflanagan, @Elchi3, @escattone, @jwhitlock, @MatonAnthony, @wbamberg)

---

<div class="post-metadata">

**Author:** ![sheppy](https://sea1.discourse-cdn.com/flex001/user_avatar/discourse.mozilla.org/sheppy/32/20903_2.png) [@sheppy](https://discourse.mozilla.org/u/sheppy)\
**Post date:** [December 5, 2018, 7:17pm UTC](https://discourse.mozilla.org/t/browser-compatibility-tables-for-api-overviews/33832/10 "2018-12-05T19:17:54Z")

</div>

> [@exe-boss](#):
>
> Well, you could use a similar algorithm to what the CSSRef macro does to determine which CSS properties belong to which group, but that will require extracting the compat macro rendering code from the `{{Compat}}` macro, which depends on:

So, I would say that I think we should consider how many things we’ve run into where these monolithic macros are causing us headaches, and that it’s time that we do something about it. I think we should find things that can be, essentially, turned into library functions. Things like collecting information about a group of pages, generating a section of sidebar content from a list of links and titles, etc.

With a library along those lines we could probably dramatically improve our macro complexity issues while also making it easier to update existing macros, create new macros, and test them all properly.

---

<div class="post-metadata">

**Author:** ![exe-boss](https://sea1.discourse-cdn.com/flex001/user_avatar/discourse.mozilla.org/exe-boss/32/43293_2.png) [@exe-boss](https://discourse.mozilla.org/u/exe-boss)\
**Post date:** [December 5, 2018, 7:48pm UTC](https://discourse.mozilla.org/t/browser-compatibility-tables-for-api-overviews/33832/11 "2018-12-05T19:48:54Z")

</div>

> [@sheppy](#):
>
> I think we should find things that can be, essentially, turned into library functions.

So resurrect my work on `browser‑compat‑toolkit`?

> <https://github.com/mdn/browser-compat-data/issues/2354>
>
> \## Depends on:
> \- \[\] mdn/browser-compat-toolkit#10
> \- \[\] mdn/browser-compat-to…olkit#12
> \- \[\] mdn/browser-compat-toolkit#13
> \- \[\] mdn/browser-compat-toolkit#14
> \- \[\] mdn/kumascript#716
> 
> \## See also
> \- https://github.com/mdn/kumascript/pull/1010
> \- https://github.com/mdn/mdn/issues/41

> <https://github.com/mdn/mdn/issues/41>
>
> I’ve been working on my local fork of \[mdn/browser‑compat‑toolkit\](https://githu…b.com/mdn/browser-compat-toolkit) and would like to merge them into the upstream repository to get closer to resolving https://github.com/mdn/browser-compat-data/issues/2354.
> 
> I have read and agree to abide by the \[Code&nbsp;of&nbsp;conduct\](https://github.com/mdn/mdn/blob/master/CODE\_OF\_CONDUCT.md) and Mozilla’s \[Commit Access Requirements\](https://www.mozilla.org/en-US/about/governance/policies/commit/requirements/).
> 
> I also have 2FA enabled on my GitHub account.