---
title: Schema Validation
description: When relation and schema rules run during client construction, push, migrate, and explicit validation
icon: shield-check
---

Schema validation checks your models for structural errors — missing IDs, broken
foreign keys, invalid referential actions, and database-specific constraints —
before anything touches the database. The complete rule set runs automatically
on `viborm push` and `viborm migrate`.

Client construction always runs the **structural gate** — the schema-wide
relation resolver that pairs every slot, decides foreign-key ownership,
uniqueness and junction topology, and materializes private variant storage —
plus the model-identity checks a client needs to address a model at all
(duplicate model name, duplicate table) and the selector checks every query
relies on (a compound key name that reuses a member name, a member named
`_count` or `_distance`). Advice about how a schema is *spelled*
— a missing ID field, a reserved model name, an index shape — belongs to the
boundary that writes DDL, so it runs on `push` and `migrate` rather than at
client construction.
Manual validation remains useful when you want all errors surfaced explicitly
at application startup.

## Manual Validation

```ts
import { validateSchema, validateSchemaOrThrow } from "viborm";
import * as schema from "./schema";

// Throws with all error messages if the schema is invalid (good for startup)
validateSchemaOrThrow(schema);

// Or inspect the result yourself
const result = validateSchema(schema);
if (!result.valid) {
  for (const error of result.errors) {
    console.log(`[${error.code}] ${error.message}`);
  }
}
for (const warning of result.warnings) {
  console.log(`[${warning.code}] Warning: ${warning.message}`);
}
```

`validateSchema(models)` returns `{ valid, errors, warnings }`, where each entry has a `code`, a `severity` (`"error" | "warning"`), and a human-readable `message`. `validateSchemaOrThrow(models)` throws an `Error` listing every failed check.

## Example Errors

```
[M001] 'user' must have an ID field (or use .id() for compound key)
[F006] ID 'id' in 'user' cannot be nullable
[F004] Default value for 'age' in 'user' doesn't match type
[R002] 'user.profile' has no inverse relation in 'profile'
```
