JSON
JSON scalar type for structured data — untyped or typed with a StandardSchema validator
Basic Usage
import { s } from "viborm";
s.json(); // Required JSON (unknown type)
s.json().nullable(); // JSON | null
JSON scalars support .nullable(), .default(), .map(), and .schema() — but not .array(), .id(), or .unique(). See the support matrix and Native Types for column types (jsonb vs json on PostgreSQL, etc.).
Typed JSON
Provide a StandardSchema (Valibot, Zod, etc.) for type-safe JSON using the .schema() method:
import { object, picklist, boolean, string } from "valibot";
const settingsSchema = object({
theme: picklist(["light", "dark"]),
notifications: boolean(),
language: string(),
});
s.json().schema(settingsSchema); // Typed as { theme: "light" | "dark"; ... }
The schema validates writes. Results are typed from .schema() but are not
re-validated on read, so rows written before a schema change, or by raw SQL or
another service, come back in the shape they were stored in. See
Scalars for how custom schemas apply
to writes and filters.
Examples
Untyped JSON
const metadata = s.json().default({});
const tags = s.json().default([]);
Defaults preserve the two null meanings: .default(JsonNull) stores the JSON
null document on either kind of column; .nullable().default(DbNull) stores SQL
NULL. A bare .default(null) means JSON null on a nonnullable column and SQL
NULL on a nullable column. Applying .nullable() after a declared JSON null
default preserves that document default. Explicit JSON writes still require the
existing sentinels when naming either null.
Typed with Valibot
import {
object,
picklist,
number,
boolean,
string,
pipe,
minValue,
maxValue,
} from "valibot";
// User preferences
const preferencesSchema = object({
theme: picklist(["light", "dark", "system"]),
fontSize: pipe(number(), minValue(10), maxValue(24)),
notifications: object({
email: boolean(),
push: boolean(),
}),
});
const preferences = s
.json()
.schema(preferencesSchema)
.default({
theme: "system",
fontSize: 14,
notifications: { email: true, push: false },
});
// Address structure
const addressSchema = object({
street: string(),
city: string(),
country: string(),
postalCode: string(),
});
const address = s.json().schema(addressSchema).nullable();
Complex Nested Types
import {
object,
string,
number,
array,
optional,
pipe,
minValue,
maxValue,
integer,
positive,
} from "valibot";
const orderItemSchema = object({
productId: string(),
quantity: pipe(integer(), positive()),
price: pipe(number(), positive()),
discount: optional(pipe(number(), minValue(0), maxValue(1))),
});
const orderSchema = object({
items: array(orderItemSchema),
shipping: addressSchema,
notes: optional(string()),
});
const orderData = s.json().schema(orderSchema);
Querying JSON
JSON scalars support path-based filtering — see JSON Filters for the full operator list and per-database caveats. A path filter names its operator explicitly.
// Filter by nested value (must use { equals: value })
await client.user.findMany({
where: {
preferences: {
path: ["theme"],
equals: "dark",
},
},
});
Writing JSON
Every write accepts the document directly or an explicit { set: value }
envelope, and both forms store the same document. This holds on create,
createMany, both arms of upsert, nested creates and updates alike:
// Replace the document directly
await client.user.update({
where: { id: "user_123" },
data: {
preferences: { theme: "dark", fontSize: 16 },
},
});
// The explicit envelope writes the same document, on create as on update
await client.user.create({
data: {
id: "user_456",
preferences: { set: { theme: "dark", fontSize: 16 } },
},
});
Both forms validate the document against .schema(...) when present.
A one-key { set: value } object is the write envelope on every write path. To
store a literal one-key document with a set property, wrap it as
{ set: { set: value } }; the inner document must satisfy the declared schema.
An invalid envelope value fails validation rather than being stored as a
literal document.
Because the envelope is unwrapped exactly once, wrapping a document you read
back always writes it unchanged. Code that copies JSON between rows should write
{ set: row.preferences } rather than the bare value, which would be read as an
envelope when the document itself is a one-key { set } object.
Writing null
A nullable JSON column has two nulls: the database NULL (no document at
all) and the JSON value null (a document that happens to be null). A bare
null does not say which one you mean, so it is rejected in write position —
at compile time and at runtime — and two exported sentinels name them instead:
import { DbNull, JsonNull } from "viborm";
// The column holds no document
await client.user.update({ where: { id }, data: { preferences: DbNull } });
// The column holds the JSON document `null`
await client.user.update({ where: { id }, data: { preferences: JsonNull } });
// Rejected: "null is ambiguous in JSON write data…"
await client.user.update({ where: { id }, data: { preferences: null } });
Only the top level is affected — { theme: null } is an ordinary document and
stays legal. DbNull requires a .nullable() field; JsonNull works on any
JSON field, since the JSON value null is a document like any other. AnyNull
is filter-only: “either null” is a question, not a value.
The write type for a JSON field is exported as InputJsonValue (every
JsonValue except a top-level null), which is useful when a fixture or
helper needs to name it.
See JSON Filters for the matching filter side.
JSON vs Separate Scalars
| Approach | Pros | Cons |
|---|---|---|
| JSON scalar | Flexible, no migrations | Harder to query, no constraints |
| Separate scalars | Type-safe queries, indexes | Schema changes need migrations |
| Related table | Full SQL power | More complex queries |
Use JSON for user preferences, per-record metadata, third-party API responses, and audit logs. Use separate scalars for data you filter or sort by, data with strict validation, and data referenced in relations.