Schema and parsers

schema describes the data your app takes in, once. A schema built with s gives you a TypeScript type, a strict check and a JSON Schema, with errors that name the path, never the value.

import { s, type Infer } from "mainsdk/schema";
import { parse } from "mainsdk/parse";

const Invoice = s.object({
  number: s.string().max(40),
  total: s.number().min(0),
  due: s.date(),
});
type Invoice = Infer<typeof Invoice>;

const invoice = Invoice.parse(body);                        // MAIN-SCHEMA-0001 lists every issue, never the value
const total = parse.number("1.234,50", { locale: "de-DE" }); // 1234.5

import assert from "node:assert/strict";
import { describe, it } from "node:test";
import { s } from "mainsdk/schema";

const Order = s.object({ id: s.string().uuid(), qty: s.int().min(1) });

describe("order schema", () => {
  it("schema.AC1 refuses an unknown key", () => {
    const result = Order.safeParse({ id: crypto.randomUUID(), qty: 1, role: "admin" });
    assert.equal(result.ok, false);
    if (!result.ok) assert.deepEqual(result.issues.map((i) => [i.code, i.path]), [["unknown_key", ["role"]]]);
  });
});

schema:
  driver: builtin

Quick start

import { s, type Infer } from "mainsdk/schema";

export const Order = s.object({
  id: s.string().uuid(),
  qty: s.int().min(1).max(99),
  kind: s.enum(["standard", "express"]),
  note: s.string().max(500).nullable(),
});
export type Order = Infer<typeof Order>;

export function readOrder(body: unknown): Order {
  return Order.parse(body);                 // throws MAIN-SCHEMA-0001 with every issue
}

parse returns a new value built from the schema, not the object you passed in. safeParse does the same without throwing, and returns { ok: false, issues } for a value that does not match.

Configuration

schema has no main.yaml key and no driver. It runs in your app, with no network call, no dependency and no setup, and it is free on every plan. The limits sit on the call: each parse function takes a maxLength, 100 000 characters by default (see Guards).

What you get

• One definition for the TypeScript type (Infer), the strict check and the JSON Schema 2020-12 that MCP tools and model calls send.
• Strict by default: unknown and missing keys are refused, and parse collects every issue in one pass.
• Errors that say where the data is wrong by path and code, and never repeat the value.
• One schema for action input, MCP tools, http.json replies and model output, through the Standard Schema v1 interface.
• parse turns raw text into checked values, and parse.first tries cheap exact and pattern parsers before it reaches a model.
• Guards against oversized input, slow patterns and prototype keys.

Strict by default

An object schema refuses keys it does not list. A missing key that is not optional is refused too. parse collects every issue in one pass, so you see all of them at once.

import { s } from "mainsdk/schema";

const Order = s.object({ name: s.string(), qty: s.int().min(1) });

const result = Order.safeParse({ name: "Priya", qty: 0, role: "admin" });
// { ok: false, issues: [
//   { path: ["qty"], code: "too_small", message: "Must be at least 1" },
//   { path: ["role"], code: "unknown_key", message: "..." }
// ] }

The issue never holds the value, so "Priya" and "admin" stay out of your logs and out of the error reply. Use .passthrough() when you want unknown keys kept in the result instead of refused.

import { s } from "mainsdk/schema";

const Loose = s.object({ name: s.string() }).passthrough();

Keys named __proto__, constructor and prototype are refused everywhere, including under .passthrough() and in s.record.

Optional, nullable and refined

import { s } from "mainsdk/schema";

const Cart = s.object({
  note: s.string().optional(),          // the key may be missing or undefined
  coupon: s.string().nullable(),        // the key must be present; null is allowed
  total: s.number().min(0),
}).refine((c) => c.total < 10_000, "Cart total must be under 10000");

A refinement runs only after the base schema passes, and it must be synchronous. Its message is the issue's message.

Types you can use

s.date refuses impossible dates such as 2026-02-30. s.number refuses NaN and infinities. Version 1 has no default values, no transforms, no async refinements and no lazy or recursive schemas. Set defaults in your code after parse.

Infer

Infer gives the type a schema accepts. Optional keys become optional properties, and nullable keys add | null.

import { s, type Infer } from "mainsdk/schema";

const Cart = s.object({
  note: s.string().optional(),
  coupon: s.string().nullable(),
});
type Cart = Infer<typeof Cart>;   // { note?: string; coupon: string | null }

JSON Schema

Every native schema emits JSON Schema 2020-12 with $schema at the root.

import { s } from "mainsdk/schema";

