Skip to main content

Workflow Schema

This page provides the complete schema for vai workflow JSON files. Workflow files define multi-step RAG pipelines as portable, declarative configurations.

TypeScript Interface​

interface VaiWorkflow {
  // Identity
  $schema?: string;
  name: string;
  description?: string;
  version?: string;

  // Store appearance
  branding?: WorkflowBranding;

  // Parameterization
  inputs?: Record<string, WorkflowInput>;

  // Shared defaults
  defaults?: WorkflowDefaults;

  // The pipeline
  steps: WorkflowStep[];

  // What the workflow produces
  output?: Record<string, any>;
}

interface WorkflowBranding {
  /** Predefined Lucide icon name (e.g., "search", "brain", "trophy") */
  icon?: string;
  /** Hex color code for the icon accent (e.g., "#00D4AA") */
  color?: string;
}

interface WorkflowInput {
  type: "string" | "number" | "boolean";
  description?: string;
  required?: boolean;
  default?: any;
}

interface WorkflowDefaults {
  db?: string;
  collection?: string;
  model?: string;
}

interface WorkflowStep {
  id: string;
  name?: string;
  description?: string;
  tool: StepTool;
  inputs: Record<string, any>;
  condition?: string;
  forEach?: string;
  continueOnError?: boolean;
}

type StepTool =
  // VAI tools
  | "query"
  | "search"
  | "rerank"
  | "embed"
  | "similarity"
  | "ingest"
  | "collections"
  | "models"
  | "explain"
  | "estimate"
  // Control flow
  | "merge"
  | "filter"
  | "transform"
  // LLM
  | "generate";

JSON Schema​

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "vai Workflow",
  "description": "A multi-step RAG pipeline definition for vai",
  "type": "object",
  "required": ["name", "steps"],
  "properties": {
    "$schema": {
      "type": "string",
      "description": "Schema URL for IDE validation"
    },
    "name": {
      "type": "string",
      "description": "Human-readable workflow name"
    },
    "description": {
      "type": "string",
      "description": "What this workflow does"
    },
    "version": {
      "type": "string",
      "pattern": "^\\d+\\.\\d+\\.\\d+$",
      "description": "Semver version"
    },
    "branding": {
      "type": "object",
      "description": "Icon and accent color for the Workflow Store",
      "properties": {
        "icon": {
          "type": "string",
          "description": "Predefined Lucide icon name"
        },
        "color": {
          "type": "string",
          "pattern": "^#[0-9A-Fa-f]{6}$",
          "description": "Hex color code for the icon accent"
        }
      }
    },
    "inputs": {
      "type": "object",
      "additionalProperties": {
        "type": "object",
        "required": ["type"],
        "properties": {
          "type": {
            "type": "string",
            "enum": ["string", "number", "boolean"]
          },
          "description": { "type": "string" },
          "required": { "type": "boolean" },
          "default": {}
        }
      }
    },
    "defaults": {
      "type": "object",
      "properties": {
        "db": { "type": "string" },
        "collection": { "type": "string" },
        "model": { "type": "string" }
      }
    },
    "steps": {
      "type": "array",
      "minItems": 1,
      "items": {
        "type": "object",
        "required": ["id", "tool", "inputs"],
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^[a-zA-Z_][a-zA-Z0-9_]*$",
            "description": "Unique step identifier"
          },
          "name": {
            "type": "string",
            "description": "Human-readable label"
          },
          "description": {
            "type": "string"
          },
          "tool": {
            "type": "string",
            "enum": [
              "query", "search", "rerank", "embed",
              "similarity", "ingest", "collections",
              "models", "explain", "estimate",
              "merge", "filter", "transform",
              "generate"
            ]
          },
          "inputs": {
            "type": "object",
            "description": "Tool-specific inputs with template expression support"
          },
          "condition": {
            "type": "string",
            "description": "Template expression; step runs only if truthy"
          },
          "forEach": {
            "type": "string",
            "description": "Template expression resolving to an array"
          },
          "continueOnError": {
            "type": "boolean",
            "default": false
          }
        }
      }
    },
    "output": {
      "type": "object",
      "description": "Template expressions defining workflow result"
    }
  }
}

Tool Input Schemas​

query​

Full RAG query with optional reranking.

InputTypeRequiredDescription
querystringYesThe search query
dbstringNoDatabase name (uses defaults)
collectionstringNoCollection name (uses defaults)
limitnumberNoMax results (default: 5)
filterobjectNoMongoDB pre-filter for vector search
rerankbooleanNoWhether to rerank results (default: true)
modelstringNoVoyage AI embedding model

Raw vector similarity search without reranking.

InputTypeRequiredDescription
querystringYesThe search query
dbstringNoDatabase name
collectionstringNoCollection name
limitnumberNoMax results (default: 10)
filterobjectNoMongoDB pre-filter
modelstringNoEmbedding model

rerank​

Rerank documents against a query.

InputTypeRequiredDescription
querystringYesThe query to rank against
documentsarrayYesDocuments to rerank
modelstringNoReranking model (default: rerank-2.5)

embed​

Generate an embedding vector.

InputTypeRequiredDescription
textstringYesText to embed
modelstringNoEmbedding model
inputType"document" | "query"NoWhether text is a document or query
dimensionsnumberNoOutput dimensions for Matryoshka models

similarity​

Compare two texts semantically.

InputTypeRequiredDescription
text1stringYesFirst text
text2stringYesSecond text
modelstringNoEmbedding model

ingest​

Chunk, embed, and store a document.

InputTypeRequiredDescription
textstringYesDocument text
sourcestringNoSource identifier for citations
dbstringNoDatabase name
collectionstringNoCollection name
chunkSizenumberNoTarget chunk size in characters (default: 512)
chunkStrategystringNoChunking strategy: fixed, sentence, paragraph, recursive, markdown
modelstringNoEmbedding model
metadataobjectNoAdditional metadata to store

estimate​

Estimate embedding costs.

InputTypeRequiredDescription
docsnumberYesNumber of documents to embed
queriesnumberNoQueries per month (default: 0)
monthsnumberNoTime horizon in months (default: 12)

merge​

Concatenate arrays from multiple steps.

InputTypeRequiredDescription
arraysarrayYesTemplate expressions resolving to arrays
dedupbooleanNoRemove duplicates (default: false)
dedup_fieldstringNoField to use for dedup comparison

filter​

Filter array items by condition.

InputTypeRequiredDescription
arraystringYesTemplate expression resolving to an array
conditionstringYesCondition using item as current element

generate​

Call the configured LLM.

InputTypeRequiredDescription
promptstringYesThe user prompt
contextanyNoContext data for the LLM
systemPromptstringNoSystem message

Validation​

Validate any workflow file against this schema:

vai workflow validate my-workflow.json

The validator checks:

  • JSON syntax
  • Schema conformance
  • Step ID uniqueness and naming conventions
  • Template expression validity
  • Circular dependency detection
  • Step reference resolution
  • Execution plan generation

Next Steps​