iSynth reaction data specification: complete field reference

How to use

Human contributors use the simple table. AI, lab software and integrations use Reaction JSON. JSON Schema defines exchange and validation; users need not fill every field, and it is not a database table layout.

Generate one Reaction per experiment → validate and check against the source → upload to a private draft → inspect the reaction preview → submit for review. Each record is serialized as a JSON string in the reaction_record column; authors, provenance and license are separate dataset metadata.

The website provides structures, stage conditions and measurements alongside original files and full JSONL downloads. Once published and prepared for search, records can be queried and retrieved through MCP.

Paper extraction

JSON Schema (Draft 2020-12) defines fields, types and nesting. The model outputs reaction JSON data conforming to it, not the schema itself. Examples follow reference field order; object key order does not affect validation, while segments array order represents the experimental sequence.

Provide the paper, supporting information and this reference. Output one Reaction per experiment; use JSONL with one object per line for multiple experiments. Omit unreported optional fields and preserve unresolved descriptions as text.

Check structure, material references, quantities and measurement ownership, then review against the source. With MCP, call get_reaction_contract(view="extraction"), followed by validate_reaction_records; validation does not save data. If a model cannot open links, supply the files in the downloaded specification bundle.

Conventions

• Use lower, upper and unit for ordinary ranges, e.g. {"lower":20,"upper":25,"unit":"°C"}. One-sided limits use value and qualifier, e.g. <0 °C. Retain exceptional boundary wording in raw.
• Custom parameters remain in JSONB. Registered names, types, units and paths enable API/MCP parameter_filters; discover support with get_parameter_catalog. Clauses in the same group match one stage; missing or unknown-unit values do not satisfy numeric filters. Registry: /schemas/reaction-parameter-registry.json.
• Examined centres identify the sites under study; the comparison defines the value. ee/er concern a complete enantiomer pair, while de/dr concern the stated diastereomers. Multi-centre molecules can still have ee/er; varying one centre with the others fixed generally concerns de/dr.
• stereocentres uses source locants, not SMILES atom indices. Preserve explicit comparison species or groups for multi-centre molecules, natural products and pooled ratios; a site list does not establish those groups.
• One JSON object represents one experiment, using materials, initial_state, segments, products and measurements.
• materials defines inputs and products defines products. Starting and subsequent inputs use Charge, with amount and concentration together.
• An ordinary reaction usually has one segment; a multi-stage reaction has ordered segments. Use an empty segments array when no stage information is reported.
• Put segment settings in conditions; omitted settings carry forward. duration is local. Procedures and qualitative observations go in text. Use segment products and measurements only for explicitly reported stage results. Overall results belong at the root, without copying them into the final segment.
• Charge.material references an input material ID. Measurement.subject references the measured Material.id or Product.id. All metrics use measurements.
• Keep source units. value and unit represent a quantity; raw alone can retain unresolved wording.
• Use parameters for additional structured attributes and text for supplementary wording. Later segments inherit omitted settings; null explicitly stops inheritance and does not mean zero.
• Existing 1.8.0, 1.7.0, 1.6.0, 1.5.0, 1.4.0, 1.3.0, 1.2.0, 1.1.0 and 1.0.0 records retain their original readers without rewriting source data.

Reaction

Every experiment records material definitions, starting charges, reaction segments and outcomes. Use one segment for an ordinary reaction and ordered segments for a multi-stage reaction.

Object example

