Skip to main content
POST
/
v1
/
workflows
/
spec
/
validate
from retab import Retab

client = Retab()

validation = client.workflows.spec.validate(yaml_definition)

print(validation.is_valid)
print(validation.diagnostics)
import { Retab } from "@retab/node";

const client = new Retab({ apiKey: process.env.RETAB_API_KEY });

const validation = await client.workflows.spec.validate(yamlDefinition);

console.log(validation.isValid);
console.log(validation.diagnostics);
package main

import (
	"context"
	"fmt"
	"log"

	retab "github.com/retab-dev/retab/clients/go"
)

func ptr[T any](v T) *T { return &v }

func main() {
	ctx := context.Background()

	client, err := retab.NewClient("")
	if err != nil {
		log.Fatal(err)
	}

	yamlDefinition := `apiVersion: workflows.retab.com/v1alpha2
kind: Workflow
metadata:
  id: wf_invoice_demo
  name: Invoice Workflow
spec:
  blocks:
    start:
      type: start_json
      label: Input JSON
      config:
        json_schema:
          type: object
          required:
            - value
          properties:
            value:
              type: string
  edges: []
`
	validation, err := client.Workflows.Spec.Validate(ctx, &retab.WorkflowSpecValidateParams{
		YamlDefinition: yamlDefinition,
	})
	if err != nil {
		log.Fatal(err)
	}

	fmt.Println(validation.IsValid)
	fmt.Println(validation.Diagnostics)
}
require 'retab'

client = Retab::Client.new(api_key: ENV['RETAB_API_KEY'])

validation = client.workflows.spec.validate(yaml_definition: yaml_definition)

puts validation.is_valid
puts validation.diagnostics
use retab::models::DeclarativeWorkflowRequest;
use retab::resources::workflow_spec::ValidateParams;
use retab::Retab;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Retab::new(std::env::var("RETAB_API_KEY")?);

    let yaml_definition = r#"apiVersion: workflows.retab.com/v1alpha2
kind: Workflow
metadata:
  id: wf_invoice_demo
  name: Invoice Workflow
spec:
  blocks:
    start:
      type: start_json
      label: Input JSON
      config:
        json_schema:
          type: object
          required:
            - value
          properties:
            value:
              type: string
  edges: []
"#;
    let validation = client
        .workflows().spec()
        .validate(ValidateParams::new(DeclarativeWorkflowRequest::new(
            yaml_definition,
        )))
        .await?;

    println!("{}", validation.is_valid);
    println!("{:?}", validation.diagnostics);
    Ok(())
}
<?php
require 'vendor/autoload.php';

use Retab\Client;

$client = new Client(apiKey: getenv('RETAB_API_KEY'));

$yamlDefinition = <<<'YAML'
apiVersion: workflows.retab.com/v1alpha2
kind: Workflow
metadata:
  id: wf_invoice_demo
  name: Invoice Workflow
spec:
  blocks:
    start:
      type: start_json
      label: Input JSON
      config:
        json_schema:
          type: object
          required:
            - value
          properties:
            value:
              type: string
  edges: []
YAML;

$result = $client->workflows()->spec()->validate(
    yamlDefinition: $yamlDefinition,
);
print_r($result);
using Retab;
using RetabClient = Retab.Retab;

var apiKey = Environment.GetEnvironmentVariable("RETAB_API_KEY")!;
var client = new RetabClient(apiKey);

var yamlDefinition = """
apiVersion: workflows.retab.com/v1alpha2
kind: Workflow
metadata:
  id: wf_invoice_demo
  name: Invoice Workflow
spec:
  blocks:
    start:
      type: start_json
      label: Input JSON
      config:
        json_schema:
          type: object
          required:
            - value
          properties:
            value:
              type: string
  edges: []
""";

var result = await client.Workflows.Spec.ValidateAsync(
    new WorkflowSpecValidateOptions { YamlDefinition = yamlDefinition }
);
Console.WriteLine(result);
import com.retab.RetabClient;

public final class Example {
  public static void main(String[] args) throws Exception {
    RetabClient client = new RetabClient(System.getenv("RETAB_API_KEY"));

    var result = client.workflows().spec().validate("metadata:\n  id: invoice-workflow\n", null);
    System.out.println(result);
  }
}
curl -X 'POST' \
  'https://api.retab.com/v1/workflows/spec/validate' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <your-api-key>' \
  -d '{
    "yaml_definition": "apiVersion: workflows.retab.com/v1alpha2\nkind: Workflow\nmetadata:\n  id: wf_abc123\n  name: Invoice Workflow\nspec:\n  blocks:\n    start_document-node:\n      type: start_document\n      label: Input Document\n    extract-node:\n      type: extract\n      label: Extract Fields\n      config:\n        inputs:\n          - name: source_doc\n            type: file\n            is_primary: true\n        json_schema:\n          type: object\n          properties: {}\n  edges:\n    - from:\n        block: start_document-node\n        handle: output-file-0\n      to:\n        block: extract-node\n        handle: input-file-source_doc\n"
  }'
{
  "workflow_id": "wf_abc123",
  "block_count": 2,
  "edge_count": 1,
  "is_valid": true,
  "diagnostics": {
    "issues": []
  }
}
Validate a declarative workflow YAML spec without changing workflow state. A declarative spec uses apiVersion: workflows.retab.com/v1alpha2. Edges must be explicit and handle-based:
spec:
  edges:
    - from:
        block: start_document-node
        handle: output-file-0
      to:
        block: extract-node
        handle: input-file-source_doc
Handles are raw runtime handles and are validated against the block type and block configuration.
from retab import Retab