const Order = s.object({ id: s.string().uuid(), qty: s.int().min(1) });
const json = Order.toJSONSchema();   // strict object: required, properties, additionalProperties: false

MCP advertises each tool's input as this document, and ai.extract sends it to the model. A refinement has no JSON Schema form, so the base document stays as it is. A schema from a library that cannot emit JSON Schema is sent as { type: "object" }, and its reply is still checked.

Standard Schema

Every native schema exposes the Standard Schema v1 interface with vendor: "mainsdk". Anywhere the SDK takes a schema, you can pass a native schema, any Standard Schema value, or an object with a parse method. Zod still works through Standard Schema: pass a Zod or Valibot schema where a schema is taken, and its issues come back as { path, code, message }, with code set to the library's code or to invalid.

The places that take a schema are the action input, the ai.generate, ai.extract, ai.classify and ai.extractor calls, http.json, and the parse.regex, parse.json, parse.csv and parse.pattern parsers.

Coercion

Coercion is off by default. A string "3" against s.number() is a type issue, because a form or an environment variable may send text where you want a number. Opt in where the text comes from a form, a query string or the environment:

import { s } from "mainsdk/schema";

const Query = s.object({
  page: s.coerce.int().min(1),
  open: s.coerce.boolean(),
});

const q = Query.parse({ page: " 2 ", open: "true" });   // { page: 2, open: true }

s.coerce.number(), s.coerce.int() and s.coerce.boolean() convert a trimmed numeric string, and booleans read "true", "false", "1" and "0". An empty string never becomes 0. To coerce every number, int and boolean in one schema, pass { coerce: true } to parse or safeParse.

Parsers

parse takes raw text, such as an email body, a CSV upload or a log line, and returns a checked value. Each parser refuses input longer than its maxLength (100 000 characters by default) before any pattern runs.

import { parse } from "mainsdk/parse";
import { s } from "mainsdk/schema";

parse.text("  Café ");                                        // "Café", trimmed and NFC
parse.match("express ", ["standard", "Express"], { caseInsensitive: true });   // "Express"
parse.lines("a\r\n\nb\rc");                                    // ["a", "b", "c"]
parse.number("12,34,567.89", { locale: "en-IN" });             // 1234567.89
parse.number("1.234.567,89", { locale: "de-DE" });             // 1234567.89
parse.date("2026-10-27T10:30:00+05:30");                       // a Date

• parse.text(raw, { maxLength? }) trims the text and normalises it to NFC.
• parse.match(raw, list, { caseInsensitive? }) returns the entry of list that equals the text. It never matches partly or fuzzily, and it fails when two entries match case-insensitively.
• parse.regex(raw, re, schema) reads the named groups of the first match into an object and checks it with the schema, coerced, since every group is a string.
• parse.json(raw, schema?) reads JSON and then checks it with the schema.
• parse.csv(raw, { schema?, header?, delimiter? }) reads RFC 4180 CSV, with quoted fields, doubled quotes and CRLF or LF line ends. With header: true the first row names the columns, and a bad cell is reported at [row, "column"], with the row counted from 0 after the header.
• parse.lines(raw, { skipEmpty? }) splits on CRLF, LF or CR, trims each line and skips empty lines unless you set skipEmpty: false.
• parse.number(raw, { locale }) reads the separators that Intl.NumberFormat uses for the locale, including Indian lakh grouping.
• parse.date(raw) accepts the same ISO 8601 forms as s.date and returns a Date.

import { parse } from "mainsdk/parse";
import { s } from "mainsdk/schema";

const Refund = s.object({ id: s.coerce.int(), qty: s.coerce.int() });

const refund = parse.regex("Order 42 x3", /Order (?<id>\d+) x(?<qty>\d+)/, Refund);
// { id: 42, qty: 3 }

Use parse.json and parse.csv with the schema that describes the rows, so bad input fails with the same codes as the rest of the SDK:

import { parse } from "mainsdk/parse";
import { s } from "mainsdk/schema";

const Row = s.object({ sku: s.string().max(20), qty: s.coerce.int().min(1) });

export function readRows(csv: string) {
  return parse.csv(csv, { schema: Row, header: true });   // typed rows, or MAIN-SCHEMA-0001 at [row, "column"]
}

parse.first

parse.first tries parsers in the order you give them. The first one that matches wins, and the result says how it was found: via is exact, pattern or model, and a model match carries its cost.

import { ai } from "mainsdk";
import { parse } from "mainsdk/parse";
import { s } from "mainsdk/schema";

const Refund = s.object({ id: s.coerce.int() });

