iSynth specification guide

iSynth 反应数据规范 / Reaction data specification

新记录使用 schema_version: "1.9.0"。普通反应与一锅多步使用相同结构：投入物料、投料、阶段和结果。

Use schema_version: "1.9.0". Ordinary and multi-stage reactions share the same structure: input identities, charges, segments and outcomes.

如何使用 / How to use

人工贡献使用简化表格模板；AI、实验室软件和数据平台使用本规范生成 Reaction JSON。规范用于交换、校验、存储和读取记录，不要求人工填写整个嵌套结构。JSON Schema 也不规定底层数据库表的设计。

Human contributors use the simple table template. AI, lab software and platforms produce Reaction JSON for exchange, validation, storage and reading. Users need not fill the full nested structure; JSON Schema does not prescribe database tables.

一次实验对应一个 Reaction，多次实验可保存为 JSONL。先用 validate_reaction_records(records=[reaction]) 校验并核对原文，再把每条对象用 JSON 编码为 reaction_record 字符串，放在上传请求的 rows 中。数据集标题、作者、来源和许可另行提供一次。

One experiment is one Reaction; multiple experiments can use JSONL. Validate with validate_reaction_records(records=[reaction]) and check the source. JSON-encode each object as a reaction_record string in upload rows. Dataset title, authors, provenance and license are supplied separately.

规范包内的 structured-upload.json 是一个包含完整一锅多步反应与元信息的虚构示例，可作为 MCP upload_records(request=...) 的请求。该通道用于行数据不超过 1 MiB 的完整文件；大型数据使用 start_upload 和 CSV 传输。CSV 中每行保留一个完整 Reaction，不将阶段拆为独立反应行。

The bundle includes structured-upload.json, a fictional complete request for MCP upload_records(request=...). This tool handles a complete source file with at most 1 MiB of row data; larger files use start_upload and CSV transfer. Each CSV row preserves one complete Reaction, including its segments.

上传后使用回执中的 file_id 调用 get_parse_report，使用 dataset_id 调用 get_dataset_status。数据先保存为私有草稿，经核对并提交审核后才可发布。网页展示结构、阶段条件和测量结果，并保留原始文件及完整 JSONL 下载。可检索的公开记录可通过 MCP 获取。

After upload, call get_parse_report with the returned file_id and get_dataset_status with dataset_id. Data remain a private draft until reviewed and approved for publication. The website provides reaction views, original files and full JSONL downloads. Searchable public records can be retrieved through MCP.

