Refactor and expand Zod schemas for data and UI models

Enhanced and reorganized field, object, action, dashboard, and view schemas for greater flexibility and clarity. Added new system translation schema for i18n support. Improved type safety, expanded configuration options (e.g., for Kanban, Calendar, Gantt views), and standardized naming conventions. Updated exports to include new translation schema.

Author: hotlong

packages/spec/src/data/field.zod.ts

@@ -2,79 +2,93 @@ import { z } from 'zod';
 
 /**
  * Field Type Enum
- * Defines the available data types for fields.
  */
 export const FieldType = z.enum([
-  // Basic
-  'text', 'textarea', 'markdown', 'html', 'password', 'email',
-  // Number
-  'number', 'currency', 'percent',
-  // Date
+  // Core Text
+  'text', 'textarea', 'email', 'url', 'phone', 'password',
+  // Rich Content
+  'markdown', 'html', 
+  // Numbers
+  'number', 'currency', 'percent', 
+  // Date & Time
   'date', 'datetime', 'time',
   // Logic
   'boolean',
-  // Choice
-  'select', 'multiselect',
+  // Selection
+  'select', 'multiselect', // Static options
   // Relational
-  'lookup', 'master_detail',
-  // Calculated
-  'formula', 'summary',
+  'lookup', 'master_detail', // Dynamic reference to other objects
   // Media
   'image', 'file', 'avatar',
-  // System
-  'id', 'owner', 'created_at', 'updated_at'
+  // Calculated / System
+  'formula', 'summary', 'autonumber'
 ]);
 
 export type FieldType = z.infer<typeof FieldType>;
 
 /**
- * Schema for select options (for select/multiselect types).
+ * Select Option Schema
  */
 export const SelectOptionSchema = z.object({
-  label: z.string().describe('Display label for the option'),
-  value: z.string().describe('Stored value for the option'),
+  label: z.string().describe('Display label'),
+  value: z.string().describe('Stored value'),
+  color: z.string().optional().describe('Color code for badges/charts'),
+  default: z.boolean().optional().describe('Is default option'),
 });
 
 /**
- * Base Schema for all fields.
- * Contains properties common to all field types.
+ * Field Schema - Best Practice Enterprise Pattern
  */
 export const FieldSchema = z.object({
-  /** Machine name of the field */
-  name: z.string().describe('Machine name of the field'),
-  
-  /** Human readable label */
-  label: z.string().optional().describe('Human readable label'),
-  
-  /** Field Data Type */
+  /** Identity */
+  name: z.string().regex(/^[a-z_][a-z0-9_]*$/).describe('Machine name (snake_case)'),
+  label: z.string().describe('Human readable label'),
   type: FieldType.describe('Field Data Type'),
+  description: z.string().optional().describe('Tooltip/Help text'),
+
+  /** Database Constraints */
+  required: z.boolean().default(false).describe('Is required'),
+  multiple: z.boolean().default(false).describe('Allow multiple values (Stores as Array/JSON). Applicable for select, lookup, file, image.'),
+  unique: z.boolean().default(false).describe('Is unique constraint'),
+  defaultValue: z.any().optional().describe('Default value'),
 
-  /** Whether the field is required */
-  required: z.boolean().optional().describe('Whether the field is required'),
-  
-  /** Default value for the field */
-  defaultValue: z.any().optional().describe('Default value for the field'),
-  
-  /** Help text / tooltip description */
-  description: z.string().optional().describe('Help text / tooltip description'),
-  
-  /** Whether the field is hidden from UI */
-  hidden: z.boolean().optional().describe('Whether the field is hidden from UI'),
+  /** Text/String Constraints */
+  maxLength: z.number().optional().describe('Max character length'),
+  minLength: z.number().optional().describe('Min character length'),
 
-  /** Whether the field is read-only */
-  readonly: z.boolean().optional().describe('Whether the field is read-only'),
+  /** Number Constraints */
+  precision: z.number().optional().describe('Total digits'),
+  scale: z.number().optional().describe('Decimal places'),
+  min: z.number().optional().describe('Minimum value'),
+  max: z.number().optional().describe('Maximum value'),
+
+  /** Selection Options */
+  options: z.array(SelectOptionSchema).optional().describe('Static options for select/multiselect'),
 
-  /** Options for select/multiselect types */
-  options: z.array(SelectOptionSchema).optional().describe('Options for select/multiselect types'),
+  /** Relationship Config */
+  reference: z.string().optional().describe('Target Object Name'),
+  referenceFilters: z.array(z.string()).optional().describe('Filters applied to lookup dialogs (e.g. "active = true")'),
+  writeRequiresMasterRead: z.boolean().optional().describe('If true, user needs read access to master record to edit this field'),
+  deleteBehavior: z.enum(['set_null', 'cascade', 'restrict']).optional().default('set_null').describe('What happens if referenced record is deleted'),
 
-  /** Target object name for lookup/master_detail types */
-  reference: z.string().optional().describe('Target object name for lookup/master_detail types'),
+  /** Calculation */
+  expression: z.string().optional().describe('Formula expression'), // Changed from formula to expression to match common usage, but keeping one consistent is key. Let's use expression as generic.
+  formula: z.string().optional().describe('Deprecated: Use expression'), // Backwards compat or just keep.
+  summaryOperations: z.object({
+    object: z.string(),
+    field: z.string(),
+    function: z.enum(['count', 'sum', 'min', 'max', 'avg'])
+  }).optional().describe('Roll-up summary definition'),
 
-  /** Expression for formula/summary types */
-  expression: z.string().optional().describe('Expression for formula/summary types'),
+  /** Security & Visibility */
+  hidden: z.boolean().default(false).describe('Hidden from default UI'),
+  readonly: z.boolean().default(false).describe('Read-only in UI'),
+  encryption: z.boolean().default(false).describe('Encrypt at rest'),
+  
+  /** Indexing */
+  index: z.boolean().default(false).describe('Create standard database index'),
+  externalId: z.boolean().default(false).describe('Is external ID for upsert operations'),
 });
 
