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):

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

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):

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.

Field

Required

Description

name

Yes

Flow display name

version

Yes

SemVer version ("MAJOR.MINOR.PATCH")

persona

No

Voice, language, LLM settings

Last updated

Was this helpful?