Add BCD for the WebNN API

[ibelem]

This PR adds BCD for the WebNN API.

Currently the WebNN feature is behind the #web-machine-learning-neural-network flag.

[anssiko]

@dontcallmedom PTAL. This is to address your request in webmachinelearning/webnn#223 (comment)

[anssiko]

@Elchi3 might be able to help review this, or knows who'd be the right peer or owner to look at this.

Our intent is to use BCD as the data source also for the implementation status page maintained by the W3C WebML WG: https://webmachinelearning.github.io/webnn-status/

@ibelem is available to answer any questions reviewers may have and iterate on this PR as needed. He is also responsible for maintaining the above-mentioned status page.

[Elchi3]

Thank you @anssiko! I will take a look!

[Elchi3]

Thanks for your PR, @ibelem, it looks great!

I checked if this PR contains all of the features that the Open Web Docs BCD collector would have found as well and it seems that your list is complete.

Three things to look into for you:

1. I just saw that the following features seem to have been dropped in the latest spec and therefore aren't added (and there is a typo for sqrt, so that needs to be corrected):

• api.ML.createContextSync
• api.MLCommandEncoder
• api.MLCommandEncoder.dispatch
• api.MLCommandEncoder.finish
• api.MLCommandEncoder.initializeGraph
• api.MLContext.computeSync
• api.MLContext.createCommandEncoder
• api.MLGraphBuilder.buildSync
• api.MLGraphBuilder.sqrt

2. The spec used is https://www.w3.org/TR/webnn/. We usually prefer the latest Editors Draft which would be at https://webmachinelearning.github.io/webnn/. I think it would be good to change to the ED URL, but let know if there are reasons why the TR URL was chosen here.

