It seems like there is largely consensus to hide mixins to the world of web developers for reasons discussed in #472 for BCD and in mdn/content#1940 for MDN docs.

@rachelandrew notes an authoring drawback when hiding mixins and documenting things directly on the interfaces, though:

So ... if I am adding ARIAMixin, which was AriaAttributes to Element, for BCD does that mean adding all of these to the 9000+ line long Element BCD file?

I think this is a good point. So, how can we remove mixins and while keeping some authoring conveniences (i.e. avoiding large BCD files)? Luckily (and ironically) BCD supports mixing in data to a particular tree! We just haven't made a lot of use of that.

Right now we have api/Element.json and it is exposing its content as "api.Element.*".
We also added files like api/AriaMixin.json and exposed content as "api.AriaMixin.*". This is not hiding the mixin but exposes it directly :(

However, to hide mixins, we could have a file AriaMixin-for-Element.json and expose its content as "api.Element.*" (we mix in data to Element, ha!)
For that to happen, the AriaMixin-for-Element.json file needs to start like this:

{
  "api": {
    "Element": {
      "ariaRole": {
        "__compat": {
          "mdn_url": "https://developer.mozilla.org/docs/Web/API/Element/animate",
          "support": {
            "chrome": {

Note the "Element" after "api". This will extend what is already defined in api/Element.json.

To keep things clean, we can also move AriaMixin-for-Element.json to api/mixins/AriaMixin-for-Element.json, so that we know files in this folder extend other interfaces in the main api/ folder.

If in the year 2525, AriaMixin is exposed to CyberElement, we have a new compat story, and so we should have api/mixins/AriaMixin-for-CyberElement.json and it will add data to the exposed API CyberElement.

Thoughts?