---
title: "Conversion spec"
description: "Every field of the IntoSQL conversion spec, the request that says how a file is read and what is written, the same in the API, the CLI and MCP."
canonical: https://intosql.com/docs/api/spec
last_updated: 2026-10-15
---

# Conversion spec

The spec is the whole request for a conversion: how to read the file, which database to write for, and what to change about single columns. It is the same object everywhere IntoSQL runs: the API takes it in `spec`, `intosql validate` checks it, and the converter on the site builds it from its options.

Every field but the database has a default that suits most files, so the API takes a spec that only names it:

```json
{ "output": { "dialect": "mysql" } }
```

The API fills in the rest and the conversion keeps the whole spec, which reads like this:

```json
{
    "version": 1,
    "input": {},
    "output": {
        "format": "sql",
        "dialect": "mysql",
        "create_table": true,
        "column_names": "snake_case",
        "style": "inserts",
        "batch_rows": 500
    },
    "inference": {
        "sample_rows": 10000,
        "date_order": "auto",
        "keep_leading_zeros": true
    },
    "columns": []
}
```

A spec that changes more, for a semicolon CSV from Mexico loaded into an existing PostgreSQL table, with one column renamed and one left out:

```json
{
    "version": 1,
    "input": { "delimiter": ";", "encoding": "windows-1252", "header_row": 2 },
    "output": {
        "format": "sql",
        "dialect": "postgresql",
        "table": "ventas",
        "schema": "staging",
        "create_table": false,
        "column_names": "snake_case",
        "style": "inserts",
        "batch_rows": 1000
    },
    "inference": {
        "sample_rows": 10000,
        "date_order": "day_first",
        "keep_leading_zeros": true,
        "locale": "es-MX"
    },
    "columns": [
        { "index": 0, "name": "folio" },
        { "index": 5, "exclude": true }
    ]
}
```


## The spec

A conversion request, the same for the browser, the CLI, the API and MCP.

| Field | Type | Description |
| --- | --- | --- |
| `version` | integer | Required.  |
| `input` | object | Required. How to read the input. |
| `output` | object | Required. What to write. |
| `inference` | object | Required. How column types are inferred. |
| `columns` | array of objects | Changes to single columns; every other column is written as detected. |

## `input`

How to read the input.

| Field | Type | Description |
| --- | --- | --- |
| `format` | one of `xlsx`, `xls`, `xlsb`, `ods`, `csv`, `tsv`, `json`, `ndjson`, `sql_dump` | Detected from the content when absent. |
| `encoding` | string or null | An encoding label such as `windows-1252`; detected when absent. |
| `delimiter` | string or null | For delimited text; detected when absent. |
| `sheet` | string or null | For spreadsheets; the first sheet when absent. |
| `header_row` | integer or null | 1-based row holding the column names; detected when absent. |

## `output`

What to write.

| Field | Type | Description |
| --- | --- | --- |
| `format` | one of `sql`, `csv`, `json` | Required. What a conversion writes. |
| `dialect` | one of `postgresql`, `mysql`, `mariadb`, `sqlite`, `sql_server`, `oracle` | Required. Decides names and types, for every format. |
| `table` | string or null | Derived from the file or sheet name when absent. |
| `schema` | string or null |  |
| `create_table` | boolean | Required.  |
| `column_names` | one of `snake_case`, `as_written` | Required. How column names are written. |
| `style` | one of `inserts`, `bulk` | Required. How rows are written. |
| `batch_rows` | integer | Required. Rows per statement or bulk batch. |

## `inference`

How column types are inferred.

| Field | Type | Description |
| --- | --- | --- |
| `sample_rows` | integer | Required. Rows read before the types are decided. |
| `date_order` | one of `day_first`, `month_first`, `year_first`, `auto` | Required. How ambiguous dates such as 03/02/2024 are read. |
| `keep_leading_zeros` | boolean | Required. Values such as 00127 stay text so the zeros survive. |
| `locale` | string or null | A BCP 47 tag such as `es-MX`. Decides what the data can't: ambiguous dates and decimal separators. Month-first and decimal point when absent. |

## `columns`

What to do with one column of the file, found by its position.

| Field | Type | Description |
| --- | --- | --- |
| `index` | integer | Required. 0-based position of the column in the file. |
| `name` | string or null | The name to write instead of the one derived from the header. |
| `as_text` | boolean | Keep every value as written: the column becomes text. |
| `exclude` | boolean | Leave the column out of the output. |