[完整提交示例 / Complete submission workflow](https://isynth.ichemdata.com/en/guides/reaction-data) · [上传请求 / Upload request](https://isynth.ichemdata.com/examples/structured-upload.json)

完整示例 / Complete example

以下是虚构的格式示例，不对应真实实验或已核实的论文。 This fictional format example does not represent a real experiment or verified publication.

必填字段为 schema_version、reaction_identifier、materials、initial_state 和 segments。未报告投入物料或阶段信息时，对应数组可为空；有产物结构而无产率时，仍可记录 products。 Required fields are schema_version, reaction_identifier, materials, initial_state and segments. Arrays may be empty when the corresponding information is unreported. Products can be recorded without a reported yield.

字段归属 / Field ownership

| 内容 / Content | 位置 / Location | | --- | --- | | 投入物料的结构、名称与角色 / Input identity and role | materials | | 起始投料 / Starting charges | initial_state.inputs | | 阶段新增投料 / Later charges | segments[].added_materials | | 投料量、浓度或商品配方 / Dose amount and concentration or formulation | Charge.amount、Charge.concentration | | 阶段条件与持续时间 / Conditions and duration | segments[].conditions、segments[].duration | | 产物结构与角色 / Product identity and role | products | | 指标、量值与测定说明 / Metric, value and measurement details | measurements | | 反应物转化率 / Reactant conversion | measurements（subject 指向 Material.id） | | 文章来源 / Source article | provenance.doi、provenance.reference |

同一投入物料多次加入时复用 Material.id，每项投料独立填写量与浓度，例如 { "material":"reagent_1", "amount":{"value":2,"unit":"mL"}, "concentration":{"raw":"2.5 M solution in hexanes"} }。concentration 描述本次所用试剂，不是整个反应体系的浓度；分散体可保留 "60% dispersion in mineral oil" 原文。

Repeated additions reuse Material.id. Each charge records its own amount and concentration or supplied formulation. concentration describes the reagent in that charge, not the bulk reaction mixture. Raw wording can preserve commercial dispersions without splitting their components.

Product 只定义产物的结构、角色和补充属性。所有定量结果统一使用 measurements，每项填写 subject（被测对象）、type（指标）和 value（量值）。subject 引用 Material.id 或 Product.id；同一对象可有多项指标或多次独立测量。

Product defines identity, role and attributes. All quantitative results use measurements with subject (Material.id or Product.id), type and value. Multiple metrics or repeated measurements use separate items.

| 实验范围 / Scope | 产物定义 / Product identities | 测量值 / Measurements | | --- | --- | --- | | 整体实验 / Overall | products | measurements | | 单独报告的阶段结果 / Reported stage results | segments[].products | segments[].measurements |

转换率与产率不再按对象拆成不同的测量数组。阶段测量不会自动成为整体结果；最终结果不重复填写到最后一个阶段。定性观察使用 Segment.text。

Conversion and yield share one array, distinguished by subject and type. Stage results remain stage-specific; final results are not copied into the last segment. Qualitative observations use Segment.text.

阶段观察与整体结果 / Stage observations and overall results

Segment 通常只需投料、条件、时间与 text。text 同时记录操作和定性观察，例如溶液变黄、析出沉淀或 TLC 观察。仅凭这些观察，不补算转化率，也不创建未确认的中间体。

A Segment usually needs only charges, conditions, duration and text. text covers procedure and qualitative observations, such as colour changes, precipitation and TLC observations. These alone do not establish a numerical conversion or an identified intermediate.

| 原文报告 / Source reports | 填写位置 / Location | | --- | --- | | 本阶段中间体的结构或名称，可有测量值 / An identified stage intermediate, with or without measurements | segments[].products | | 本阶段中间体的 NMR 产率 / NMR yield of a stage intermediate | segments[].measurements | | 本阶段反应物转化率 / Stage reactant conversion | segments[].measurements，subject 指向投入物料 / references the input | | 整体实验的最终产物、产率或 ee / Final product, yield or ee for the experiment | products、measurements |

这些位置按实验范围区分，测量对象由 subject 指定。最终结果不重复填入最后一个阶段。阶段产物可省略，不要求每一步都有产物结构或测量。

Experimental scope determines placement; subject identifies the measured entity. Do not copy final results into the last segment. Stage products are optional; a stage does not require a product structure or measurement.

用于论文提取 / Applying the specification to extraction

规范文件是 JSON Schema（Draft 2020-12），用于约束字段、类型和嵌套关系。模型应输出符合规范的 Reaction 数据。提供论文正文与补充信息、完整字段说明和示例，再按提取指南执行；通过结构与语义校验后仍需核对原文。

The specification file is a JSON Schema (Draft 2020-12) defining fields, types and nesting. The model produces conforming Reaction data. Supply the paper/SI, complete field reference and an example, then follow the extraction guide. Review against the source after structural and semantic validation.

[提取指南与提示词 / Extraction guide and prompts](https://isynth.ichemdata.com/schemas/extraction-instructions.md)

示例顺序与字段说明一致；JSON 对象的键顺序不影响校验，segments 数组的顺序表示实验先后。

Examples follow reference field order. Object key order does not affect validation; the segments array describes chronological order.

parameters 与 text

新记录的补充结构化属性统一写在所属对象的 parameters，例如阶段条件中的球磨频率。text 统一保存补充文字：阶段中为操作与观察，测量中为方法及样品，物料中为补充物料说明，反应根对象中为其他实验说明。后处理仍写 workup，文献引用仍写 provenance.reference。

Use parameters for additional structured values and text for additional wording, on the object to which the content belongs. Parameters may contain strings, numbers, booleans or JSON objects. Existing fields take priority. Nested objects under a parameter key replace as a whole; there is no implicit nested merge. Reviewed literal paths under parameters can be registered for typed search. A custom JSON object is not automatically searchable or scientifically validated.

旧记录继续使用其冻结版本，原有 extensions、notes 和 description 不改写。新记录不再要求独立模块包装；当前格式版本与参数登记表共同规定可识别字段的含义。

Historical extensions, notes and description keep their frozen readers. New records use parameters and text without a separate module wrapper.

null 是 JSON 空值，不是一个指标或数值 0。阶段之间省略字段会沿用旧值；明确写 null 则停止沿用，此后不再假定旧值仍然有效。例如：

| 后续阶段写法 / Later segment input | 含义 / Meaning | | --- | --- | | 不写 parameters / Omit parameters | 沿用之前的补充条件 / Inherit earlier settings | | {"parameters":{"milling_frequency":{"value":20,"unit":"Hz"}}} | 改为 20 Hz / Replace frequency with 20 Hz | | {"parameters":{"milling_frequency":null}} | 不再沿用旧频率，新频率未给出 / Clear frequency without asserting a new value | | {"parameters":null} | 不再沿用全部补充条件 / Clear all extra settings |

JSON null explicitly clears inherited information. It does not mean zero or establish that equipment was switched off. An empty object updates no keys and therefore leaves earlier settings in place.

阶段与测量 / Segments and measurements

普通反应通常一个阶段，一锅多步按顺序增加阶段。conditions 省略的条件沿用前值，duration 仅属于当前阶段。过程及定性观察写在 text，后处理写在 workup。整体测量填写根对象 measurements；阶段测量填写 segments[].measurements。

Measurement 按 subject、type、value、stereocentres、basis、text 阅读。所有指标使用相同结构；text 记录测量方法、样品和补充说明。

Use one segment for an ordinary reaction and ordered segments for a sequence. Product identity and measurements are separate. Each measurement references its subject and belongs either to the whole experiment or to a reported stage.

来源、量值与存储 / Sources, quantities and storage

Provenance 主要填写来源论文的 doi 与 reference；无 DOI 的实验记录可填写来源引用。来源论文 DOI 与数据集 DOI 分开管理。原文件、原始列与导入定位由平台保存，不要求提取者重复填写。

保留来源单位。Quantity 使用 value/unit 表示单值、lower/upper 表示范围、qualifier 表示单边界、uncertainty 表示 ± 不确定度，raw 可保留无法可靠拆分的原文。

例如 20–25 °C 写为 {"lower":20,"upper":25,"unit":"°C"}，无需逐一标记边界是否包含。单侧界限如 <0 °C 写为 {"value":0,"unit":"°C","qualifier":"<"}。特殊边界表述可保留在 raw。旧边界字段仅兼容读取，不出现在新数据的填写说明中。

For 20–25 °C use {"lower":20,"upper":25,"unit":"°C"}. A one-sided limit such as <0 °C uses {"value":0,"unit":"°C","qualifier":"<"}. Preserve exceptional boundary wording in raw. Legacy boundary fields remain readable but are excluded from new authoring instructions.

完整记录存于 reaction_facts.document（JSONB）；阶段条件、投料浓度和分析说明保留在各自的事实载荷。结构检索仍使用统一的内部化学实体索引，公开记录里的产物仍位于 products。投料量和浓度的数值关联 operation_id，测量值关联 measurement_id。

新增 parameters 或模块内容不必增加 SQL 列；专用校验、数值筛选和建模特征仍需定义语义后接入。未知模块完整保留，不自动宣称已经完成科学校验。已有 1.4.0、1.3.0、1.2.0、1.1.0、1.0.0 和上线前记录继续使用原读取规则，不改写历史数据。

Cite the source paper with provenance.doi and reference. The platform keeps original files and import traceability separately. Preserve source units and raw wording. Full records and unknown extension content remain in JSONB; supported numeric facts have scoped indexes. New parameter keys do not require database columns, but scientific validation and numerical search need explicit support. Earlier records retain their original readers without data migration.

完整字段见 [中文字段说明](reaction-reference.zh.html) / [English field reference](reaction-reference.en.html)。

立体选择性 / Stereoselectivity

• ee/er 比较一对对映体，不限于单手性中心。例如 (2R,5S):(2S,5R)，前提是两者确为不同的对映体。
• 固定 C2 为 R、考察 C5 时，stereocentres: "5S"；basis: "(2R,5S):(2R,5R)" 表明 dr 的比较对象。
• 多个中心或天然产物仍使用相同字段，每个测量单独记录比较对象。分组比例明确写出各组成员；多项比例保留全部项，不强行折合 de。
• 位次沿用原文，不等于 SMILES 原子序号。结构未完成原子映射时，位点文字仅作为来源标注；不据此自动生成比较结构。

The examined sites do not define the comparison. ee/er concern a complete enantiomer pair; de/dr concern the stated diastereomers. Keep fixed-centre comparisons and pooled group sums explicit. No counterpart, group membership, ratio order or unreported measurement is inferred during extraction. Source locants do not constitute a graph atom mapping. Existing 1.4.0 and older records retain their original shapes and semantics. The authoring change does not rewrite historical data.

Definitions: [IUPAC enantiomeric excess](https://goldbook.iupac.org/terms/view/E02070), [diastereoisomers](https://goldbook.iupac.org/terms/view/D01680), [epimers](https://goldbook.iupac.org/terms/view/E02167).

手性位点写法 / Examined-site notation

| 情况 / Case | 写法 / Format | | --- | --- | | 一个考察位点 / One examined site | 5S | | 多个考察位点 / Several examined sites | (2R,5S) | | 更多位点 / More sites | (7S,8R,12R) | | 原文含稠环位次 / Source fusion locants | (3aR,7S) |

按来源位次升序排列，用英文括号和逗号，不加空格、不重复位次。R/S 表示绝对构型；原文假不对称构型保留 r/s。只列本次考察的位点；已固定且不考察的位点不必重复。未编号、未确定构型或其他类型的立体信息保留在 text。此为 iSynth 的统一输入写法，不替代化学命名或分子原子映射。

Use ascending source locants, ASCII parentheses/commas, no spaces or duplicates. Preserve R/S and source pseudoasymmetric r/s. Other stereogenic elements or unknown locants remain in text. This input syntax does not assign SMILES atom indices or validate the chemical configuration.

人工表推荐 product_stereocentres，含义与 Measurement.stereocentres 一致。一个单元格适用于本行所有立体选择性指标；不同指标考察不同位点时，使用机器格式分别记录。product_structure 保留完整结构；旧 product_configuration 仍按原义保存完整构型标签，不自动转换为考察位点。

Human tables recommend product_stereocentres. One cell applies to the row’s stereoselectivity metrics; use individual machine measurements for different examined sites. Full structure belongs in product_structure. Legacy product_configuration remains a source configuration label, not an alias for the examined sites. Human typography is normalized without changing source cells; unrecognized labels remain in measurement text.

自定义参数登记与检索 / Parameter registration and search

未登记的参数完整保存在原始 JSONB 和所属对象的事实载荷中，读取完整反应即可取得，不会因缺少专用字段而丢弃。

登记表为每个可检索参数固定 ID、所属对象、JSON 路径、类型、单位和转换规则。当前支持数量、文字、布尔值；parameters 下的嵌套字面路径也可登记。旧扩展模块的指定版本读取规则继续保留。维护者在 backend/isynth_schema/parameter-registry.json 增补定义，使用 python -m isynth_schema.parameters candidate.json --previous previous.json 检查兼容性，补充检索测试后部署。已有 ID 的含义与单位规则不覆盖修改；有破坏性变化时新增 ID 或模块版本。这是维护者审核的登记流程，目前没有开放的网页注册表单。

MCP 先调用 get_parameter_catalog，再调用 search_reaction_records；HTTP 可读取 [参数登记表](/api/reactions/parameter-catalog)，并向 POST /api/reactions/search 提交：

数值上下界使用登记的标准单位，此例为 Hz；原数据的单位不改写。所有条件参数默认须同时匹配某一个阶段。segment: 0 限定起始状态，segment: 1 限定第一个阶段；物料或产物属性可用 subject 限定对象。多个对象范围的条件之间采用 AND。范围按区间交集匹配，保留开闭边界；只有原文、单位未知或类型不符的值不参与数值筛选。

当前查询复用已有 JSONB 和按反应/对象建立的索引，不新增参数值副本或 SQL 列；兼容的历史事实可以直接查询，不要求重新上传。parameter_coverage 报告可查记录与缺少或过期事实的记录数。事实不完整的记录不参与“缺失”筛选，避免把未解析当作未报告。登记使参数可被筛选，不代表已经建立专用数值索引；高频参数可在性能评估后增加可重建索引，原始数据与查询含义保持一致。

Unknown parameters remain preserved. A reviewed, versioned registry declares queryable paths, types and units. Use get_parameter_catalog and parameter_filters; clauses sharing scope and selector match one stage/object. Numeric filters overlap reported intervals and use canonical units without rewriting originals. Current queries use existing scoped JSONB with reaction/object indexes, not a dedicated numerical index or duplicated values. Compatible historical facts are queryable immediately; check parameter_coverage for unavailable or stale facts. Registry additions do not alter old records; incompatible semantics require a new ID/module version.

Dimensionless proportions / 无量纲比例

80% is a dimensionless proportion equal to 0.8; % denotes a factor of 1/100. In new Reaction 1.9.0 records use {"value":80,"scale":"percent","raw":"80%"}. An explicitly reported decimal fraction uses {"value":0.8,"scale":"fraction"}. Do not supply unit together with scale. Physical quantities use unit, such as mmol or °C; relative dosing retains equiv or mol%. Historical percentage unit spellings remain readable. Numerical search indexes compare equivalent values on the same scale, without rewriting the original record.

百分比不是独立的物理量。新记录用 scale 明确其表示方式：percent 表示百分数，fraction 表示小数比例。raw 保留原文；历史记录中的 unit: "%" 仍可读取。

Custom condition workflow / 补充条件的使用

Contributors may add additional structured values under conditions.parameters. Values remain in the source JSONB and returned record. Only reviewed entries in the parameter registry are available to parameter_filters. New compatible registrations can query existing parsed facts without re-uploading source data. Registration does not imply a dedicated physical value index. See [storage and retrieval](https://isynth.ichemdata.com/en/guides/retrieval#custom-parameters), the [complete fictional upload](https://isynth.ichemdata.com/examples/parameter-upload.json) and its [search request](https://isynth.ichemdata.com/examples/parameter-query.json).

### 参数类型与检索操作 / Parameter types and operators

参数登记时确定 quantity、text 或 boolean 类型；数值参数登记单位（或无量纲比例的 scale）与换算规则。上传的自定义字段不会自动加入检索列表。登记表中的英文 id 固定不变，页面按语言选择登记过的显示名称。

A registered quantity supports equals with a single value, or range with minimum and/or maximum. Equals matches explicitly reported points after conversion, excluding intervals, approximate values and inequalities. Range matches overlap with reported points or intervals. Equal lower and upper query bounds test containment, not exact reported equality. Text supports equals/contains; booleans support equals. Registration defines these operations; they are not guessed from uploaded strings.

摄氏温度的新示例使用单位符号 °C。C 仅为历史输入的兼容别名。百分数使用 scale: "percent"，如 {"value":5,"scale":"percent","qualifier":"<","raw":"<5%"}。

### 键变化检索 / Bond-change search

网页、MCP 与 API 共用 bond_changes，例如 {"bond_changes":[{"change":"broken","elements":["C","N"]}]}。支持 broken、formed、order_changed，多个条件按 AND 组合。

Net changes compare source atom-mapped SMILES in reactant/reagent materials and final products. Atom maps must be unique within each side and preserve element/isotope identity across sides. Only atom pairs present on both sides are compared; omitted byproducts never prove bond cleavage. Unmapped or conflicting structures are unavailable, not negative evidence. Results include bond_change_coverage. This does not infer a reaction mechanism, transient intermediate steps or automatic atom mapping; broad queries must first be narrowed by dataset, structures or conditions.

构建、校验、读写与提交 / Build, validate, read, write and submit

下载 [Python 工具包](/schemas/isynth-python-toolkit.zip)，解压后 python -m pip install .。工具包使用平台同一套代码，提供片段构建、完整反应语义校验、JSON/JSONL 读写与 CSV 上传准备，附完整可运行示例。isynth-validate reactions.jsonl 离线校验；MCP 客户端使用有范围限制的凭证上传草稿、查询处理回执。填写来源、作者及许可并核对之后再提交审核。

Download the toolkit, extract and install with python -m pip install .. Run examples/build_reaction.py to prepare complete records and upload files without sending data. See the [usage guide](/en/guides/reaction-data#python-toolkit) and [RxnSeek handoff](/schemas/reactionseek-handoff.md) for integration choices. Historical files are read with their original versions, without automatic conversion.