---
title: L3 - Operation Schemas
description: Validation schemas generated for where, create, update, and args operations
icon: filter
---

**Location:** `src/validation/model/`, `src/validation/relations/`

## Why This Layer Exists

VibORM validates query inputs at runtime:

```typescript
orm.user.findMany({
  where: { email: { contains: "@example.com" } },  // Validated!
  include: { posts: true },                         // Validated!
});
```

Operation schemas define what's valid for each operation. They're built dynamically by `SchemaRegistry` from model definitions.

## Schema Categories

### Core Schemas (Per Scalar)

Each scalar type generates its own schemas:

| Schema | Purpose | Example |
|--------|---------|---------|
| **Base** | Raw input validation | `string` or `null` |
| **Filter** | Where clause operators | `{ contains: string }` |
| **Create** | Create operation input | Required unless defaulted |
| **Update** | Update operation input | Optional, can be `null` |

### Args Schemas (Per Model)

The validation registry composes scalar, relation, and model state into operation schemas:

| Schema | Purpose |
|--------|---------|
| **WhereSchema** | Full `where` clause with all fields |
| **CreateDataSchema** | Full `data` for create operations |
| **UpdateDataSchema** | Full `data` for update operations |
| **FindArgs** | `where` + `select` + `include` + `orderBy` |
| **CreateArgs** | `data` with nested relation creates |
| **UpdateArgs** | `where` + `data` with nested writes |

## Dynamic Schema Generation

Schemas are generated based on scalar state:

```typescript
// If scalar is nullable + has default:
// - Filter: allows null comparisons
// - Create: optional (has default)  
// - Update: accepts null or value
```

The logic considers:
- Is the scalar nullable?
- Does it have a default value?
- Is it an auto-generated scalar (UUID, timestamps)?
- Is it optional vs required?

## Handling Relations

Relations add complexity because queries can be nested:

```typescript
orm.user.findMany({
  where: {
    posts: { some: { published: true } }  // Nested where
  },
  include: {
    posts: {
      where: { published: true },  // Nested filter
      select: { title: true }      // Nested select
    }
  }
});
```

Operation schemas handle this with recursive definitions using thunks to avoid infinite loops.

## Why Registry Building?

Schemas are expensive to construct and nested relation inputs need full model graph context. VibORM builds them through `SchemaRegistry`:

```typescript
const registry = createSchemaRegistry({ user });
registry.proxy.user.core.where; // Built through registry access, then cached
```

This keeps schema definitions focused on structure while operation validation stays centralized.

## Keys an Extension Adds

Operation schemas belong to the schema and are shared by every client over
it, so no extension rewrites them. A client's extensions still make a call
accept what the schema alone would refuse, through the context of that one
parse (`parseProviding`): a projection key a `facts` declares (`$access`) in
`select` and `include`, and a required field a `defaults` part writes, which
the caller's `data` may then leave out. An object built with the `provides`
option admits, inside that synchronous parse only, the keys the context
lists under its name, with the validator the context gives. A projection key
is therefore validated where the caller wrote it and keeps that place in the
result; `select: { $access: false }` alone is an empty `select` and refused
like one; and since a `select` and a create's `data` are provided under
different names, no `data` admits a projection key.

## Boundary With the Query Engine

An operation schema is the trust boundary for public query input. Its output can
contain defaults, normalized shorthands, and transformed values, so the query
engine treats that output as a domain value rather than reparsing the caller's
raw object.

For nested writes, L6 separates scalar fields from relation payloads. As soon as
a relation payload is schema-transformed, it becomes a
`RelationMutationProgram`. The program preserves mutation-kind order, source
array order, duplicates, and explicit values such as `set: []`. OwnWrite
analysis and relation emitters consume the same program.

This gives the validation transform one owner and one execution. Downstream
compilers do not assume that a transform is idempotent.

## Connection to Other Layers

- **L1 (Validation)**: Operation schemas use `v.*` primitives and `SchemaRegistry`
- **L2 (Scalars)**: Scalar base schemas and state feed registry scalar schemas
- **L4 (Relations)**: Relation state feeds nested operation schemas
- **L6 (Query Engine)**: Validates at the operation boundary, then compiles the schema-transformed values without reparsing them