{
  "schema_version": "1.9.0",
  "reaction_identifier": "EXP-0001",
  "materials": [
    {
      "id": "alcohol",
      "identifiers": [
        {
          "type": "SMILES",
          "value": "CCO"
        }
      ],
      "role": "reactant"
    },
    {
      "id": "reagent",
      "identifiers": [
        {
          "type": "NAME",
          "value": "acetic anhydride"
        }
      ],
      "role": "reagent"
    }
  ],
  "initial_state": {
    "inputs": [
      {
        "material": "alcohol",
        "amount": {
          "value": 0.25,
          "unit": "mmol",
          "raw": "0.25 mmol"
        }
      },
      {
        "material": "reagent"
      }
    ]
  },
  "segments": [
    {
      "conditions": {
        "temperature": {
          "value": 25,
          "unit": "°C",
          "raw": "25 °C"
        }
      }
    }
  ],
  "products": [
    {
      "id": "product",
      "identifiers": [
        {
          "type": "SMILES",
          "value": "CCOC(C)=O"
        }
      ]
    }
  ],
  "measurements": [
    {
      "subject": "product",
      "type": "yield",
      "value": {
        "value": 80,
        "scale": "percent",
        "raw": "80%"
      }
    }
  ],
  "provenance": {
    "reference": "Fictional teaching record; Example A"
  },
  "text": "Fictional format illustration, not a measured result. Unreported amounts, method and calculation bases are omitted."
}

"1.9.0"

"EXP-0001"

[
  {
    "id": "alcohol",
    "identifiers": [
      {
        "type": "SMILES",
        "value": "CCO"
      }
    ],
    "role": "reactant"
  },
  {
    "id": "reagent",
    "identifiers": [
      {
        "type": "NAME",
        "value": "acetic anhydride"
      }
    ],
    "role": "reagent"
  }
]

{
  "inputs": [
    {
      "material": "alcohol",
      "amount": {
        "value": 0.25,
        "unit": "mmol",
        "raw": "0.25 mmol"
      }
    },
    {
      "material": "reagent"
    }
  ]
}

[
  {
    "conditions": {
      "temperature": {
        "value": 25,
        "unit": "°C",
        "raw": "25 °C"
      }
    }
  }
]

[
  {
    "id": "product_1",
    "identifiers": [
      {
        "type": "SMILES",
        "value": "C[C@H](O)c1ccccc1"
      }
    ],
    "role": "desired_product",
    "text": "Isolated target product",
    "parameters": {
      "reported_stereochemistry": "(S)"
    }
  }
]

[
  {
    "subject": "reactant_1",
    "type": "conversion",
    "value": {
      "value": 90,
      "scale": "percent"
    },
    "text": "Determined by GC."
  }
]

{
  "reference": "Fictional teaching record; Example A"
}

"Fictional format illustration, not a measured result. Unreported amounts, method and calculation bases are omitted."

{
  "run_id": "RUN-0001"
}

Identifier

Use SMILES / INCHI for structures, INCHIKEY for a structure key, NAME for a name or abbreviation (DCM), and CUSTOM for source-local labels (1a, with a source locator). A material may have multiple evidenced identifiers; never infer a structure from a name or label.

Object example

{
  "type": "SMILES",
  "value": "CCO"
}

"SMILES"

"CCO"

Quantity

A quantity, such as {"value":1,"unit":"mmol"}, used for amounts, temperature, time or measurements. raw can retain the source wording.

Object example

[
  {
    "value": 25,
    "unit": "°C"
  },
  {
    "unit": "°C",
    "raw": "20–25 °C",
    "lower": 20,
    "upper": 25
  },
  {
    "value": 25,
    "unit": "°C",
    "raw": "25 ± 2 °C",
    "uncertainty": 2
  },
  {
    "value": 5,
    "scale": "percent",
    "raw": "<5%",
    "qualifier": "<"
  }
]

25

"percent"

"°C"

"20–25 °C"

"<"

20

25

2

Material

Input material identity and role. Record the amount and concentration on its Charge.

Object example

{
  "id": "reactant_1",
  "identifiers": [
    {
      "type": "SMILES",
      "value": "CCO"
    }
  ],
  "role": "reactant",
  "is_limiting": true,
  "text": "Ethanol used as the limiting reactant",
  "parameters": {
    "purity": "99.5%"
  }
}

"reactant_1"

[
  {
    "type": "SMILES",
    "value": "CCO"
  }
]

"reactant"

true

"Ethanol used as the limiting reactant"

{
  "purity": "99.5%"
}

Charge

One addition: material identifies the input, amount records the dose, and concentration records the concentration or formulation used in this addition.

Object example

