> ## Documentation Index
> Fetch the complete documentation index at: https://docs.atomscale.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Parsing Schema Reference

> Describe your CSV tool log's columns, units, timestamps, and recipe steps so Atomscale can parse it

A parsing schema is a small JSON document that tells Atomscale how to read a CSV tool log: which column holds the timestamp, which columns to keep as channels, what to call them, and in which units. You load or write it in the **Parsing schema** section of the [Tool Log Streamer configuration](https://docs.atomscale.ai/gateway/tool-state/setup.md). EpiTrend logs don't need one.

You don't need to write the JSON by hand. [Ask the Gateway assistant to draft and preview the schema](https://docs.atomscale.ai/gateway/tool-state/setup.md#set-up-with-the-assistant) using a sample of your log. Use this reference if you want to review or edit the schema yourself.

## Example

For a log that starts like this:

```csv sample.csv theme={null}
Timestamp,Substrate Temperature,Chamber Pressure,Ga Shutter,Step
2026-09-14T12:00:00+0000,580.2,2.1e-8,0,Buffer
2026-09-14T12:00:01+0000,580.3,2.1e-8,1,Buffer
```

this schema keeps three channels and ignores the `Step` column. It is the built-in example you get from Create new parsing schema.

```json schema.json theme={null}
{
  "schema_version": 1,
  "delimiter": ",",
  "header_offset": 0,
  "skip_footer_rows": 0,
  "encoding": "utf-8",
  "decimal": ".",
  "time_axis": {
    "mode": "datetime_single",
    "columns": ["Timestamp"],
    "datetime_format": "%Y-%m-%dT%H:%M:%S%z"
  },
  "columns": [
    { "source_name": "Substrate Temperature", "property_name": "substrate_temperature", "unit": "degC" },
    { "source_name": "Chamber Pressure", "property_name": "chamber_pressure", "unit": "Torr" },
    { "source_name": "Ga Shutter", "property_name": "ga_shutter", "unit": null }
  ],
  "drop_columns": ["Step"],
  "confidence": 1
}
```

To record the growth step instead of ignoring it, move `Step` from `drop_columns` to `recipe_columns`; see [Recipe Columns](#recipe-columns).

## Fields

| Field | Default | Description |
| - | - | - |
| `schema_version` | `1` | Always `1`. |
| `delimiter` | `","` | The single character between fields, for example `","`, `";"`, or `"\t"` for tabs. Can't be a quote or a newline. |
| `header_offset` | `0` | The number of rows before the header row. Use `0` when the header is the first line. |
| `skip_footer_rows` | `0` | Must be `0`, because a growing file has no footer. |
| `encoding` | `"utf-8"` | `"utf-8"` or `"latin-1"`. |
| `decimal` | `"."` | The decimal separator in numbers: `"."` or `","`. |
| `time_axis` | Required | Which column or columns hold the timestamp. See [Time Axis](#time-axis). |
| `columns` | Required | One entry per channel to keep; at least one. See [Columns](#columns). |
| `drop_columns` | `[]` | Headers to ignore. Each must exist in the file's header. |
| `recipe_columns` | `null` | Columns that name the running recipe and step. See [Recipe Columns](#recipe-columns). |
| `confidence` | Required | Set to `1` for a schema you write yourself. |
| `notes` | None | Free text, for example the tool and software version the schema was written for. |

Columns in the file that the schema doesn't mention are ignored. Unknown fields in the schema are rejected.

### Time Axis

Every row needs a timestamp. Choose the mode that matches your log:

| `mode` | Use when | `columns` and `datetime_format` |
| - | - | - |
| `datetime_single` | One column holds the date and time, for example `2026-09-14T12:00:00+0000` or `2026-09-14 12:00:00`. | One header. A `strptime` format, or `null` for ISO 8601. |
| `datetime_split` | The date and time are in separate columns. Their values are joined with a space before parsing. | Two headers, date first. A `strptime` format covering both values, separated by a space. |
| `unix_seconds` | Seconds since 1970-01-01 UTC, with or without a fractional part. Convert millisecond values to seconds first. | One header. Omit `datetime_format`. |

**Time zones.** If timestamps include a UTC offset, include `%z` in the format. If they don't, Atomscale reads them in the gateway computer's time zone, and handles the repeated hour when daylight saving time ends. Don't use `%Z` (a zone name); it is rejected. See [Timestamps and Clocks](https://docs.atomscale.ai/gateway/data.md#timestamps-and-clocks).

Timestamps must not go backward from one row to the next. Rows with equal timestamps are allowed.

### Columns

Each entry in `columns` describes one channel:

| Key | Description |
| - | - |
| `source_name` | The column header exactly as it appears in the file, including capitalization and spaces. |
| `property_name` | The channel name to store in Atomscale. Use a short `snake_case` name, such as `ga_cell_temperature`. |
| `unit` | The unit, such as `"degC"`, `"K"`, or `"Torr"`, or `null` for unitless values such as shutter states. |

Columns can be listed in any order; they are matched by header name. Values must be numbers. Text values, such as `OPEN` or `CLOSED`, are stored as missing, so record shutter states as `0` and `1` where your software allows.

### Recipe Columns

If your log records which recipe and step are running, `recipe_columns` lets Atomscale split the growth into process steps named after them.

```json theme={null}
"recipe_columns": {
  "program": { "source_name": "Recipe", "key": null },
  "step": { "source_name": "Step", "key": null }
}
```

| Key | Description |
| - | - |
| `program` | The column naming the recipe or program file in effect, for example `growth_rev8.silk`. Optional. |
| `step` | The column naming the step that is running, for example `DepMain`. Optional. Without it, the program is used as the step. |
| `source_name` | The column header, exactly as in the file. |
| `key` | When a cell packs key/value pairs, such as `{ { Process, BTO }, { Step, DepMain } }`, the key whose value to read (`"Step"`). `null` when the cell holds the value itself. |

Cells that are empty, `-`, `0`, `n/a`, `na`, `nan`, `none`, or `null` mean no recipe is running. A recipe column can't also be the time axis, a channel, or a dropped column.

## More Examples

### Separate Date and Time Columns

A semicolon-separated log with a comma decimal separator, in the gateway computer's local time:

```csv theme={null}
Date;Time;Ga Cell;As Cracker;BEP
2026-09-14;12:00:00;950,5;600,0;1,2e-6
```

```json theme={null}
{
  "delimiter": ";",
  "decimal": ",",
  "time_axis": {
    "mode": "datetime_split",
    "columns": ["Date", "Time"],
    "datetime_format": "%Y-%m-%d %H:%M:%S"
  },
  "columns": [
    { "source_name": "Ga Cell", "property_name": "ga_cell_temperature", "unit": "degC" },
    { "source_name": "As Cracker", "property_name": "as_cracker_temperature", "unit": "degC" },
    { "source_name": "BEP", "property_name": "beam_equivalent_pressure", "unit": "Torr" }
  ],
  "confidence": 1
}
```

### Unix Timestamps

```csv theme={null}
timestamp_unix_s,elapsed_time_s,GM1_Vacuum_reading,GM1_Cu1_base_temperature
1789387200.0,0.0,2.1e-8,850.1
```

```json theme={null}
{
  "time_axis": { "mode": "unix_seconds", "columns": ["timestamp_unix_s"] },
  "columns": [
    { "source_name": "elapsed_time_s", "property_name": "elapsed_time_s", "unit": "s" },
    { "source_name": "GM1_Vacuum_reading", "property_name": "gm1_vacuum_reading", "unit": null },
    { "source_name": "GM1_Cu1_base_temperature", "property_name": "gm1_cu1_base_temperature", "unit": null }
  ],
  "confidence": 1
}
```

Fields left out of these examples take their defaults.

## Validation Rules

Atomscale checks a schema in two stages.

**When you apply the configuration**, the schema's structure is checked:

* The file is valid JSON, UTF-8 text, and at most 256 KiB.
* `time_axis.columns` has the right number of headers for its mode, and `datetime_format` is readable and doesn't use `%Z`.
* `columns` has at least one entry, and each `source_name` and `property_name` is unique and not blank.
* No header appears in more than one of `time_axis.columns`, `columns`, `drop_columns`, and `recipe_columns`.
* The delimiter is a single ASCII character other than a quote or newline.

**When a file is parsed**, the schema is checked against the file:

* Every header named in the schema must exist in the file's header row exactly. A mismatch fails the file immediately with Schema columns absent from header.
* The file's header names must be unique and not blank.
* Rows with the wrong number of fields, or with a missing, unreadable, or backward timestamp, are skipped. Non-numeric channel values are stored as missing.
* After 50 consecutive rows that can't be used, parsing stops and the data item shows Stream Error.

> [!TIP]
>
> Write the schema against a real log file from your system, then test it with a short run before
> relying on it for a growth campaign.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.