---
title: JSON
description: JSON scalar type for structured data — untyped or typed with a StandardSchema validator
icon: braces
---

## Basic Usage

```ts
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](/docs/schema/scalars) and [Native Types](/docs/schema/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:

```ts
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](/docs/schema/scalars#support-matrix) for how custom schemas apply
to writes and filters.

## Examples

### Untyped JSON

```ts
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

```ts
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

```ts
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](/docs/client/filtering/json) for the full operator list and per-database caveats. A path filter names its operator explicitly.

```ts
// 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:

```ts
// 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:

```ts
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](/docs/client/filtering/json#the-two-nulls) 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.
