Sapphire Documentation

Schema once, types and adapters everywhere. These docs walk you from a first install through every concept and adapter Sapphire ships with.

Getting Started

Getting Started — install, your first schema, parse/safeParse, plugging in an adapter.

Overview — what Sapphire is, what it isn’t, and the mental model.
Fields and modifiers — full vocabulary of primitives, composites, and modifiers.
Inferring types — Infer<> vs InferInput<> and the brand-type model.
Composition — pick, omit, partial, required, extend, merge.
Unions, literals, and enums — the a.type() namespace.
Tuples vs arrays — fixed-position vs homogeneous collections.
Refs and relations — named schemas and a.ref().
Nullable vs optional — the canonical confusion, resolved.
Validation — parse / safeParse, issues, message resolution.
Config — Sapphire options and per-call overrides.
Escape hatch — .adapter(name, opts) for ORM-specific options.

Mongo (@ascendance-hub/sapphire-bson) — native MongoDB driver $jsonSchema collection validators.
Mongoose (@ascendance-hub/sapphire-mongoose) — Mongoose Schema output, with refs, timestamps, and composite indexes.
JSON Schema (@ascendance-hub/sapphire-json-schema) — JSON Schema 2020-12 output for AJV, MCP tools, and frontend form generators.
Drizzle (@ascendance-hub/sapphire-drizzle) — pgTable / mysqlTable / sqliteTable output with lazy refs and composite indexes.

Form validation — collect every issue from safeParse and pivot to per-field UI errors.
Share types with the frontend — one schema feeds Mongo, Infer<> types, and JSON Schema for forms or MCP tools.
One schema, many adapters — register multiple adapters and emit each from the same IR.
Writing a custom adapter — walk the IR’s 12 kinds and plug into the registry.
Custom error messages — i18n and branded messages through the 5-level resolution hierarchy.
Migrating from Zod — side-by-side mapping plus what each library does that the other doesn’t.