Data Validation & Schema Usage

IdentityFlow embraces the Standard Schema specification, a common interface for TypeScript validation libraries. This approach allows you to use your preferred validation tools, like Valibot, Zod, and ArkType (all of which are Standard Schema compliant), ensuring flexibility and interoperability. Learn more at standardschema.dev.

Schema Validation

Use Standard Schema to validate workflow inputs and outputs with your preferred validation library.

Type Safety

Get full TypeScript type inference from your validation schemas. See Type-Safe Development.

Multiple Libraries

Choose from popular validation libraries like Valibot, Zod, and more.

Example Usage

Lightweight validation library with excellent TypeScript support (v1.0+).

import * as v from '@identity-flow/sdk/valibot';
import { defineWorkflow } from '@identity-flow/sdk';

const UserSchema = v.object({
  id: v.string([v.uuid()]),
  email: v.string([v.email()]),
  role: v.union([v.literal('admin'), v.literal('user')]),
});

export default defineWorkflow(
  'user-onboarding',
  {
    schema: UserSchema, // Validate workflow input
  },
  async (flow) => {
    const user = flow.params; // Typed as User
    await flow.do('create user', async () => {
      await createUser(user);
    });
  },
);

Popular schema validation with strong type inference (3.24.0+).

npm i zod

pnpm add zod

yarn add zod

import { defineWorkflow } from '@identity-flow/sdk';
import { z } from 'zod';

const UserSchema = z.object({
  id: z.string().uuid(),
  email: z.string().email(),
  role: z.enum(['admin', 'user']),
});

export default defineWorkflow('user-onboarding', { schema: UserSchema }, async (flow) => {
  const user = flow.params; // Typed as User
  await flow.do('create user', async () => {
    await createUser(user);
  });
});

High-performance validation with runtime type checking (v2.0+).

npm i arktype

pnpm add arktype

yarn add arktype

import { defineWorkflow } from '@identity-flow/sdk';
import { type } from 'arktype';

const UserSchema = type({
  id: 'string', // For specific formats like UUID, ArkType uses constraints (see ArkType docs).
  email: 'string', // For specific formats like email, ArkType uses constraints (see ArkType docs).
  role: "'admin' | 'user'",
});

export default defineWorkflow('user-onboarding', { schema: UserSchema }, async (flow) => {
  const user = flow.params; // Typed as User
  await flow.do('create user', async () => {
    await createUser(user);
  });
});

Best Practices

Validate Early

Add schemas to workflow definitions to catch invalid data before processing starts.

Type Safety

Let TypeScript infer types from schemas for compile-time checks.

Consistent Validation

Use the same schemas across related workflows to maintain consistency.

Step-Level Validation

export default defineWorkflow('order-processing', async (flow) => {
  await flow.do('validate order', { schema: OrderSchema }, async (input) => {
    // input is typed from OrderSchema
    return processOrder(input);
  });
});

Error Handling

See the main Error Handling guide for detailed strategies.

Basic Validation
Custom Validation

export default defineWorkflow('user-registration', async (flow) => {
  try {
    await flow.do('create user', {
      schema: UserSchema
    }, async (input) => {
      return createUser(input);
    });
  } catch (error) {
    if (error instanceof ValidationError) {
      flow.error('Invalid user data', {
        errors: error.errors
      });
    }
    throw error;
  }
});

export default defineWorkflow('payment-processing', async (flow) => {
  await flow.do('process payment', {
    validate: async (input) => {
      if (input.amount <= 0) {
        throw new ValidationError('Amount must be positive');
      }
      if (input.currency !== 'USD') {
        throw new ValidationError('Only USD is supported');
      }
      return input;
    }
  }, async (input) => {
    return processPayment(input);
  });
});

Schema Composition

const AddressSchema = v.object({
  street: v.string(),
  city: v.string(),
  country: v.string(),
  postal: v.string(),
});

const UserSchema = v.object({
  id: v.string([v.uuid()]),
  email: v.string([v.email()]),
  addresses: v.array(AddressSchema),
});

export default defineWorkflow('user-registration', { schema: UserSchema }, async (flow) => {
  // flow.params is typed with nested address array
  await flow.do('create user', async () => {
    return createUser(flow.params);
  });
});