{
  "material": "reagent_1",
  "amount": {
    "value": 2,
    "unit": "mL"
  },
  "concentration": {
    "raw": "2.5 M solution in hexanes"
  }
}

"reagent_1"

{
  "value": 2,
  "unit": "mL"
}

{
  "raw": "2.5 M solution in hexanes"
}

Conditions

Reaction conditions. Later segments inherit omitted settings; JSON null stops inheriting a setting and does not mean zero. Put elapsed time in Segment.duration.

Object example

{
  "temperature": {
    "value": 25,
    "unit": "°C"
  },
  "pressure": {
    "value": 1,
    "unit": "atm"
  },
  "atmosphere": "nitrogen",
  "parameters": {
    "humidity": {
      "raw": "40% RH"
    },
    "light_source_type": "blue LED",
    "wavelength": "450 nm"
  }
}

{
  "value": 25,
  "unit": "°C"
}

{
  "value": 1,
  "unit": "atm"
}

"nitrogen"

{
  "milling_frequency": {
    "value": 30,
    "unit": "Hz"
  }
}

InitialState

Materials and settings present at the start. inputs refers to materials; solvents are materials too.

Object example

{
  "inputs": [
    {
      "material": "reactant_1",
      "amount": {
        "value": 1,
        "unit": "mmol",
        "raw": "1 mmol"
      }
    },
    {
      "material": "solvent_1",
      "amount": {
        "value": 2,
        "unit": "mL",
        "raw": "2 mL"
      }
    }
  ],
  "conditions": {
    "temperature": {
      "value": 0,
      "unit": "°C"
    }
  },
  "text": "The starting materials were charged at 0 °C."
}

[
  {
    "material": "reactant_1",
    "amount": {
      "value": 1,
      "unit": "mmol",
      "raw": "1 mmol"
    }
  },
  {
    "material": "solvent_1",
    "amount": {
      "value": 2,
      "unit": "mL",
      "raw": "2 mL"
    }
  }
]

{
  "temperature": {
    "value": 0,
    "unit": "°C"
  }
}

"The starting materials were charged at 0 °C."

Segment

Ordered additions, settings, duration, procedure and observations. These usually suffice; add products or measurements only for explicitly reported stage results.

Object example

{
  "added_materials": [
    {
      "material": "reagent_1",
      "amount": {
        "value": 1,
        "unit": "mmol"
      }
    }
  ],
  "conditions": {
    "temperature": {
      "value": 0,
      "unit": "°C"
    }
  },
  "duration": {
    "value": 1,
    "unit": "h"
  },
  "text": "The reagent was added dropwise. The solution turned yellow."
}

[
  {
    "material": "reagent_1",
    "amount": {
      "value": 1,
      "unit": "mmol"
    }
  }
]

{
  "temperature": {
    "value": 0,
    "unit": "°C"
  }
}

{
  "value": 1,
  "unit": "h"
}

"The reagent was added dropwise. The solution turned yellow and a precipitate formed."

[
  {
    "id": "intermediate_1",
    "identifiers": [
      {
        "type": "NAME",
        "value": "Intermediate A (source label)"
      }
    ],
    "role": "intermediate"
  }
]

[
  {
    "subject": "reactant_1",
    "type": "conversion",
    "value": {
      "value": 90,
      "scale": "percent"
    },
    "text": "Determined by GC."
  }
]

Product

Product identity, role and attributes. Put measured results in the reaction or segment measurements, referencing this product ID through subject.

Object example

{
  "id": "product_1",
  "identifiers": [
    {
      "type": "SMILES",
      "value": "C[C@H](O)c1ccccc1"
    }
  ],
  "role": "desired_product",
  "text": "Isolated target product",
  "parameters": {
    "reported_stereochemistry": "(S)"
  }
}

"product_1"

[
  {
    "type": "SMILES",
    "value": "C[C@H](O)c1ccccc1"
  }
]

"desired_product"

"Isolated target product"

{
  "reported_stereochemistry": "(S)"
}

Measurement

