Fields and modifiers

Sapphire’s field DSL is the user-facing surface of the library. Every call on a Sapphire instance (a.string(), a.object({...}), a.type().union([...])) returns a new, immutable Field. Modifiers like .optional(), .min(3), .default('x') return new fields rather than mutating the previous one — chains are safe to share and reuse.

This page is the reference for every field constructor and every modifier it supports. For composition methods on objects (pick, omit, partial, required, extend, merge) see Composition. For union/literal/enum see Unions, literals, and enums.

Minimal example

const user = a.object({
  name: a.string().min(1).max(120),
  age: a.number().int().nonnegative(),
  active: a.boolean().default(true),
  createdAt: a.date(),
})

type User = Infer<typeof user>
// User = { name: string; age: number; active: boolean; createdAt: Date }

Primitives

a.string()

Example:

const email = a.string().min(3).max(254).email()

[!NOTE] .email() is pragmatic, not RFC 5322 complete. The built-in regex covers ~99% of practical addresses — it rejects obvious junk (a@b..c, leading/trailing dots, missing TLD) but does not accept exotic-but-RFC-legal forms like quoted local parts ("foo bar"@example.com). If you need full RFC compliance, plug a third-party validator via .regex(yourRegex) or post-safeParse checks.

a.number()

Example:

const age = a.number().int().gte(0).lte(150)

a.boolean()

Boolean has no rule modifiers — just universal ones and .coerce(). With coerce, the strings 'true'/'false' and numbers 1/0 are accepted.

a.date()

Strict by default — only Date instances are accepted. Call .coerce() to also accept strings or numbers (form payloads, URL params, JSON-deserialized timestamps); the adapter IR (coerce: false vs coerce: true) honestly reflects what runtime will accept.

Composites

a.object(shape)

Shape is a record of Fields. The output is a plain object whose keys mirror shape, with optional fields lifted into ?: positions.

ObjectField carries schema-level metadata too: .name(n), .timestamps(), .index(keys, opts?). It also exposes the composition methods pick, omit, partial, required, extend, merge — those have their own page in Composition.

a.array(item)

Homogeneous, variable-length. The single item argument is the inner field — every entry is validated against it. Modifiers: .min(n), .max(n), .length(n), .nonempty().

a.tuple([f1, f2, ...])

Heterogeneous, fixed-length. See Tuples vs arrays for the comparison.

Type namespace

a.type() returns a builder for the non-leaf kinds:

Refs

a.ref(target) declares “this position holds a reference to a named schema”. target is either an ObjectField returned by .name(...) or the name string directly. Validation checks presence and that the referenced name is registered on the Sapphire instance — an unregistered target fails safeParse with a ref_target_missing issue. It does not check the referenced value’s shape in v1. Adapters resolve the target shape (Mongo ObjectId, JSON Schema $ref, Drizzle references(() => target.id)). Detailed coverage in Refs and relations.

Universal modifiers

These are available on every field. (unique, index, and the schema-level name/timestamps are not strictly universal — see the per-field tables — but follow the same chainable convention.)

Example:

const bio = a.string().max(280).optional().describe('User bio (markdown)')
const nickname = a.string().nullable()
const role = a.string().default('member')

Pitfalls

[!WARNING] .coerce() runs first. Order is coerce → default substitution → null/undefined handling → invalid_type check → transforms → rule checks. Validators see the coerced value, not the raw input. The snippet below converts 42 to "42" before the min(3) check fires.

const slug = a.string().coerce().toLowerCase().min(3)
// The number 42 becomes the string "42" first, then lowercases (no-op),
// then is checked against min(3) — which fails because "42".length === 2.

[!WARNING] .nullable() is NOT .optional(). nullable accepts null; optional accepts undefined. They are independent — combine them if you want both. See Nullable vs optional.

Related

• Inferring types — how modifiers feed into Infer<>.
• Composition — pick, omit, partial, required, extend, merge.
• Unions, literals, and enums.
• Tuples vs arrays.
• Recipes → Custom error messages.
• Recipes → Writing a custom adapter.