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
1---2name: arktype-validation3description: ArkType runtime validation with TypeScript-native syntax. Type-safe schemas using string expressions, morphs, scopes, and generics. Includes ArkEnv for typesafe environment variable validation with auto-coercion and Vite plugin. Use when defining schemas, validating data, transforming input, building type-safe APIs with ArkType, or validating environment variables with ArkEnv.4license: MIT5---6
7# ArkType Validation
8
9## Overview
10
11ArkType 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.
12
13**Package:** `arktype`
14
15## Quick Reference
16
17| Pattern | Usage |
18| --------------------------------- | ----------------------------------------------- |
19| `type({ key: "string" })` | Define object schema |
20| `type("string")` | Primitive type |
21| `"string.email"`, `"string.url"` | Built-in string validators |
22| `"string.trim"`, `"string.lower"` | Built-in string morphs (transforms) |
23| `"string.json.parse"` | Parse JSON string to validated object |
24| `"number > 0"`, `"string >= 1"` | Inline constraints |
25| `"string \| number"` | Union types |
26| `"'a' \| 'b' \| 'c'"` | String literal unions |
27| `"string[]"` | Array types |
28| `"key?": "string"` | Optional properties |
29| `"key = 'default'"` | Default values |
30| `.pipe()`, `.to()` | Transform output (morphs) |
31| `.narrow()` | Custom validation (like Zod refine) |
32| `.pick()`, `.omit()` | Object property selection |
33| `.merge()` | Combine object types |
34| `scope({...}).export()` | Named type scopes with cross-references |
35| `type("<t>", { box: "t" })` | Generic type definitions |
36| `type.errors` | Error handling (check `instanceof type.errors`) |
37| `.assert(data)` | Throws on invalid input instead of returning |
38| `"(number % 2)#even"` | Branding — type-only validated marker |
39| `"0 <= number <= 100"` | Compact range constraints |
40| `configure()` | Global defaults (from `arktype/config`) |
41| `match()` | Type-safe pattern matching (2.1) |
42| `"+" : "reject"` | Inline undeclared key handling |
43| `arkenv({ PORT: "number" })` | Typesafe env var validation (ArkEnv) |
44| `arkenvVitePlugin(Env)` | Build-time env validation for Vite |
45
46## Common Mistakes
47
48| Mistake | Fix |
49| ------------------------------------- | ----------------------------------------------- |
50| `type("string.email()")` with parens | `type("string.email")` (no parens) |
51| Checking errors with `=== null` | Use `instanceof type.errors` |
52| `{ key: "string?" }` for optional | `{ "key?": "string" }` (question mark on key) |
53| Importing from `arktype/types` | Import `type` and `scope` from `"arktype"` |
54| Nested `type()` in string expressions | Use `scope()` for cross-referencing types |
55| Raw `.pipe()` without error handling | Use `.pipe.try()` for operations that can throw |
56| `"string.lowercase"` for case morph | `"string.lower"` (also `"string.upper"`) |
57| Configuring after importing `arktype` | Import `arktype/config` before `arktype` |
58| Manual `process.env` parsing | Use `arkenv()` for auto-coercion and validation |
59
60## Delegation
61
62Use this skill for ArkType schema definitions, runtime validation, morphs/transforms, scopes, and type inference. For Zod-based validation, delegate to the zod-validation skill.
63
64## References
65
66- [Schema Types](references/schema-types.md) — primitives, string keywords, number constraints, objects, arrays, tuples, unions, optional, defaults
67- [Morphs and Scopes](references/morphs-and-scopes.md) — pipe, morph transforms, narrow validation, scopes, recursive types, generics, global configuration, pattern matching
68- [Common Patterns](references/common-patterns.md) — JSON parsing, form validation, API responses, error handling, ArkEnv environment variables, Vite plugin, comparison with Zod
oakoss