@pylon/schema-core

Standard abstraction layer for schema definition: FieldType, BaseFieldDef, Semantics, defineEnum.

Consumed by:

• @pylon/mysql-schema — column/table DSL (col(), defineTable()), DDL & enum generation
• @pylon/dsl-dto — DTO field definitions

FieldType

| FieldType | MySQL type (via @pylon/mysql-schema) | Notes | |-----------|---------------------------------------|-------| | INT | INT | integer columns | | REAL | DECIMAL(precision, scale) | money/rate columns | | STRING | VARCHAR(max) | text columns | | ENUM | VARCHAR(20) | stored as string, never MySQL ENUM; enum: references a defineEnum | | BOOLEAN | — | | | DATE | DATE | date only | | DATETIME | DATETIME | date + time | | ARRAY | — | |

Column rules

Empty-string default rule

default: '' is not allowed. A column default is either:

1. a real business value — e.g. 'enabled', '0', '#FF6B35', 'CURRENT_TIMESTAMP'; or
2. nullable: true — the column allows NULL, meaning "no value yet" (optional data).

An empty-string default has no distinguishable business meaning: it cannot be told apart from "not provided" once written, and it hides whether the data is optional or required-but-unset.

Mapping guidance:

| Intent | Declare as | |--------|-----------| | Optional data, value may be absent | nullable: true | | Required data with a sensible default | default: '<real value>' | | Auto-generated timestamp | default: 'CURRENT_TIMESTAMP' |

If a genuinely special case requires an empty-string default, document the business reason in the column description — but the col() factory rejects it by default (see @pylon/mysql-schema col()).

nullable vs default

• nullable: true → column allows NULL; omitting the column on INSERT stores NULL.
• default: '<value>' → column is NOT NULL; omitting the column on INSERT stores the default.

They are not interchangeable in the database model: NULL means "no value", '' means "an empty string value". Prefer NULL for absent data.

Enum definitions

import { defineEnum } from '@pylon/schema-core';

export const OrderStatus = defineEnum('OrderStatus', {
  PENDING: { value: 'pending', label: '待处理' },
  DONE:    { value: 'done', label: '已完成' },
});

Enums are referenced by col({ type: FieldType.ENUM, enum: OrderStatus }) — stored as VARCHAR, generated into TS enum products by @pylon/mysql-schema generate-enums.

Semantics

Semantic codes annotate a column's business meaning (see semantics.ts). Project-specific semantics are defined in schema/semantics.ts and layered over the standard set.