Open Reaction Database: Schema (ord-schema)

This repository contains the schema for the Open Reaction Database initiative; please see the documentation at https://docs.open-reaction-database.org.

This repository does not contain the database itself; that is stored in ord-data. Rather, ord-schema is designed to store the database schema and tools for creating, validating, and submitting data to the database.

Installation

$ pip install ord-schema

This installs the core schema and helpers (building, parsing, validation, and message/Parquet I/O). Heavier, single-purpose features live behind optional extras so the default install stays lightweight:

Extra	Enables	Install
huggingface	ord_schema.huggingface.fetch_dataset: download datasets from the Hugging Face ord-data mirror	pip install "ord-schema[huggingface]"
orm	ord_schema.orm: map the schema into a relational (SQLAlchemy + PostgreSQL) database	pip install "ord-schema[orm]"
github	the GitHub-issue submission flow in ord_schema.scripts.process_dataset	pip install "ord-schema[github]"
examples	running the notebooks under examples/ (see below)	pip install "ord-schema[examples]"

Extras combine, e.g. pip install "ord-schema[orm,huggingface]". Importing a feature without its extra installed raises a normal ImportError.

Examples

The examples/ directory contains examples of dataset creation and use. To run locally, install with:

$ pip install "ord-schema[examples]"

Click here to run the examples with Binder:

Development

To install in editable/development mode (recommended: uv):

$ git clone https://github.com/open-reaction-database/ord-schema.git
$ cd ord-schema
$ uv sync --extra tests

The tests extra pulls in the feature extras (github, huggingface, orm) it needs to exercise their code paths, so this is enough to run the full suite. Add --extra examples as well to run the notebooks (heavier deps):

$ uv sync --extra examples --extra tests

You can still use pip if you prefer: pip install -e ".[tests]".

If you make changes to the protocol buffer definitions, install protoc and run ./compile_proto_wrappers.sh to rebuild the wrappers.

Conventions

1. convention: compound stoichiometry

Created: 2023.07.04

Last updated: 2023.07.04

Description

1. The preferred field for compound stoichiometry is the map Compound.features or ProductCompound.features.
2. The key should be "stoichiometric_coefficient" or "stoichiometric_ratio".
3. The value should be a Data message with its float_value representing the compound's stoichiometric coefficient or ratio.

Related links

#683 #684