-/**
- * TypeScript type inferred from FieldSchema.
- */
 export type Field = z.infer<typeof FieldSchema>;
+export type SelectOption = z.infer<typeof SelectOptionSchema>;

packages/spec/src/data/object.zod.ts

@@ -1,6 +1,30 @@
 import { z } from 'zod';
 import { FieldSchema } from './field.zod';
 
+/**
+ * Capability Flags
+ * Defines what system features are enabled for this object.
+ */
+export const ObjectCapabilities = z.object({
+  /** Enable history tracking (Audit Trail) */
+  trackHistory: z.boolean().default(false),
+  
+  /** Enable global search indexing */
+  searchable: z.boolean().default(true),
+  
+  /** Enable REST/GraphQL API access */
+  apiEnabled: z.boolean().default(true),
+  
+  /** Enable attachments/files */
+  files: z.boolean().default(false),
+  
+  /** Enable discussions/chatter */
+  feedEnabled: z.boolean().default(false),
+  
+  /** Enable Recycle Bin mechanics */
+  trash: z.boolean().default(true),
+});
+
 /**
  * Schema for database indexes.
  */
@@ -11,36 +35,32 @@ export const IndexSchema = z.object({
 });
 
 /**
- * Schema for Objects (Models/Tables).
+ * Object Schema - Enterprise Data Model
  */
 export const ObjectSchema = z.object({
-  /** Machine name (snake_case) */
+  /** Identify */
   name: z.string().regex(/^[a-z_][a-z0-9_]*$/).describe('Machine name (snake_case)'),
-  
-  /** Human readable label */
-  label: z.string().optional().describe('Human readable label'),
-  
-  /** Documentation / Description */
-  description: z.string().optional().describe('Documentation / Description'),
-  
-  /** Icon name (Lucide) */
-  icon: z.string().optional().describe('Icon name (Lucide)'),
-  
-  /** Datasource name */
+  label: z.string().optional().describe('Singular Label (e.g. "Account")'),
+  pluralLabel: z.string().optional().describe('Plural Label (e.g. "Accounts")'),
+  description: z.string().optional().describe('Internal description'),
+  icon: z.string().optional().describe('Lucide icon name'),
+
+  /** Storage Config */
   datasource: z.string().default('default').describe('Datasource name'),
+  tableName: z.string().optional().describe('Physical DB table override'),
+  isSystem: z.boolean().default(false).describe('Is system object (protected)'),
 
-  /** Physical database table name override */
-  dbName: z.string().optional().describe('Physical database table name override'),
-  
-  /** Map of field definitions */
+  /** Fields Definition */
   fields: z.record(FieldSchema).describe('Map of field definitions'),
 
-  /** Database indexes */
+  /** Indexes */
   indexes: z.array(IndexSchema).optional().describe('Database indexes definition'),
+  
+  /** Key Fields */
+  nameField: z.string().optional().describe('Which field represents the record name/title (usually "name")'),
+  
+  /** Features & Capabilities */
+  enable: ObjectCapabilities.optional().describe('Enabled system capabilities'),
 });
 
-/**
- * TypeScript type inferred from ObjectSchema.
- * Note: 'Object' is a reserved word in JavaScript/TypeScript, so we use 'ServiceObject'.
- */
 export type ServiceObject = z.infer<typeof ObjectSchema>;

packages/spec/src/index.ts

@@ -22,6 +22,7 @@ export * from './ui/action.zod';
 
 // System Protocol (Manifest, Runtime, Constants)
 export * from './system/manifest.zod';
+export * from './system/translation.zod';
 export * from './system/constants';
 export * from './system/types';
 

packages/spec/src/system/translation.zod.ts

