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

# Ingestion specs

> Define how Solya detects, parses, and transforms each incoming file into its standard data model.

An **ingestion spec** is the contract that tells Solya how to interpret an incoming
file from a [data source](/en/data-layer/data-source). It describes how to recognize
the file, how to read its columns, and how to transform the raw data into Solya's
standard model so it can power analytics, forecasts, and plans.

## What a spec contains

* **Name & description** — what the spec is for.
* **POS system / source** — which system the spec targets (e.g. Polaris, Kezia).
* **Detection rules** — how Solya identifies which incoming file matches this spec
  (filename patterns, sheet names, expected column headers).
* **Parsing configuration** — how to extract and parse each column (field types,
  delimiters, date and number formats).
* **Promotion steps** — the transformations that enrich the data (joins, type
  coercions, filtering, renaming, taxonomy mapping).
* **Scope** — `Global` (shared) or `Org` (specific to your organization).
* **Priority** — which spec wins when several could match the same file.
* **Version** — specs are versioned so configuration changes are traceable.

## Lifecycle

A spec moves through these statuses:

| Status         | Meaning                                     |
| -------------- | ------------------------------------------- |
| **Draft**      | Being authored; not used on incoming files. |
| **Active**     | In use and applied to matching files.       |
| **Deprecated** | Superseded; kept for reference.             |
| **Archived**   | Retired and hidden from day-to-day use.     |

A spec also has a **deployed** flag — only deployed specs are applied to live files.

## Working with ingestion specs

<Steps>
  <Step title="Open the configuration page">
    Go to **Data platform → Configuration → Ingestion specs** to browse existing specs.
    Filter by POS system, format, scope, and deployment status.
  </Step>

  <Step title="Create a spec">
    Create a new spec by defining its detection rules, parsing configuration, and
    promotion steps. Solya can also **recommend** a spec from a sample file to speed
    this up.
  </Step>

  <Step title="Deploy it">
    Deploy the spec to start applying it to incoming files. Deployment is recorded so
    you can see when it went live.
  </Step>

  <Step title="Iterate safely">
    Because specs are versioned, you can refine detection and parsing over time while
    keeping a clear history.
  </Step>
</Steps>

<Note>
  Every time a spec is applied to a file, the import is recorded as an
  [ingestion run](/en/data-layer/ingestion-runs) you can monitor.
</Note>