# 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

--- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.ixhello.com/ixhc2/technical-specifications/yflow-a-yaml-based-conversational-flow-language/file-structure-and-core-syntax.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.