JSON schemas
Define a schema as a JSON document — the surface for programmatic and agent-written schemas
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.
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
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 document
version and models are required. Every other key is optional.
{
"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 })
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; 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 |
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:
{
"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 themselves produce:
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.
{
"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:
{
"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:
{
"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:
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.
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:
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.
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:
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.
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.
An unknown version is refused by name. A document key never changes meaning
between versions; evolution only adds keys.
The untyped client
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 —
findManiis 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):
- Store the text, with its key order. Keep the document as text or
json, not PostgreSQLjsonb, which reorders object keys. A reordered document migrates as anoop, but the next table it creates, or SQLite rebuilds, takes the reordered column order. - Parse once per document.
parseSchemabuilds a fresh graph on every call, and clients built over the same schema object share its validation, registries and prepared queries. Cache one parsedSchemaper tenant and document hash, validated once with{ validate: true }, and build each client over it withskipSchemaValidation: true.
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.