Custom field types
WeaveKit ships a fixed set of built-in field types (see Schema).
WeaveKit ships a fixed set of built-in field types (see Schema). These fall
into two buckets: PG-native value types (string…jsonb) and custom types (enum,
relation, image, currency, user, …). The custom ones are built-in registrations — the engine
ships them through the same mechanism you use below. When a project needs a business type the built-ins
don't cover (address, rating, …), you can register your own custom field type without patching
the engine.
A registered type is a thin, declarative layer over a built-in primitive: you declare a base,
and the engine inherits storage, TypeScript generation, OpenAPI schemas and describe behaviour from
it. Registered types are project-local and committed to Git, so every environment resolves the same
set — schemas stay reproducible.
Naming: the namespace rule
- Bare names are reserved for the engine (
string,currency,seq_no,user, …). A registration cannot use one. - Registered types must be namespaced:
<namespace>_<name>(lowercase snake_case). This keeps user/plugin types from ever colliding with built-ins — now or in a future release. x_is the conventional namespace for one-off project types; plugins use their own (acme_money).
Declaring a registration
A registration module lives under field-types/ and default-exports a registration (or an array):
// field-types/acme.ts
import type { FieldTypeRegistration } from '@weave-kit/engine';
export default [
{ namespace: 'acme', name: 'money', base: 'number' },
{ namespace: 'acme', name: 'email', base: 'string', openApiFormat: 'email' },
{ namespace: 'acme', name: 'account', base: 'relation', relationLike: true },
] satisfies FieldTypeRegistration[];| Field | Meaning |
|---|---|
namespace | prefix auto-applied to name (acme + money → acme_money) |
name | the type name (without the namespace, or already prefixed) |
base | required; the built-in primitive to inherit from (a value primitive, or relation) |
scalar | a scalar value type (defaults from base) |
keyEligible | eligible as a primary key (defaults from base; json/jsonb/interval/real/double are scalar but not key-eligible) |
relationLike | carries a target (defaults from base) |
ui | frontend hint, e.g. { visual: 'image' } (never a widget — the engine is headless) |
openApiFormat | OpenAPI format keyword for string-based types (email, uri, …) |
attrs | typed extra attributes a field of this type accepts: { <name>: { type, values?, required?, default? } } (validated, fail-closed) |
storage | custom column mapping: { pgType: (field) => string } (output safety-checked; non-relation bases only) |
validate | pure, synchronous write-time check (field, value) => string | undefined (non-relation bases only) |
reverse | optional introspect hint: { pgType: 'NUMERIC(12,2)' } maps a matching live column back to this type |
Allowed bases: string, text, char, smallint, integer, bigint, number, real,
double, currency, boolean, date, time, timetz, timestamp, timestamptz, interval,
uuid, json, jsonb, relation. The structural types (enum, details, multiRelation,
seq_no) and the semantic types (image, user, department) are not valid bases.
Enabling registrations
Point the engine at the directory (and/or inline entries) in weavekit.config.ts:
export default {
schemaDir: '.',
fieldTypes: { dir: 'field-types' }, // relative to schemaDir
features: {
// the whitelist also gates registered types by name
fieldTypes: ['string', 'integer', 'number', 'currency', 'acme_money'],
},
};The effective registry is compiled once at load: built-ins + registrations. It is passed through
validation and every consumer (explicit injection — there is no mutable global). A schema using a
type that is not registered fails closed with field.type.unknown; one outside
features.fieldTypes fails with field.type.disabled.
Using a registered type
Once registered, a type is just a type:
// objects/invoice/schema.json
{
"schemaVersion": 6,
"name": "invoice",
"fields": [
{ "name": "id", "type": "string", "primary": true },
{ "name": "amount", "type": "acme_money", "required": true },
{ "name": "billing_email", "type": "acme_email" }
]
}acme_money stores as NUMERIC, appears as number in generated TypeScript, and as
{ "type": "number" } in OpenAPI — all inherited from base: "number".
Beyond the base: attrs, storage & validation
A registered type can go beyond inheriting its base:
attrs— declare typed extra attributes. The engine validates each field value at schema load (field.attr.type/field.attr.enum/field.attr.required) and preserves the values on the field. AnAttrSpec.defaultis validated against itstype(andvaluesforenum) at load; it is not injected into fields (it is documentation/tooling only). The base primitive's own attributes (min/max/minLength/maxLength/regex/precision) are inherited automatically and enforced at write time.describe_object(and the REST metadata endpoint) surface each declared attr together with its type's spec —{ value?, type, values?, default?, description? }— so clients and agents can interpret values without knowing the type in code. Only registered attributes are exposed;storage/validateinternals never are.- resolved
base— the metadata contract (describe_object/ the REST metadata endpoint) carriesbasefor any field whose type delegates to a primitive — a registeredacme_moneyreportsbase: "number", and built-ins report theirs too (email → "string",user → "relation"). It is neutral data semantics, not a widget: it lets a front-end map any type to a built-in control without the engine ever emitting UI hints. storage.pgType— map the field to a custom PostgreSQL column type. The function is pure; its output is checked against a safe grammar (a known type with optional size and[]) before it reaches DDL, and an unsafe value fails closed (fieldtype.storage.invalid). Relation-like types cannot override storage (the column type follows the FK target).validate— a pure, synchronous write-time check. Return a human-readable detail to reject the value (data.field.custom, whose detail string is passed through verbatim), orundefinedto allow. No I/O: cross-record or database-backed rules belong to server hooks or a data-drivenenum(options.from).
// field-types/acme.ts
import type { FieldTypeRegistration } from '@weave-kit/engine';
export default [
{
namespace: 'acme',
name: 'money',
base: 'number',
attrs: { currency: { type: 'string', required: true }, scale: { type: 'integer', default: 2 } },
storage: { pgType: (f) => `NUMERIC(12,${(f as { scale?: number }).scale ?? 2})` },
},
{
namespace: 'acme',
name: 'iso3',
base: 'string',
validate: (_f, v) => (typeof v === 'string' && v.length === 3 ? undefined : 'must be a 3-letter code'),
},
] satisfies FieldTypeRegistration[];Custom
pgTypeaffects new tables and the drift report (weave schema:map). Migrations are additive-only — a changed mapping is reported astypedrift, never auto-ALTERed.
Production builds
weave dev loads field-types/*.ts directly. For production, weave build compiles them to
dist/field-types/*.js; point the engine at the compiled output:
export default { fieldTypes: { dir: 'dist/field-types' } };Existing databases (brownfield)
Registered types are a forward authoring concept; the engine does not reverse-infer them unless
you give a registration a reverse hint.
- With a
reversehint —{ pgType: 'NUMERIC(12,2)' }—weave introspectmaps a live column whose PostgreSQL type matches back to the registered type, so the generatedschema.jsonalready carries it. If several registrations match one column, the primitive is kept and a warning is emitted (no ambiguity failure). Relation columns are never reverse-mapped. - Without a hint —
weave introspectreverse-models live tables into built-in types only. Hand-edit the generatedschema.jsonto switch a field to a registered type; generated files are kept unless you pass--force. - The existing column must be compatible with the registration's
basestorage (e.g.NUMERICforbase: "number").weave migrateon an existing table only checks that the column exists and never alters its type;weave schema:mapreports atypedrift if the column doesn't match.
Limits
validatemust be pure and synchronous (no I/O). Database-backed or cross-record rules belong to server hooks, a data-drivenenum(options.from), or custom tools.storagemaps the column type only; there is no custom SQLDEFAULT(the basedefaultis used) and no custom type-change migration (additive-only).- Registered types have a single-column shape: a value base is scalar (PK-eligible), a
relationbase is relation-like (carries atarget). There is nomultiple/array form — model a related object or use a built-in multi-value type instead. - Reverse inference (
introspect) requires an explicitreversehint; without one, registered types are forward-authoring only.