Update API specifications with fern api update #4075
Conversation
WalkthroughThe OpenAPI schema is updated to support conditional block structures for workflow branching, introducing BranchCondition, BranchCriteria, and ConditionalBlock schemas. Additionally, a LocateElementAction is added for element location capabilities, versioning is introduced to workflow definitions, and descriptive metadata is expanded across multiple block schemas. Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Areas requiring extra attention:
Possibly related PRs
Suggested labels
Suggested reviewers
Poem
Pre-merge checks and finishing touches❌ Failed checks (1 inconclusive)
✅ Passed checks (2 passed)
✨ Finishing touches🧪 Generate unit tests (beta)
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. Comment |
![ellipsis-dev[bot]](https://avatars.githubusercontent.com/in/64358?s=60&v=4){kind=small}
There was a problem hiding this comment.
Important
Looks good to me! 👍
Reviewed everything up to 3071f5d in 2 minutes and 25 seconds. Click for details.
- Reviewed
1199lines of code in1files - Skipped
0files when reviewing. - Skipped posting
6draft comments. View those below. - Modify your settings and rules to customize what types of comments Ellipsis leaves. And don't forget to react with 👍 or 👎 to teach Ellipsis.
1. fern/openapi/skyvern_openapi.json:3800
- Draft comment:
Consider using OpenAPI’s 'nullable: true' (if supported) instead of the anyOf with null for next_block_label. - Reason this comment was not posted:
Decided after close inspection that this draft comment was likely wrong and/or not actionable: usefulness confidence = 20% vs. threshold = 50% This comment is about code style/structure rather than correctness. BothanyOfwith null andnullable: trueare valid OpenAPI patterns for representing optional nullable fields. The comment says "Consider using" which is a soft suggestion, not pointing out a bug or issue. The diff shows this pattern is used consistently throughout the entire file fornext_block_labelacross all block types. Changing this would require a large refactor with no functional benefit. The comment also hedges with "if supported" which suggests uncertainty. This appears to be a stylistic preference rather than a necessary change. According to the rules, I should not keep comments that are purely about code quality unless they are actionable and clear - this is more of a "nice to have" suggestion about an alternative approach. The comment could be valid ifnullable: trueis indeed the preferred or more standard approach in OpenAPI specs. It's possible that the current pattern is more verbose than necessary, and the suggestion could improve readability and maintainability. The consistency argument cuts both ways - if it's wrong, it's consistently wrong throughout. While both approaches are technically valid, this is a stylistic preference without clear evidence that one is superior to the other. The comment uses "Consider" language and includes "if supported" which shows uncertainty. This is not pointing out a bug or clear issue. The rules state not to make comments that are purely stylistic unless they are clearly actionable - this falls into the category of a suggestion rather than a required change. Additionally, this would require changing the pattern across the entire file, which is a large refactor for minimal benefit. This comment should be deleted. It's a stylistic suggestion about an alternative OpenAPI pattern rather than identifying a bug or clear issue. Both approaches are valid, and the comment doesn't provide strong evidence that a change is necessary.
2. fern/openapi/skyvern_openapi.json:4090
- Draft comment:
The description references [[s-4bnl]]. Ensure this placeholder is documented or updated for clarity. - Reason this comment was not posted:
Confidence changes required:50%<= threshold50%None
3. fern/openapi/skyvern_openapi.json:9578
- Draft comment:
LocateElementAction has been reintroduced later in the file. Verify that downstream references and client generators are updated accordingly. - Reason this comment was not posted:
Comment did not seem useful. Confidence is useful =0%<= threshold50%This comment is asking the PR author to verify downstream references and client generators, which is against the rules. It doesn't provide a specific suggestion or point out a specific issue with the code.
4. fern/openapi/skyvern_openapi.json:15536
- Draft comment:
A new 'version' field was added in WorkflowDefinition. Consider adding a description to clarify its purpose and lifecycle. - Reason this comment was not posted:
Confidence changes required:50%<= threshold50%None
5. fern/openapi/skyvern_openapi.json:5793
- Draft comment:
For ConditionalBlock, consider specifying a minimum number of items for 'branches' if at least one branch is always required. - Reason this comment was not posted:
Decided after close inspection that this draft comment was likely wrong and/or not actionable: usefulness confidence = 20% vs. threshold = 50% This comment is suggesting a schema improvement for the newly addedConditionalBlock. However, this falls into a gray area: 1) It's about new code being added (the ConditionalBlock is new), 2) It's phrased as "consider" which makes it sound optional/speculative rather than pointing out a definite issue, 3) It's a code quality suggestion about validation constraints, 4) Without seeing the actual implementation or requirements, I can't determine if branches should always have at least one item or if zero branches is valid. The comment uses "consider" and "if at least one branch is always required" which shows uncertainty - this is speculative. The comment could be valid if having zero branches in a ConditionalBlock is logically invalid - a conditional block without branches wouldn't make sense. This might be catching a real schema design issue rather than being purely speculative. While the logic makes sense, the comment is phrased speculatively ("consider", "if...required") rather than definitively stating there's a problem. According to the rules, speculative comments should be removed. The comment doesn't provide strong evidence that this is definitely wrong - it's a suggestion for improvement. If this were a critical issue, it would be caught at runtime or in validation. This comment should be deleted. It's phrased as a speculative suggestion ("consider...if") rather than identifying a definite issue. It's asking the author to consider adding validation constraints without clear evidence that the current implementation is wrong.
6. fern/openapi/skyvern_openapi.json:7119
- Draft comment:
Consider standardizing the 'next_block_label' description across schemas for consistency. - Reason this comment was not posted:
Confidence changes required:33%<= threshold50%None
Workflow ID: wflow_YWLj63MiXtoyHHzp
You can customize 
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (5)
fern/openapi/skyvern_openapi.json (5)
486-488: Curl examples send YAML as text/plain to JSON-only endpoints.Spec declares application/json for POST /v1/workflows and POST /v1/workflows/{workflow_id}, but curl samples use Content-Type: text/plain with raw YAML bodies. This will not validate against the OpenAPI contract and misleads users.
Suggested fix (either option):
- Update examples to send application/json with a WorkflowRequest wrapper (e.g., {"yaml_definition": ""} or {"json_definition": {...}}), or
- Extend requestBody content to also accept text/plain (string) and document raw-YAML payload semantics.
Also applies to: 764-766
490-496: JSON examples include unsupported fieldparameter_keys.In multiple Python/TS examples, blocks under json_definition include parameter_keys, which is not present in JSON block schemas (use parameters array instead). These samples won’t validate.
Action: Replace parameter_keys with parameters (or drop it) in JSON examples; keep parameter_keys only in corresponding YAML block examples.
Also applies to: 768-774, 215-221
15537-15708: YAML parity missing for ConditionalBlock.BlockType includes "conditional" and JSON WorkflowDefinition/ForLoopBlock support ConditionalBlock, but WorkflowDefinitionYAML and ForLoopBlockYAML do not include ConditionalBlockYAML in their unions/discriminators. No ConditionalBlockYAML schema is defined.
Action: Add ConditionalBlockYAML schema and include "conditional" in WorkflowDefinitionYAML.blocks and ForLoopBlockYAML.loop_blocks discriminator mappings to maintain JSON/YAML feature parity.
Also applies to: 15710-15872, 8521-8586
15069-15121: WaitBlockYAML doesn’t require wait_sec (JSON does).JSON WaitBlock requires wait_sec; YAML variant lists wait_sec with a default but not required. This mismatch can produce YAML that the server rejects after conversion.
Suggested change: add wait_sec to WaitBlockYAML.required and align defaults.
2816-2819: Python example syntax error (extra comma/parenthesis).The login Python sample has a trailing comma and unmatched parenthesis, causing a SyntaxError on copy/paste.
Fix: remove the stray comma and extra “)”.
🧹 Nitpick comments (2)
fern/openapi/skyvern_openapi.json (2)
6056-6069: ProxyLocation options: enum vs description mismatch.Description lists fewer geo options than the enum (e.g., enum includes RESIDENTIAL_BR/TR/CA/MX/IT/NL, description omits these).
Sync prose lists with enum or link to a single authoritative list to avoid drift.
Also applies to: 11320-11349
9579-9597: Action type naming inconsistency.New LocateElementAction uses type "locate_element" while other AI-driven actions use "ai_*" prefixes (ai_click, ai_input_text, etc.). Minor style inconsistency that can confuse SDK users.
Consider renaming to ai_locate_element or document why it differs.
Also applies to: 11424-11440
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
fern/openapi/skyvern_openapi.json(51 hunks)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)
- GitHub Check: Run tests and pre-commit hooks
🔇 Additional comments (2)
fern/openapi/skyvern_openapi.json (2)
3800-3814: Author-facing label/next_block_label docs: good addition.The added titles/descriptions for label and next_block_label improve author UX and clarify DAG semantics.
Also applies to: 5610-5623, 6451-6464, 6650-6663, 7065-7078, 7660-7672, 7825-7838, 8638-8651, 8920-8934, 9603-9616, 10339-10352, 11156-11169, 12190-12203, 13251-13264, 13459-13472, 14026-14040, 14156-14169, 14522-14535, 14921-14934
11362-11451: RunSdkAction union updated cleanly with LocateElementAction.Discriminator mapping and required fields look consistent; response remains generic, which is acceptable.
If specific result shapes are expected for locate_element (e.g., selector/xpath), consider documenting possible result structure in RunSdkActionResponse.
| "type": "string", | ||
| "title": "Label" | ||
| "title": "Label", | ||
| "description": "Author-facing identifier; must be unique per workflow." | ||
| }, | ||
| "next_block_label": { | ||
| "anyOf": [ | ||
| { | ||
| "type": "string" | ||
| }, | ||
| { | ||
| "type": "null" | ||
| } | ||
| ], | ||
| "title": "Next Block Label", | ||
| "description": "Optional pointer to the label of the next block. When omitted, it will default to sequential order. See [[s-4bnl]]." | ||
| }, |
There was a problem hiding this comment.
Leaked placeholder reference in descriptions ("See [[s-4bnl]]").
Several YAML block schemas’ next_block_label descriptions reference an internal anchor [[s-4bnl]], which is broken in public docs.
Action: Remove or replace with a valid public reference.
Also applies to: 5736-5750, 6519-6533, 6942-6956, 7363-7377, 7743-7757, 7980-7994, 8812-8825, 9264-9277, 9902-9915, 10631-10645, 11237-11251, 12490-12503, 13362-13376, 13609-13622, 14102-14115, 14449-14462, 14821-14834, 15079-15092
🤖 Prompt for AI Agents
fern/openapi/skyvern_openapi.json lines 4098-4113: the description for
next_block_label contains a leaked internal anchor reference "See [[s-4bnl]]"
which should not appear in public docs; remove that fragment or replace it with
a valid public reference (or a short explanatory sentence such as "Defaults to
sequential order."), and apply the same change to the other occurrences at
ranges 5736-5750, 6519-6533, 6942-6956, 7363-7377, 7743-7757, 7980-7994,
8812-8825, 9264-9277, 9902-9915, 10631-10645, 11237-11251, 12490-12503,
13362-13376, 13609-13622, 14102-14115, 14449-14462, 14821-14834, and 15079-15092
so all descriptions no longer reference the internal anchor.
| "ConditionalBlock": { | ||
| "properties": { | ||
| "label": { | ||
| "type": "string", | ||
| "title": "Label", | ||
| "description": "Author-facing identifier for a block; unique within a workflow." | ||
| }, | ||
| "next_block_label": { | ||
| "anyOf": [ | ||
| { | ||
| "type": "string" | ||
| }, | ||
| { | ||
| "type": "null" | ||
| } | ||
| ], | ||
| "title": "Next Block Label", | ||
| "description": "Optional pointer to the next block label when constructing a DAG. Defaults to sequential order when omitted." | ||
| }, | ||
| "block_type": { | ||
| "type": "string", | ||
| "const": "conditional", | ||
| "title": "Block Type", | ||
| "default": "conditional" | ||
| }, | ||
| "output_parameter": { | ||
| "$ref": "#/components/schemas/OutputParameter" | ||
| }, | ||
| "continue_on_failure": { | ||
| "type": "boolean", | ||
| "title": "Continue On Failure", | ||
| "default": false | ||
| }, | ||
| "model": { | ||
| "anyOf": [ | ||
| { | ||
| "additionalProperties": true, | ||
| "type": "object" | ||
| }, | ||
| { | ||
| "type": "null" | ||
| } | ||
| ], | ||
| "title": "Model" | ||
| }, | ||
| "disable_cache": { | ||
| "type": "boolean", | ||
| "title": "Disable Cache", | ||
| "default": false | ||
| }, | ||
| "branches": { | ||
| "items": { | ||
| "$ref": "#/components/schemas/BranchCondition" | ||
| }, | ||
| "type": "array", | ||
| "title": "Branches" | ||
| } | ||
| }, | ||
| "type": "object", | ||
| "required": [ | ||
| "label", | ||
| "output_parameter" | ||
| ], | ||
| "title": "ConditionalBlock", | ||
| "description": "Branching block that selects the next block label based on ordered conditions." | ||
| }, |
There was a problem hiding this comment.
🧩 Analysis chain
Conditional branching constraints under-specified; likely validation gaps.
- BranchCondition.next_block_label is optional; selecting a branch without a target should be invalid.
- ConditionalBlock.branches has no minItems or requirement for a default branch; evaluation order semantics aren’t enforced.
- BranchCriteria is an abstract shell with only criteria_type and no discriminator/variants, making client validation and tooling weak.
Recommendations (schema-level):
- Require next_block_label in BranchCondition.
- Add "minItems": 1 to ConditionalBlock.branches; consider requiring exactly one is_default=true (can be checked server-side if not feasible in JSON Schema).
- Define concrete BranchCriteria variants with oneOf + discriminator so SDKs and validators can enforce structure.
Also applies to: 5184-5235, 5236-5260
I'll verify the schema constraints in the OpenAPI file by examining the actual definitions.
🏁 Script executed:
#!/bin/bash
# Search for BranchCondition, BranchCriteria, and ConditionalBlock definitions
rg -n "\"(BranchCondition|BranchCriteria|ConditionalBlock)\"" fern/openapi/skyvern_openapi.json | head -20Length of output: 218
🏁 Script executed:
#!/bin/bash
# Extract and display BranchCondition schema
jq '.components.schemas.BranchCondition' fern/openapi/skyvern_openapi.json 2>/dev/null | head -50Length of output: 834
🏁 Script executed:
#!/bin/bash
# Extract and display BranchCriteria schema
jq '.components.schemas.BranchCriteria' fern/openapi/skyvern_openapi.json 2>/dev/nullLength of output: 469
🏁 Script executed:
#!/bin/bash
# Extract ConditionalBlock.branches property to check for minItems
jq '.components.schemas.ConditionalBlock.properties.branches' fern/openapi/skyvern_openapi.json 2>/dev/nullLength of output: 113
🏁 Script executed:
#!/bin/bash
# Check for YAML variants (e.g., ConditionalBlockYAML, BranchConditionYAML)
rg -n "\"(ConditionalBlockYAML|BranchConditionYAML)\"" fern/openapi/skyvern_openapi.jsonLength of output: 0
🏁 Script executed:
#!/bin/bash
# Count total required fields in ConditionalBlock
jq '.components.schemas.ConditionalBlock.required' fern/openapi/skyvern_openapi.json 2>/dev/nullLength of output: 35
🏁 Script executed:
#!/bin/bash
# Check BranchCondition required fields
jq '.components.schemas.BranchCondition.required' fern/openapi/skyvern_openapi.json 2>/dev/nullLength of output: 13
🏁 Script executed:
#!/bin/bash
# Search for next_block_label in BranchCondition properties
jq '.components.schemas.BranchCondition.properties.next_block_label' fern/openapi/skyvern_openapi.json 2>/dev/nullLength of output: 120
🏁 Script executed:
#!/bin/bash
# Look for discriminator in BranchCriteria
jq '.components.schemas.BranchCriteria | keys' fern/openapi/skyvern_openapi.json 2>/dev/nullLength of output: 70
🏁 Script executed:
#!/bin/bash
# List all properties in BranchCriteria
jq '.components.schemas.BranchCriteria' fern/openapi/skyvern_openapi.json 2>/dev/nullLength of output: 469
🏁 Script executed:
#!/bin/bash
# Extract line numbers and context for the mentioned line ranges
sed -n '5794,5859p' fern/openapi/skyvern_openapi.json | head -30Length of output: 976
🏁 Script executed:
#!/bin/bash
# Check lines 5184-5235 for schema definitions
sed -n '5184,5235p' fern/openapi/skyvern_openapi.json | grep -E '(BranchCondition|BranchCriteria|required|minItems|discriminator)' | head -20Length of output: 146
🏁 Script executed:
#!/bin/bash
# Check lines 5236-5260 for schema definitions
sed -n '5236,5260p' fern/openapi/skyvern_openapi.json | grep -E '(BranchCondition|BranchCriteria|required|minItems|discriminator)' | head -20Length of output: 82
🏁 Script executed:
#!/bin/bash
# Full BranchCondition schema inspection
jq '.components.schemas.BranchCondition' fern/openapi/skyvern_openapi.json 2>/dev/null | jq -r 'tostring'Length of output: 550
🏁 Script executed:
#!/bin/bash
# Full ConditionalBlock schema inspection
jq '.components.schemas.ConditionalBlock' fern/openapi/skyvern_openapi.json 2>/dev/null | jq -r 'tostring' | head -80Length of output: 1061
🏁 Script executed:
#!/bin/bash
# List all schema names containing "Branch" or "Conditional"
jq '.components.schemas | keys[] | select(contains("Branch") or contains("Conditional"))' fern/openapi/skyvern_openapi.json 2>/dev/nullLength of output: 53
🏁 Script executed:
#!/bin/bash
# Check for any schema using oneOf with BranchCriteria
jq '.components.schemas | to_entries[] | select(.value.oneOf != null and (.value.oneOf | tostring | contains("BranchCriteria"))) | .key' fern/openapi/skyvern_openapi.json 2>/dev/nullLength of output: 0
🏁 Script executed:
#!/bin/bash
# Search for discriminator in any schema
rg -n "discriminator" fern/openapi/skyvern_openapi.json | head -10Length of output: 384
🏁 Script executed:
#!/bin/bash
# Check specific lines to understand ConditionalBlock.branches definition
sed -n '5810,5830p' fern/openapi/skyvern_openapi.jsonLength of output: 730
🏁 Script executed:
#!/bin/bash
# Extract references to BranchCondition throughout the file
rg -n "\$ref.*BranchCondition" fern/openapi/skyvern_openapi.jsonLength of output: 0
🏁 Script executed:
#!/bin/bash
# Check BranchCondition full definition with line numbers
rg -n -A 30 "\"BranchCondition\": {" fern/openapi/skyvern_openapi.json | head -50Length of output: 103
🏁 Script executed:
#!/bin/bash
# Check BranchCriteria full definition with line numbers
rg -n -A 30 "\"BranchCriteria\": {" fern/openapi/skyvern_openapi.json | head -50Length of output: 101
🏁 Script executed:
#!/bin/bash
# Validate JSON syntax and structure
python3 << 'EOF'
import json
try:
with open('fern/openapi/skyvern_openapi.json', 'r') as f:
data = json.load(f)
# Check BranchCondition
if 'BranchCondition' in data.get('components', {}).get('schemas', {}):
bc = data['components']['schemas']['BranchCondition']
print("=== BranchCondition ===")
print(f"Required fields: {bc.get('required', [])}")
print(f"Properties: {list(bc.get('properties', {}).keys())}")
print(f"next_block_label in required: {'next_block_label' in bc.get('required', [])}")
# Check ConditionalBlock.branches
if 'ConditionalBlock' in data.get('components', {}).get('schemas', {}):
cb = data['components']['schemas']['ConditionalBlock']
branches = cb.get('properties', {}).get('branches', {})
print("\n=== ConditionalBlock.branches ===")
print(f"minItems: {branches.get('minItems', 'NOT SET')}")
print(f"type: {branches.get('type')}")
print(f"Full definition: {json.dumps(branches, indent=2)}")
# Check BranchCriteria
if 'BranchCriteria' in data.get('components', {}).get('schemas', {}):
brc = data['components']['schemas']['BranchCriteria']
print("\n=== BranchCriteria ===")
print(f"Properties: {list(brc.get('properties', {}).keys())}")
print(f"Has oneOf: {'oneOf' in brc}")
print(f"Has discriminator: {'discriminator' in brc}")
print(f"Type: {brc.get('type')}")
print(f"Full definition: {json.dumps(brc, indent=2)}")
except Exception as e:
print(f"Error: {e}")
EOFLength of output: 976
Conditional branching constraints are under-specified; validation gaps confirmed.
Verification of the schema confirms all three core issues:
- BranchCondition.next_block_label is optional — not listed in required fields; a branch may exist without a target.
- ConditionalBlock.branches has no minItems — array can be empty; no schema enforcement of default routing.
- BranchCriteria lacks discriminator and variants — defined as an abstract interface with only criteria_type, but no oneOf or discriminator to enforce concrete implementations. Other schemas in the file successfully use discriminators (e.g., at lines 286, 4001, 5696).
Recommended fixes:
- Require
next_block_labelin BranchCondition, or enforce runtime validation if optional design is intentional. - Add
"minItems": 1to ConditionalBlock.branches. - Replace BranchCriteria with oneOf + discriminator pattern to define concrete criteria variants.
Update API specifications by running fern api update.
🔄 This PR updates API specifications by running the
fern api updatecommand to synchronize the project's API definitions with the latest schema changes. The update ensures that the API documentation and generated code remain consistent with current specifications.🔍 Detailed Analysis
Key Changes
Technical Implementation
flowchart TD A[Fern API Update Command] --> B[Schema Validation] B --> C[Specification Files Updated] C --> D[Generated Code Refresh] D --> E[Documentation Sync] E --> F[API Consistency Maintained]Impact
Created with Palmier
Important
Update
skyvern_openapi.jsonto enhance API with conditional logic and improved property documentation.next_block_labelproperty to multiple block definitions inskyvern_openapi.jsonfor DAG construction.labelproperties to specify uniqueness within workflows.ConditionalBlock,BranchCondition, andBranchCriteriacomponents for conditional logic.versionproperty toWorkflowDefinitionandWorkflowDefinitionYAMLwith default value 1.This description was created by
for 3071f5d. You can customize this summary. It will automatically update as commits are pushed.
Summary by CodeRabbit
✏️ Tip: You can customize this high-level summary in your review settings.