Skip to main content

Composing the Rail

The rail is the ordered sequence of stages that defines a Spec. You compose it visually in the Spec editor, or set it through the API. When you run the Spec, the rail compiles deterministically into the pipeline phases the One Engine executes. The rail is a faithful description of the run: the compiler preserves order and stage configuration, so what you see in the editor is exactly what the engine does.

A typical rail reads left to right as the document journey: Source (where documents come from), Field Registry (deterministic transfer), Extraction (AI capture of gaps), Resolution (Data Policy normalization), Validation (quality checkpoints), and a terminal Data Product. You add only the stages you need. The minimum runnable rail is a single extraction stage; everything else is optional configuration layered on top.

Rail stage types

ParameterTypeDescription
schemaextractionThe extraction stage. Compiles to the Extraction phase that runs Claude over gap fields. The minimum runnable rail is a single schema stage.
registrytransferField Registry transfer. Compiles to the Transfer phase that fills cells deterministically from known field occurrences at no AI cost.
resolveresolutionResolution. Carries json.policy_ids; compiles to one resolution phase per active Data Policy, applied in order.
validcheckpointA positional validation checkpoint. Carries json.stage_ids (member gates) and optional json.target_phases. Validates the output of the stages before it.
assemblycomposePost-run compose. Carries json.grouping_field and json.anchor_field. Runs once after every document is terminal.
source / delivermarkerComposition markers for where documents enter and where the data product is delivered. They frame the rail; the per-document phases sit between them.

Each stage points at server-backed configuration rather than carrying its own copy of the data. A resolve stage references the Data Policies bound to the schema by ID. A valid stage references validation gates configured through the validation-stages endpoints. An assembly stage names the grouping and anchor fields. This indirection keeps the rail small and means editing a policy or a gate updates every Spec that uses it, with no rail rewrite.

Setting the rail via API

Set the rail with a PUT to the schema rail endpoint. Pass an array of stages; an empty array clears the rail. The example below composes a four-stage rail: registry transfer, extraction, resolution against one policy, and a validation checkpoint that covers the extraction output.

Compose a rail
curl -X PUT https://api.talonic.com/v1/schemas/sch_delivery_notes/rail \
  -H "Authorization: Bearer $TALONIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "rail": [
      { "type": "registry", "name": "Field Registry" },
      { "type": "schema", "name": "Extraction" },
      { "type": "resolve", "name": "Normalize",
        "json": { "policy_ids": ["pol_dates_amounts"] } },
      { "type": "valid", "name": "Checks",
        "json": { "stage_ids": ["vs_required_fields"] } }
    ]
  }'
A minimal runnable rail is a single extraction stage: {"rail":[{"type":"schema","name":"Extraction"}]}. Add a registry stage in front to fill known fields for free, a resolve stage to normalize values, and one or more valid checkpoints to gate quality. The order you set is the order the engine runs.

Frequently asked questions

What stages can a rail contain?+
The compiler understands source, registry (transfer), schema (extraction), resolve (resolution, one phase per policy), valid (positional validation checkpoint), assembly (post-run compose), and deliver, plus a few composition markers. Registry, extraction, resolution, and validation map to per-document phases; assembly runs once after all documents finish.
What is the minimum rail I can run?+
A single extraction stage: {"rail":[{"type":"schema","name":"Extraction"}]}. That compiles to one Extraction phase and runs the documents through Claude with registry context. Everything else (transfer, resolution, validation, assembly) is optional and added in the order you want it to run.
How do rail stages reference policies and gates?+
Stages point at server-backed config by ID rather than embedding it. A resolve stage carries json.policy_ids referencing Data Policies; a valid stage carries json.stage_ids referencing validation gates. Editing the underlying policy or gate updates every Spec that references it without rewriting the rail.
Does the order of rail stages matter?+
Yes. The rail order is the execution order. A validation checkpoint validates the cumulative output of the stages before it, so a checkpoint after Resolution sees resolved values, while one after Extraction sees raw extraction. Place transfer before extraction so known fields are filled for free before the AI runs.

Related

The Spec & One Engine
Validation Checkpoints
Field Registry