MLOperand

Experimental: This is an experimental technology. Check the browser compatibility table carefully before using it in production.

The MLOperand interface of the Web Neural Network (WebNN) API represents a node in a computational graph that is being built: a graph input, a constant, or the output of an operation. Operands are symbolic — they describe the data type and shape of a value, but hold no data that script can read.

MLOperand objects are created by the methods of MLGraphBuilder, such as input(), constant(), and every operation like add() or conv2d(). An operand belongs to the builder that created it, and therefore to that builder’s MLContext; passing it to a different builder throws a TypeError.

This feature is available only in secure contexts  (HTTPS or localhost), and is available in both the main thread and Web Workers .

Web IDL

[SecureContext, Exposed=(Window, Worker)]
interface MLOperand {
  readonly attribute MLOperandDataType dataType;
  readonly attribute FrozenArray<unsigned long> shape;
};

dictionary MLOperatorOptions {
  USVString label = "";
};

typedef (bigint or unrestricted double) MLNumber;

Constructor

None. Operands are created by MLGraphBuilder methods.

Instance properties

dataType

A read-only MLOperandDataType string giving the operand’s element type, for example "float32".

shape

A read-only, frozen array of unsigned long values giving the size of each dimension. The number of entries is the operand’s rank. The array is empty ([]) for a scalar.

Because operation outputs have their shapes computed at graph-construction time, you can inspect shape to check intermediate results while building:

const x = builder.input('x', { dataType: 'float32', shape: [1, 3, 224, 224] });
const y = builder.averagePool2d(x, { windowDimensions: [2, 2], strides: [2, 2] });
console.log(y.dataType, y.shape); // "float32" [1, 3, 112, 112]

Instance methods

None.

MLOperandDescriptor

The MLOperandDescriptor dictionary describes the data type and shape of an operand. It is passed to MLGraphBuilder.input(), MLGraphBuilder.constant() and MLContext.createConstantTensor(), and is the base of MLTensorDescriptor.

enum MLInputOperandLayout {
  "nchw",
  "nhwc"
};

enum MLOperandDataType {
  "float32",
  "float16",
  "int32",
  "uint32",
  "int64",
  "uint64",
  "int8",
  "uint8"
};

dictionary MLOperandDescriptor {
  required MLOperandDataType dataType;
  required sequence<[EnforceRange] unsigned long> shape;
};

Each dimension must be an integer greater than zero (zero-sized dimensions are not currently allowed) and within the range of a 32-bit signed integer. The total number of elements must also be in that range, and the total byte length must not exceed the implementation’s limit (see MLOpSupportLimits.maxTensorByteLength). Otherwise, the method receiving the descriptor throws a TypeError.

The byte length of a descriptor is the product of all dimensions multiplied by the element size of the data type.

MLOperandDataType

Not every operator supports every data type on every platform. Each operator lists its allowed and required data types; use MLContext.opSupportLimits() to query what the current context supports.

MLInputOperandLayout

The memory layout of 4-D image-like tensors, used by layout-dependent operators such as conv2d(), convTranspose2d(), pooling, instanceNormalization() and resample2d().

The layout that the current platform prefers is reported by MLOpSupportLimits.preferredInputLayout.

MLOperatorOptions

The MLOperatorOptions dictionary is the base of every operation’s options dictionary. Every operation accepts it, either directly or through a derived dictionary such as MLConv2dOptions.

The label is not intended to be a natural-language string; treat it like a variable name or error code, for example "mul#1234" or "encoder.layer3.attention.matmul".

try {
  builder.matmul(a, b, { label: 'decoder.proj' });
} catch (e) {
  console.error(e.message); // The message may mention "decoder.proj".
}

MLNumber

MLNumber is a union of bigint and unrestricted double, used for numeric options whose type depends on an operand’s data type — for example minValue/maxValue of clamp(), value of pad(), and the scalar constant(dataType, value) overload.

A double alone would lose precision for 64-bit integers above 2⁵³, and a long long could not hold values above 2⁶³. The implementation casts the MLNumber to the relevant operand data type:

• For integer types, the value is converted to that integer type; use a bigint (for example 2n ** 60n) to keep full 64-bit precision.
• For floating-point types, the value is converted to the nearest representable value.
• Values outside the range of the target type are truncated.

const big = builder.constant('int64', 9007199254740993n); // Exact, beyond 2^53.
const clamped = builder.clamp(x, { minValue: 0, maxValue: 6 }); // Cast to x.dataType.

Examples

Inspecting operands while building a graph

const context = await navigator.ml.createContext();
const builder = new MLGraphBuilder(context);
 
const input = builder.input('input', { dataType: 'float32', shape: [1, 4] });
const weights = builder.constant(
  { dataType: 'float32', shape: [4, 2] },
  new Float32Array([1, 0, 0, 1, 1, 0, 0, 1]),
);
const scalar = builder.constant('float32', 0.5);
 
const product = builder.matmul(input, weights);
const output = builder.mul(product, scalar);
 
console.log(product.shape); // [1, 2]
console.log(scalar.shape);  // [] (scalar)
console.log(output.dataType); // "float32"

Specifications

The latest Editor’s Draft is available at webmachinelearning.github.io/webnn .

Browser compatibility

WebNN is under active development and support varies across browsers, operating systems, and hardware.

See Browser Compatibility: WebNN APIs.

See also

• MLGraphBuilder
• MLGraphBuilder operations
• MLTensor