const find = parse.first(
  parse.exact(["refund"]),                                    // no model, no cost
  parse.pattern(/refund (?<id>\d+)/, Refund),                 // no model, no cost
  ai.extractor(s.object({ orderId: s.string() }), { model: "anthropic/claude-sonnet-4-5", feature: "support" }),
);

const hit = await find("my order 42 never came");
// { value: { orderId: "42" }, via: "model", cost: "$0.01" }

A parser that throws MAIN-SCHEMA-0001 or MAIN-SCHEMA-0004 counts as no match. Any other error stops the search and reaches your code. When no parser matches, parse.first throws MAIN-SCHEMA-0004. The model runs only when the cheaper parsers before it miss.

Guards

• Size. Every parse function refuses input over its maxLength with MAIN-SCHEMA-0002 before any pattern runs. The default is 100 000 characters. A string schema's .regex() checks its max first, with 100 000 characters when none is set.
• Patterns. A pattern with a nested quantifier, such as (a+)+, (\w*)* or (a|ab+){2,}, is refused when you define it, with MAIN-SCHEMA-0003. Nothing runs against input.
• Values. Issues and errors carry paths, codes and messages, never a value. A parser that finds no match does not echo the input.
• Prototypes. __proto__, constructor and prototype are refused as keys, so a request body cannot write to an object's prototype.
• Process. Schemas and parsers run in your app with no network call.

Errors and checks

An action whose input fails its schema returns MAIN-ACTION-0001 (400) with the same errors list. An http.json reply that fails its schema returns MAIN-SCHEMA-0001, and no part of the body is in the error.

Swapping drivers

There is no driver to swap: schemas and parsers run in process. What you can change is the validator. Anywhere the SDK takes a schema you can pass a native s schema, a Standard Schema value such as Zod or Valibot, or an object with a parse method (see Standard Schema). Your calls stay the same.

Testing

Schemas run in process, so a test calls them directly. Name the test by the behaviour it proves:

import assert from "node:assert/strict";
import { describe, it } from "node:test";
import { s } from "mainsdk/schema";

const Order = s.object({ id: s.string().uuid(), qty: s.int().min(1) });

describe("order schema", () => {
  it("schema.AC1 refuses an unknown key", () => {
    const result = Order.safeParse({ id: crypto.randomUUID(), qty: 1, role: "admin" });
    assert.equal(result.ok, false);
    if (!result.ok) assert.deepEqual(result.issues.map((i) => [i.code, i.path]), [["unknown_key", ["role"]]]);
  });
});

FAQ

Do I still use Zod? You can. Zod and Valibot work wherever a schema is taken, through Standard Schema. New code should use s, because its JSON Schema, its issues and its guards are the ones MCP and the model verbs use.

Why is there no .default()? Version 1 keeps parse a pure check. Set the default in your code after parse returns, so the value you store is the one you wrote.

Can a schema call a database or a model? No. A refinement is synchronous and in process, so a check never waits on the network.

Why does parse not return my input object? It returns a new value built from the schema, so keys you did not declare cannot slip through, and the object you passed is never changed.

Methods on a schema

Every schema has schema.parse(value), which throws MAIN-SCHEMA-0001 for a bad value, schema.safeParse(value), which returns { ok, issues }, and schema.toJSONSchema(). For a validator you did not build with s, such as a Standard Schema or a { parse } object, use the functions below.

import { check, checkAsync, jsonSchemaOf, s } from "mainsdk";

const Order = s.object({ id: s.string(), qty: s.int().min(1) });
const input: unknown = { id: "o_1", qty: 2 };

const order = check(Order, input);                // throws MAIN-SCHEMA-0001 on a bad value
const later = await checkAsync(Order, input);     // for validators that run asynchronously
const json = jsonSchemaOf(Order);                 // the JSON Schema, or undefined

Reference

s and parse are plain objects of builders and parsers, not functions: write s.string() and parse.json(raw, schema), never s(...) or parse(...). The builders are in Types you can use, and the parsers are parse.text, match, regex, json, csv, lines, number, date, first, exact and pattern.

Three small helpers from the same package read values you meet while building validators and settings.

import { parseDuration, parseSize } from "mainsdk";

parseDuration("1.5h");   // 5_400_000
parseSize("25MB");       // 26_214_400

Next

• Actions and agent tools: the input schema that every door validates.
• AI calls: ai.extract, ai.classify, ai.summarize and ai.extractor, which send your schema to a model.
• Extract structured data from an email: regex first, a model as the fallback, and a typed invoice at the end.
• Errors and problem details: the errors member and the codes above.