@@ -0,0 +1,38 @@
+import { z } from 'zod';
+
+/**
+ * Translation Schema
+ * Supports i18n for labels, messages, and options.
+ * Example structure:
+ * {
+ *   "en": { "objects": { "account": { "label": "Account" } } },
+ *   "zh-CN": { "objects": { "account": { "label": "客户" } } }
+ * }
+ */
+export const TranslationDataSchema = z.object({
+  /** Object translations */
+  objects: z.record(z.object({
+    label: z.string(),
+    pluralLabel: z.string().optional(),
+    fields: z.record(z.object({
+      label: z.string().optional(),
+      help: z.string().optional(),
+      options: z.record(z.string()).optional(), // Option value -> Label map
+    })).optional(),
+  })).optional(),
+  
+  /** App/Menu translations */
+  apps: z.record(z.object({
+    label: z.string(),
+    description: z.string().optional(),
+  })).optional(),
+
+  /** UI Messages */
+  messages: z.record(z.string()).optional(),
+});
+
+export const LocaleSchema = z.string().describe('BCP-47 Language Tag (e.g. en-US, zh-CN)');
+
+export const TranslationBundleSchema = z.record(LocaleSchema, TranslationDataSchema);
+
+export type TranslationBundle = z.infer<typeof TranslationBundleSchema>;

packages/spec/src/ui/action.zod.ts

@@ -1,31 +1,20 @@
 import { z } from 'zod';
+import { FieldType } from '../data/field.zod';
 
 /**
- * Action Type Definitions
- * Defines the type of execution for the action.
+ * Action Parameter Schema
+ * Defines inputs required before executing an action.
  */
-export const ActionType = z.enum([
-  'script',  // Execute a server-side script
-  'client',  // Execute a client-side function
-  'url',     // Open a URL
-  'flow',    // Trigger a workflow/process
-  'call_service' // Call a microservice
-]);
-
-/**
- * Action Location
- * Defines where the action button should appear.
- */
-export const ActionLocation = z.enum([
-  'record',            // Record detail page
-  'record_more',       // Record detail "More" menu
-  'list',             // List view toolbar
-  'list_item',        // List view row action
-  'global'            // Global header/sidebar
-]);
+export const ActionParamSchema = z.object({
+  name: z.string(),
+  label: z.string(),
+  type: FieldType,
+  required: z.boolean().default(false),
+  options: z.array(z.object({ label: z.string(), value: z.string() })).optional(),
+});
 
 /**
- * Schema for Actions (Buttons/Operations).
+ * Action Schema
  */
 export const ActionSchema = z.object({
   /** Machine name of the action */
@@ -34,31 +23,36 @@ export const ActionSchema = z.object({
   /** Display label */
   label: z.string().describe('Display label'),
 
-  /** Action functionality type */
-  type: ActionType.default('script').describe('Action functionality type'),
+  /** Icon name (Lucide) */
+  icon: z.string().optional().describe('Icon name'),
+
+  /** Where does this action appear? */
+  locations: z.array(z.enum([
+    'list_toolbar', 'list_item', 
+    'record_header', 'record_more', 'record_related',
+    'global_nav'
+  ])).optional().describe('Locations where this action is visible'),
 
-  /** Locations where this action is visible */
-  location: z.union([ActionLocation, z.array(ActionLocation)]).describe('Locations where this action is visible'),
+  /** Legacy location support */
+  location: z.any().optional(),
+
+  /** What type of interaction? */
+  type: z.enum(['script', 'url', 'modal', 'flow', 'api']).default('script').describe('Action functionality type'),
 
-  /** 
-   * The actual logic to execute.
-   * - For 'script': The script code or file path.
-   * - For 'url': The URL template.
-   * - For 'call_service': Service endpoint.
-   */
-  execute: z.string().optional().describe('Execution logic (script, url, or endpoint)'),
+  /** Payload / Target */
+  target: z.string().optional().describe('URL, Script Name, Flow ID, or API Endpoint'), // For URL/Flow types
+  execute: z.string().optional().describe('Legacy execution logic'),
 
-  /** Visibility condition expression (Formula returning boolean) */
-  visible: z.string().optional().describe('Visibility condition (Formula)'),
+  /** User Input Requirements */
+  params: z.array(ActionParamSchema).optional().describe('Input parameters required from user'),
 
-  /** Confirmation message before execution */
+  /** UX Behavior */
   confirmText: z.string().optional().describe('Confirmation message before execution'),
-  
-  /** Icon name (Lucide) */
-  icon: z.string().optional().describe('Icon name'),
-
-  /** Success message after execution */
   successMessage: z.string().optional().describe('Success message to show after execution'),
+  refreshAfter: z.boolean().default(false).describe('Refresh view after execution'),
+  
+  /** Access */
+  visible: z.string().optional().describe('Formula returning boolean'),
 });
 
 export type Action = z.infer<typeof ActionSchema>;

packages/spec/src/ui/dashboard.zod.ts

@@ -32,10 +32,10 @@ export const DashboardWidgetSchema = z.object({
   filter: z.any().optional().describe('Data filter criteria'),
 
   /** Category Field (X-Axis / Group By) */
-  category_field: z.string().optional().describe('Field for grouping (X-Axis)'),
+  categoryField: z.string().optional().describe('Field for grouping (X-Axis)'),
 
   /** Value Field (Y-Axis) */
-  value_field: z.string().optional().describe('Field for values (Y-Axis)'),
+  valueField: z.string().optional().describe('Field for values (Y-Axis)'),
 
   /** Aggregate operation */
   aggregate: z.enum(['count', 'sum', 'avg', 'min', 'max']).optional().default('count').describe('Aggregate function'),