Open Reaction Database Schema (JavaScript)

0.4.7 · active · verified Wed Apr 22

The `ord-schema` package provides JavaScript and TypeScript wrappers for interacting with the Open Reaction Database (ORD) schema. The ORD project standardizes the representation of chemical reaction data, facilitating data exchange, analysis, and machine learning applications within the chemistry domain. This library offers client-side tools, primarily built on Protocol Buffers (protobuf), to create, manipulate, and validate reaction data according to the ORD specification. Currently at version 0.4.7, the package has a consistent release cadence, often addressing internal tooling, dependency updates (like Protobuf), and minor bug fixes. Its core differentiator lies in enabling structured, interoperable chemical reaction data handling.

Common errors

```
TypeError: reaction.setReactionId is not a function
```
cause Attempting to call Protobuf setter methods on a plain JavaScript object or an uninitialized message.

fix Ensure `reaction` is an instance of `ord-schema.Reaction`. Instantiate it with `const reaction = new Reaction();` before calling any Protobuf-specific methods.
```
Error: Reaction validation failed: Error: Reaction.reaction_id is required.
```
cause A required field in the ORD schema was not set or was set with an invalid value before calling `validateReaction`.

fix Consult the ORD schema documentation for the specific message type (e.g., `Reaction`) to identify all required fields and their expected data types. Ensure all mandatory fields are populated correctly before validation.
```
Error: Cannot find module 'ord-schema/proto/ord_pb' or its corresponding type declarations.
```
cause Trying to import directly from internal Protobuf-generated paths instead of the main `ord-schema` entry point.

fix Most common symbols like `Reaction`, `validateReaction`, etc., are re-exported directly from the root `ord-schema` package. Use `import { Reaction } from 'ord-schema';` instead of `import { Reaction } from 'ord-schema/proto/ord_pb';`.

Warnings

breaking The underlying `protobuf` dependency was updated from `v4` to `v5` in `ord-schema@0.4.4`. While efforts are made to ensure backward compatibility for generated code, direct usage of `protobufjs` APIs or interaction with other libraries that strictly depend on `protobufjs@4` might lead to unexpected behavior or dependency conflicts.
Fix: Review your `package.json` for other `protobufjs` dependencies. If conflicts arise, consider upgrading other dependencies or using package manager overrides if possible. Thoroughly test your application after upgrading `ord-schema` to version `0.4.4` or later.
gotcha Direct modification of Protobuf message objects returned by `get*()` methods (e.g., `reaction.getMeasurements()`) can lead to unexpected behavior or state management issues, as these often return references. Use `add*()` or `set*()` methods for collections, or create new instances for nested objects.
Fix: Always use the provided setters (`set*`, `add*`) to modify Protobuf message fields. For example, instead of `reaction.getMeasurements()[0].setOutcome('FAILURE')`, create a new `ReactionMeasurement` or ensure you're modifying a detached copy if complex manipulation is needed.

Install

npm install ord-schema npm
yarn add ord-schema yarn
pnpm add ord-schema pnpm

Imports

Reaction
wrong:
```
import Reaction from 'ord-schema';
```
correct:
```
import { Reaction } from 'ord-schema';
```
Main Protobuf message type for a chemical reaction. It is a named export.
validateReaction
wrong:
```
import { validate } from 'ord-schema';
```
correct:
```
import { validateReaction } from 'ord-schema';
```
Utility function for schema validation of Reaction messages. Specific named export.

Reaction.toObject

wrong:

import { toObject } from 'ord-schema'; // ... `toObject` is a method on Reaction instances, not a direct export.

correct:

import { Reaction } from 'ord-schema'; const reaction = new Reaction(); const obj = reaction.toObject();

Protobuf messages have methods like `toObject()` and `serializeBinary()`. These are instance methods, not top-level exports.

Quickstart

Demonstrates creating a new Reaction object, populating basic fields, performing client-side validation, and handling Protobuf serialization/deserialization.

import { Reaction, validateReaction, ReactionMeasurement, Product } from 'ord-schema';

const reaction = new Reaction();
reaction.setReactionId('my-unique-reaction-id');

const measurement = new ReactionMeasurement();
measurement.setOutcome('SUCCESS');
reaction.addMeasurements(measurement);

const product = new Product();
product.setReactionProduct('my-product-smiles'); // Example SMILES string
reaction.addProducts(product);

// Add a textual description
reaction.setText('A simple example reaction with one product and a success outcome.');

// Validate the reaction object against the schema
try {
  validateReaction(reaction);
  console.log('Reaction is valid:', reaction.toObject());
} catch (error) {
  console.error('Reaction validation failed:', error);
}

// Example of serializing to binary (for sending over network/saving)
const binaryData = reaction.serializeBinary();
console.log(`Serialized reaction to ${binaryData.length} bytes.`);

// Example of deserializing from binary
const deserializedReaction = Reaction.deserializeBinary(binaryData);
console.log('Deserialized reaction ID:', deserializedReaction.getReactionId());

view raw JSON →