client = Retab()

validation = client.workflows.spec.validate(yaml_definition)

print(validation.is_valid)
print(validation.diagnostics)
import { Retab } from "@retab/node";

const client = new Retab({ apiKey: process.env.RETAB_API_KEY });

const validation = await client.workflows.spec.validate(yamlDefinition);

console.log(validation.isValid);
console.log(validation.diagnostics);
package main

import (
	"context"
	"fmt"
	"log"

	retab "github.com/retab-dev/retab/clients/go"
)

func ptr[T any](v T) *T { return &v }

func main() {
	ctx := context.Background()

	client, err := retab.NewClient("")
	if err != nil {
		log.Fatal(err)
	}

	yamlDefinition := `apiVersion: workflows.retab.com/v1alpha2
kind: Workflow
metadata:
  id: wf_invoice_demo
  name: Invoice Workflow
spec:
  blocks:
    start:
      type: start_json
      label: Input JSON
      config:
        json_schema:
          type: object
          required:
            - value
          properties:
            value:
              type: string
  edges: []
`
	validation, err := client.Workflows.Spec.Validate(ctx, &retab.WorkflowSpecValidateParams{
		YamlDefinition: yamlDefinition,
	})
	if err != nil {
		log.Fatal(err)
	}

	fmt.Println(validation.IsValid)
	fmt.Println(validation.Diagnostics)
}
require 'retab'

client = Retab::Client.new(api_key: ENV['RETAB_API_KEY'])

validation = client.workflows.spec.validate(yaml_definition: yaml_definition)

puts validation.is_valid
puts validation.diagnostics
use retab::models::DeclarativeWorkflowRequest;
use retab::resources::workflow_spec::ValidateParams;
use retab::Retab;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Retab::new(std::env::var("RETAB_API_KEY")?);

    let yaml_definition = r#"apiVersion: workflows.retab.com/v1alpha2
kind: Workflow
metadata:
  id: wf_invoice_demo
  name: Invoice Workflow
spec:
  blocks:
    start:
      type: start_json
      label: Input JSON
      config:
        json_schema:
          type: object
          required:
            - value
          properties:
            value:
              type: string
  edges: []
"#;
    let validation = client
        .workflows().spec()
        .validate(ValidateParams::new(DeclarativeWorkflowRequest::new(
            yaml_definition,
        )))
        .await?;

    println!("{}", validation.is_valid);
    println!("{:?}", validation.diagnostics);
    Ok(())
}
<?php
require 'vendor/autoload.php';

use Retab\Client;

$client = new Client(apiKey: getenv('RETAB_API_KEY'));

$yamlDefinition = <<<'YAML'
apiVersion: workflows.retab.com/v1alpha2
kind: Workflow
metadata:
  id: wf_invoice_demo
  name: Invoice Workflow
spec:
  blocks:
    start:
      type: start_json
      label: Input JSON
      config:
        json_schema:
          type: object
          required:
            - value
          properties:
            value:
              type: string
  edges: []
YAML;

$result = $client->workflows()->spec()->validate(
    yamlDefinition: $yamlDefinition,
);
print_r($result);
using Retab;
using RetabClient = Retab.Retab;

var apiKey = Environment.GetEnvironmentVariable("RETAB_API_KEY")!;
var client = new RetabClient(apiKey);

var yamlDefinition = """
apiVersion: workflows.retab.com/v1alpha2
kind: Workflow
metadata:
  id: wf_invoice_demo
  name: Invoice Workflow
spec:
  blocks:
    start:
      type: start_json
      label: Input JSON
      config:
        json_schema:
          type: object
          required:
            - value
          properties:
            value:
              type: string
  edges: []
""";

var result = await client.Workflows.Spec.ValidateAsync(
    new WorkflowSpecValidateOptions { YamlDefinition = yamlDefinition }
);
Console.WriteLine(result);
import com.retab.RetabClient;

public final class Example {
  public static void main(String[] args) throws Exception {
    RetabClient client = new RetabClient(System.getenv("RETAB_API_KEY"));

    var result = client.workflows().spec().validate("metadata:\n  id: invoice-workflow\n", null);
    System.out.println(result);
  }
}
curl -X 'POST' \
  'https://api.retab.com/v1/workflows/spec/validate' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <your-api-key>' \
  -d '{
    "yaml_definition": "apiVersion: workflows.retab.com/v1alpha2\nkind: Workflow\nmetadata:\n  id: wf_abc123\n  name: Invoice Workflow\nspec:\n  blocks:\n    start_document-node:\n      type: start_document\n      label: Input Document\n    extract-node:\n      type: extract\n      label: Extract Fields\n      config:\n        inputs:\n          - name: source_doc\n            type: file\n            is_primary: true\n        json_schema:\n          type: object\n          properties: {}\n  edges:\n    - from:\n        block: start_document-node\n        handle: output-file-0\n      to:\n        block: extract-node\n        handle: input-file-source_doc\n"
  }'
{
  "workflow_id": "wf_abc123",
  "block_count": 2,
  "edge_count": 1,
  "is_valid": true,
  "diagnostics": {
    "issues": []
  }
}

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Body carrying a workflow's full YAML definition for validate, plan, apply, or export.

yaml_definition
string
required

Workflow YAML definition

project_id
string | null

Project that should own a workflow created from this spec. Required when applying a spec that creates a new workflow.

Response

Successful Response

Result of validating a workflow YAML definition: whether it is_valid, block/edge counts, and diagnostics.

workflow_id
string
required
block_count
integer
required
edge_count
integer
required
is_valid
boolean
required
diagnostics
Diagnostics · object
required