schemaTask

schemaTask defines a task with runtime payload validation. If the payload doesn't match the schema, the task won't execute.

Basic Usage

import { schemaTask } from "@trigger.dev/sdk";
import { z } from "zod";

const myTask = schemaTask({
  id: "my-task",
  schema: z.object({
    name: z.string(),
    age: z.number(),
  }),
  run: async (payload) => {
    console.log(payload.name, payload.age);
  },
});

schemaTask accepts all the same options as task(), plus a schema field.

Schema Validation on Trigger

When triggering directly via the typed task reference, validation runs before creating the run:

await myTask.trigger({ name: "Alice", age: "oops" }); // throws — age must be number

// tasks.trigger bypasses TypeScript schema validation:
await tasks.trigger<typeof myTask>("my-task", { name: "Alice", age: "oops" }); // does NOT throw

Input/Output Types

Schema libraries like Zod can have different input and output types:

const myTask = schemaTask({
  id: "my-task",
  schema: z.object({
    name: z.string().default("John"),  // optional in input, required in output
    age: z.number(),
    dob: z.coerce.date(),              // string in, Date out
  }),
  run: async (payload) => {
    // payload.name is string (defaults applied)
    // payload.dob is Date (coerced)
  },
});

	Type
Trigger payload	{ name?: string; age: number; dob: string }
Run payload	{ name: string; age: number; dob: Date }

Using as an AI Tool (ai.tool)

Convert a schemaTask into a Vercel AI SDK tool:

import { ai } from "@trigger.dev/sdk/ai";
import { schemaTask } from "@trigger.dev/sdk";
import { z } from "zod";
import { generateText } from "ai";
import { openai } from "@ai-sdk/openai";

const myToolTask = schemaTask({
  id: "my-tool-task",
  schema: z.object({ query: z.string() }),
  run: async (payload) => {
    return { result: `Processed: ${payload.query}` };
  },
});

const myTool = ai.tool(myToolTask);

export const myAiTask = schemaTask({
  id: "my-ai-task",
  schema: z.object({ text: z.string() }),
  run: async (payload) => {
    const { text } = await generateText({
      prompt: payload.text,
      model: openai("gpt-4o"),
      tools: { myTool },
    });
    return { text };
  },
});

ai.tool is compatible with Zod, ArkType, and any schema implementing .toJsonSchema().

Supported Schema Libraries

Library	Syntax
Zod	z.object({ ... })
Yup	yup.object({ ... })
Superstruct	object({ ... })
ArkType	type({ ... }).assert
@effect/schema	Schema.decodeUnknownSync(Schema.Struct({ ... }))
runtypes	T.Record({ ... })
valibot	v.parser(v.object({ ... }))
typebox	wrap(Type.Object({ ... }))
Custom parser	Any function (data: unknown) => T