typebox-model-schema

Files (1)

• SKILL.md

SKILL.md (first lines)

# TypeBox Model Schema Skill

Use this skill when:
- creating a new model schema file
- adding fields or commands to an existing model
- replacing manual interfaces with TypeBox schemas
- designing the shape of list, form, picker, and payload data

## TypeBox

Library: [`@sinclair/typebox`](https://github.com/sinclairzx81/typebox)  
Import: `import { Type, type Static } from "@sinclair/typebox";`

TypeBox schemas are standard JSON Schema objects with TypeScript types derived via `Static<typeof Schema>`. They work at runtime (validation) and compile time (types) from a single definition.

## Core principle

One `<model>.schema.ts` file is the single source of truth for:
- TypeScript types (via `Static<>`)
- Backend payload validation
- SQL function contract documentation
- Frontend form fields, list columns, and picker display

No separate hand-written interfaces alongside TypeBox schemas. Every shape is a TypeBox schema.

## Primary key rules

- **Default**: `bigint generated by default as identity` starting at **100**.  
  Starting at 100 leaves room for seed/reference data inserted with explicit ids (1–99).
- **In JSON/TypeScript**: bigint travels as `string` to avoid JS number precision loss.  
  Use `Type.String()` for the `id` field in all schemas — annotate with `"x-db-type": "bigint"` to document the DB type.
- **UUID**: only when the entity genuinely needs a non-sequential, globally unique identifier  
  (e.g. external integrations, distributed generation, public-facing tokens).  
  Do not use UUID for ordinary catalog or document models.
- The `id` field in `ItemSchema` is always `Type.Union([Type.String(), Type.Null()])` —  
  `null` means new record, string means existing record.
- Reference fields (foreign keys) that point to another model's bigint id are `Type.String()` in TypeScript, `bigint` in SQL.

### SQL pattern for bigint identity starting at 100

The schema name in SQL comes from the `schema` field in the model's `manifest.json`.  
The table and function names use the `model` field from the same file.

```json
{ "model": "bank", "type": "catalog", "schema": "app" }
```

```sql
-- table: {schema}.{model}
create table if not exists app.bank (
  id bigint generated by default as identity (start with 100) primary key,
  ...
);

-- functions: {schema}.{model}_{command}
-- app.bank_list, app.bank_get, app.bank_save, app.bank_delete, app.bank_lookup
```

## Shared base types

Import common framework contracts from the client shared schema — do not redefine
them per model:

```ts
import { type SortDir } from "@client/shared/schema.ts";
```

What that module holds (it lives in the `@altera/client` package, not in the app —
the app depends on the framework, never the reverse):

```ts
// @client/shared/schema.ts
import { Type, type Static } from "@sinclair/typebox";

export const SortDirSchema = Type.Union([Type.Literal("asc"), Type.Literal("desc")]);
export type SortDir = Static<typeof SortDirSchema>;

// плюс Query/Totals (контракт списку) і DocumentHeader (шапка документа)
```

## Field annotations

Standard JSON Schema annotations drive both validation and UI:

| Annotation      | Purpose                                      |
|-----------------|----------------------------------------------|
| `title`         | Field label in forms and list column headers |
| `description`   | Tooltip / help text                          |
| `minLength`     | Minimum string length (also form validation) |
| `maxLength`     | Maximum string length                        |
| `minimum`       | Minimum numeric value                        |
| `maximum`       | Maximum numeric value                        |
| `format`        | `"date"`, `"date-time"`, `"email"` — drives input type |
| `default`       | Default value for new record                 |

Custom UI annotations (prefix `x-`):

| Annotation   | Values                          | Purpose                              |
|--------------|---------------------------------|--------------------------------------|
| `x-form`     | `true` or `{ order, width }`    | Include field in the generated form  |
| `x-list`     | `true` or `{ width, sortable }` | Include field as a list column       |
| `x-lookup`   | `true`                          | Include field in picker display/search |
| `x-picker`   | `{ url, displayField }`         | Field is a reference — render ui-picker |
| `x-readonly` | `true`                          | Display only, not editable           |
| `x-filter`   | `true` or `{ op, key }`         | Field can filter the list — generates the SQL (see below) |
| `x-transient`| `true`                          | Field exists in the form type but has no column — the generator ignores it entirely |
| `x-secret`   | `true`                          | A secret (bank API token, service key): no column, kept encrypted in `app.secret` by the runtime, never returned — see below |

### `x-secret` — a secret the server keeps and never returns

```ts
token:          Type.Optional(Type.Union([Type.String(), Type.Null()], { "x-secret": true })),
tokenSet:       Type.Optional(Type.Boolean({ "x-transient": true })),
tokenChangedAt: Type.Optional(Type.Union([Type.String(), Type.Null()], { "x-transient": true })),
```

- **There is no column for it** — do not write one in `db/struc.sql`. The generator skips the field; the runtime takes it out of `save` before your SQL function runs and stores it encrypted (`SECRET_KEY`) in the core table `app.secret`. Add `"@core/secret"` to `app/sql.json` — `sql:registry` refuses without it.
- **The value in the model is an intent, not the secret**: absent or `""` — keep, a string — replace, `null` — clear. `get` and `save` answer with `<field>Set` and `<field>ChangedAt` only; `list`, export, print and the agent channel never see the field at all.
- **Only a TS command of the same model reads it** — `await ctx.secret(id, "token")`. SQL has no key and cannot decrypt.

From IgorAIvanov/altera03, MIT.

More from IgorAIvanov/altera03