Add dataset schema and import mode enums

Introduces DatasetSchema and DatasetMode using zod for standardized data import strategies and seed data handling. Also exports these from the package spec index for external use.

Author: hotlong

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

@@ -0,0 +1,60 @@
+import { z } from 'zod';
+
+/**
+ * Data Import Strategy
+ * Defines how the engine handles existing records.
+ */
+export const DatasetMode = z.enum([
+  'insert',    // Try to insert, fail on duplicate
+  'update',    // Only update found records, ignore new
+  'upsert',    // Create new or Update existing (Standard)
+  'replace',   // Delete ALL records in object then insert (Dangerous - use for cache tables)
+  'ignore'     // Try to insert, silently skip duplicates
+]);
+
+/**
+ * Dataset Schema (Seed Data / Fixtures)
+ * 
+ * Standardized format for transporting data.
+ * Used for:
+ * 1. System Bootstrapping (Admin accounts, Standard Roles)
+ * 2. Reference Data (Countries, Currencies)
+ * 3. Demo/Test Data
+ */
+export const DatasetSchema = z.object({
+  /** 
+   * Target Object 
+   * The machine name of the object to populate.
+   */
+  object: z.string().regex(/^[a-z_][a-z0-9_]*$/).describe('Target Object Name'),
+
+  /** 
+   * Idempotency Key (The "Upsert" Key)
+   * The field used to check if a record already exists.
+   * Best Practice: Use a natural key like 'code', 'slug', 'username' or 'external_id'.
+   * Standard: '_id' (internal ID) is rarely used for portable seed data.
+   */
+  externalId: z.string().default('name').describe('Field match for uniqueness check'),
+
+  /** 
+   * Import Strategy
+   */
+  mode: DatasetMode.default('upsert').describe('Conflict resolution strategy'),
+
+  /**
+   * Environment Scope
+   * - 'all': Always load
+   * - 'dev': Only for development/demo
+   * - 'test': Only for CI/CD tests
+   */
+  env: z.array(z.enum(['prod', 'dev', 'test'])).default(['prod', 'dev', 'test']).describe('Applicable environments'),
+
+  /** 
+   * The Payload
+   * Array of raw JSON objects matching the Object Schema.
+   */
+  records: z.array(z.record(z.any())).describe('Data records'),
+});
+
+export type Dataset = z.infer<typeof DatasetSchema>;
+export type DatasetImportMode = z.infer<typeof DatasetMode>;

packages/spec/src/index.ts

@@ -14,6 +14,7 @@ export * from './data/validation.zod';
 export * from './data/permission.zod';
 export * from './data/workflow.zod';
 export * from './data/flow.zod';
+export * from './data/dataset.zod';
 
 // UI Protocol (Layout, Navigation, Interaction)
 export * from './ui/app.zod';