---
title: JSON schemas
description: "Define a schema as a JSON document — the surface for programmatic and agent-written schemas"
icon: braces
---

A VibORM schema is normally written in TypeScript. `viborm/schema/json` lets a
program write one as **data** instead: a JSON document goes in, a real schema
comes out.

```ts
import { createClient } from "viborm";
import { parseSchema, serializeSchema } from "viborm/schema/json";

const schema = parseSchema(document);        // JSON text OR a plain object
const db = createClient({ schema, driver });
const back = serializeSchema(schema);        // the reverse direction
```

`parseSchema` calls the same builders a human calls, so what it returns is not a
second kind of schema — it is the same models. `createClient`, `push` and the
query engine consume it unchanged and refuse a bad graph with their own
diagnostics.

To start from a database that already exists, [`introspectSchema`](/docs/schema/introspect)
reads it into a document of this format.

The one thing you give up is **type inference**: the model names are strings, so
the client is an `UntypedClient` — see [The untyped
client](#the-untyped-client).

## The document

`version` and `models` are required. Every other key is optional.

```json
{
  "version": 1,
  "enums": {
    "role": { "values": ["admin", "member"], "name": "user_role" }
  },
  "models": {
    "user": {
      "table": "users",
      "fields": {
        "id":    { "type": "string", "id": true, "generate": { "kind": "ulid", "prefix": "usr" } },
        "email": { "type": "string", "unique": true },
        "role":  { "type": "enum", "enum": "role", "default": "member" },
        "bio":   { "type": "string", "nullable": true },
        "posts": { "type": "toMany", "target": "post", "name": "PostAuthor" }
      },
      "indexes": [{ "fields": ["email"], "unique": true }],
      "omit": ["bio"]
    },
    "post": {
      "fields": {
        "id":       { "type": "string", "id": true, "generate": { "kind": "ulid" } },
        "authorId": { "type": "string" },
        "author":   { "type": "toOne", "target": "user", "name": "PostAuthor",
                      "fields": ["authorId"], "references": ["id"], "onDelete": "cascade" },
        "topic":    { "type": "toOne",
                      "variants": { "thread": "thread", "review": "review" },
                      "values": { "thread": "topic.thread.v1", "review": "topic.review.v1" },
                      "optional": true }
      }
    },
    "thread": {
      "fields": {
        "id":    { "type": "string", "id": true, "generate": { "kind": "ulid" } },
        "title": { "type": "string" }
      }
    },
    "review": {
      "fields": {
        "id":     { "type": "string", "id": true, "generate": { "kind": "ulid" } },
        "rating": { "type": "int" }
      }
    }
  }
}
```

Every `json` block on this page is a complete document that the test suite
parses and round-trips, so an example here cannot drift from the parser.

**`"light": true`** marks a light document, which
[`introspectSchema({ light: true })`](/docs/schema/introspect#a-light-document)
writes: what a client reads, without the indexes only migrations read. A client
reads and writes through it; every migration path refuses its models (`V11009`).
`false` is the same as no key, and `serializeSchema` writes `"light": true` for a
schema holding any model of a light document.

**Field order matters for new tables.** DDL column order follows the order of
the keys in `fields` when a table is created, or rebuilt on SQLite, and the
format binds it to JSON key order. `JSON.parse` preserves that order; a producer
that sorts keys destroys it. On an existing table order is cosmetic: migrations
match models and columns by name, so a document that only reorders them
generates `noop` and publishes nothing.

### Model

| Key | Means |
| --- | --- |
| `table` | `.map(tableName)` |
| `fields` | the model's scalars and relations, in declaration order |
| `indexes` | `.index(fields, options)` — `{ fields, name?, unique?, type? }` |
| `ids` | compound `.id(fields, { name })`, in declaration order |
| `uniques` | compound `.unique(fields, { name })`, in declaration order |
| `omit` | scalar field keys to hide from every result |
| `withoutRowid` | `true` for `.withoutRowid()` |

`.extends()` has no spelling: a document states the complete, merged shape.

### Scalar fields

`type` is one of `string`, `int`, `number`, `decimal`, `boolean`, `datetime`,
`date`, `time`, `bigint`, `json`, `blob`, `vector`, `point`, `enum`.

| Key | Means |
| --- | --- |
| `native` | the factory's native-type argument — `{ "db": "pg" \| "mysql" \| "sqlite", "type": "varchar(255)" }`, see [Native types](#native-types); absent on `decimal` |
| `nativeByDialect` | the factory's argument when it is a map by dialect — `{ "pg"?: { "db": "pg", "type": … }, "mysql"?: …, "sqlite"?: … }`, each entry spelled like `native`; a field carries at most one of `native` and `nativeByDialect`; absent on `decimal` |
| `nullable`, `array`, `id`, `unique` | the matching modifier |
| `column` | `.map(columnName)` |
| `default` | a literal default — see [Defaults](#defaults) |
| `generate` | `{ "kind": "uuid" \| "uuidv7" \| "ulid" \| "ksuid" \| "nanoid" \| "cuid" \| "increment" \| "now" \| "updatedAt", "prefix"?, "length"?, "generate"?: boolean }` |
| `enum` | an `enums` reference, or the values inline — `type: "enum"` only |
| `dimension` | `.dimension(n)` — vectors |
| `withoutTimezone` | `.withoutTimezone()` — `datetime` and `time` |
| `precision`, `scale` | the required fixed-decimal descriptor — `type: "decimal"` only |

`point` is the fixed GeoPoint scalar. It accepts `nullable`, `column`, and a
literal default with exactly `longitude` and `latitude`. It has no `native`,
`nativeByDialect`, `array`, `id`, or `unique` spelling. A spatial index is declared at the model:

```json
{
  "version": 1,
  "models": {
    "place": {
      "fields": {
        "id": { "type": "string", "id": true },
        "location": { "type": "point" }
      },
      "indexes": [
        { "fields": ["location"], "type": "spatial" }
      ]
    }
  }
}
```

The same definition-time rules as TypeScript apply: exactly one non-null point,
no `unique` or `where`, and no ordinary index. Query-only `GeoArea` values do
not appear in the schema document.

The key set is the same for every type; whether a given type HAS a modifier is
decided by the scalar itself. `{ "type": "json", "array": true }` is refused
because `s.json()` has no `.array()`, and the error says so.

`"id": true` means exactly what `.id()` means — including the implicit ULID
generator on a string id. That generator is only a default; supplying an id at
create time overrides it.

### Relations

`type` is `toOne` or `toMany`. The target domain is `target` (one model key)
**or** `variants` (a map of variant key → model key) — exactly one of the two.

| Key | Arm |
| --- | --- |
| `name` | any — the pairing label, a free-form non-empty string |
| `fields`, `references`, `onDelete`, `onUpdate` | `toOne` with `target` |
| `junction` | `toMany` with `target` — `{ table?, source?, target?, onDelete?, onUpdate?, onDeleteSides?, onUpdateSides? }`, at least one key |
| `values` | variants — the stored discriminator per variant, exact over every variant key |
| `optional` | `toOne` with `variants` |
| `through` | `toMany` with `variants` — `{ "<variant>": { "table", "source", "target" } }` |

A key that belongs to another arm is refused, so a `toMany` cannot carry
`references` and a `toOne` cannot carry `through`.

A junction action is either one action for both foreign keys (`onDelete`) or
one per key (`onDeleteSides: { "source": "cascade", "target": "noAction" }`,
both keys required), never both for the same action. The serializer writes the
side map only when the two sides differ; equal sides come back as `onDelete`.

### Native types

`native.type` is the one string in a document that reaches the database
verbatim: the migration drivers emit it as the column's type, unescaped. A
document is written by whoever hands you one, so the parser does not try to
RECOGNIZE a type — a constraint clause and a multi-word type name are the same
shape, and `TEXT UNIQUE` is not a type. It checks MEMBERSHIP instead, against a
closed catalog **per dialect**, and the catalog is the set of values the
[native type constants](/docs/schema/native-types) themselves produce:

```text
pg      text   varchar(191)  double precision  timestamptz
mysql   TEXT   VARCHAR(191)  TINYINT UNSIGNED  BIGINT UNSIGNED
sqlite  TEXT   INTEGER       REAL             BLOB
```

A value belongs to the catalog of the `db` it declares and no other: `TEXT` is a
mysql and sqlite type, and a pg field spells it `text`. A parameterized type is
admitted at the argument counts its constant publishes, with integer arguments —
`varchar(191)`. Anything else is `J011`, including every
spelling that made this a raw SQL channel: quotes, semicolons, comment markers,
newlines, and constraint clauses such as `TEXT UNIQUE` or `TEXT REFERENCES
other(id)`.

So a document written from the `PG`, `MYSQL` and `SQLITE` constants is never
refused, and a native type those constants cannot produce is a **coded-schema**
capability: `s.string({ db, type })` in TypeScript takes any type you like,
because you wrote it. `serializeSchema` applies the identical rule, so a schema
holding a type the document cannot carry is named rather than written into a
document its own parser would reject.

A map by dialect is written as `nativeByDialect`, and every entry is held to the
same catalog as `native` (`J011` at the entry's `type`). Its keys are exactly
`pg`, `mysql` and `sqlite` (`J003` for any other), each entry's `db` is its own
key (`J004`), and a field with both `native` and `nativeByDialect` is refused
(`J003`). A map that names no dialect is refused by the scalar factory (`J010`).
The serializer writes a map as `nativeByDialect` with every entry, in the order
`pg`, `mysql`, `sqlite`, and a single constant as `native` — so a one-entry map
and the constant it resembles stay distinct declarations through a round trip.
Unlike `native`, a map in TypeScript takes only catalog values too, so any map a
schema holds can be written.

```json
{
  "version": 1,
  "models": {
    "note": {
      "fields": {
        "id": { "type": "string", "id": true },
        "body": {
          "type": "string",
          "nativeByDialect": {
            "pg": { "db": "pg", "type": "citext" },
            "mysql": { "db": "mysql", "type": "LONGTEXT" }
          }
        }
      }
    }
  }
}
```

### Enums

An `enums` definition with a `name` yields ONE database enum type shared by
every field that references it. Without `name` — or written inline as
`"enum": ["a", "b"]` — each column keeps its own derived type. That is the same
distinction `.name()` makes in code.

**The key and the name are different things.** An `enums` key is a
document-local reference and must be a schema identifier (`J005`); `name` is the
database's own type name, which may be anything the database allows. When a
database name happens to be a valid identifier the canonical document uses it as
the key too; when it is not — `status-v2` — the key becomes `enum_1`, `enum_2` …
by declaration order and `name` carries the real spelling:

```json
{
  "version": 1,
  "enums": { "enum_1": { "values": ["draft", "live"], "name": "status-v2" } },
  "models": {
    "article": {
      "fields": {
        "id":     { "type": "string", "id": true, "generate": { "kind": "ulid" } },
        "status": { "type": "enum", "enum": "enum_1", "default": "draft" }
      }
    }
  }
}
```

### Defaults

A default is a JSON value. Values from domains JSON has no spelling for take a
**tag**: a one-key object naming the domain.

| Tag | Means |
| --- | --- |
| `{ "$bigint": "9007199254740993" }` | a `bigint`, written as a decimal integer string |
| `{ "$bytes": "AQID" }` | bytes, written as base64 |
| `{ "$date": "2020-01-02T03:04:05.000Z" }` | a real `Date` |
| `{ "$jsonNull": "JsonNull" }` / `{ "$jsonNull": "DbNull" }` | the existing JSON document null / SQL NULL sentinel (`DbNull` requires a nullable JSON field) |
| `{ "$raw": <value> }` | the value itself, when its own shape looks like a tag |
| anything else | the JSON value itself |

Tags are read **at any depth**, so a `bigint[]` default is an array of them:

```json
{
  "version": 1,
  "models": {
    "reading": {
      "fields": {
        "id":     { "type": "string", "id": true, "generate": { "kind": "ulid" } },
        "counts": { "type": "bigint", "array": true,
                    "default": [{ "$bigint": "1" }, { "$bigint": "2" }] },
        "seed":   { "type": "blob", "default": { "$bytes": "AQID" } },
        "at":     { "type": "datetime", "default": { "$date": "2020-01-02T03:04:05.000Z" } },
        "since":  { "type": "datetime", "default": "2020-01-02T03:04:05.000Z" },
        "shape":  { "type": "json", "default": { "$raw": { "$date": "not a date" } } }
      }
    }
  }
}
```

**`at` and `since` are different declarations.** A temporal field accepts both a
`Date` and an ISO string, and the two do not produce the same table: a string
default becomes a SQL `DEFAULT` clause, while a `Date` is applied by the
application at insert time. `{ "$date": … }` says `Date`; a bare string says
string. Nothing is inferred from the field's type.

A one-key object whose key starts with `$` is **reserved**: an unknown one is
refused rather than read as a literal, so a later version can add a tag without
changing what an existing document means. A literal that really does look like a
tag — `{"$date": "not a date"}` above — says so with `$raw`.

A default that is outside the field's own domain is refused **at parse time**,
because a default bypasses validation everywhere downstream — an `int` field
with `"default": "seven"` would otherwise survive all the way to the database.
That includes an untagged value on a tagged domain: `"default": "42"` on a
`bigint` field is the string `"42"`, and the field's domain refuses it.
A `decimal` default is a string, `"default": "1.5"`: a JSON number is a double,
and the decimal domain refuses `"default": 1.5` the same way it refuses one in
a query.

## What the format refuses

Three things, each with a named alternative.

**Function defaults.** `.default(() => …)` is arbitrary code. Use one of the
nine `generate` kinds, a literal default, or a database-side default through
`native`.

A requested generator installs a closure of its own, so `.uuid({ generate: true })` serializes as
`"generate": { "kind": "uuid" }` with no `default`. A domain-only `.uuid()`
serializes with `"generate": { "kind": "uuid", "generate": false }`.
The nested boolean is available for string formats; omission preserves generation
in existing documents. `.id({ generate: false })` retains its disabled choice too.
`.uuid({ generate: true }).default(() => …)`
does not: the generator declaration is still in state but the function standing
in `default` is yours, and emitting `generate` there would publish a field that
produces random values where the original produced a fixed one. That is refused
by name too.

**Custom validators.** `.schema(someStandardSchema)` is arbitrary code too. A
hybrid codebase re-attaches them by field path:

```ts
import { attachFieldSchemas, parseSchema } from "viborm/schema/json";

const schema = attachFieldSchemas(parseSchema(document), {
  "user.email": z.string().email(),
});
```

`attachFieldSchemas` re-reads the schema as a document and applies each
validator through the real `.schema()` builder, last — after nullability and
arity are settled. A path that names no scalar field is refused, because a
validator nobody applies validates nothing.

**Partial-index predicates.** `indexes[].where` is refused in v1. It is the
declaration surface's only raw SQL, interpolated unescaped into DDL, and a
document written by a program is exactly the artifact that must not carry an
execution channel: anyone who can hand you a document could otherwise hand you
a statement to run. It returns when a structured predicate form exists. Until
then a partial index stays in TypeScript.

Each refusal happens in **both** directions — `serializeSchema` names the field
carrying a function default, a validator or a `where` rather than dropping it,
so a round trip can never silently produce a different schema.

## The canonical form

The canonical form of a document IS `serializeSchema(parseSchema(doc))`. Running
the pair once normalizes every builder coupling — an enum reference becomes its
database type name, a `values` bag that merely echoes its keys disappears, a
compound-constraint name equal to the default disappears — and running it again
changes nothing.

```ts
const canonical = serializeSchema(parseSchema(document));
// Two documents describe the same schema iff their canonical forms match.
```

That is also how to diff two schemas: canonicalize both, then compare.

## Validating the graph

A document can be perfectly well-formed and still describe a schema no client
will accept — a `toMany` whose target names nobody back, two models mapped to
one table, a foreign key that does not pair. Neither `parseSchema` nor
`serializeSchema` checks that by default: a document is often read to inspect,
canonicalize or diff it, and a schema is often dumped precisely because it is
broken.

Both take an options object to ask for the check:

```ts
const schema = parseSchema(document, { validate: true });
const back = serializeSchema(schema, { validate: true });
```

`validate: true` runs **the schema validator** — the same full rule list `push`
and the CLI run. It is not a second opinion about what a valid schema is; it is
the same one, called earlier.

**The two vocabularies stay separate.** A `J0xx` code describes the shape of the
**artifact** — a key the format does not define, a default outside its domain.
A graph is refused in the graph's own words: a `SchemaValidationError` carrying
`M0xx` / `R0xx` / `P0xx` issues, untranslated.

```ts
parseSchema(loneToManyDocument, { validate: true });
// SchemaValidationError: [R002] 'user.posts' has no inverse relation in 'post'
```

Where it runs differs by direction, and each has a consequence worth knowing:

| Call | When | Consequence |
| --- | --- | --- |
| `parseSchema(doc, { validate: true })` | **after** the document is interpreted | the models are name-bound under the document's own keys — the same binding `createClient` performs, so the client that follows is unaffected |
| `serializeSchema(schema, { validate: true })` | **before** anything is emitted | garbage in is refused loudly, and **the call is no longer non-mutating**: validating hydrates the passed record's keys and settles its relation targets, exactly as `createClient` would |

Leave the option off — the default — to keep `serializeSchema` a pure dump you
can point at a schema you do not own.

An unknown option is refused rather than ignored, because an option that asked
for validation and silently did not get it is worse than not asking:

```text
Validation failed for schema-json: 1 validation error
  /options/validat   [J003] Unknown option 'validat'; this call declares 'validate'
```

## Errors

Every refusal is one `ValidationError` (`V4002`) carrying every issue the
document has, each with a `J0xx` code and a JSON pointer into the document.

```text
Validation failed for schema-json: 2 validation errors
  /models/user/fields/email/uniqu   [J003] Unknown key 'uniqu'; …
  /models/user/fields/role/enum     [J006] `enum` must name a definition in `enums` …
```

| Code | Means |
| --- | --- |
| `J001` | the input is not a JSON document |
| `J002` | the `version` is not one this parser reads |
| `J003` | a node carries a key the format does not define |
| `J004` | a node is missing a required key, or a value has the wrong shape |
| `J005` | a key that must be a schema identifier is not one |
| `J006` | a reference names something the document does not declare |
| `J007` | the scalar type has no such modifier |
| `J008` | a default is outside the field's own domain |
| `J009` | the document spells a surface v1 refuses |
| `J010` | a builder refused the declaration this node denotes |
| `J011` | a `native.type` (or a `nativeByDialect` entry's `type`) is not in the declared dialect's native type catalog |

Anything the document itself can be wrong about is reported **all at once**.
Anything semantic — a foreign key that does not pair, a graph that does not
resolve — is refused by the builder or the resolution gate that owns it, with
the document location attached, and keeps its own code: see [Validating the
graph](#validating-the-graph).

An unknown `version` is refused by name. A document key never changes meaning
between versions; evolution only adds keys.

## The untyped client

```ts
import type { UntypedClient } from "viborm/schema/json";
```

A parsed schema is `Record<string, Model<any>>`, so the client built from it
cannot know model names or field shapes. What survives, measured:

- **model access is stringly and possibly-undefined** — write
  `db.user?.findMany(…)`;
- **the operation set stays exact** — `findMani` is still a type error;
- **clause keys are still refused** — a loose model publishes no field clauses,
  so an unknown one does not silently pass;
- **results are an empty row** — reading a field off one is a type error.

`UntypedClient` is not a supertype to which every concrete client can be
assigned; it does not make field clauses `any`. Keep a literal TypeScript schema
when application queries need static field and result types. Runtime validation
is unaffected: the validators are built from the real schema state,
so a bad payload is refused exactly as it would be for a typed client.

## One document per tenant

When each tenant's schema is a stored document (the whole setup, with
migrations from a Durable Object, is in
[Per-tenant schemas from Durable Objects](/docs/migration/per-tenant-schemas-durable-objects)):

- **Store the text, with its key order.** Keep the document as text or `json`,
  not PostgreSQL `jsonb`, which reorders object keys. A reordered document
  migrates as a `noop`, but the next table it creates, or SQLite rebuilds,
  takes the reordered column order.
- **Parse once per document.** `parseSchema` builds a fresh graph on every
  call, and clients built over the same schema object share its validation,
  registries and prepared queries. Cache one parsed `Schema` per tenant and
  document hash, validated once with `{ validate: true }`, and build each
  client over it with `skipSchemaValidation: true`.

```ts
import { parseSchema, type Schema } from "viborm/schema/json";
import { createClient } from "viborm/pg";

const schemas = new Map<string, Schema>(); // key: `${tenant}:${documentHash}`

function tenantSchema(tenant: string, documentHash: string, text: string) {
  const key = `${tenant}:${documentHash}`;
  let schema = schemas.get(key);
  if (!schema) {
    schema = parseSchema(text, { validate: true });
    schemas.set(key, schema);
  }
  return schema;
}

const db = createClient({
  pool,
  schema: tenantSchema(tenant, documentHash, text),
  skipSchemaValidation: true,
});
```

## Dialect neutrality

The document is dialect-neutral exactly as far as the builders are. A decimal
node declares `precision` and `scale`, the same descriptor passed to
`s.decimal({ precision, scale })`; it must not carry `native`. The interpreter
derives `NUMERIC(p,s)`, `DECIMAL(p,s)`, or checked scaled `INTEGER` when the
schema binds to a provider.

## Client configuration is not in the document

`omit` at the client level, cache and extensions are **client** configuration,
not schema declaration. Decimal precision and scale are schema facts and do
belong in the document. The client is still constructed in code.
