File Structure and Core Syntax

YFlow uses a clear, opinionated file structure designed to support readability, safety, version control, and collaboration. The structure reinforces YFlow’s declarative nature while making flows easy to author, review, validate, and deploy.

YFlow files describe flows as data, not as executable programs.

YFlow uses a single .yflow extension. A flow file can contain everything in one place:

    yflow: '1.0'    
         
    flow:    
      name: My Application    
      persona:    
        language: en-US    
        voice: Jessica    
        llmModel: gpt-4o    
         
    nodes:    
      - start:    
          next: greeting    
         
      - greeting:    
          type: say    
          message: Welcome to our service!    
          next: main_agent    
         
      - main_agent:    
          type: agent    
          system: Help the user with their request.    
          goals:    
            done:    
              next: farewell    
          fallback:    
            next: farewell    
      # ... more nodes    
          integrations:    
      banking_api: # ID - snake_case, immutable    
        type: rest    
        base_url: https://api.bank.com    
        # ...    

Top-Level Keys

Key	Required	Description
yflow:	No	YFlow spec version (default: "1.0")
flow:	Yes	Flow metadata (name, persona, version)
nodes:	Yes	Main flow nodes (ordered array)
components:	No	Component definitions — see YFLOW_SPEC_COMPONENTS.md
integrations:	No	API/MCP integration definitions

Flow Versioning

Flow Versioning in YFlow provides a safe, explicit way to evolve conversational flows over time without breaking running conversations, integrations, or consumers. Versioning is a lifecycle and governance mechanism, not a control‑flow feature.

Every flow document must have a version number using Semantic Versioning (SemVer):

    MAJOR.MINOR.PATCH    

Level	When to Increment	Example
MAJOR	Breaking changes (removed nodes, changed contracts, incompatible routing)	1.0.0 → 2.0.0
MINOR	New features, backward-compatible (new nodes, new goals, new integrations)	1.0.0 → 1.1.0
PATCH	Bug fixes, non-functional changes (typos, prompt tweaks, refactoring)	1.0.0 → 1.0.1

yflow: '1.0' # YFlow spec version (format)    
         
    flow:    
      name: Banking Assistant    
      version: '2.1.0' # Flow document version (SemVer)    
      persona:    
        language: en-US    
        voice: Jessica    

Version Field Rules:

• Required: Every flow must have a version under flow:

• Format: String in "MAJOR.MINOR.PATCH" format (quotes required)

• Initial: New flows start at "1.0.0"

• Immutable per release: Once deployed, a version is immutable

When to Bump:

Change Type	Version Bump	Example
Fix typo in prompt	PATCH	1.0.0 → 1.0.1
Adjust iteration_limit	PATCH	1.0.1 → 1.0.2
Add new goal to agent	MINOR	1.0.2 → 1.1.0
Add new API integration	MINOR	1.1.0 → 1.2.0
Add new component	MINOR	1.2.0 → 1.3.0
Remove a goal	MAJOR	1.3.0 → 2.0.0
Change component contract	MAJOR	2.0.0 → 3.0.0
Rename node (breaking refs)	MAJOR	3.0.0 → 4.0.0

Version vs YFlow Spec:

Field	Purpose	Example
yflow:	YFlow language/spec version	"1.0" (rarely changes)
flow: version:	This flow document's version	"2.1.0" (changes with edits)

Pre-release and Build Metadata (optional):

    flow:    
      version: "2.0.0-beta.1"        # Pre-release    
      version: "2.0.0+build.123"     # Build metadata    
      version: "2.0.0-rc.1+build.456" # Both    

Core Syntax

The Core Syntax of YFlow defines the minimal, canonical building blocks used to describe conversational flows. It is intentionally small, explicit, and restrictive to ensure that flows remain readable, secure, and statically analyzable.

YFlow syntax is descriptive, not executable.

Flow Definition

A Flow Definition is the complete, declarative specification of a YFlow conversational flow. It defines what the flow is, what data it expects, and how conversation states connect, without containing executable code or runtime logic.

A flow definition is a static artifact that can be validated, versioned, deployed, and executed safely.

# YFlow spec version (optional, defaults to 1.0)    
    yflow: '1.0'    
         
    flow:    
      name: Customer Service Bot    
         
      # REQUIRED: Flow document version (SemVer)    
      version: '1.0.0'    
         
      # Persona settings (voice, language, LLM model)    
      persona:    
        language: en-US    
        voice: Jessica    
        llmModel: gpt-4o # Optional: override default LLM    
         
    # The flow graph (ordered array)    
    nodes:    
      - start:    
          next: main_menu    
      # ... more nodes    

Field	Required	Description
name	Yes	Flow display name
version	Yes	SemVer version ("MAJOR.MINOR.PATCH")
persona	No	Voice, language, LLM settings