Document FlowDefinition fields in the JSON schema

[vinibrsl]

Adds a description and examples to every FlowDefinition field so the generated JSON schema documents itself.

[coderabbitai]

📝 Walkthrough

Walkthrough

Refactors all Pydantic model field declarations in flow_definition.py from bare attribute assignments to explicit Field(...)-based declarations with descriptions, examples, and defaults. Adds language: Literal["python"] to FlowScriptActionDefinition. Adds two tests asserting the resulting JSON schema carries the expected descriptions and examples.

Changes

FlowDefinition Pydantic Field metadata enrichment

Layer / File(s)	Summary
Import cleanup and discriminator field standardization lib/crewai/src/crewai/flow/flow_definition.py	Removes the Literal as TypingLiteral alias and updates FlowPydanticStateDefinition, FlowJsonSchemaStateDefinition, and FlowUnknownStateDefinition discriminator type fields to Field-backed Literal declarations with explicit defaults.
Diagnostic, config, persistence, and feedback model Field declarations lib/crewai/src/crewai/flow/flow_definition.py	Converts FlowDefinitionDiagnostic, FlowConfigDefinition, FlowPersistenceDefinition, and FlowHumanFeedbackDefinition from bare attribute assignments to Field(...) declarations with explicit defaults and schema metadata.
Action definition Field declarations and language discriminator lib/crewai/src/crewai/flow/flow_definition.py	Converts FlowCodeActionDefinition, FlowToolActionDefinition, FlowCrewActionDefinition, FlowExpressionActionDefinition, FlowScriptActionDefinition, FlowEachInnerActionDefinition, and FlowEachActionDefinition to Field(...)-based declarations; adds language: Literal["python"] to FlowScriptActionDefinition.
FlowMethodDefinition and FlowDefinition Field declarations lib/crewai/src/crewai/flow/flow_definition.py	Converts FlowMethodDefinition and FlowDefinition fields to Field(...) declarations with explicit defaults, schema metadata, and aliasing (schema_ → schema).
JSON schema validation tests lib/crewai/tests/test_flow_definition.py	Adds two tests verifying that FlowDefinition.json_schema() emits expected "description" text on method/script/state properties and that "examples" appear only on targeted fields with correct concrete values.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~15 minutes

Suggested reviewers

• greysonlalonde
• joaomdmoura

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title directly and accurately describes the main change: adding field documentation to the FlowDefinition JSON schema via explicit Field() descriptors.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch flow-definition-field-docs

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@lib/crewai/tests/test_flow_definition.py`:
- Around line 82-83: In the test_flow_definition.py file, replace the hardcoded
anyOf index selection at line 82 with logic that finds the correct schema branch
by checking for the presence of the "discriminator" key instead of relying on
anyOf[0]. Iterate through the anyOf list and select the branch that contains the
"discriminator" property so the test validates behavior independently of
Pydantic's branch ordering.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 1f6f3787-067b-4b67-8666-14c3f9da45cd

📥 Commits

Reviewing files that changed from the base of the PR and between 5bd10ee and fbf5570.

📒 Files selected for processing (2)

• lib/crewai/src/crewai/flow/flow_definition.py
• lib/crewai/tests/test_flow_definition.py