# Getting Started

> Validate Taskbox payloads with @taskbox/schemas.

Source: https://taskbox.n.yatsyk.com/docs/schemas/getting-started

# Getting Started

`@taskbox/schemas` is a leaf package — it has no Taskbox runtime dependencies
and is safe to use anywhere you need to validate or type Taskbox JSON.

## 1. Install

```bash
npm i @taskbox/schemas zod
```

The package re-exports the `zod` instance it built its schemas with, so you
can do `import { z } from "@taskbox/schemas"` if you only need one zod in
your tree.

## 2. Validate a TaskSpec

```ts
import { TaskSpecSchema } from "@taskbox/schemas";

const spec = TaskSpecSchema.parse({
  tool: "media.downloadSubtitles",
  input: { url: "https://youtu.be/jNQXAC9IVRw", languages: ["en"] },
  network: { mode: "direct" },
  runtime: { backend: "podman" },
});
```

If parsing fails, zod throws a `ZodError` with the path of every mismatch.

## 3. Type a callback

```ts
import type { TaskEvent, TaskResult } from "@taskbox/schemas";

function onEvent(e: TaskEvent) {
  if (e.type === "process.stdout") process.stdout.write(e.data + "\n");
}

function reportResult(r: TaskResult) {
  if (!r.ok) console.error(r.error.code, r.error.message);
}
```

## 4. Build a TaskboxError shape by hand

```ts
import { TaskboxErrorSchema } from "@taskbox/schemas";

const err = TaskboxErrorSchema.parse({
  code: "E_TIMEOUT",
  category: "timeout",
  message: "task exceeded 30s",
  retryable: true,
  suggestions: ["raise resources.timeoutMs"],
});
```

The schemas are the same ones the in-container runner serializes, so anything
you parse here matches what `@taskbox/core` produces in `result.json`.