db-model-router 1.0.10 → 1.0.11

package/docs/dbmr-schema-spec.md

@@ -1,393 +1,597 @@
-# dbmr.schema.json — Column Rule Specification
-
-This document defines the full column rule syntax for `dbmr.schema.json`. Column rules are pipe-delimited strings that describe the **data type**, **sub-type**, and **validation constraints** for each column.
-
----
-
-## Syntax
-
-```
-[required|]<type>[:<subtype>][|<validator>[|<validator>...]]
-```
-
-**Parts:**
-
-| Part        | Required | Description                                                    |
-| ----------- | -------- | -------------------------------------------------------------- |
-| `required`  | No       | Prefix — marks column as NOT NULL                              |
-| `type`      | Yes      | Base data type (see table below)                               |
-| `:subtype`  | No       | Colon-suffixed sub-type for finer SQL type control             |
-| `validator` | No       | One or more validation rules (node-input-validator compatible) |
-
-**Examples:**
-
-```
-"name": "required|string"                          # VARCHAR(255) NOT NULL
-"description": "string:text"                       # TEXT, nullable
-"body": "required|string:longtext"                 # LONGTEXT NOT NULL
-"email": "required|string|email|maxLength:255"     # VARCHAR(255) NOT NULL + email validation
-"phone": "string|phoneNumber"                      # VARCHAR(255) + phone validation
-"stock": "required|integer:unsigned"               # INT UNSIGNED NOT NULL
-"view_count": "integer:bigint"                     # BIGINT, nullable
-"price": "required|numeric:decimal(10,4)"          # DECIMAL(10,4) NOT NULL
-"rating": "required|integer|min:1|max:5"           # INTEGER NOT NULL + range validation
-"slug": "required|string|regex:^[a-z0-9-]+$"      # VARCHAR(255) NOT NULL + pattern validation
-```
-
----
-
-## Base Types
-
-| Type             | Default SQL Type | Description                    |
-| ---------------- | ---------------- | ------------------------------ |
-| `auto_increment` | SERIAL / INT AI  | Auto-incrementing primary key  |
-| `string`         | VARCHAR(255)     | Text/string columns            |
-| `integer`        | INTEGER          | Whole number columns           |
-| `numeric`        | DECIMAL(12,2)    | Decimal/floating-point columns |
-| `boolean`        | BOOLEAN          | True/false columns             |
-| `datetime`       | TIMESTAMP        | Date and time columns          |
-| `object`         | JSON / JSONB     | JSON data columns              |
-
----
-
-## Sub-Types (colon syntax)
-
-Sub-types refine the SQL column type generated for each adapter. If no sub-type is specified, the default mapping is used.
-
-### String Sub-Types
-
-| Sub-Type     | MySQL / MariaDB | PostgreSQL   | SQLite3 | MSSQL            | Oracle        |
-| ------------ | --------------- | ------------ | ------- | ---------------- | ------------- |
-| _(default)_  | VARCHAR(255)    | VARCHAR(255) | TEXT    | NVARCHAR(255)    | VARCHAR2(255) |
-| `text`       | TEXT            | TEXT         | TEXT    | NVARCHAR(MAX)    | CLOB          |
-| `mediumtext` | MEDIUMTEXT      | TEXT         | TEXT    | NVARCHAR(MAX)    | CLOB          |
-| `longtext`   | LONGTEXT        | TEXT         | TEXT    | NVARCHAR(MAX)    | CLOB          |
-| `char`       | CHAR(255)       | CHAR(255)    | TEXT    | NCHAR(255)       | CHAR(255)     |
-| `char(N)`    | CHAR(N)         | CHAR(N)      | TEXT    | NCHAR(N)         | CHAR(N)       |
-| `varchar(N)` | VARCHAR(N)      | VARCHAR(N)   | TEXT    | NVARCHAR(N)      | VARCHAR2(N)   |
-| `uuid`       | CHAR(36)        | UUID         | TEXT    | UNIQUEIDENTIFIER | CHAR(36)      |
-
-**Usage:**
-
-```json
-"description": "string:text"
-"content": "required|string:longtext"
-"code": "string:char(10)"
-"external_id": "string:uuid"
-"title": "required|string:varchar(500)"
-```
-
-### Integer Sub-Types
-
-| Sub-Type          | MySQL / MariaDB | PostgreSQL | SQLite3 | MSSQL    | Oracle     |
-| ----------------- | --------------- | ---------- | ------- | -------- | ---------- |
-| _(default)_       | INT             | INTEGER    | INTEGER | INT      | NUMBER(10) |
-| `tinyint`         | TINYINT         | SMALLINT   | INTEGER | TINYINT  | NUMBER(3)  |
-| `smallint`        | SMALLINT        | SMALLINT   | INTEGER | SMALLINT | NUMBER(5)  |
-| `bigint`          | BIGINT          | BIGINT     | INTEGER | BIGINT   | NUMBER(19) |
-| `unsigned`        | INT UNSIGNED    | INTEGER    | INTEGER | INT      | NUMBER(10) |
-| `bigint_unsigned` | BIGINT UNSIGNED | BIGINT     | INTEGER | BIGINT   | NUMBER(19) |
-
-**Usage:**
-
-```json
-"stock_quantity": "required|integer:unsigned"
-"view_count": "integer:bigint"
-"flags": "integer:tinyint"
-"population": "integer:bigint_unsigned"
-```
-
-### Numeric Sub-Types
-
-| Sub-Type       | MySQL / MariaDB | PostgreSQL       | SQLite3 | MSSQL         | Oracle        |
-| -------------- | --------------- | ---------------- | ------- | ------------- | ------------- |
-| _(default)_    | DECIMAL(12,2)   | DECIMAL(12,2)    | REAL    | DECIMAL(12,2) | NUMBER(12,2)  |
-| `float`        | FLOAT           | REAL             | REAL    | FLOAT         | FLOAT         |
-| `double`       | DOUBLE          | DOUBLE PRECISION | REAL    | FLOAT         | BINARY_DOUBLE |
-| `decimal(P,S)` | DECIMAL(P,S)    | DECIMAL(P,S)     | REAL    | DECIMAL(P,S)  | NUMBER(P,S)   |
-| `money`        | DECIMAL(19,4)   | MONEY            | REAL    | MONEY         | NUMBER(19,4)  |
-
-**Usage:**
-
-```json
-"price": "required|numeric:decimal(10,4)"
-"weight": "numeric:float"
-"latitude": "numeric:double"
-"balance": "required|numeric:money"
-```
-
----
-
-## Validation Rules
-
-Validation rules are appended after the type (and optional sub-type) using the pipe `|` separator. These map directly to [node-input-validator](https://www.npmjs.com/package/node-input-validator) rules and are enforced at the API layer during insert/update operations.
-
-### Available Validators
-
-| Validator             | Description                              | Example                          |
-| --------------------- | ---------------------------------------- | -------------------------------- |
-| `email`               | Must be a valid email address            | `string\|email`                  |
-| `phoneNumber`         | Must be a valid phone number             | `string\|phoneNumber`            |
-| `url`                 | Must be a valid URL                      | `string\|url`                    |
-| `ip`                  | Must be a valid IP address               | `string\|ip`                     |
-| `minLength:N`         | Minimum string length                    | `string\|minLength:3`            |
-| `maxLength:N`         | Maximum string length                    | `string\|maxLength:100`          |
-| `lengthBetween:N1,N2` | String length must be between N1 and N2  | `string\|lengthBetween:3,50`     |
-| `min:N`               | Minimum numeric value                    | `integer\|min:0`                 |
-| `max:N`               | Maximum numeric value                    | `integer\|max:100`               |
-| `between:N1,N2`       | Numeric value must be between N1 and N2  | `integer\|between:1,5`           |
-| `regex:PATTERN`       | Must match the regex pattern             | `string\|regex:^[a-z0-9-]+$`     |
-| `alpha`               | Only alphabetic characters               | `string\|alpha`                  |
-| `alphaNumeric`        | Only alphanumeric characters             | `string\|alphaNumeric`           |
-| `alphaDash`           | Alphanumeric, dashes, and underscores    | `string\|alphaDash`              |
-| `in:val1,val2,...`    | Must be one of the listed values (enum)  | `string\|in:active,inactive`     |
-| `notIn:val1,val2,...` | Must NOT be one of the listed values     | `string\|notIn:banned,suspended` |
-| `digits:N`            | Must be exactly N digits                 | `string\|digits:6`               |
-| `digitsBetween:N1,N2` | Digit count must be between N1 and N2    | `string\|digitsBetween:4,8`      |
-| `dateFormat:FORMAT`   | Must match date format (e.g. YYYY-MM-DD) | `string\|dateFormat:YYYY-MM-DD`  |
-| `json`                | Must be valid JSON string                | `string\|json`                   |
-| `same:field`          | Must match another field's value         | `string\|same:password`          |
-| `different:field`     | Must differ from another field's value   | `string\|different:old_email`    |
-
-### Validation Rule Parsing
-
-The parser distinguishes between **type/sub-type tokens** and **validation tokens**:
-
-1. `required` — always a modifier (NOT NULL)
-2. First non-`required` token — the **base type** (string, integer, numeric, boolean, object, datetime, auto_increment)
-3. If the base type contains a colon `:` — the part after `:` is the **sub-type**
-4. All remaining pipe-separated tokens — **validation rules**
-
-**Parsing example:**
-
-```
-"required|string:text|minLength:10|maxLength:5000"
-```
-
-| Token            | Role       |
-| ---------------- | ---------- |
-| `required`       | Modifier   |
-| `string:text`    | Type + Sub |
-| `minLength:10`   | Validator  |
-| `maxLength:5000` | Validator  |
-
-Result:
-
-- SQL: `TEXT NOT NULL`
-- Validation: `{ required: true, minLength: 10, maxLength: 5000 }`
-
----
-
-## Full Example Schema
-
-```json
-{
-  "adapter": "postgres",
-  "framework": "express",
-  "options": {
-    "session": "redis",
-    "rateLimiting": true,
-    "helmet": true,
-    "logger": true,
-    "loki": false
-  },
-  "tables": {
-    "products": {
-      "columns": {
-        "product_id": "auto_increment",
-        "category_id": "required|integer:unsigned",
-        "name": "required|string:varchar(300)|minLength:3|maxLength:300",
-        "slug": "required|string|regex:^[a-z0-9-]+$|maxLength:300",
-        "description": "string:text|maxLength:5000",
-        "short_description": "string:varchar(500)|maxLength:500",
-        "sku": "required|string|alphaNumeric|minLength:3|maxLength:50",
-        "price": "required|numeric:decimal(10,2)|min:0",
-        "compare_at_price": "numeric:decimal(10,2)|min:0",
-        "cost_price": "numeric:decimal(10,2)|min:0",
-        "currency": "required|string|minLength:3|maxLength:3",
-        "stock_quantity": "required|integer:unsigned|min:0",
-        "low_stock_threshold": "integer:unsigned|min:0",
-        "weight": "numeric:float|min:0",
-        "weight_unit": "string|in:kg,lb,oz,g",
-        "is_active": "boolean",
-        "is_featured": "boolean",
-        "is_deleted": "boolean",
-        "meta": "object",
-        "created_at": "datetime",
-        "modified_at": "datetime"
-      },
-      "pk": "product_id",
-      "unique": ["sku", "slug"],
-      "softDelete": "is_deleted",
-      "timestamps": {
-        "created_at": "created_at",
-        "modified_at": "modified_at"
-      },
-      "parent": null
-    },
-    "users": {
-      "columns": {
-        "user_id": "auto_increment",
-        "name": "required|string|minLength:2|maxLength:100",
-        "email": "required|string|email|maxLength:255",
-        "phone": "string|phoneNumber",
-        "password_hash": "required|string:varchar(500)",
-        "avatar_url": "string|url",
-        "bio": "string:text|maxLength:2000",
-        "age": "integer|min:13|max:150",
-        "role": "required|string|in:admin,user,moderator",
-        "login_count": "integer:unsigned|min:0",
-        "is_verified": "boolean",
-        "is_deleted": "boolean",
-        "last_login_ip": "string|ip",
-        "metadata": "object|json",
-        "created_at": "datetime",
-        "modified_at": "datetime"
-      },
-      "pk": "user_id",
-      "unique": ["email"],
-      "softDelete": "is_deleted",
-      "timestamps": {
-        "created_at": "created_at",
-        "modified_at": "modified_at"
-      },
-      "parent": null
-    },
-    "addresses": {
-      "columns": {
-        "address_id": "auto_increment",
-        "user_id": "required|integer:unsigned",
-        "label": "string|in:home,work,billing,shipping|maxLength:50",
-        "line1": "required|string|minLength:5|maxLength:255",
-        "line2": "string|maxLength:255",
-        "city": "required|string|minLength:2|maxLength:100",
-        "state": "required|string|minLength:2|maxLength:100",
-        "postal_code": "required|string|minLength:3|maxLength:20",
-        "country": "required|string|minLength:2|maxLength:2",
-        "is_default": "boolean",
-        "created_at": "datetime",
-        "modified_at": "datetime"
-      },
-      "pk": "address_id",
-      "unique": ["address_id"],
-      "timestamps": {
-        "created_at": "created_at",
-        "modified_at": "modified_at"
-      },
-      "parent": null
-    },
-    "orders": {
-      "columns": {
-        "order_id": "auto_increment",
-        "user_id": "required|integer:unsigned",
-        "order_number": "required|string|alphaDash|maxLength:50",
-        "status": "required|string|in:pending,processing,shipped,delivered,cancelled",
-        "subtotal": "required|numeric:money|min:0",
-        "tax_amount": "required|numeric:money|min:0",
-        "shipping_amount": "required|numeric:money|min:0",
-        "discount_amount": "numeric:money|min:0",
-        "total": "required|numeric:money|min:0",
-        "currency": "required|string|minLength:3|maxLength:3",
-        "notes": "string:text|maxLength:2000",
-        "created_at": "datetime",
-        "modified_at": "datetime"
-      },
-      "pk": "order_id",
-      "unique": ["order_number"],
-      "timestamps": {
-        "created_at": "created_at",
-        "modified_at": "modified_at"
-      },
-      "parent": null
-    }
-  }
-}
-```
-
----
-
-## How It Affects Code Generation
-
-### Migration Generation
-
-The sub-type controls the SQL column type in generated migrations:
-
-```sql
--- "name": "required|string:varchar(300)|minLength:3|maxLength:300"
-CREATE TABLE products (
-  name VARCHAR(300) NOT NULL,
-  ...
-);
-
--- "description": "string:text|maxLength:5000"
-CREATE TABLE products (
-  description TEXT,
-  ...
-);
-
--- "stock_quantity": "required|integer:unsigned|min:0"
-CREATE TABLE products (
-  stock_quantity INT UNSIGNED NOT NULL,  -- MySQL
-  stock_quantity INTEGER NOT NULL,       -- PostgreSQL (no unsigned)
-  ...
-);
-```
-
-### Model Generation
-
-Validation rules are extracted and passed to the model structure for runtime enforcement:
-
-```js
-// Generated model structure
-const products = model(
-  db,
-  "products",
-  {
-    name: "required|string|minLength:3|maxLength:300",
-    slug: "required|string|regex:^[a-z0-9-]+$|maxLength:300",
-    price: "required|numeric|min:0",
-    weight_unit: "string|in:kg,lb,oz,g",
-    // ...
-  },
-  "product_id",
-  ["sku", "slug"],
-  { safeDelete: "is_deleted" },
-);
-```
-
-The model passes these rules to `node-input-validator` on every insert/update/patch operation. Sub-types are stripped — only the base type and validators are kept in the runtime structure.
-
-### OpenAPI Generation
-
-Validators map to OpenAPI schema properties:
-
-| Validator       | OpenAPI Property                      |
-| --------------- | ------------------------------------- |
-| `email`         | `format: "email"`                     |
-| `url`           | `format: "uri"`                       |
-| `ip`            | `format: "ipv4"`                      |
-| `phoneNumber`   | `pattern: "^\\+?[0-9\\s\\-\\(\\)]+$"` |
-| `minLength:N`   | `minLength: N`                        |
-| `maxLength:N`   | `maxLength: N`                        |
-| `min:N`         | `minimum: N`                          |
-| `max:N`         | `maximum: N`                          |
-| `between:N1,N2` | `minimum: N1, maximum: N2`            |
-| `in:a,b,c`      | `enum: ["a", "b", "c"]`               |
-| `regex:PATTERN` | `pattern: "PATTERN"`                  |
-| `alpha`         | `pattern: "^[a-zA-Z]+$"`              |
-| `alphaNumeric`  | `pattern: "^[a-zA-Z0-9]+$"`           |
-| `alphaDash`     | `pattern: "^[a-zA-Z0-9_-]+$"`         |
-
----
-
-## Backward Compatibility
-
-The new syntax is fully backward compatible:
-
-- `"required|string"` — still works (VARCHAR(255) NOT NULL, no extra validation)
-- `"integer"` — still works (INTEGER, nullable, no extra validation)
-- `"string:text"` — new sub-type, no validation
-- `"required|string|email"` — new validation, default sub-type
-- `"required|string:text|minLength:10|maxLength:5000"` — full syntax
-
-Existing schemas without sub-types or validators continue to work unchanged.
+# dbmr.schema.json — Complete Authoritative Specification
+
+This document is the single source of truth for writing a `dbmr.schema.json` file. It covers the top-level structure, every table field, the full column rule syntax, how nested object validation works, and which tables are auto-generated by the SaaS structure so you never duplicate them. It also explains how each part of the schema drives code generation (migrations, models, OpenAPI).
+
+---
+
+## Top-Level Structure
+
+```json
+{
+  "adapter": "postgres",
+  "framework": "express",
+  "options": {
+    "session": "redis",
+    "rateLimiting": true,
+    "helmet": true,
+    "logger": true,
+    "loki": false
+  },
+  "tables": { ... },
+  "relationships": [ ... ]
+}
+```
+
+| Field           | Required | Description                                                                    |
+| --------------- | -------- | ------------------------------------------------------------------------------ |
+| `adapter`       | Yes      | Database adapter. One of: `mysql`, `mariadb`, `postgres`, `sqlite3`, `mongodb`, `mssql`, `cockroachdb`, `oracle`, `redis`, `dynamodb` |
+| `framework`     | Yes      | Express variant. One of: `express`, `ultimate-express`                           |
+| `options`       | No       | Project scaffolding options (session store, rate limiting, helmet, logger, loki) |
+| `tables`        | Yes      | Object where each key is a table name and the value is a **Table Definition**    |
+| `relationships` | No       | Array of parent-child route nesting descriptors                                |
+
+---
+
+## Table Definition
+
+Each entry in `tables` is a Table Definition object:
+
+```json
+{
+  "columns": { ... },
+  "pk": "product_id",
+  "unique": ["sku"],
+  "softDelete": "is_deleted",
+  "timestamps": {
+    "created_at": "created_at",
+    "modified_at": "modified_at"
+  },
+  "parent": null
+}
+```
+
+| Field        | Required | Description                                                                                   |
+| ------------ | -------- | --------------------------------------------------------------------------------------------- |
+| `columns`    | Yes      | **All** columns in the table, including PK, timestamps, and soft-delete. Each key is a column name; the value is a **Column Rule** string. |
+| `pk`         | Yes      | Primary key column name. Convention: `<table>_id` (e.g. `user_id`, `order_id`).                 |
+| `unique`     | No       | Array of column names with unique constraints. Defaults to `[pk]` if omitted.                   |
+| `softDelete` | No       | Column name used for soft-delete. When set, `remove()` updates this column to `1`/`true` instead of hard-deleting. |
+| `timestamps` | No       | Object mapping `{ created_at: "col_name", modified_at: "col_name" }`. These columns are auto-excluded from insert/update payloads. |
+| `parent`     | No       | Parent table name for route nesting, or `null` for a top-level route.                           |
+
+> **Important:** `columns` must list **every** column in the table, even ones that are auto-managed (PK, timestamps, soft-delete). The generator knows to exclude them from the runtime model structure, but they must be present for migration and introspection generation.
+
+---
+
+## Column Rules
+
+Column rules are pipe-delimited strings that describe the data type, sub-type, and validation constraints.
+
+### Syntax
+
+```
+[required|]<type>[:<subtype>][|<validator>[|<validator>...]]
+```
+
+**Parts:**
+
+| Part        | Required | Description                                          |
+| ----------- | -------- | ---------------------------------------------------- |
+| `required`  | No       | Prefix — marks column as NOT NULL                    |
+| `type`      | Yes      | Base data type (see Base Types table)                |
+| `:subtype`  | No       | Refines the SQL column type for migrations           |
+| `validator` | No       | Runtime validation rules (node-input-validator)        |
+
+### Base Types
+
+| Type             | Default SQL Type | Description                          |
+| ---------------- | ---------------- | ------------------------------------ |
+| `auto_increment` | SERIAL / INT AI  | Auto-incrementing primary key        |
+| `string`         | VARCHAR(255)     | Text/string columns                  |
+| `integer`        | INTEGER          | Whole number columns                 |
+| `numeric`        | DECIMAL(12,2)    | Decimal/floating-point columns       |
+| `boolean`        | BOOLEAN          | True/false columns                   |
+| `datetime`       | TIMESTAMP        | Date and time columns                |
+| `object`         | JSON / JSONB     | JSON data columns                    |
+
+### Sub-Types (colon syntax)
+
+Sub-types refine the SQL column type generated for each adapter. If no sub-type is specified, the default mapping is used.
+
+#### String Sub-Types
+
+| Sub-Type     | MySQL / MariaDB | PostgreSQL   | SQLite3 | MSSQL            | Oracle        |
+| ------------ | --------------- | ------------ | ------- | ---------------- | ------------- |
+| _(default)_  | VARCHAR(255)    | VARCHAR(255) | TEXT    | NVARCHAR(255)    | VARCHAR2(255) |
+| `text`       | TEXT            | TEXT         | TEXT    | NVARCHAR(MAX)    | CLOB          |
+| `mediumtext` | MEDIUMTEXT      | TEXT         | TEXT    | NVARCHAR(MAX)    | CLOB          |
+| `longtext`   | LONGTEXT        | TEXT         | TEXT    | NVARCHAR(MAX)    | CLOB          |
+| `char`       | CHAR(255)       | CHAR(255)    | TEXT    | NCHAR(255)       | CHAR(255)     |
+| `char(N)`    | CHAR(N)         | CHAR(N)      | TEXT    | NCHAR(N)         | CHAR(N)       |
+| `varchar(N)` | VARCHAR(N)      | VARCHAR(N)   | TEXT    | NVARCHAR(N)      | VARCHAR2(N)   |
+| `uuid`       | CHAR(36)        | UUID         | TEXT    | UNIQUEIDENTIFIER | CHAR(36)      |
+
+**Usage:**
+
+```json
+"description": "string:text"
+"content": "required|string:longtext"
+"code": "string:char(10)"
+"external_id": "string:uuid"
+"title": "required|string:varchar(500)"
+```
+
+#### Integer Sub-Types
+
+| Sub-Type          | MySQL / MariaDB | PostgreSQL | SQLite3 | MSSQL    | Oracle     |
+| ----------------- | --------------- | ---------- | ------- | -------- | ---------- |
+| _(default)_       | INT             | INTEGER    | INTEGER | INT      | NUMBER(10) |
+| `tinyint`         | TINYINT         | SMALLINT   | INTEGER | TINYINT  | NUMBER(3)  |
+| `smallint`        | SMALLINT        | SMALLINT   | INTEGER | SMALLINT | NUMBER(5)  |
+| `bigint`          | BIGINT          | BIGINT     | INTEGER | BIGINT   | NUMBER(19) |
+| `unsigned`        | INT UNSIGNED    | INTEGER    | INTEGER | INT      | NUMBER(10) |
+| `bigint_unsigned` | BIGINT UNSIGNED | BIGINT     | INTEGER | BIGINT   | NUMBER(19) |
+
+**Usage:**
+
+```json
+"stock_quantity": "required|integer:unsigned"
+"view_count": "integer:bigint"
+"flags": "integer:tinyint"
+"population": "integer:bigint_unsigned"
+```
+
+#### Numeric Sub-Types
+
+| Sub-Type       | MySQL / MariaDB | PostgreSQL       | SQLite3 | MSSQL         | Oracle        |
+| -------------- | --------------- | ---------------- | ------- | ------------- | ------------- |
+| _(default)_    | DECIMAL(12,2)   | DECIMAL(12,2)    | REAL    | DECIMAL(12,2) | NUMBER(12,2)  |
+| `float`        | FLOAT           | REAL             | REAL    | FLOAT         | FLOAT         |
+| `double`       | DOUBLE          | DOUBLE PRECISION | REAL    | FLOAT         | BINARY_DOUBLE |
+| `decimal(P,S)` | DECIMAL(P,S)    | DECIMAL(P,S)     | REAL    | DECIMAL(P,S)  | NUMBER(P,S)   |
+| `money`        | DECIMAL(19,4)   | MONEY            | REAL    | MONEY         | NUMBER(19,4)  |
+
+**Usage:**
+
+```json
+"price": "required|numeric:decimal(10,2)"
+"weight": "numeric:float"
+"latitude": "numeric:double"
+"balance": "required|numeric:money"
+```
+
+### Validation Rules
+
+Validation rules are appended after the type (and optional sub-type) using the pipe `|` separator. These map directly to [node-input-validator](https://www.npmjs.com/package/node-input-validator) rules and are enforced at the API layer during insert/update/patch operations.
+
+| Validator             | Description                             | Example                          |
+| --------------------- | --------------------------------------- | -------------------------------- |
+| `email`               | Valid email address                     | `string\|email`                |
+| `phoneNumber`         | Valid phone number                      | `string\|phoneNumber`           |
+| `url`                 | Valid URL                               | `string\|url`                   |
+| `ip`                  | Valid IP address                        | `string\|ip`                    |
+| `minLength:N`         | Minimum string length                   | `string\|minLength:3`           |
+| `maxLength:N`         | Maximum string length                   | `string\|maxLength:100`        |
+| `lengthBetween:N1,N2` | String length between N1 and N2         | `string\|lengthBetween:3,50`    |
+| `min:N`               | Minimum numeric value                   | `integer\|min:0`               |
+| `max:N`               | Maximum numeric value                   | `integer\|max:100`              |
+| `between:N1,N2`       | Numeric value between N1 and N2         | `integer\|between:1,5`         |
+| `regex:PATTERN`       | Regex pattern match                     | `string\|regex:^[a-z0-9-]+$`  |
+| `alpha`               | Only alphabetic                         | `string\|alpha`                |
+| `alphaNumeric`        | Alphanumeric                            | `string\|alphaNumeric`         |
+| `alphaDash`           | Alphanumeric, dash, underscore          | `string\|alphaDash`            |
+| `in:val1,val2`        | Enum                                    | `string\|in:active,inactive`  |
+| `notIn:val1,val2`     | Excluded enum                           | `string\|notIn:banned`         |
+| `digits:N`            | Exactly N digits                        | `string\|digits:6`              |
+| `digitsBetween:N1,N2` | Digits between N1 and N2                | `string\|digitsBetween:4,8`    |
+| `dateFormat:FORMAT`   | Date format match                       | `string\|dateFormat:YYYY-MM-DD` |
+| `json`                | Valid JSON string                       | `string\|json`                 |
+| `same:field`          | Must match another field                | `string\|same:password`        |
+| `different:field`     | Must differ from another field          | `string\|different:old_email`  |
+
+### Validation Rule Parsing
+
+The parser distinguishes between **type/sub-type tokens** and **validation tokens**:
+
+1. `required` — always a modifier (NOT NULL)
+2. First non-`required` token — the **base type** (string, integer, numeric, boolean, object, datetime, auto_increment)
+3. If the base type contains a colon `:` — the part after `:` is the **sub-type**
+4. All remaining pipe-separated tokens — **validation rules**
+
+**Parsing example:**
+
+```
+"required|string:text|minLength:10|maxLength:5000"
+```
+
+| Token            | Role       |
+| ---------------- | ---------- |
+| `required`       | Modifier   |
+| `string:text`    | Type + Sub |
+| `minLength:10`   | Validator  |
+| `maxLength:5000` | Validator  |
+
+Result:
+
+- SQL: `TEXT NOT NULL`
+- Validation: `{ required: true, minLength: 10, maxLength: 5000 }`
+
+### Full Column Rule Examples
+
+```json
+{
+  "product_id": "auto_increment",
+  "name": "required|string|minLength:3|maxLength:300",
+  "slug": "required|string|regex:^[a-z0-9-]+$|maxLength:300",
+  "description": "string:text|maxLength:5000",
+  "price": "required|numeric:decimal(10,2)|min:0",
+  "stock": "required|integer:unsigned|min:0",
+  "is_active": "boolean",
+  "metadata": "object",
+  "created_at": "datetime"
+}
+```
+
+---
+
+## Object Columns and Nested Key Validation
+
+### How Object Columns Work in the Database
+
+When a column is declared as `object`, the migration generator creates **exactly one** JSON-compatible column in the database:
+
+| Adapter       | SQL Type Created |
+| ------------- | ---------------- |
+| `postgres`    | `JSONB`          |
+| `cockroachdb` | `JSONB`          |
+| `mysql`       | `JSON`           |
+| `mariadb`     | `JSON`           |
+| `sqlite3`     | `TEXT`           |
+| `mssql`       | `NVARCHAR(MAX)`  |
+| `oracle`      | `CLOB`           |
+| `mongodb`     | Native document  |
+| `dynamodb`    | Map attribute    |
+| `redis`       | Hash field       |
+
+> **Critical:** The database table only contains the parent column (e.g., `config`). It does **not** create separate columns for sub-keys like `config.primary`, `config.secondary`, etc. The entire nested object is stored as a single JSON value.
+
+### Sub-Key Validation at the Model Layer
+
+While the database stores the object as a single JSON column, the runtime model can still validate individual keys inside the object using **dot-notation paths**. The validator (`node-input-validator`) supports nested path validation, so the generated model structure can include rules like:
+
+```js
+const products = model(
+  db,
+  "products",
+  {
+    name: "required|string|maxLength:300",
+    config: "object",
+    "config.primary": "required|string",
+    "config.secondary": "required|string",
+    "config.border_color": "string|regex:^[#a-fA-F0-9]+$",
+  },
+  "product_id",
+  ["sku"],
+  { safeDelete: "is_deleted" },
+);
+```
+
+In the schema file, this is expressed by placing dot-notation keys alongside the parent `object` column in the `columns` definition:
+
+```json
+{
+  "columns": {
+    "config": "object",
+    "config.primary": "required|string",
+    "config.secondary": "required|string",
+    "config.border_color": "string|regex:^[#a-fA-F0-9]+$"
+  }
+}
+```
+
+**What the generator does with these entries:**
+
+- **Migration (`generate-migration.js`):** Only the parent key (`config`) produces a database column. Dot-notation keys are **ignored** during table creation — they exist purely for runtime validation.
+- **Model (`schema-to-meta.js`):** Both the parent (`config: "object"`) and the dot-notation keys (`config.primary: "required|string"`) are included in the generated model structure, so the API validates nested fields on every insert/update.
+- **OpenAPI (`generate-openapi.js`):** The parent `config` is emitted as an `object` schema. Dot-notation keys are flattened into the same schema object with their types and constraints.
+
+### Rules for Object Sub-Keys
+
+1. The parent key **must** be declared as `object` (or `required|object`).
+2. Sub-keys use dot notation relative to the parent: `config.primary`, `config.secondary`.
+3. Sub-key rules follow the same syntax as top-level column rules (`required|`, type, validators), but the **type** is still required for validation clarity even though the DB column is already JSON.
+4. You can nest arbitrarily deep: `settings.theme.dark_mode.primary_color`.
+5. Sub-keys are **never** created as separate SQL columns. They are validation-only entries.
+
+---
+
+## SaaS Auto-Generated Tables
+
+When you run `db-model-router generate` (or `db-model-router init`), the **SaaS structure is generated by default** unless you explicitly disable it with `--saas-structure=false`.
+
+The following tables, middleware, routes, and seeds are scaffolded automatically. **Do NOT add these tables to your `dbmr.schema.json`** — doing so will cause duplication errors.
+
+### Auto-Generated Tables
+
+| Table              | Description                                                |
+| ------------------ | ---------------------------------------------------------- |
+| `tenants`          | Multi-tenant root entity (tenant name, domain, settings)   |
+| `users`            | User accounts with password hash, role, tenant linkage     |
+| `roles`            | Role definitions (e.g. Admin, User, Moderator)               |
+| `role_permissions` | Junction table mapping roles to permission strings           |
+| `webhooks`         | Outgoing webhook subscriptions per tenant                  |
+| `webhook_logs`     | Delivery attempt logs for webhooks                         |
+
+### Auto-Generated Middleware
+
+| File                      | Purpose                                          |
+| ------------------------- | ------------------------------------------------ |
+| `middleware/authenticate.js` | JWT / session validation                         |
+| `middleware/tenantIsolation.js` | Injects `tenant_id` from user into all queries   |
+| `middleware/hasPermission.js` | RBAC check against `role_permissions`            |
+
+### Auto-Generated Routes
+
+| Route                              | Description                          |
+| ---------------------------------- | ------------------------------------ |
+| `POST /api/auth/login`             | Login (returns JWT or session)       |
+| `POST /api/auth/logout`            | Logout                               |
+| `GET /api/users`                   | User CRUD                            |
+| `GET /api/tenants`                 | Tenant CRUD                          |
+| `GET /api/roles`                   | Role CRUD                            |
+| `GET /api/roles/:role_id/permissions` | Permission management for a role   |
+
+### Auto-Generated Utilities
+
+| File                     | Purpose                                          |
+| ------------------------ | ------------------------------------------------ |
+| `commons/password.js`    | `crypto.scrypt` password hashing                 |
+| `commons/modules.js`     | Registry of all generated models                 |
+| `commons/webhook.js`     | Webhook delivery with retry logic                |
+| `seeds/saas-seed.js`     | Super Admin user + Tenant Admin role template    |
+
+### What This Means for Your Schema
+
+**Only define your product/domain-specific tables in `dbmr.schema.json`.** Examples of tables that belong in your schema:
+
+- `products`, `orders`, `order_items`
+- `projects`, `tasks`, `comments`
+- `invoices`, `payments`, `subscriptions`
+- `categories`, `tags`, `articles`
+
+Tables that must **never** appear in your schema (because SaaS generates them):
+
+- `users`, `tenants`, `roles`, `role_permissions`
+
+> **Note:** Foreign key columns referencing SaaS tables (e.g., `user_id`, `tenant_id`) **can** and **should** appear in your schema tables. They are ordinary integer columns. Just don't define the `users` table itself.
+
+---
+
+## Relationships and Route Nesting
+
+The `relationships` array defines parent-child route nesting independent of foreign key columns.
+
+```json
+"relationships": [
+  {
+    "parent": "posts",
+    "child": "comments",
+    "foreignKey": "post_id"
+  }
+]
+```
+
+| Field        | Description                                                    |
+| ------------ | -------------------------------------------------------------- |
+| `parent`     | Parent table name. Must exist in `tables`.                   |
+| `child`      | Child table name. Must exist in `tables`.                    |
+| `foreignKey` | Column in the child table that references the parent's PK.     |
+
+### Routing Behavior
+
+- `parent: null` → Top-level routes: `GET /products/`, `GET /products/:product_id`
+- `parent: "posts"` → Nested routes: `GET /posts/:post_id/comments/`, `GET /posts/:post_id/comments/:comment_id`
+- Child routes are **also** mounted at top-level for direct access: `GET /comments/:comment_id`
+
+### Best Practice: Don't Nest System Tables
+
+Tables like `users`, `tenants`, `roles`, `permissions`, `sessions`, `accounts`, and `auth_tokens` are cross-cutting concerns. They are referenced by almost every feature module via foreign key columns (`user_id`, `tenant_id`), but they should **not** be used as `parent` values. Only use `parent` for true domain hierarchies:
+
+- `posts → comments`
+- `orders → order_items`
+- `projects → tasks`
+- `invoices → invoice_items`
+
+---
+
+## How Column Rules Affect Code Generation
+
+### Migration Generation
+
+The sub-type controls the SQL column type in generated migrations:
+
+```sql
+-- "name": "required|string:varchar(300)|minLength:3|maxLength:300"
+CREATE TABLE products (
+  name VARCHAR(300) NOT NULL,
+  ...
+);
+
+-- "description": "string:text|maxLength:5000"
+CREATE TABLE products (
+  description TEXT,
+  ...
+);
+
+-- "stock_quantity": "required|integer:unsigned|min:0"
+CREATE TABLE products (
+  stock_quantity INT UNSIGNED NOT NULL,  -- MySQL
+  stock_quantity INTEGER NOT NULL,       -- PostgreSQL (no unsigned)
+  ...
+);
+```
+
+### Model Generation
+
+Validation rules are extracted and passed to the model structure for runtime enforcement:
+
+```js
+// Generated model structure
+const products = model(
+  db,
+  "products",
+  {
+    name: "required|string|minLength:3|maxLength:300",
+    slug: "required|string|regex:^[a-z0-9-]+$|maxLength:300",
+    price: "required|numeric|min:0",
+    weight_unit: "string|in:kg,lb,oz,g",
+    // ...
+  },
+  "product_id",
+  ["sku", "slug"],
+  { safeDelete: "is_deleted" },
+);
+```
+
+The model passes these rules to `node-input-validator` on every insert/update/patch operation. Sub-types are stripped — only the base type and validators are kept in the runtime structure.
+
+### OpenAPI Generation
+
+Validators map to OpenAPI schema properties:
+
+| Validator       | OpenAPI Property                      |
+| --------------- | ------------------------------------- |
+| `email`         | `format: "email"`                     |
+| `url`           | `format: "uri"`                       |
+| `ip`            | `format: "ipv4"`                      |
+| `phoneNumber`   | `pattern: "^\\+?[0-9\\s\\-\\(\\)]+$"` |
+| `minLength:N`   | `minLength: N`                        |
+| `maxLength:N`   | `maxLength: N`                        |
+| `min:N`         | `minimum: N`                          |
+| `max:N`         | `maximum: N`                          |
+| `between:N1,N2` | `minimum: N1, maximum: N2`            |
+| `in:a,b,c`      | `enum: ["a", "b", "c"]`               |
+| `regex:PATTERN` | `pattern: "PATTERN"`                  |
+| `alpha`         | `pattern: "^[a-zA-Z]+$"`              |
+| `alphaNumeric`  | `pattern: "^[a-zA-Z0-9]+$"`           |
+| `alphaDash`     | `pattern: "^[a-zA-Z0-9_-]+$"`         |
+
+---
+
+## Complete Example Schema
+
+```json
+{
+  "adapter": "postgres",
+  "framework": "express",
+  "options": {
+    "session": "redis",
+    "rateLimiting": true,
+    "helmet": true,
+    "logger": true,
+    "loki": false
+  },
+  "tables": {
+    "products": {
+      "columns": {
+        "product_id": "auto_increment",
+        "name": "required|string|minLength:3|maxLength:300",
+        "slug": "required|string|regex:^[a-z0-9-]+$|maxLength:300",
+        "description": "string:text|maxLength:5000",
+        "price": "required|numeric:decimal(10,2)|min:0",
+        "currency": "required|string|minLength:3|maxLength:3",
+        "is_active": "boolean",
+        "config": "object",
+        "config.primary": "required|string",
+        "config.secondary": "required|string",
+        "config.border_color": "string|regex:^[#a-fA-F0-9]+$",
+        "is_deleted": "boolean",
+        "created_at": "datetime",
+        "modified_at": "datetime"
+      },
+      "pk": "product_id",
+      "unique": ["slug"],
+      "softDelete": "is_deleted",
+      "timestamps": {
+        "created_at": "created_at",
+        "modified_at": "modified_at"
+      },
+      "parent": null
+    },
+    "orders": {
+      "columns": {
+        "order_id": "auto_increment",
+        "user_id": "required|integer:unsigned",
+        "order_number": "required|string|alphaDash|maxLength:50",
+        "status": "required|string|in:pending,processing,shipped,delivered,cancelled",
+        "total": "required|numeric:money|min:0",
+        "currency": "required|string|minLength:3|maxLength:3",
+        "notes": "string:text|maxLength:2000",
+        "is_deleted": "boolean",
+        "created_at": "datetime",
+        "modified_at": "datetime"
+      },
+      "pk": "order_id",
+      "unique": ["order_number"],
+      "softDelete": "is_deleted",
+      "timestamps": {
+        "created_at": "created_at",
+        "modified_at": "modified_at"
+      },
+      "parent": null
+    },
+    "order_items": {
+      "columns": {
+        "order_item_id": "auto_increment",
+        "order_id": "required|integer:unsigned",
+        "product_id": "required|integer:unsigned",
+        "quantity": "required|integer:unsigned|min:1",
+        "unit_price": "required|numeric:money|min:0",
+        "discount_amount": "numeric:money|min:0",
+        "created_at": "datetime",
+        "modified_at": "datetime"
+      },
+      "pk": "order_item_id",
+      "unique": ["order_item_id"],
+      "timestamps": {
+        "created_at": "created_at",
+        "modified_at": "modified_at"
+      },
+      "parent": "orders"
+    }
+  },
+  "relationships": [
+    {
+      "parent": "orders",
+      "child": "order_items",
+      "foreignKey": "order_id"
+    }
+  ]
+}
+```
+
+---
+
+## Backward Compatibility
+
+The column rule syntax is fully backward compatible:
+
+- `"required|string"` — still works (VARCHAR(255) NOT NULL, no extra validation)
+- `"integer"` — still works (INTEGER, nullable, no extra validation)
+- `"string:text"` — new sub-type, no validation
+- `"required|string|email"` — new validation, default sub-type
+- `"required|string:text|minLength:10|maxLength:5000"` — full syntax
+
+Existing schemas without sub-types or validators continue to work unchanged.
+
+---
+
+## Best Practices
+
+1. **Include every column** in `columns`, even auto-managed ones (PK, timestamps, soft-delete). The generator excludes them from the model structure automatically.
+2. **Use the `<table>_id` convention** for primary keys: `user_id`, `order_id`, `product_id`.
+3. **Never define SaaS tables** (`users`, `tenants`, `roles`, `role_permissions`) in your schema. They are generated automatically.
+4. **Use `parent` only for domain hierarchies**, not for system tables.
+5. **Use `object` columns for flexible nested data**, and add dot-notation sub-keys for API-level validation without bloating the database schema.
+6. **Set `softDelete` and `timestamps`** whenever you need audit trails; the runtime handles them transparently.
+7. **Use `unique`** wisely — it drives the `upsert` conflict resolution. If a table has a natural unique key (like `sku` or `email`), include it.