3. The note "Currently supported on Windows and ChromeOS." should be "Currently supported on ChromeOS and Windows only." (Operating system names sorted alphabetically, plus the word "only".). Also it would be good to put this note on all 93 features (or a subset if it doesn't apply everywhere).

---

Some useful lists to check if this PR is correct otherwise:

All 93 features added in this PR

• api.ML
• api.ML.createContext
• api.MLActivation
• api.MLContext
• api.MLContext.compute
• api.MLGraph
• api.MLGraphBuilder
• api.MLGraphBuilder.MLGraphBuilder
• api.MLGraphBuilder.abs
• api.MLGraphBuilder.add
• api.MLGraphBuilder.argMax
• api.MLGraphBuilder.argMin
• api.MLGraphBuilder.averagePool2d
• api.MLGraphBuilder.batchNormalization
• api.MLGraphBuilder.build
• api.MLGraphBuilder.cast
• api.MLGraphBuilder.ceil
• api.MLGraphBuilder.clamp
• api.MLGraphBuilder.concat
• api.MLGraphBuilder.constant
• api.MLGraphBuilder.conv2d
• api.MLGraphBuilder.convTranspose2d
• api.MLGraphBuilder.cos
• api.MLGraphBuilder.div
• api.MLGraphBuilder.elu
• api.MLGraphBuilder.equal
• api.MLGraphBuilder.erf
• api.MLGraphBuilder.exp
• api.MLGraphBuilder.expand
• api.MLGraphBuilder.floor
• api.MLGraphBuilder.gather
• api.MLGraphBuilder.gemm
• api.MLGraphBuilder.greater
• api.MLGraphBuilder.greaterOrEqual
• api.MLGraphBuilder.gru
• api.MLGraphBuilder.gruCell
• api.MLGraphBuilder.hardSigmoid
• api.MLGraphBuilder.hardSwish
• api.MLGraphBuilder.identity
• api.MLGraphBuilder.input
• api.MLGraphBuilder.instanceNormalization
• api.MLGraphBuilder.l2Pool2d
• api.MLGraphBuilder.layerNormalization
• api.MLGraphBuilder.leakyRelu
• api.MLGraphBuilder.lesser
• api.MLGraphBuilder.lesserOrEqual
• api.MLGraphBuilder.linear
• api.MLGraphBuilder.log
• api.MLGraphBuilder.lstm
• api.MLGraphBuilder.lstmCell
• api.MLGraphBuilder.matmul
• api.MLGraphBuilder.max
• api.MLGraphBuilder.maxPool2d
• api.MLGraphBuilder.min
• api.MLGraphBuilder.mul
• api.MLGraphBuilder.neg
• api.MLGraphBuilder.not
• api.MLGraphBuilder.pad
• api.MLGraphBuilder.pow
• api.MLGraphBuilder.prelu
• api.MLGraphBuilder.qrt
• api.MLGraphBuilder.reciprocal
• api.MLGraphBuilder.reduceL1
• api.MLGraphBuilder.reduceL2
• api.MLGraphBuilder.reduceLogSum
• api.MLGraphBuilder.reduceLogSumExp
• api.MLGraphBuilder.reduceMax
• api.MLGraphBuilder.reduceMean
• api.MLGraphBuilder.reduceMin
• api.MLGraphBuilder.reduceProduct
• api.MLGraphBuilder.reduceSum
• api.MLGraphBuilder.reduceSumSquare
• api.MLGraphBuilder.relu
• api.MLGraphBuilder.resample2d
• api.MLGraphBuilder.reshape
• api.MLGraphBuilder.sigmoid
• api.MLGraphBuilder.sin
• api.MLGraphBuilder.slice
• api.MLGraphBuilder.softmax
• api.MLGraphBuilder.softplus
• api.MLGraphBuilder.softsign
• api.MLGraphBuilder.split
• api.MLGraphBuilder.sub
• api.MLGraphBuilder.tan
• api.MLGraphBuilder.tanh
• api.MLGraphBuilder.transpose
• api.MLGraphBuilder.triangular
• api.MLGraphBuilder.where
• api.MLOperand
• api.MLOperand.dataType
• api.MLOperand.shape
• api.Navigator.ml
• api.WorkerNavigator.ml

35 features marked supported in Chromium 112 (with flag)

• api.ML
• api.ML.createContext
• api.MLActivation
• api.MLContext
• api.MLContext.compute
• api.MLGraph
• api.MLGraphBuilder
• api.MLGraphBuilder.MLGraphBuilder
• api.MLGraphBuilder.add
• api.MLGraphBuilder.averagePool2d
• api.MLGraphBuilder.build
• api.MLGraphBuilder.clamp
• api.MLGraphBuilder.constant
• api.MLGraphBuilder.conv2d
• api.MLGraphBuilder.div
• api.MLGraphBuilder.exp
• api.MLGraphBuilder.gemm
• api.MLGraphBuilder.hardSwish
• api.MLGraphBuilder.input
• api.MLGraphBuilder.max
• api.MLGraphBuilder.maxPool2d
• api.MLGraphBuilder.min
• api.MLGraphBuilder.mul
• api.MLGraphBuilder.reduceProduct
• api.MLGraphBuilder.relu
• api.MLGraphBuilder.resample2d
• api.MLGraphBuilder.reshape
• api.MLGraphBuilder.sigmoid
• api.MLGraphBuilder.softmax
• api.MLGraphBuilder.sub
• api.MLOperand
• api.MLOperand.dataType
• api.MLOperand.shape
• api.Navigator.ml
• api.WorkerNavigator.ml

4 features marked supported in Chromium 113 (with flag)

• api.MLGraphBuilder.concat
• api.MLGraphBuilder.convTranspose2d
• api.MLGraphBuilder.leakyRelu
• api.MLGraphBuilder.transpose

1 feature marked supported in Chromium 114 (with flag)

• api.MLGraphBuilder.pad

2 features marked supported in Chromium 115 (with flag)

• api.MLGraphBuilder.elu
• api.MLGraphBuilder.prelu

6 features marked supported in Chromium 116 (with flag)

• api.MLGraphBuilder.abs
• api.MLGraphBuilder.floor
• api.MLGraphBuilder.neg
• api.MLGraphBuilder.slice
• api.MLGraphBuilder.split
• api.MLGraphBuilder.tanh

1 feature marked supported in Chromium 119 (with flag)

• api.MLGraphBuilder.pow

1 feature marked supported in Chromium 120 (with flag)

• api.MLGraphBuilder.reduceMean

20 features marked supported in Chromium 121 (with flag)

• api.MLGraphBuilder.ceil
• api.MLGraphBuilder.cos
• api.MLGraphBuilder.erf
• api.MLGraphBuilder.expand
• api.MLGraphBuilder.identity
• api.MLGraphBuilder.log
• api.MLGraphBuilder.matmul
• api.MLGraphBuilder.not
• api.MLGraphBuilder.qrt
• api.MLGraphBuilder.reciprocal
• api.MLGraphBuilder.reduceL1
• api.MLGraphBuilder.reduceL2
• api.MLGraphBuilder.reduceLogSum
• api.MLGraphBuilder.reduceLogSumExp
• api.MLGraphBuilder.reduceMax
• api.MLGraphBuilder.reduceMin
• api.MLGraphBuilder.reduceSum
• api.MLGraphBuilder.reduceSumSquare
• api.MLGraphBuilder.sin
• api.MLGraphBuilder.tan

15 features marked supported in Chromium 122 (with flag)

• api.MLGraphBuilder.argMax
• api.MLGraphBuilder.argMin
• api.MLGraphBuilder.batchNormalization
• api.MLGraphBuilder.cast
• api.MLGraphBuilder.equal
• api.MLGraphBuilder.gather
• api.MLGraphBuilder.greater
• api.MLGraphBuilder.greaterOrEqual
• api.MLGraphBuilder.instanceNormalization
• api.MLGraphBuilder.layerNormalization
• api.MLGraphBuilder.lesser
• api.MLGraphBuilder.lesserOrEqual
• api.MLGraphBuilder.linear
• api.MLGraphBuilder.softplus
• api.MLGraphBuilder.where

3 features marked supported in Chromium 123 (with flag)

• api.MLGraphBuilder.hardSigmoid
• api.MLGraphBuilder.l2Pool2d
• api.MLGraphBuilder.softsign

5 features marked supported in Chromium 124 (with flag)

• api.MLGraphBuilder.gru
• api.MLGraphBuilder.gruCell
• api.MLGraphBuilder.lstm
• api.MLGraphBuilder.lstmCell
• api.MLGraphBuilder.triangular

[anssiko]

@Elchi3 much thanks for your review!

Quickly on 2. We use https://github.com/webmachinelearning/webnn/blob/main/.github/workflows/auto-publish.yml so both the URLs serve identical content, only style differs. Each merge produces a new CRD: https://www.w3.org/standards/history/webnn/

Our ED is served from the dedicated GH org and its URL is a bit verbose, so we’ve used the TR URL instead (bonus is a better rank in search). We will align this PR with what is the convention for BCD. Let us know.

[Elchi3]

Thanks for the context, @anssiko!

I think we should keep the TR URLs then. If MDN docs are created then the reference pages will also link to the TR spec. (BCD's convention is to only allow spec urls that are included in web-specs and whether that project has marked the spec with "standing: good" -- this criteria is met here)

This brings me to another point:

4. Given we don't have MDN reference docs (yet?), we try to not submit 404 mdn_urls to BCD. So, it would be good to remove for them for now.

[ibelem]

Thank you @anssiko for the help and thanks @Elchi3 for the review!

I just saw that the following features seem to have been dropped in the latest spec and therefore aren't added (and there is a typo for sqrt, so that needs to be corrected)

Yes, I didn't add dropped APIs into BCD, and the typo of sqrt op was fixed.

The note "Currently supported on Windows and ChromeOS." should be "Currently supported on ChromeOS and Windows only." (Operating system names sorted alphabetically, plus the word "only".). Also it would be good to put this note on all 93 features (or a subset if it doesn't apply everywhere).

Updated "Currently supported on ChromeOS and Windows only." to more features that applied.

Given we don't have MDN reference docs (yet?), we try to not submit 404 mdn_urls to BCD. So, it would be good to remove for them for now.

Removed all "mdn_urls" for 93 features.

Based on the openwebdocs/project#193, I have an open question needs @Elchi3 's help, specifically for WebNN operations in MLGraphBuilder.json . Usually, these operations e.g. clamp have different browser implementation status on different platforms, and even different on different device types.

Current Browser Implementation Status for clamp:

• Chrome
  • ChromsOS
    • CPU: 123
    • GPU: Later version
    • NPU (potential to be added into spec later): Later version
  • Windows
    • CPU: 112
    • GPU: 120
    • NPU (potential to be added into spec later): Later version
  • Android
    • WIP
  • ...

I used the first supported version if the op supported by multiple platforms and device types in current PR. The node partial_implementation is not the exact case as https://github.com/mdn/browser-compat-data/blob/main/docs/data-guidelines/api.md mentioned, and I am afraid adding "notes": "Currently supported on ChromeOS and Windows only." into codes below for these operations cannot describe the implementation status exactly (https://webmachinelearning.github.io/webnn-status/). What is the best way to describe them clearly in the BCD do you think? @Elchi3 Thanks!

"chrome": {
              "version_added": "112",
              "flags": [
                {
                  "name": "#web-machine-learning-neural-network",
                  "type": "preference",
                  "value_to_set": "Enabled"
                }
              ]
            },

MLGraphBuilder.json

      "clamp": {
        "__compat": {
          "spec_url": "https://www.w3.org/TR/webnn/#api-mlgraphbuilder-clamp",
          "tags": [
            "web-features:webnn"
          ],
          "support": {
            "chrome": {
              "version_added": "112",
              "flags": [
                {
                  "name": "#web-machine-learning-neural-network",
                  "type": "preference",
                  "value_to_set": "Enabled"
                }
              ]
            },
            "chrome_android": {
              "version_added": false
            },
            "deno": {
              "version_added": false
            },
            "edge": "mirror",
            "firefox": {
              "version_added": false
            },
            "firefox_android": "mirror",
            "ie": {
              "version_added": false
            },
            "oculus": "mirror",
            "opera": "mirror",
            "opera_android": "mirror",
            "safari": {
              "version_added": false
            },
            "safari_ios": "mirror",
            "samsunginternet_android": "mirror",
            "webview_android": "mirror"
          },
          "status": {
            "experimental": true,
            "standard_track": true,
            "deprecated": false
          }
        }
      },

[Elchi3]

Thanks for your fixes, @ibelem. This looks all good to me now.

On the questions about how to record the more complex support situation:

Based on the openwebdocs/project#193, I have an open question needs @Elchi3 's help, specifically for WebNN operations in MLGraphBuilder.json . Usually, these operations e.g. clamp have different browser implementation status on different platforms, and even different on different device types.

I used the first supported version if the op supported by multiple platforms and device types in current PR. The node partial_implementation is not the exact case as https://github.com/mdn/browser-compat-data/blob/main/docs/data-guidelines/api.md mentioned, and I am afraid adding "notes": "Currently supported on ChromeOS and Windows only." into codes below for these operations cannot describe the implementation status exactly (https://webmachinelearning.github.io/webnn-status/). What is the best way to describe them clearly in the BCD do you think? @Elchi3 Thanks!

Yeah, much like for accessibility support data (where you add the AT software and the operating system as new dimensions), it looks like the WebNN support data also wants two new dimensions: OS and device types. The BCD data model is currently not really designed take into account this additional complexity. However, we might get away with it for now by using an array support statement and notes. This will at least help BCD data consumers like MDN and caniuse to display something useful today.

Array support statement plus notes could look like this (because of the flag, this data looks a bit repetitive).

"chrome": [
  {
    "version_added": "140",
    "flags": [
      {
        "name": "#web-machine-learning-neural-network",
        "type": "preference",
        "value_to_set": "Enabled"
      }
    ],
    "notes": "Supported on NPUs on Windows."
  },
  {
    "version_added": "120",
    "flags": [
      {
        "name": "#web-machine-learning-neural-network",
        "type": "preference",
        "value_to_set": "Enabled"
      }
    ],
    "notes": "Supported on GPUs on Windows."
  },
  {
    "version_added": "112",
    "flags": [
      {
        "name": "#web-machine-learning-neural-network",
        "type": "preference",
        "value_to_set": "Enabled"
      }
    ],
    "notes": "Supported on CPUs on Windows."
  }
],

[ibelem]

Many thanks @Elchi3 for guiding me by using array support statement and notes, now the implementation status of WebNN operations have been added with more exact hardware and OS info. PTAL

[Elchi3]

Thanks @ibelem, I'm going to trust your expertise on all the hardware and OS info. Some spot checking with https://webmachinelearning.github.io/webnn-status/ looks good to me.

Let's merge this. Thank you! 🎉