Validation 🔍

Add type safety to your workflows with input and output validation.

Quick Examples

Here's how you can add validation to your workflows using the TypeScript SDK with Zod:

import { z } from 'zod'

// Using Zod
const zodSchema = z.object({
  id: z.string(),
  email: z.string().email()
})

workflow
  .addHttpNode('get_user')
  .withValidation({ output: zodSchema })

Why Validate? 🤔

Validation is completely optional in Graph Compose, but it can help you:

• 🐛 Catch errors early before they cascade through your workflow
• 🔍 Debug issues faster by knowing exactly where data isn't matching expectations
• 📝 Document the shape of data flowing through your nodes
• ✨ Get TypeScript autocompletion for your workflow data

Using Validation 🚀

Our TypeScript SDK uses Zod schemas for validation, providing strong typing and excellent developer experience. The SDK automatically converts these Zod schemas into standard JSON Schema when defining the workflow for our REST API.

import { z } from 'zod'
import { GraphCompose } from '@graphcompose/sdk'

// Define your schema with Zod
const UserSchema = z.object({
  id: z.string(),
  email: z.string().email(),
  age: z.number().min(0)
})

const workflow = new GraphCompose()
  .addHttpNode('get_user')
  .get('https://api.example.com/users/{{context.userId}}')
  .withValidation({
    // Validates the response data returned by this node
    output: UserSchema  // Zod automatically converts to JSON Schema
  });

What Can You Validate? 🎯

Input Validation

Ensure dependencies provide the data your node needs:

import { z } from 'zod'
import { GraphCompose } from '@graphcompose/sdk'

const InputSchema = z.object({
  get_user: z.object({
    result: z.object({
      id: z.string(),
      permissions: z.array(z.string())
    })
  })
})

const workflow = new GraphCompose()
  .addHttpNode('check_access')
  .post('https://api.example.com/check-access')
  .withValidation({
    // Validates the data from dependencies before this node runs
    input: InputSchema  // Validate dependency data
  });

Output Validation

Ensure your node produces the expected data:

import { z } from 'zod'
import { GraphCompose } from '@graphcompose/sdk'

const OutputSchema = z.object({
  status: z.enum(['success', 'error']),
  data: z.object({
    processed: z.number(),
    errors: z.array(z.string()).optional()
  })
})

const workflow = new GraphCompose()
  .addHttpNode('process_data')
  .post('https://api.example.com/process')
  .withValidation({
    // Validates the response data returned by this node
    output: OutputSchema  // Validate the response
  });

Best Practices 💡

1. Choose Your Approach

   • Use Zod for TypeScript projects to get type inference and a more intuitive API
   • Use JSON Schema when you have existing schemas or need to share them
   • Mix and match approaches as needed - both work equally well

2. Leverage Zod in the SDK

   • Use Zod schemas with the .withValidation() method in the TypeScript SDK for the best developer experience and type safety.
   • The SDK handles the conversion to the JSON Schema format required by the REST API.

3. Start Small

   • Begin with just the critical fields
   • Add more validation as you need it
   • Use our visual tools to test schemas

4. Handle Failures Gracefully

   • Add error boundaries for validation failures
   • Provide clear error messages
   • Consider fallback values

5. Keep it Maintainable

   • Share schemas between related nodes
   • Version schemas with your API
   • Document your validation rules