Graph Compose

Graph Validation 🛡️

Graph Compose helps ensure your workflows are valid before execution. Validation occurs both client-side via the SDK and server-side via the API.

Double Validation for Extra Safety: While the SDK provides immediate feedback during development, our API also performs comprehensive validation prior to every execution and returns detailed error messages if any issues are found.

Client SDK Validation

The @graph-compose/client package includes a builder pattern with built-in validation checks. You can explicitly trigger this validation using the .validate() method on your workflow definition:

import { GraphCompose } from '@graphcompose/sdk';

const workflow = new GraphCompose()
  .node("get_user")
    .get("https://your-api.com/api/users/123") // Ensure valid URL
  .end()
  .node("process_data")
    .post("https://your-api.com/api/process")
    .withBody({ result: "{{results.get_user.body.data}}" }) // Validates JSONata
    .withDependencies(["get_user"]) // Checks dependencies
  .end();

// Validate workflow before execution
const validation = workflow.validate(); // Returns { isValid: boolean, errors: Error[] }

if (!validation.isValid) {
  console.error("Workflow validation failed:", validation.errors);
  // Validation errors can include:
  // - Invalid node IDs (format, uniqueness)
  // - Circular dependencies (cycles in the graph)
  // - Missing node dependencies
  // - Invalid URLs or HTTP configurations (e.g., body on GET)
  // - Incorrect JSONata syntax in template expressions
  // - Missing or invalid Agent node configurations
} else {
  console.log("Workflow is valid!");
  // Proceed to execute...
  // const result = await workflow.execute({ userId: "123" });
}

This client-side validation provides quick feedback during development, helping you catch structural and configuration errors early.

For more details on using the SDK, including advanced configurations and error handling, please see our Client Libraries documentation.

REST API Validation

You can also validate a workflow definition directly against our API endpoint. This is useful if you are constructing workflow JSON manually or using a different client.

Endpoint: POST /api/v1/workflows/validate

Headers:

  • Authorization: Bearer YOUR_API_KEY
  • Content-Type: application/json

Request Body:

Request Body Example

{
  "workflow": {
    "nodes": [
      {
        "id": "get_data",
        "type": "http",
        "http": {
          "method": "GET",
          "url": "https://example.com/data"
        }
      },
      {
        "id": "process_data",
        "type": "http",
        "dependencies": ["get_data"],
        "http": {
          "method": "POST",
          "url": "https://example.com/process",
          "body": {
            "input": "{{ results.get_data.someField }}"
          }
        }
      }
    ],
    "tools": [],
    "context": {},
    "webhookUrl": null
    // ... other optional WorkflowGraph properties
  },
  "organizationId": "your-organization-uuid"
}

Response:

The API returns a standard ApiResponse wrapper. The data field within this wrapper contains the validation result:

{
  "success": true,
  "message": "Workflow validation successful",
  "data": {
    "isValid": true,
    "errors": []
  }
}
View Detailed API Schema
Previous: Node TypesNext: Executing Workflows