参考
字段类型 你可以在对象上声明的所有字段类型 —— 存储什么、接受哪些选项、在 REST、Console 和 AI Builder 中如何呈现。
48 个内置字段类型,按家族分组。完整的 Zod schema 在
packages/spec/src/data/field.zod.ts
属性 类型 默认值 用途 namestring (snake_case) — 机器标识符 —— REST 路径段、SQL 列 labelstring — Console 中的显示标签 typeFieldType — 见下方类型表 requiredboolean falseNOT NULL 约束 uniqueboolean false唯一索引 searchableboolean false为 /api/v1/search 建索引 multipleboolean false存储值的数组 defaultValueunknown — 初始值（字面量或 CEL） hiddenboolean false在默认 Console 视图中隐藏 readonlyboolean false表单中禁用 systemboolean false自动注入（id、created_at……） externalIdboolean false可用作外部键 upsert inlineHelpTextstring — 提示/帮助文本 conditionalRequiredP 谓词— CEL 为真时必填 trackHistoryboolean false将值变更渲染为记录活动时间线上可读的条目（ADR-0052）
16.0 中已移除：columnName（物理列始终等于字段名；外部/联邦对象通过
external.columnMap 映射列）以及字段级 index 布尔值（请在对象的
indexes[] 数组中声明索引）。
类型 用途 关键选项 text短字符串 maxLength、minLengthtextarea多行 maxLengthemail邮箱 格式校验;小写化 urlURL 格式校验 phone电话 E.164 password单向密钥 由 auth 子系统哈希;GET 永不返回 secret可逆密钥（API key、token、数据库密码） 通过加密提供方在静态时加密,存为不透明引用,读取时脱敏。Fail-closed —— 未配置提供方时,写入会抛错而非以明文持久化 markdownmarkdown 正文 在 Console 预览中渲染 html清洗后的 HTML 写入时经 DOMPurify richtext所见即所得 Console 编辑器 + 序列化 JSON
类型 用途 关键选项 number浮点 min、max、precision、scalecurrency货币 currencyConfig: { precision, currencyMode: 'fixed' | 'dynamic', defaultCurrency }percent0–100 % min、max、scale
integer 和 decimal 不是独立类型 —— 整数用 number 配 scale: 0,定点小数用 precision+scale。
类型 存储 说明 date日历日期 无时区 datetime瞬时 UTC time时钟时间 无日期
类型 说明 boolean复选框 toggle等同 boolean,开关 UI
类型 说明 select单选 —— 内联声明选项或引用 picklist multiselect多选,以数组存储 radio以单选按钮渲染的 select UI 别名 checkboxes以复选框渲染的 multiselect UI 别名
选项形状：
options : [ { value: 'low' , label: 'Low' }, { value: 'high' , label: 'High' , color: '#e02' }, { value: 'urgent' , label: 'Urgent' , color: '#c00' } ] 类型 基数 语义 lookup多对一 松引用;删除父记录默认不会删除子记录 master_detail多对一,级联 子记录不能脱离父记录;权限从父继承 tree自引用 层级（同一对象上的 parent_id）
常用选项：
{ type : 'lookup' , reference : 'account' , // 目标对象名 lookupFilters : [ // 收窄查找选择器 { field: 'status' , operator: 'eq' , value: 'active' } ], deleteBehavior : 'set_null' // 'set_null' | 'cascade' | 'restrict' }
旧的字符串数组 referenceFilters 已在 16.0 移除——记录选择器只识别结构化的
lookupFilters 形式。支持的 operator 取值：eq、ne、gt、lt、gte、
lte、contains、in、notIn。
类型 作用 关键选项 formula派生值,读取或重新计算时求值 expression: F\record.qty * record.unit_price`` —— 见 CEL summary子关系上的汇总 summaryOperations: { object, field, function, filter? }（count | sum | avg | min | max；可选 filter —— 查询 where 条件，如 { status: 'received' } —— 仅聚合匹配的子行，16.0+）autonumber自动递增显示编号 format（如 TKT-{0000}）、startAt
公式示例：
{ name : 'profit_margin' , type : 'formula' , expression : F `(record.revenue - record.cost) / record.revenue * 100` } 类型 用途 关键选项 image图像附件 multiple / accept / maxSize（见下）file任意文件 同 avatar头像 方形裁剪,合理默认 video视频上传 时长 + 缩略图捕获 audio音频 波形预览
{ type : 'file' , multiple : true , // 存储附件数组 accept : [ 'image/png' , 'image/jpeg' ], // MIME 类型 / 扩展名 maxSize : 10_000_000 // 字节 }
嵌套的 fileAttachmentConfig 对象已在 16.0 移除——运行时从未读取过它。
请使用扁平的 multiple / accept / maxSize 属性。存储按部署配置
（见 Configure → Storage），而非按字段配置。
类型 存储 说明 json任意 JSON Postgres 上存为 JSONB composite带命名字段的子记录 内联结构,非独立表 repeatercomposite 值数组 无子对象的一对多
类型 说明 location经纬度 + 精度 address街/市/区/邮编/国家 code源代码字段 —— language、theme、lineNumbers colorcolorFormat: 'hex' | 'rgb' | 'rgba' | 'hsl'、presetColors[]rating1–N 星 —— max、icon slider带滑块 UI 的有界数字 signature手绘签名,存为图像 qrcode将值渲染为 QR 或条形码（EAN / UPC / Code128） progress派生百分比,以进度条渲染 tags带自动完成的自由标签数组 vector嵌入列 —— 扁平的 dimensions（如 OpenAI 嵌入为 1536）；嵌套的 vectorConfig（distanceMetric/indexed/indexType）已在 16.0 移除
字段 类型 说明 idtext (ULID) 主键 created_atdatetime UTC 插入时间 updated_atdatetime UTC 最后写入时间 created_bylookup → user 谁插入 updated_bylookup → user 谁最后写入 versioninteger 乐观并发 token
你不声明它们 —— 通过 ObjectSpec.systemFields: false 按对象退出（很少是好主意）。
*.object.ts (field spec) │ ├─► Postgres / MySQL / SQLite column + index + constraint ├─► REST: validated on POST/PATCH, exposed on GET ├─► Console: form widget + list column ├─► AI Builder: tool argument schema (so the AI knows what to ask) └─► Audit: change-tracked if `trackHistory: true` 
ObjectOS