Skip to main content
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

1

Detection

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

Parsing

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

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:
FieldRequiredDescription
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_idconditionalRequired 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:
  1. Specs are ranked by priority (descending).
  2. Newer spec_version takes precedence.
  3. 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.