---
title: "FlowComposition · types"
url: https://developers.dagio.ai/reference/types-flow-composition/
---

# FlowComposition · types

   
                                
                                                                          
                                        
                  
           
          
   

The following types define named objects and their relationships. Tables include inherited properties. Schema-derived types refer to their validated structures; a TypeScript declaration does not replace the compiler’s semantic checks.

## FlowComposition

Explicit Model grammar for the existing canonical Flow engine's composed extension.

```typescript
export type FlowComposition = z.infer<typeof flowCompositionSchema>;
```

## FlowCompositionStep

One referenced control or executable step, distinct from canonical parenthood and layout.

```typescript
export type FlowCompositionStep = FlowComposition['steps'][number];
```

```typescript
type FlowCompositionStep = { key: string; kind: "task"; workNodeKey: string; actionKey: string; inputs: Record<string, { kind: "input"; key: string; } | { kind: "input-node-id"; key: string; } | { kind: "field"; definitionPath: string; fieldKey: string; } | { kind: "literal"; value: string | number | boolean | null; } | { kind: "collection-item"; } | { kind: "collection-node-id"; } | { kind: "iteration-number"; } | { kind: "step-output"; stepKey: string; outputKey: string; }>; outputs: { key: string; type: "number" | "boolean" | "text" | "surface-reference" | "result-reference"; provenance: "caller" | "canonical" | "derived"; minimum: number; maximum: number; result: "outputs" | "reference" | "summary" | "decisions" | "nextSteps" | "blockers"; }[]; reservedCostUnits: number; maximumAttempts: number; } | { key: string; kind: "sequence"; steps: string[]; } | { key: string; kind: "choice"; mode: "exclusive" | "multiple"; branches: { key: string; stepKey: string; ruleKey: string; }[]; minimum: number; maximum: number; selection: "all-eligible" | "explicit"; confirmation: "required" | "not-required"; freshness: "captured" | "require-current"; join: { mode: "all"; remaining: "wait"; } | { mode: "quorum"; successes: number; remaining: "wait" | "request-cancel"; }; } | { key: string; kind: "parallel"; branches: { key: string; stepKey: string; }[]; maximumConcurrency: number; join: { mode: "all"; remaining: "wait"; } | { mode: "quorum"; successes: number; remaining: "wait" | "request-cancel"; }; } | { key: string; kind: "subflow"; blueprintKey: string; inputs: Record<string, { kind: "input"; key: string; } | { kind: "input-node-id"; key: string; } | { kind: "field"; definitionPath: string; fieldKey: string; } | { kind: "literal"; value: string | number | boolean | null; } | { kind: "collection-item"; } | { kind: "collection-node-id"; } | { kind: "iteration-number"; } | { kind: "step-output"; stepKey: string; outputKey: string; }>; } | { key: string; kind: "collection"; queryKey: string; parameters: Record<string, { kind: "input"; key: string; } | { kind: "input-node-id"; key: string; } | { kind: "field"; definitionPath: string; fieldKey: string; } | { kind: "literal"; value: string | number | boolean | null; } | { kind: "collection-item"; } | { kind: "collection-node-id"; } | { kind: "iteration-number"; } | { kind: "step-output"; stepKey: string; outputKey: string; }>; stepKey: string; maximumItems: number; maximumPages: number; maximumOutputBytes: number; maximumConcurrency: number; freshness: "captured" | "require-current"; join: { mode: "all"; remaining: "wait"; } | { mode: "quorum"; successes: number; remaining: "wait" | "request-cancel"; }; } | { key: string; kind: "iterate"; stepKey: string; stopRuleKey: string; maximumIterations: number; inputs: Record<string, { kind: "input"; key: string; } | { kind: "input-node-id"; key: string; } | { kind: "field"; definitionPath: string; fieldKey: string; } | { kind: "literal"; value: string | number | boolean | null; } | { kind: "collection-item"; } | { kind: "collection-node-id"; } | { kind: "iteration-number"; } | { kind: "step-output"; stepKey: string; outputKey: string; }>; } | { key: string; kind: "wait"; inputs: ({ key: string; minimum: number; maximum: number; type: "number" | "boolean" | "text"; provenance: "caller"; } | { key: string; minimum: number; maximum: number; type: "surface-reference" | "result-reference"; provenance: "canonical"; selector: { contract: "SurfaceFlowReferenceSelector@1"; queryKey: string; parameters: Record<string, { kind: "input"; key: string; } | { kind: "input-node-id"; key: string; } | { kind: "field"; definitionPath: string; fieldKey: string; } | { kind: "literal"; value: string | number | boolean | null; } | { kind: "collection-item"; } | { kind: "collection-node-id"; } | { kind: "iteration-number"; } | { kind: "step-output"; stepKey: string; outputKey: string; }>; }; })[]; arrival: "active-only"; ordering: "first-committed"; eventKey: string; recipient: "initiator"; timeoutMilliseconds: number; onExpiration: "fail" | "cancel"; } | { key: string; kind: "delay"; resume: { kind: "duration"; milliseconds: number; } | { kind: "instant"; at: number; }; };
```

