ArkType Validation
Overview
ArkType is a TypeScript-native runtime validation library that defines schemas using string expressions mirroring TypeScript syntax, providing editor autocomplete, syntax highlighting, and optimized validators. Use when building type-safe APIs, validating JSON payloads, or replacing Zod with a more TypeScript-idiomatic approach. Not suitable for projects that need Zod ecosystem compatibility or JSON Schema output.
Package: arktype
Quick Reference
| Pattern | Usage | ||
|---|---|---|---|
type({key: "string"}) | Define object schema | ||
type("string") | Primitive type | ||
"string.email", "string.url" | Built-in string validators | ||
"string.trim", "string.lower" | Built-in string morphs (transforms) | ||
"string.json.parse" | Parse JSON string to validated object | ||
"number > 0", "string >= 1" | Inline constraints | ||
| `"string \ | number"` | Union types | |
| `"'a' \ | 'b' \ | 'c'"` | String literal unions |
"string[]" | Array types | ||
"key?": "string" | Optional properties | ||
"key = 'default'" | Default values | ||
.pipe(), .to() | Transform output (morphs) | ||
.narrow() | Custom validation (like Zod refine) | ||
.pick(), .omit() | Object property selection | ||
.merge() | Combine object types | ||
scope({...}).export() | Named type scopes with cross-references | ||
type("<t>", {box: "t"}) | Generic type definitions | ||
type.errors | Error handling (check instanceof type.errors) | ||
.assert(data) | Throws on invalid input instead of returning | ||
"(number % 2)#even" | Branding — type-only validated marker | ||
"0 <= number <= 100" | Compact range constraints | ||
configure() | Global defaults (from arktype/config) | ||
match() | Type-safe pattern matching (2.1) | ||
"+": "reject" | Inline undeclared key handling | ||
arkenv({PORT: "number"}) | Typesafe env var validation (ArkEnv) | ||
arkenvVitePlugin(Env) | Build-time env validation for Vite |
Common Mistakes
| Mistake | Fix |
|---|---|
type("string.email()") with parens | type("string.email") (no parens) |
Checking errors with === null | Use instanceof type.errors |
{key: "string?"} for optional | {"key?": "string"} (question mark on key) |
Importing from arktype/types | Import type and scope from "arktype" |
Nested type() in string expressions | Use scope() for cross-referencing types |
Raw .pipe() without error handling | Use .pipe.try() for operations that can throw |
"string.lowercase" for case morph | "string.lower" (also "string.upper") |
Configuring after importing arktype | Import arktype/config before arktype |
Manual process.env parsing | Use arkenv() for auto-coercion and validation |
Delegation
Use this skill for ArkType schema definitions, runtime validation, morphs/transforms, scopes, and type inference. For Zod-based validation, delegate to the zod-validation skill.
References
- Schema Types — primitives, string keywords, number constraints, objects, arrays, tuples, unions, optional, defaults
- Morphs and Scopes — pipe, morph transforms, narrow validation, scopes, recursive types, generics, global configuration, pattern matching
- Common Patterns — JSON parsing, form validation, API responses, error handling, ArkEnv environment variables, Vite plugin, comparison with Zod