One measurement: subject, metric type, value and context. Use separate items for different metrics or repeated measurements of one object.

Object example

{
  "subject": "product_1",
  "type": "ee",
  "value": {
    "value": 96,
    "scale": "percent",
    "raw": "96%"
  },
  "stereocentres": "(2R,5S)",
  "basis": "(2R,5S):(2S,5R)",
  "text": "Isolated target diastereomer fraction analysed by chiral HPLC."
}

"reactant_1"

"ee"

{
  "value": 96,
  "scale": "percent",
  "raw": "96%"
}

"5S"

"(2R,5S):(2S,5R)"

"Isolated product analysed by chiral HPLC."

Provenance

Article source: DOI and citation. The platform preserves the original experimental files separately.

Object example

{
  "doi": "10.1234/isynth.example",
  "reference": "Fictional article for documentation examples"
}

"10.1234/isynth.example"

"Fictional article for documentation examples"

Complete one-pot example

{
  "schema_version": "1.9.0",
  "reaction_identifier": "EXP-0002",
  "materials": [
    {
      "id": "reactant_1",
      "identifiers": [
        {
          "type": "SMILES",
          "value": "C[C@H](O)c1ccccc1"
        }
      ],
      "role": "reactant"
    },
    {
      "id": "reagent_1",
      "identifiers": [
        {
          "type": "SMILES",
          "value": "CC(=O)OC(C)=O"
        }
      ],
      "role": "reagent"
    },
    {
      "id": "solvent_1",
      "identifiers": [
        {
          "type": "SMILES",
          "value": "CC#N"
        }
      ],
      "role": "solvent"
    }
  ],
  "initial_state": {
    "inputs": [
      {
        "material": "reactant_1",
        "amount": {
          "value": 1,
          "unit": "mmol",
          "raw": "1 mmol"
        }
      },
      {
        "material": "solvent_1",
        "amount": {
          "value": 2,
          "unit": "mL",
          "raw": "2 mL"
        }
      }
    ],
    "conditions": {
      "temperature": {
        "value": 0,
        "unit": "°C"
      }
    }
  },
  "segments": [
    {
      "added_materials": [
        {
          "material": "reagent_1",
          "amount": {
            "value": 1,
            "unit": "mmol"
          }
        }
      ],
      "duration": {
        "value": 1,
        "unit": "h"
      },
      "text": "The reagent was added dropwise at 0 °C, and the solution turned yellow. After 1 h, an aliquot was taken for HPLC.",
      "measurements": [
        {
          "subject": "reactant_1",
          "type": "conversion",
          "value": {
            "value": 95,
            "scale": "percent",
            "raw": "95 %"
          },
          "text": "Method: HPLC."
        }
      ]
    },
    {
      "added_materials": [
        {
          "material": "reagent_1",
          "amount": {
            "value": 1,
            "unit": "mmol"
          }
        }
      ],
      "conditions": {
        "temperature": {
          "value": 80,
          "unit": "°C"
        }
      },
      "duration": {
        "value": 3,
        "unit": "h"
      },
      "text": "The same mixture was heated to 80 °C for 3 h."
    }
  ],
  "products": [
    {
      "id": "product_1",
      "identifiers": [
        {
          "type": "SMILES",
          "value": "CC(=O)O[C@H](C)c1ccccc1"
        }
      ]
    }
  ],
  "measurements": [
    {
      "subject": "product_1",
      "type": "yield",
      "value": {
        "value": 80,
        "scale": "percent",
        "raw": "80 %"
      },
      "text": "Method: isolated."
    },
    {
      "subject": "product_1",
      "type": "ee",
      "value": {
        "value": 94,
        "scale": "percent",
        "raw": "94 %"
      },
      "text": "Method: chiral HPLC."
    }
  ],
  "workup": "The reaction mixture was worked up and purified as reported.",
  "provenance": {
    "reference": "Fictional documentation fixture. All quantities and observations illustrate format only; no experiment or source paper is claimed."
  },
  "text": "FORMAT EXAMPLE ONLY. Not a laboratory instruction or a reported experimental result."
}