## FlowCompositionValueSource

Exact typed value mapping; arbitrary expressions, code and tool names are not admitted.

```typescript
export type FlowCompositionValueSource = z.infer<typeof valueSource>;
```

## FlowReferenceSelector

Exact Query and closed Flow bindings; the canonical Query service owns execution.

```typescript
export type FlowReferenceSelector = z.infer<typeof referenceSelector>;
```

[All references](https://developers.dagio.ai/reference/)

<!-- surface-examples:start -->

## Applied examples : Prepare a quote

The Flow declares Client and Need inputs, an executable step and a bounded budget.

### Configuration

Fragment placed in `flowBlueprints[].composition`. [Properties and accepted values](https://developers.dagio.ai/reference/flow-composition/).

```json
{
  "contract": "FlowComposition@1",
  "rootWorkNodeKey": "prepare-quote",
  "stateSurfaceDefinitionPath": "workspace/work/surface/preparation",
  "subflowLinkTypePath": null,
  "entryStepKey": "prepare",
  "inputs": [
    {
      "key": "client",
      "type": "surface-reference",
      "provenance": "caller",
      "minimum": 1,
      "maximum": 1
    },
    {
      "key": "need",
      "type": "text",
      "provenance": "caller",
      "minimum": 1,
      "maximum": 1
    }
  ],
  "contexts": [],
  "outputs": [],
  "steps": [
    {
      "key": "prepare",
      "kind": "task",
      "workNodeKey": "prepare",
      "actionKey": "prepare",
      "inputs": {},
      "outputs": [
        {
          "key": "proposal",
          "type": "result-reference",
          "provenance": "canonical",
          "minimum": 1,
          "maximum": 1,
          "result": "reference"
        }
      ],
      "reservedCostUnits": 1,
      "maximumAttempts": 1
    }
  ],
  "budgets": {
    "maximumDepth": 2,
    "maximumOccurrences": 20,
    "maximumConcurrency": 2,
    "maximumIterations": 3,
    "maximumDurationMilliseconds": 86400000,
    "maximumCostUnits": 100,
    "maximumStateBytes": 32000
  }
}
```

### Variation and connection

Fragment placed in `flowBlueprints[].composition.inputs`. [Properties and accepted values](https://developers.dagio.ai/reference/flow-composition/).

```json
[
  {
    "key": "client",
    "type": "surface-reference",
    "provenance": "caller",
    "minimum": 1,
    "maximum": 1
  },
  {
    "key": "need",
    "type": "text",
    "provenance": "caller",
    "minimum": 1,
    "maximum": 1
  }
]
```

### UI layout example

The illustrative layout below places this configuration in the Clients/Quotes app. Insert each fragment at the stated location, with Field, Query and Action references matching the Model declarations.

1. Qualify need
2. Prepare proposal
3. Wait for decision
4. Retain result

<!-- surface-examples:end -->