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