Use modern WebIDL and Infra standard conventions

[anssiko]

ℹ️ This is a meta issue. See the (living) task list for pointers to specific issues and PRs.

The WebIDL spec recommends algorithmic method steps for defining operations: https://heycam.github.io/webidl/#method-steps

This spec currently uses a WebGPU spec inspired convention that differs from this best practice. We should consider adopting the "method steps" convention.

(Here's one example of method steps in context of the WebNN API spec:
https://webmachinelearning.github.io/webnn/#dom-ml-createcontext)

[anssiko]

I labeled this issue with "cr" implying we should address this issue before our Candidate Recommendation publication to satisfy "The document is considered complete and fit for purpose" requirement.

[anssiko]

Updated patterns for defining getters, setters, methods and constructors:

https://webidl.spec.whatwg.org/#getter-steps
https://webidl.spec.whatwg.org/#setter-steps
https://webidl.spec.whatwg.org/#method-steps
https://webidl.spec.whatwg.org/#constructor-steps

[anssiko]

@zolkis we discussed this issue on our call with a recommendation on tasks where to start:
https://www.w3.org/2022/09/22-webmachinelearning-minutes.html#t04

This issue is tagged as "cr" so we'll allocate time to discuss this on our bi-weeklies. Please bring any open issues or questions either to this issue or to the call. There is likely a lot of details that need to be clarified as you translate the current text into an algorithmic form. Thanks for your contributions!

[anssiko]

(API review questions that'll also inform this work on method steps discussed in #298)

[anssiko]

(Renamed the issue to better reflect the scope of this work.)

@zolkis I will document here the spec sections where we need to do editorial work such as add algorithmic method steps, add internal slots, use getters, setters, define methods and constructors using the modern WebIDL and Infra standard conventions.

This helps the WG understand the scope of this effort and areas where contributions are welcome. I would focus this task on editorial changes and only propose normative changes when they are needed to fix a spec bug, or to clarify an aspect where the spec and implementation disagree.

Integration branch

January 2024 update: Review feedback status (🟡 WIP, 🟢 fixed) updated.

August 2023 update: The big PR #446 has been merged. The remaining "review feedback" issues to be addressed separately.

June 2023 update: We use the zk-conventions-integration integration branch for this conventions alignment task.

PRs related to this conventions update will be merged to this integration branch. We merge the integration branch into main when all the related issues are addressed in the integration branch to keep main in a cohesive state and changes to it atomic.

Issues and PRs

zk-conventions-integration

Global changes

• MLActivation, MLOperand, input(), constant(), batchNormalization(), clamp(), concat()
  • fixed by Align algorithms defined so far #405
• Style changes to hide large algorithms and examples, frames for internal slots, etc.
  • fixed by Add stylistic changes #401
• Any bugs identified after merge of the PRs enumerated in this issue
  • fixed by Fix merge errors #437
• 🟡 review feedback Use deep copy for setting internal slots? #395
• 🟢 review feedback Improve algorithmic steps definitions #447
• 🟡 review feedback Use web spec best practices #450
• 🟡 review feedback Reserve asserts only for non-obvious things #455

MLOperand, MLActivation

• Add internal slots to MLOperand, MLActivation and basic algorithms #336
  • fixed by Add internal slots to MLOperand, MLActivation and basic algorithms #336 (comment)
• Clarify intermediate values (activations) vs MLActivation vs operations #335
  • fixed by ???
• 🟢 review feedback (bikeshed naming) MLOperandDataType #454
  • fixed by MLOperandType -> MLOperandDataType #464

MLGraphBuilder

• Add the build() method, the build() and buildSync() algorithms, MLBufferResourceView dictionary definitions
  • fixed by Add the build() and buildSync() algorithms #406
  • 🟡 review feedback Add traversal algorithm to buildSync() #448

Ops

• The batchNormalization() method
  • Improve batchNorm #334 fixed by Add the batch normalization algorithm #397
• The clamp() method
  • Add the clamp() algorithm #347 fixed by Clamp algorithm #399
• The concat() method
  • fixed by Add algorithm to concat() #398
• The conv2d() method
  • fixed by Add the conv2d and convTranspose2d algorithms #407
  • 🟢 review feedback Add missing conv2d validation steps #439
  • fixed by Fix #439: add missing conv2d() and convTranspose2d() validation steps #441
• The convTranspose2d() method
  • fixed by Add the conv2d and convTranspose2d algorithms #407
• Element-wise binary operations
  • fixed by Add element-wise binary operation algorithms #408
• Element-wise unary operations
  • fixed by Add element-wise unary algorithms #409
• The elu() method
  • fixed by Add the elu() algorithm #410
• The gemm() method
  • fixed by Add the gemm() algorithm #411
• The gru() method
  • fixed by Add the gru() and gruCell() algorithms #412
• The gruCell() method
  • fixed by Add the gru() and gruCell() algorithms #412
• The hardSigmoid() method
  • fixed by Add the hard-sigmoid algorithms #413
• The hardSwish() method
  • fixed by Add the hard-swish algorithm #414
• The instanceNormalization() method
  • fixed by Add the instance normalization algorithm #415
• The leakyRelu() method
  • fixed by Add the Leaky RELU algorithm #416
• The matmul() method
  • fixed by Add the matmul() algorithm #419
• The linear() method
  • fixed by Add the linear function algorithm #417
• The lstm() method
  • fixed by Add the LSTM and LSTM Cell algorithms #418
• The lstmCell() method
  • fixed by Add the LSTM and LSTM Cell algorithms #418
• The pad() method
  • fixed by Add the pad() algorithm #420
• Pooling operations
  • fixed by Add the pooling algorithms #421
  • 🟡 review feedback Fix description and formula in pooling operations #449
• The prelu() method
  • fixed by Add the prelu() algorithm #422 depends on Add element-wise binary operation algorithms #408
• Reduction operations
  • fixed by Add the reduction algorithms #423
  • 🟢 review feedback The default values of |options|.{{MLReduceOptions/axes}} should be {0, ...., N-1} rather than null. #451
• The relu() method
  • fixed by Add the relu() algorithm #424
• The resample2d() method
  • related Define algorithms for dictionaries with lists as default values #211
  • fixed by Add the resample2d() algorithm #425 and Wording change: Prefix literal lists with "the list" #515
• The reshape() method
  • fixed by Add the reshape algorithm #426
  • 🟡 review feedback Reshape: what if |newShape| is a scalar number #452
• The sigmoid() method
  • fixed by Add the sigmoid algorithm #427
• The slice() method
  • fixed by Add the slice algorithm #428
• The softmax() method
  • fixed by Add the softmax algorithm #429
• The softplus() method
  • fixed by Add the softplus algorithm #430
• The softsign() method
  • fixed by Add the softsign method #431
• The split() method
  • fixed by Add the split algorithm #432
• The squeeze() method
  • fixed by Add the squeeze() algorithm #433
• The tanh() method
  • fixed by Add the tanh algorithm #434
• The transpose() method
  • fixed by Add the transpose algorithm #435

main

• Validate MLContext #308
  • fixed by Fix #308: refer to MLContext validation steps from MLGraphBuilder #332
• Add MLGraphBuilder constructor steps
  • fixed by Add constructor steps to MLGraphBuilder #309
• Improve spec prose on "exists" #311
  • fixed by Fix #311: use [=map/exist=] instead of exist #313
• Improve createContext method steps
  • fixed by MlContext improvements #310
• Add method steps for createContextSync
  • fixed by MlContext improvements #310
• Handle errors according to Web IDL conventions #314
  • fixed by Fix error handling #315
• Add the builder.input() method steps
  • fixed by Add the builder.input() method steps #364
• Add the constant() method steps
  • fixed by Add the constant() method steps. #365
• Review sync vs async compute differences #316
  • fixed by Rework the sync async algorithms based on PR 323 #329

Other

Proposals for normative changes that were unearthed as part of the editorial work.

• API simplification: context types, context options, createContext() #302
• API simplification: context owns builder, graph becomes internal slot #303
• Clarify/simplify graph execution on GPU / MLCommandEncoder #333
• Ensure the programming model section reads well and is up to date with the latest changes

[zolkis]

This issue is good aggregate tracker. Issues might be spanned on need, if the discussion is expected to be contained, or too big.