Ingestion specs — anatomy

An ingestion spec is the full contract that turns an incoming file into rows in Solya’s analytics model. This reference documents every part of it. For the user-facing introduction, see the data layer guide.

How a file flows through a spec

Detection

Solya decides which spec applies to an incoming file, using the spec’s detection rules.

Parsing

The file is read into a tabular form and its columns are mapped to typed fields, using the parsing config.

Promotion

One or more promotion pipelines transform the parsed data and write it to silver/gold tables.

Top-level shape

A spec is authored as JSON (snake_case keys). Its fields:

Field	Required	Description
`spec_id`	✓	Canonical identifier, stable across versions (e.g. `polaris_sav`, `ginkoia_tickets`).
`spec_version`	✓	Monotonic version number. Unique per `(spec_id, spec_version)`.
`name`	–	Display name.
`description`	–	What the spec is for.
`pos_system`	–	Source system identifier (e.g. `polaris`, `ginkoia`).
`status`	✓	`DRAFT` · `ACTIVE` · `DEPRECATED` · `ARCHIVED`.
`scope`	✓	`GLOBAL` (platform-seeded, shared) or `ORG` (organization-owned).
`organization_id`	conditional	Required for `ORG` scope; null for `GLOBAL`.
`is_default`	✓	Whether this is the default spec for its `pos_system` + `scope`.
`priority`	✓	Tie-breaker when several specs match (higher wins). Default `0`.
`detection`	✓	The detection config.
`parsing`	✓	The parsing config.
`promotions`	–	An array of promotion pipelines, one per output dataset.
`promotion`	–	Deprecated single-promotion form; use `promotions`.
`tags`	✓	`{ "systems": [...], "formats": [...] }` for UI filtering.

{
  "spec_id": "ginkoia_tickets",
  "spec_version": 2,
  "name": "Ginkoia — Tickets",
  "pos_system": "ginkoia",
  "status": "ACTIVE",
  "scope": "GLOBAL",
  "is_default": true,
  "priority": 0,
  "detection": { "match_mode": "composite", "rules": [ /* … */ ] },
  "parsing":   { "parser": { /* … */ }, "mapping": { /* … */ } },
  "promotions": [ { /* … */ } ],
  "tags": { "systems": ["ginkoia"], "formats": ["excel"] }
}

Scope: GLOBAL vs ORG

GLOBAL specs are seeded by the platform and available to every organization. They cover the standard POS formats (Polaris, Ginkoia, Kezia, …).
ORG specs belong to a single organization (organization_id set) and are only visible to it.

Deployment

Existence isn’t the same as activation for an org. A spec is deployed to an organization via an activation record (enabled flag) — so an org turns specs on/off without anyone editing the spec itself. In the API/DTO this surfaces as isDeployed on each spec.

Priority & conflict resolution

When more than one spec matches a file:

Specs are ranked by priority (descending).
Newer spec_version takes precedence.
The first matching spec is applied.

Lifecycle & versioning

DRAFT → ACTIVE ⇄ DEPRECATED → ARCHIVED

A spec_id can have multiple versions; (spec_id, spec_version) is unique.
Seeding is idempotent (upsert on that pair); GLOBAL specs removed from the seed set are archived, not deleted, to preserve history.

Continue to the three building blocks: Detection, Parsing, and the Promotion steps catalog — then see full examples.

API integration

API recipes

Platform & data model

Decision layer (reference)

Operations & infrastructure

Ingestion specs (reference)

Workflows (reference)

Tagging rules (reference)

Alerts (reference)

Ingestion specs — anatomy

How a file flows through a spec

Top-level shape

Scope: GLOBAL vs ORG

Deployment

Priority & conflict resolution

Lifecycle & versioning

​How a file flows through a spec

​Top-level shape

​Scope: GLOBAL vs ORG

​Deployment

​Priority & conflict resolution

​Lifecycle & versioning

How a file flows through a spec

Top-level shape

Scope: GLOBAL vs ORG

Deployment

Priority & conflict resolution

Lifecycle & versioning