ONNX Protobuf Definitions for JavaScript

Common errors

• TypeError: Cannot read properties of undefined (reading 'create')

  cause Attempting to access a protobuf message constructor (e.g., `TensorProto`) that is nested within the `onnx` namespace directly, rather than through `onnx.TensorProto`.
  fix Ensure you are accessing the specific protobuf message via the `onnx` namespace, like `onnx.TensorProto.create()`.

• SyntaxError: Cannot use import statement outside a module

  cause Attempting to use ES module `import` syntax in a CommonJS environment without proper transpilation or configuration, indicating the runtime does not recognize ES modules.
  fix Configure your `package.json` with `"type": "module"` if targeting a pure ES module environment, or use a bundler (e.g., Webpack, Rollup) with Babel or TypeScript to transpile to CommonJS if targeting older Node.js or specific browser environments.

• TypeError: onnx.TensorProto is not a constructor

  cause Incorrect instantiation of a Protobuf message by trying to use `new onnx.TensorProto()` instead of the static `create` method.
  fix Always instantiate Protobuf messages using their static `create` method: `onnx.TensorProto.create({ ... })`.

Warnings

• breaking Major version 8.0.0 updates the internal ONNX IR_VERSION to 8, corresponding to ONNX v1.10.2. This may introduce breaking changes if your application relies on specific older IR_VERSION structures or expects backward compatibility with models built against prior ONNX specifications.
  Fix: Review the official ONNX release notes for v1.10.2 and migrate any model serialization/deserialization logic to accommodate IR_VERSION 8. Thoroughly test your application with models compiled against the new IR version.
• breaking Older major versions (e.g., 4.0.0, 3.1.0) also updated the underlying ONNX definition, potentially introducing breaking changes in the protobuf structures. Users should always check the upstream ONNX changelog relevant to the `IR_VERSION` noted in the `onnx-proto` version changelog.
  Fix: Consult the changelog for `onnx-proto` and the corresponding ONNX `IR_VERSION` to understand any structural changes introduced by specific package versions.
• gotcha This package provides only the ONNX Protobuf *definitions* (types, enums, message constructors), not an ONNX runtime or inference engine. Attempting to run or evaluate ONNX models directly with this package will result in errors.
  Fix: To perform ONNX model inference in JavaScript environments, use a dedicated ONNX Runtime library such as `onnxruntime-web` or `onnxruntime-node` in conjunction with these definitions for structure validation and serialization.
• gotcha Protobuf message instances are typically created using static factory methods (e.g., `create()`) rather than direct constructor calls (`new`). Using `new` can lead to runtime errors or unexpected behavior.
  Fix: Always use the static `create` method provided on each protobuf message constructor, e.g., `onnx.TensorProto.create({ ... })`.

Install

• npm install onnx-proto npm
• yarn add onnx-proto yarn
• pnpm add onnx-proto pnpm

Imports

• onnx
  wrong:

  const onnx = require('onnx-proto');

  correct:

  import { onnx } from 'onnx-proto';

  The 'onnx' object is a namespace containing all compiled protobuf messages, enums, and services. While `require` might work in some transpiled environments, the package is primarily designed for ES module imports as demonstrated in TypeScript examples.
• TensorProto
  wrong:

  import { TensorProto } from 'onnx-proto';

  correct:

  import { onnx } from 'onnx-proto'; // Access via onnx.TensorProto

  Individual ONNX Protobuf messages like `TensorProto` are nested within the top-level `onnx` namespace, not directly exported as root symbols.
• ModelProto
  wrong:

  import ModelProto from 'onnx-proto';

  correct:

  import { onnx } from 'onnx-proto'; // Access via onnx.ModelProto

  Similar to other protobuf messages, `ModelProto` is accessed as a property of the `onnx` namespace and is not a default export.

Quickstart

Demonstrates how to import the `onnx` namespace and construct a basic `TensorProto` using its static `create` method, illustrating the package's utility for creating ONNX data structures.

import { onnx } from 'onnx-proto';

// Create a simple ONNX TensorProto object
const tensorProto = onnx.TensorProto.create({
  dims: [2, 2],
  dataType: onnx.TensorProto.DataType.FLOAT,
  floatData: [1.0, 2.0, 3.0, 4.0]
});

console.log('Created ONNX TensorProto:');
console.log(JSON.stringify(tensorProto.toJSON(), null, 2));

// Access an enum value from the ONNX definition
const floatDataType = onnx.TensorProto.DataType.FLOAT;
console.log(`\nONNX TensorProto.DataType.FLOAT value: ${floatDataType}`);

// This package provides type definitions and constructors for ONNX structures.
// It does not include an ONNX runtime. For model inference, a separate
// runtime library (e.g., onnxruntime-web) is required.