openyida 2026.7.29-beta.2 → 2026.7.30

package/README.md

@@ -387,6 +387,7 @@ Run `openyida --help` or `openyida <command> --help` for detailed usage.
 | Command | Description |
 |---------|-------------|
 | `openyida create-form create <appType> ... [--locale zh_CN\|en_US\|ja_JP] [--open\|--no-open]` | Create a form page |
+| `openyida create-form validate-fields <fieldsJsonOrFile> [--json]` | Validate form field JSON locally |
 | `openyida create-form update <appType> ... [--locale zh_CN\|en_US\|ja_JP] [--open\|--no-open]` | Update a form page |
 | `openyida create-form patch <appType> <formUuid> <patchJsonOrFile> [--open\|--no-open]` | Update a form page |
 | `openyida create-form rule <appType> <formUuid> <rulesJsonOrFile> [--open\|--no-open]` | Update a form page |

package/lib/app/create-form/args.js

@@ -115,6 +115,10 @@ function createParseArgs(dependencies) {
         options.force = true;
         args.splice(i, 1);
         i--;
+      } else if (args[i] === '--json') {
+        options.json = true;
+        args.splice(i, 1);
+        i--;
       }
     }
 
@@ -132,6 +136,21 @@ function createParseArgs(dependencies) {
 
     const mode = args[0];
 
+    if (mode === 'validate-fields') {
+      if (args.length === 2) {
+        return {
+          mode: 'validate-fields',
+          fieldsJsonOrFile: args[1],
+          ...options
+        };
+      }
+      usage(
+        'openyida create-form validate-fields <fieldsJsonOrFile> --json',
+        'openyida create-form validate-fields .cache/openyida/forms/fields.json --json'
+      );
+      throwCreateFormError('openyida create-form validate-fields <fieldsJsonOrFile> --json', 'CREATE_FORM_INVALID_ARGUMENTS');
+    }
+
     if (mode === 'create') {
       if (args.length < 4) {
         usage(t('create_form.usage_create'), t('create_form.example_create'));

package/lib/app/create-form/commands.js

@@ -16,6 +16,8 @@ function dispatchCreateFormCommand(parsedArgs, authContext, handlers) {
       return handlers.bindDataSource(...args);
     case 'add-option':
       return handlers.addOption(...args);
+    case 'validate-fields':
+      return handlers.validateFields(...args);
     case 'create':
       return handlers.create(...args);
     default:

package/lib/app/create-form.js

@@ -81,6 +81,9 @@ const { deepMerge, splitJsonPointer } = require('./create-form/schema-patch');
 const { FORM_RULES_BLOCK_END, FORM_RULES_BLOCK_START } = require('./create-form/rule-builder');
 const { SMART_VALIDATION_BLOCK_END, SMART_VALIDATION_BLOCK_START } = require('./create-form/validation-builder');
 const { createFieldNormalizers } = require('./create-form/field-normalizers');
+const {
+  validateFormFieldDefinitions: collectFormFieldValidationDiagnostics,
+} = require('./form-field-validator');
 
 function parseOpenOption(inputArgs) {
   const openOption = parseBrowserOpenOption(inputArgs);
@@ -351,182 +354,134 @@ function throwInvalidFieldDefinition(message, code, field, fieldPath, extra) {
   );
 }
 
-function validatePlainFieldObject(field, fieldPath) {
-  if (!field || typeof field !== 'object' || Array.isArray(field)) {
-    throwInvalidFieldDefinition(
-      '字段定义必须是对象: ' + fieldPath,
-      'CREATE_FORM_INVALID_FIELD_DEFINITION',
-      field,
-      fieldPath
-    );
+function getValueAtDiagnosticPath(root, diagnosticPath, rootPath) {
+  const normalizedRootPath = rootPath || 'fields';
+  if (!diagnosticPath || diagnosticPath.indexOf(normalizedRootPath) !== 0) {
+    return undefined;
   }
-}
-
-function validateContainerChildrenArray(field, fieldPath, componentName) {
-  if (field.children === undefined || field.children === null) {
-    return [];
+  const relativePath = diagnosticPath.slice(normalizedRootPath.length);
+  const tokens = [];
+  const pattern = /\[(\d+)\]|\.([A-Za-z_$][\w$]*)/g;
+  let match;
+  while ((match = pattern.exec(relativePath)) !== null) {
+    tokens.push(match[1] !== undefined ? Number(match[1]) : match[2]);
   }
-  if (!Array.isArray(field.children)) {
-    throwInvalidFieldDefinition(
-      componentName + '.children 必须是数组: ' + fieldPath,
-      'CREATE_FORM_INVALID_CONTAINER_CHILDREN',
-      field,
-      fieldPath,
-      { componentName }
-    );
+  let current = root;
+  for (let index = 0; index < tokens.length; index++) {
+    if (current === undefined || current === null) {
+      return undefined;
+    }
+    current = current[tokens[index]];
   }
-  return field.children;
+  return current;
 }
 
-function hasNonEmptyAssociationFormUuid(field) {
-  const associationForm = field && field.associationForm;
-  if (!associationForm || typeof associationForm !== 'object' || Array.isArray(associationForm)) {
-    return false;
+function findDiagnosticField(fields, diagnosticPath, rootPath) {
+  let currentPath = diagnosticPath || rootPath || 'fields';
+  while (currentPath && currentPath !== (rootPath || 'fields')) {
+    const value = getValueAtDiagnosticPath(fields, currentPath, rootPath);
+    if (value && typeof value === 'object' && !Array.isArray(value)) {
+      return value;
+    }
+    const dotIndex = currentPath.lastIndexOf('.');
+    const bracketIndex = currentPath.lastIndexOf('[');
+    const cutIndex = Math.max(dotIndex, bracketIndex);
+    if (cutIndex <= 0) {
+      break;
+    }
+    currentPath = currentPath.slice(0, cutIndex);
   }
-  return typeof associationForm.formUuid === 'string' && associationForm.formUuid.trim().length > 0;
+  return undefined;
 }
 
-function validateAssociationFormFieldDefinition(field, fieldPath) {
-  if (hasNonEmptyAssociationFormUuid(field)) {
-    return;
-  }
-  throwInvalidFieldDefinition(
-    'AssociationFormField.associationForm.formUuid 必须是非空字符串: ' + fieldPath,
-    'CREATE_FORM_ASSOCIATION_FORM_UUID_MISSING',
-    field,
-    fieldPath,
-    { componentName: 'AssociationFormField' }
-  );
+function mapFieldValidationCode(code) {
+  const cliErrorCodesByValidationCode = {
+    FIELD_TYPE_MISSING: 'CREATE_FORM_FIELD_TYPE_MISSING',
+    INVALID_FIELD_DEFINITION: 'CREATE_FORM_INVALID_FIELD_DEFINITION',
+    INVALID_FIELDS_ROOT: 'CREATE_FORM_INVALID_FIELD_DEFINITION',
+    UNSUPPORTED_FIELD_TYPE: 'CREATE_FORM_UNSUPPORTED_FIELD_TYPE',
+    COLUMN_OUTSIDE_COLUMN_CONTAINER: 'CREATE_FORM_COLUMN_OUTSIDE_COLUMNS_LAYOUT',
+    ASSOCIATION_FORM_MISSING: 'CREATE_FORM_ASSOCIATION_FORM_UUID_MISSING',
+    TABLE_CHILD_PRESENTATION_UNSUPPORTED: 'CREATE_FORM_TABLE_CHILD_PRESENTATION_UNSUPPORTED',
+    INVALID_TABLE_FIELD_CHILDREN_DEPTH: 'CREATE_FORM_INVALID_TABLE_CHILDREN',
+    INVALID_COLUMN_CONTAINER_CHILDREN_DEPTH: 'CREATE_FORM_INVALID_COLUMN_CONTAINER_CHILDREN_DEPTH',
+    INVALID_CHILDREN_SHAPE: 'CREATE_FORM_INVALID_CONTAINER_CHILDREN',
+    NESTED_TABLE_FIELD_UNSUPPORTED: 'CREATE_FORM_NESTED_TABLE_FIELD_UNSUPPORTED',
+    OPTION_FIELD_DATASOURCE_MISSING: 'CREATE_FORM_OPTION_FIELD_DATASOURCE_MISSING',
+    BUSINESS_FIELD_LABEL_MISSING: 'CREATE_FORM_BUSINESS_FIELD_LABEL_MISSING',
+    INVALID_MULTIPLE_TYPE: 'CREATE_FORM_INVALID_MULTIPLE_TYPE',
+    INVALID_DIVIDER_TITLE: 'CREATE_FORM_INVALID_DIVIDER_TITLE',
+    INVALID_DIVIDER_TYPE: 'CREATE_FORM_INVALID_DIVIDER_TYPE',
+  };
+  return cliErrorCodesByValidationCode[code] || 'CREATE_FORM_FIELD_JSON_INVALID';
 }
 
-function validateFieldDefinition(field, fieldPath, options) {
-  const validationOptions = options || {};
-  validatePlainFieldObject(field, fieldPath);
-
-  const componentName = normalizeFormDefinitionType(field);
-  if (!componentName) {
-    throwInvalidFieldDefinition(
-      '字段定义缺少 type/componentName/componentType: ' + fieldPath,
-      'CREATE_FORM_FIELD_TYPE_MISSING',
-      field,
-      fieldPath
-    );
+function normalizeDiagnosticDetailPath(diagnostic) {
+  if (!diagnostic || !diagnostic.path) {
+    return 'fields';
   }
-
-  if (isFormPresentationComponent(componentName)) {
-    if (validationOptions.disallowPresentation) {
-      throwInvalidFieldDefinition(
-        'TableField.children 不支持展示布局组件: ' + componentName,
-        'CREATE_FORM_TABLE_CHILD_PRESENTATION_UNSUPPORTED',
-        field,
-        fieldPath,
-        { componentName }
-      );
-    }
-    if (componentName === 'Column' && !validationOptions.allowColumn) {
-      throwInvalidFieldDefinition(
-        'Column 只能作为 ColumnContainer.children 的 Column 对象使用: ' + fieldPath,
-        'CREATE_FORM_COLUMN_OUTSIDE_COLUMNS_LAYOUT',
-        field,
-        fieldPath,
-        { componentName }
-      );
-    }
-    if (componentName === 'ColumnsLayout') {
-      validateColumnsLayoutDefinition(field, fieldPath);
-    } else if (componentName === 'PageSection') {
-      validateContainerChildrenArray(field, fieldPath, componentName).forEach(function (child, childIndex) {
-        validateFieldDefinition(child, fieldPath + '.children[' + childIndex + ']');
-      });
-    } else if (componentName === 'Column') {
-      validateContainerChildrenArray(field, fieldPath, componentName).forEach(function (child, childIndex) {
-        validateFieldDefinition(child, fieldPath + '.children[' + childIndex + ']');
-      });
-    }
-    return componentName;
+  if (diagnostic.code === 'FIELD_TYPE_MISSING' && diagnostic.path.endsWith('.type')) {
+    return diagnostic.path.slice(0, -'.type'.length);
   }
-
-  if (!isSupportedBusinessFieldType(componentName)) {
-    throwInvalidFieldDefinition(
-      '不支持的字段类型: ' + componentName,
-      'CREATE_FORM_UNSUPPORTED_FIELD_TYPE',
-      field,
-      fieldPath,
-      { componentName }
-    );
+  if (diagnostic.code === 'ASSOCIATION_FORM_MISSING' && diagnostic.path.endsWith('.associationForm')) {
+    return diagnostic.path.slice(0, -'.associationForm'.length);
   }
+  return diagnostic.path;
+}
 
-  if (componentName === 'AssociationFormField') {
-    validateAssociationFormFieldDefinition(field, fieldPath);
-  }
+function validateFormFieldDefinitions(fields, rootPath) {
+  const diagnostics = collectFormFieldValidationDiagnostics(fields, {
+    rootPath: rootPath || 'fields',
+  });
+  throwFieldValidationDiagnostics(fields, diagnostics, rootPath || 'fields');
+}
 
-  if (componentName === 'TableField') {
-    validateTableFieldChildren(field, fieldPath, validationOptions);
+function throwFieldValidationDiagnostics(fields, diagnostics, rootPath) {
+  if (diagnostics.length === 0) {
+    return;
   }
 
-  return componentName;
+  const first = diagnostics[0];
+  const detailPath = normalizeDiagnosticDetailPath(first);
+  const field = findDiagnosticField(fields, detailPath, rootPath || 'fields');
+  const details = buildInvalidFieldDefinitionDetails(field, detailPath, {
+    diagnostics,
+    expected: first.expected,
+    actual: first.actual,
+    suggestion: first.suggestion,
+  });
+  throwCreateFormError(
+    first.message,
+    mapFieldValidationCode(first.code),
+    details
+  );
 }
 
-function validateColumnsLayoutDefinition(field, fieldPath) {
-  const columns = validateContainerChildrenArray(field, fieldPath, 'ColumnsLayout');
-  columns.forEach(function (columnDefinition, columnIndex) {
-    const columnPath = fieldPath + '.children[' + columnIndex + ']';
-    if (Array.isArray(columnDefinition)) {
-      columnDefinition.forEach(function (child, childIndex) {
-        validateFieldDefinition(child, columnPath + '[' + childIndex + ']');
-      });
-      return;
-    }
-    if (
-      columnDefinition &&
-      typeof columnDefinition === 'object' &&
-      !Array.isArray(columnDefinition) &&
-      normalizeFormDefinitionType(columnDefinition) === 'Column'
-    ) {
-      validateFieldDefinition(columnDefinition, columnPath, { allowColumn: true });
-      return;
-    }
-    throwInvalidFieldDefinition(
-      'ColumnContainer.children 只能包含二维字段数组或 Column 对象: ' + columnPath,
-      'CREATE_FORM_INVALID_COLUMNS_LAYOUT_CHILDREN',
-      columnDefinition,
-      columnPath,
-      { componentName: normalizeFormDefinitionType(columnDefinition) || readFormDefinitionType(columnDefinition) }
-    );
+function collectSingleFieldValidationDiagnostics(field, rootPath) {
+  const internalRootPath = '__field';
+  const diagnostics = collectFormFieldValidationDiagnostics([field], {
+    rootPath: internalRootPath,
+  });
+  return diagnostics.map(function (diagnostic) {
+    return Object.assign({}, diagnostic, {
+      path: diagnostic.path.replace(internalRootPath + '[0]', rootPath),
+    });
   });
 }
 
-function validateTableFieldChildren(field, fieldPath, options) {
-  if (field.children === undefined || field.children === null) {
-    return;
-  }
-  if (!Array.isArray(field.children)) {
-    throwInvalidFieldDefinition(
-      'TableField.children 必须是字段数组: ' + fieldPath,
-      'CREATE_FORM_INVALID_TABLE_CHILDREN',
-      field,
-      fieldPath,
-      { componentName: 'TableField' }
-    );
-  }
-  field.children.forEach(function (child, childIndex) {
-    validateFieldDefinition(child, fieldPath + '.children[' + childIndex + ']', Object.assign({}, options, {
-      disallowPresentation: true,
-    }));
-  });
+function validateSingleFieldDefinition(field, rootPath) {
+  const diagnostics = collectSingleFieldValidationDiagnostics(field, rootPath);
+  throwFieldValidationDiagnostics(field, diagnostics, rootPath);
 }
 
-function validateFormFieldDefinitions(fields, rootPath) {
-  if (!Array.isArray(fields)) {
-    throwInvalidFieldDefinition(
-      '字段定义必须是数组',
-      'CREATE_FORM_INVALID_FIELD_DEFINITION',
-      null,
-      rootPath || 'fields'
-    );
+function validateChangeFieldDefinitions(changes) {
+  if (!Array.isArray(changes)) {
+    return;
   }
-  fields.forEach(function (field, index) {
-    validateFieldDefinition(field, (rootPath || 'fields') + '[' + index + ']');
+  changes.forEach(function (change, changeIndex) {
+    if (change && change.action === 'add') {
+      validateSingleFieldDefinition(change.field, 'changes[' + changeIndex + '].field');
+    }
   });
 }
 
@@ -5095,6 +5050,24 @@ async function saveSchemaAndUpdateConfig(authRef, appType, formUuid, schema, ver
 
 // ── create 模式主流程 ─────────────────────────────────
 
+async function mainValidateFields(parsedArgs) {
+  const { fieldsJsonOrFile } = parsedArgs;
+  assertNoEmojiInDefinitionFileName(fieldsJsonOrFile);
+  const { fields } = readFieldsDefinition(fieldsJsonOrFile);
+  const diagnostics = collectFormFieldValidationDiagnostics(fields, { rootPath: 'fields' });
+  const output = {
+    success: diagnostics.length === 0,
+    valid: diagnostics.length === 0,
+    fieldCount: Array.isArray(fields) ? fields.length : 0,
+    diagnostics,
+  };
+  console.log(JSON.stringify(output, null, parsedArgs.json ? 2 : 0));
+  if (diagnostics.length > 0) {
+    process.exitCode = 1;
+  }
+  return output;
+}
+
 async function mainCreate(parsedArgs, authRef) {
   const { appType, formTitle, fieldsJsonOrFile, layout, theme, labelAlign } = parsedArgs;
 
@@ -6030,7 +6003,21 @@ async function mainUpdate(parsedArgs, authRef) {
   label('Form UUID:', formUuid);
   label('Changes:', changesJsonOrFile);
 
-  step(2, t('create_form.step_get_schema', 2));
+  step(2, t('create_form.step_read_changes', 2));
+  const changes = readChangesDefinition(changesJsonOrFile);
+  validateChangeFieldDefinitions(changes);
+  success(t('create_form.changes_loaded', changes.length));
+  changes.forEach(function (change, changeIndex) {
+    if (change.action === 'add') {
+      listItem((changeIndex + 1) + '. [' + t('create_form.action_add') + '] ' + change.field.type + ': ' + change.field.label);
+    } else if (change.action === 'delete') {
+      listItem((changeIndex + 1) + '. [' + t('create_form.action_delete') + '] ' + change.label);
+    } else if (change.action === 'update') {
+      listItem((changeIndex + 1) + '. [' + t('create_form.action_update') + '] ' + change.label + ' → ' + Object.keys(change.changes || {}).join(', '));
+    }
+  });
+
+  step(3, t('create_form.step_get_schema', 3));
   info(t('create_form.sending_get_schema'));
   const schemaResult = await requestWithAutoLogin(function (auth) {
     return sendGetRequest(
@@ -6082,7 +6069,7 @@ async function mainUpdate(parsedArgs, authRef) {
     warn(t('create_form.schema_got_empty'));
   }
 
-  step(3, t('create_form.step_check_data', 3));
+  step(4, t('create_form.step_check_data', 4));
   const dataCheckResult = await requestWithAutoLogin(function (auth) {
     return sendGetRequest(
       auth.baseUrl,
@@ -6122,19 +6109,6 @@ async function mainUpdate(parsedArgs, authRef) {
     success(t('create_form.data_check_empty'));
   }
 
-  step(4, t('create_form.step_read_changes', 4));
-  const changes = readChangesDefinition(changesJsonOrFile);
-  success(t('create_form.changes_loaded', changes.length));
-  changes.forEach(function (change, changeIndex) {
-    if (change.action === 'add') {
-      listItem((changeIndex + 1) + '. [' + t('create_form.action_add') + '] ' + change.field.type + ': ' + change.field.label);
-    } else if (change.action === 'delete') {
-      listItem((changeIndex + 1) + '. [' + t('create_form.action_delete') + '] ' + change.label);
-    } else if (change.action === 'update') {
-      listItem((changeIndex + 1) + '. [' + t('create_form.action_update') + '] ' + change.label + ' → ' + Object.keys(change.changes || {}).join(', '));
-    }
-  });
-
   step(5, t('create_form.step_apply_changes', 5));
   const appliedChanges = applyChangesToSchema(schema, changes);
   const fieldDiagnostics = appliedChanges.diagnostics || [];
@@ -6215,6 +6189,9 @@ async function run(args) {
   if (parsedArgs.help) {
     return parsedArgs;
   }
+  if (parsedArgs.mode === 'validate-fields') {
+    return mainValidateFields(parsedArgs);
+  }
 
   step(1, t('common.step_login', 1));
   const authRef = createAuthRef();
@@ -6232,6 +6209,7 @@ async function run(args) {
       validation: mainValidation,
       bindDataSource: mainBindDataSource,
       addOption: mainAddOption,
+      validateFields: mainValidateFields,
     }
   );
 }
@@ -6254,6 +6232,7 @@ module.exports = {
     collectComponentNames,
     normalizeFormDefinitionType,
     validateFormFieldDefinitions,
+    collectFormFieldValidationDiagnostics,
     ensureDividerThemeAction,
     applyChangesToSchema,
   },

package/lib/app/form-field-validator.js

@@ -0,0 +1,560 @@
+'use strict';
+
+const FIELD_TYPE_ALIAS = Object.freeze({
+  TextAreaField: 'TextareaField',
+  Textareafield: 'TextareaField',
+  textareaField: 'TextareaField',
+  textAreaField: 'TextareaField',
+  Textfield: 'TextField',
+  textfield: 'TextField',
+  Numberfield: 'NumberField',
+  numberfield: 'NumberField',
+  Selectfield: 'SelectField',
+  selectfield: 'SelectField',
+  Radiofield: 'RadioField',
+  radiofield: 'RadioField',
+  Checkboxfield: 'CheckboxField',
+  checkboxfield: 'CheckboxField',
+  Datefield: 'DateField',
+  datefield: 'DateField',
+  Tablefield: 'TableField',
+  tablefield: 'TableField',
+  Ratefield: 'RateField',
+  ratefield: 'RateField',
+  Imagefield: 'ImageField',
+  imagefield: 'ImageField',
+  Attachmentfield: 'AttachmentField',
+  attachmentfield: 'AttachmentField',
+  Employeefield: 'EmployeeField',
+  employeefield: 'EmployeeField',
+  MultiSelectfield: 'MultiSelectField',
+  Multiselectfield: 'MultiSelectField',
+  multiselectfield: 'MultiSelectField',
+  SerialNumberfield: 'SerialNumberField',
+  Serialnumberfield: 'SerialNumberField',
+  serialnumberfield: 'SerialNumberField',
+});
+
+const PRESENTATION_TYPE_ALIAS = Object.freeze({
+  Divider: 'Divider',
+  divider: 'Divider',
+  ColumnsLayout: 'ColumnContainer',
+  columnsLayout: 'ColumnContainer',
+  ColumnContainer: 'ColumnContainer',
+  columnContainer: 'ColumnContainer',
+  Column: 'Column',
+  column: 'Column',
+  GroupContainer: 'GroupContainer',
+  groupContainer: 'GroupContainer',
+  PageSection: 'PageSection',
+  pageSection: 'PageSection',
+});
+
+const BUSINESS_FIELD_TYPES = Object.freeze([
+  'TextField',
+  'TextareaField',
+  'RadioField',
+  'SelectField',
+  'CheckboxField',
+  'MultiSelectField',
+  'NumberField',
+  'RateField',
+  'DateField',
+  'CascadeDateField',
+  'EmployeeField',
+  'DepartmentSelectField',
+  'CountrySelectField',
+  'AddressField',
+  'AttachmentField',
+  'ImageField',
+  'TableField',
+  'AssociationFormField',
+  'SerialNumberField',
+]);
+
+const PRESENTATION_FIELD_TYPES = Object.freeze([
+  'Divider',
+  'ColumnContainer',
+  'Column',
+  'GroupContainer',
+  'PageSection',
+]);
+
+const OPTION_FIELD_TYPES = Object.freeze([
+  'SelectField',
+  'RadioField',
+  'CheckboxField',
+  'MultiSelectField',
+]);
+
+const READABLE_I18N_LABEL_KEYS = Object.freeze([
+  'zh_CN',
+  'en_US',
+  'ja_JP',
+  'zh_TW',
+  'zh_HK',
+  'pureEn_US',
+  'name',
+]);
+
+function isPlainObject(value) {
+  return !!value && typeof value === 'object' && !Array.isArray(value);
+}
+
+function describeActual(value) {
+  if (Array.isArray(value)) {
+    return 'array';
+  }
+  if (value === null) {
+    return 'null';
+  }
+  return typeof value;
+}
+
+function readDefinitionType(field) {
+  if (!isPlainObject(field)) {
+    return '';
+  }
+  if (field.type !== undefined && field.type !== null && field.type !== '') {
+    return String(field.type).trim();
+  }
+  if (field.componentName !== undefined && field.componentName !== null && field.componentName !== '') {
+    return String(field.componentName).trim();
+  }
+  if (field.componentType !== undefined && field.componentType !== null && field.componentType !== '') {
+    return String(field.componentType).trim();
+  }
+  return '';
+}
+
+function normalizeDefinitionType(field) {
+  const rawType = readDefinitionType(field);
+  if (!rawType) {
+    return '';
+  }
+  return PRESENTATION_TYPE_ALIAS[rawType] || FIELD_TYPE_ALIAS[rawType] || rawType;
+}
+
+function isBusinessFieldType(type) {
+  return BUSINESS_FIELD_TYPES.indexOf(type) !== -1;
+}
+
+function isPresentationFieldType(type) {
+  return PRESENTATION_FIELD_TYPES.indexOf(type) !== -1;
+}
+
+function hasNonEmptyText(value) {
+  return typeof value === 'string' && value.trim().length > 0;
+}
+
+function hasNonEmptyI18nObject(value) {
+  if (!isPlainObject(value)) {
+    return false;
+  }
+  return READABLE_I18N_LABEL_KEYS.some(function (key) {
+    return hasNonEmptyText(value[key]);
+  });
+}
+
+function hasFieldLabel(value) {
+  return hasNonEmptyText(value) || hasNonEmptyI18nObject(value);
+}
+
+function hasFixedOptionSource(field) {
+  return Array.isArray(field.dataSource) && field.dataSource.length > 0;
+}
+
+function hasLegacyOptionSource(field) {
+  return Array.isArray(field.options) && field.options.length > 0;
+}
+
+function hasRemoteOptionSource(field) {
+  return !!(
+    field.remoteDataSource ||
+    field.searchDataSource ||
+    field.dataSourceConfig ||
+    field.dataSourceUrl ||
+    field.searchConfig
+  );
+}
+
+function hasAssociationForm(field) {
+  return isPlainObject(field.associationForm) && hasNonEmptyText(field.associationForm.formUuid);
+}
+
+function createDiagnostic(code, path, expected, actual, message, suggestion) {
+  return {
+    code,
+    path,
+    expected,
+    actual,
+    message,
+    suggestion,
+  };
+}
+
+function pushDiagnostic(diagnostics, code, path, expected, actual, message, suggestion) {
+  diagnostics.push(createDiagnostic(code, path, expected, actual, message, suggestion));
+}
+
+function validateChildrenPropertyShape(field, path, diagnostics, expectedDescription) {
+  if (field.children === undefined || field.children === null) {
+    return true;
+  }
+  if (!Array.isArray(field.children)) {
+    pushDiagnostic(
+      diagnostics,
+      'INVALID_CHILDREN_SHAPE',
+      path + '.children',
+      expectedDescription,
+      describeActual(field.children),
+      'children must be an array with the expected depth for this component.',
+      'Rewrite children to match the component-specific shape before creating or updating the form.'
+    );
+    return false;
+  }
+  return true;
+}
+
+function validateDivider(field, path, diagnostics) {
+  if (
+    field.title !== undefined &&
+    typeof field.title !== 'string' &&
+    !isPlainObject(field.title)
+  ) {
+    pushDiagnostic(
+      diagnostics,
+      'INVALID_DIVIDER_TITLE',
+      path + '.title',
+      'string or i18n object',
+      describeActual(field.title),
+      'Divider.title must be a string or an i18n object when provided.',
+      'Use a plain string title or omit title.'
+    );
+  }
+  if (field.dividerType !== undefined && typeof field.dividerType !== 'string') {
+    pushDiagnostic(
+      diagnostics,
+      'INVALID_DIVIDER_TYPE',
+      path + '.dividerType',
+      'string',
+      describeActual(field.dividerType),
+      'Divider.dividerType must be a string when provided.',
+      'Use a supported divider style string or omit dividerType.'
+    );
+  }
+}
+
+function validateFieldDefinition(field, path, diagnostics, options) {
+  const validationOptions = options || {};
+
+  if (!isPlainObject(field)) {
+    pushDiagnostic(
+      diagnostics,
+      'INVALID_FIELD_DEFINITION',
+      path,
+      'object',
+      describeActual(field),
+      'Field definition must be an object.',
+      'Replace this item with an object such as {"type":"TextField","label":"Name"}.'
+    );
+    return;
+  }
+
+  const type = normalizeDefinitionType(field);
+  if (!type) {
+    pushDiagnostic(
+      diagnostics,
+      'FIELD_TYPE_MISSING',
+      path + '.type',
+      'non-empty supported field type',
+      'missing',
+      'Field definition must include type, componentName, or componentType.',
+      'Add a supported type such as TextField, SelectField, TableField, or ColumnContainer.'
+    );
+    return;
+  }
+
+  if (!isBusinessFieldType(type) && !isPresentationFieldType(type)) {
+    pushDiagnostic(
+      diagnostics,
+      'UNSUPPORTED_FIELD_TYPE',
+      path + '.type',
+      BUSINESS_FIELD_TYPES.concat(PRESENTATION_FIELD_TYPES).join(', '),
+      type,
+      'Field type is not supported by openyida create-form.',
+      'Use one of the supported field types, or add CLI support before using this type.'
+    );
+    return;
+  }
+
+  if (validationOptions.insideTable && type === 'TableField') {
+    pushDiagnostic(
+      diagnostics,
+      'NESTED_TABLE_FIELD_UNSUPPORTED',
+      path,
+      'non-TableField child',
+      'TableField',
+      'TableField.children cannot contain another TableField.',
+      'Move the nested table to the top level or flatten the subtable fields.'
+    );
+    return;
+  }
+
+  if (validationOptions.insideTable && isPresentationFieldType(type)) {
+    pushDiagnostic(
+      diagnostics,
+      'TABLE_CHILD_PRESENTATION_UNSUPPORTED',
+      path,
+      'business field object',
+      type,
+      'TableField.children cannot contain presentation components.',
+      'Use business fields only inside TableField.children.'
+    );
+    return;
+  }
+
+  if (type === 'Column') {
+    if (!validationOptions.allowColumn) {
+      pushDiagnostic(
+        diagnostics,
+        'COLUMN_OUTSIDE_COLUMN_CONTAINER',
+        path,
+        'Column object inside ColumnContainer.children',
+        'Column',
+        'Column can only be used as a ColumnContainer.children Column object.',
+        'Move this Column object under ColumnContainer.children, or replace it with a normal field definition.'
+      );
+      return;
+    }
+    validateColumnObject(field, path, diagnostics);
+    return;
+  }
+
+  if (isBusinessFieldType(type) && !hasFieldLabel(field.label)) {
+    pushDiagnostic(
+      diagnostics,
+      'BUSINESS_FIELD_LABEL_MISSING',
+      path + '.label',
+      'non-empty string or i18n object',
+      field.label === undefined ? 'missing' : describeActual(field.label),
+      'Business field definitions must include a non-empty label.',
+      'Add a label that users will see on the form, such as "Name" or {"zh_CN":"姓名","en_US":"Name"}.'
+    );
+  }
+
+  if (type === 'Divider') {
+    validateDivider(field, path, diagnostics);
+    return;
+  }
+
+  if (type === 'ColumnContainer') {
+    validateColumnContainer(field, path, diagnostics);
+    return;
+  }
+
+  if (type === 'GroupContainer' || type === 'PageSection') {
+    validateOneDimensionalChildren(field, path, diagnostics, type);
+    return;
+  }
+
+  if (type === 'TableField') {
+    validateTableField(field, path, diagnostics);
+  }
+
+  if (
+    OPTION_FIELD_TYPES.indexOf(type) !== -1 &&
+    !hasFixedOptionSource(field) &&
+    !hasLegacyOptionSource(field) &&
+    !hasRemoteOptionSource(field)
+  ) {
+    pushDiagnostic(
+      diagnostics,
+      'OPTION_FIELD_DATASOURCE_MISSING',
+      path + '.dataSource',
+      'non-empty dataSource/options array or remote data source config',
+      'missing',
+      type + ' must define fixed options or a remote data source.',
+      'Provide dataSource (preferred), options, remoteDataSource, dataSourceConfig, dataSourceUrl, or searchConfig.'
+    );
+  }
+
+  if (type === 'AssociationFormField' && !hasAssociationForm(field)) {
+    pushDiagnostic(
+      diagnostics,
+      'ASSOCIATION_FORM_MISSING',
+      path + '.associationForm',
+      'object with non-empty formUuid',
+      field.associationForm === undefined ? 'missing' : describeActual(field.associationForm),
+      'AssociationFormField must include associationForm.formUuid.',
+      'Set associationForm to the target form metadata before creating or updating the form.'
+    );
+  }
+
+  if (
+    (type === 'EmployeeField' || type === 'DepartmentSelectField') &&
+    field.multiple !== undefined &&
+    typeof field.multiple !== 'boolean'
+  ) {
+    pushDiagnostic(
+      diagnostics,
+      'INVALID_MULTIPLE_TYPE',
+      path + '.multiple',
+      'boolean',
+      describeActual(field.multiple),
+      type + '.multiple must be a boolean when provided.',
+      'Use true or false instead of strings or numbers.'
+    );
+  }
+}
+
+function validateColumnObject(field, path, diagnostics) {
+  if (!validateChildrenPropertyShape(field, path, diagnostics, 'FieldDefinition[]')) {
+    return;
+  }
+  if (field.children === undefined || field.children === null) {
+    return;
+  }
+  field.children.forEach(function (child, childIndex) {
+    const childPath = path + '.children[' + childIndex + ']';
+    if (Array.isArray(child)) {
+      pushDiagnostic(
+        diagnostics,
+        'INVALID_COLUMN_CONTAINER_CHILDREN_DEPTH',
+        childPath,
+        'FieldDefinition object',
+        'array',
+        'Column.children must be a one-dimensional field array.',
+        'Remove the extra array nesting so Column.children is FieldDefinition[].'
+      );
+      return;
+    }
+    validateFieldDefinition(child, childPath, diagnostics);
+  });
+}
+
+function validateColumnContainer(field, path, diagnostics) {
+  if (!validateChildrenPropertyShape(field, path, diagnostics, 'FieldDefinition[][] or Column[]')) {
+    return;
+  }
+  if (field.children === undefined || field.children === null) {
+    return;
+  }
+  field.children.forEach(function (columnChildren, columnIndex) {
+    const columnPath = path + '.children[' + columnIndex + ']';
+    if (isPlainObject(columnChildren) && normalizeDefinitionType(columnChildren) === 'Column') {
+      validateFieldDefinition(columnChildren, columnPath, diagnostics, { allowColumn: true });
+      return;
+    }
+    if (!Array.isArray(columnChildren)) {
+      pushDiagnostic(
+        diagnostics,
+        'INVALID_COLUMN_CONTAINER_CHILDREN_DEPTH',
+        columnPath,
+        'array of FieldDefinition objects or Column object',
+        describeActual(columnChildren),
+        'ColumnContainer.children must contain two-dimensional field arrays or Column objects.',
+        'Use children: [[fieldA], [fieldB]] or children: [{ type: "Column", children: [fieldA] }].'
+      );
+      return;
+    }
+    columnChildren.forEach(function (child, childIndex) {
+      const childPath = columnPath + '[' + childIndex + ']';
+      if (Array.isArray(child)) {
+        pushDiagnostic(
+          diagnostics,
+          'INVALID_COLUMN_CONTAINER_CHILDREN_DEPTH',
+          childPath,
+          'FieldDefinition object',
+          'array',
+          'ColumnContainer.children must be exactly two levels deep.',
+          'Remove the extra array nesting so children is FieldDefinition[][].'
+        );
+        return;
+      }
+      validateFieldDefinition(child, childPath, diagnostics);
+    });
+  });
+}
+
+function validateOneDimensionalChildren(field, path, diagnostics, type) {
+  if (!validateChildrenPropertyShape(field, path, diagnostics, 'FieldDefinition[]')) {
+    return;
+  }
+  if (field.children === undefined || field.children === null) {
+    return;
+  }
+  field.children.forEach(function (child, childIndex) {
+    const childPath = path + '.children[' + childIndex + ']';
+    if (Array.isArray(child)) {
+      pushDiagnostic(
+        diagnostics,
+        'INVALID_' + type.toUpperCase() + '_CHILDREN_DEPTH',
+        childPath,
+        'FieldDefinition object',
+        'array',
+        type + '.children must be a one-dimensional field array.',
+        'Remove extra array nesting from ' + type + '.children.'
+      );
+      return;
+    }
+    validateFieldDefinition(child, childPath, diagnostics);
+  });
+}
+
+function validateTableField(field, path, diagnostics) {
+  if (!validateChildrenPropertyShape(field, path, diagnostics, 'FieldDefinition[]')) {
+    return;
+  }
+  if (field.children === undefined || field.children === null) {
+    return;
+  }
+  field.children.forEach(function (child, childIndex) {
+    const childPath = path + '.children[' + childIndex + ']';
+    if (Array.isArray(child)) {
+      pushDiagnostic(
+        diagnostics,
+        'INVALID_TABLE_FIELD_CHILDREN_DEPTH',
+        childPath,
+        'FieldDefinition object',
+        'array',
+        'TableField.children must be a one-dimensional field array.',
+        'Remove extra array nesting from TableField.children.'
+      );
+      return;
+    }
+    validateFieldDefinition(child, childPath, diagnostics, { insideTable: true });
+  });
+}
+
+function validateFormFieldDefinitions(fields, options) {
+  const validationOptions = options || {};
+  const rootPath = validationOptions.rootPath || 'fields';
+  const diagnostics = [];
+
+  if (!Array.isArray(fields)) {
+    pushDiagnostic(
+      diagnostics,
+      'INVALID_FIELDS_ROOT',
+      rootPath,
+      'FieldDefinition[]',
+      describeActual(fields),
+      'Field definitions root must be an array.',
+      'Use an array of field definitions or an object with a fields array.'
+    );
+    return diagnostics;
+  }
+
+  fields.forEach(function (field, index) {
+    validateFieldDefinition(field, rootPath + '[' + index + ']', diagnostics);
+  });
+
+  return diagnostics;
+}
+
+module.exports = {
+  validateFormFieldDefinitions,
+  normalizeDefinitionType,
+  BUSINESS_FIELD_TYPES,
+  PRESENTATION_FIELD_TYPES,
+};

package/lib/core/command-manifest.js

@@ -358,6 +358,7 @@ const COMMAND_SIDE_EFFECTS = new Map([
     'agent-capabilities',
     'check-page',
     'commands',
+    'create-form.validate-fields',
     'dingtalk-link',
     'formula.evaluate',
     'integration.diagnose',
@@ -616,6 +617,7 @@ const COMMAND_PERMISSIONS = new Map([
     'connector.list',
     'connector.list-actions',
     'connector.list-connections',
+    'create-form.validate-fields',
     'dingtalk-link',
     'dws.contact-user-search',
     'formula.evaluate',
@@ -1025,6 +1027,9 @@ const COMMAND_GROUPS = [
     titleKey: 'help.group_form',
     commands: [
       command('create-form.create', ['create-form', 'create'], 'create-form create <appType> ... [--locale zh_CN|en_US|ja_JP] [--open|--no-open]', 'help.cmd_create_form'),
+      command('create-form.validate-fields', ['create-form', 'validate-fields'], 'create-form validate-fields <fieldsJsonOrFile> [--json]', 'help.cmd_validate_form', {
+        requiresLogin: false,
+      }),
       command('create-form.update', ['create-form', 'update'], 'create-form update <appType> ... [--locale zh_CN|en_US|ja_JP] [--open|--no-open]', 'help.cmd_update_form'),
       command('create-form.patch', ['create-form', 'patch'], 'create-form patch <appType> <formUuid> <patchJsonOrFile> [--open|--no-open]', 'help.cmd_update_form'),
       command('create-form.rule', ['create-form', 'rule'], 'create-form rule <appType> <formUuid> <rulesJsonOrFile> [--open|--no-open]', 'help.cmd_update_form'),

package/lib/core/locales/en.js

@@ -30,6 +30,7 @@ module.exports = {
     cmd_import: 'Import migration package, rebuild app',
     group_form: 'Forms & Pages',
     cmd_create_form: 'Create a form page',
+    cmd_validate_form: 'Validate form field JSON locally',
     cmd_update_form: 'Update a form page',
     cmd_list_forms: 'List forms/pages in an app',
     cmd_aggregate_table: 'Manage aggregate tables (virtualView)',

package/lib/core/locales/zh.js

@@ -30,6 +30,7 @@ module.exports = {
     cmd_import: '导入迁移包，重建应用',
     group_form: '表单 & 页面',
     cmd_create_form: '创建表单页面',
+    cmd_validate_form: '本地校验表单字段 JSON',
     cmd_update_form: '更新表单页面',
     cmd_list_forms: '列出应用下的表单/页面',
     cmd_aggregate_table: '管理聚合表（virtualView）',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openyida",
-  "version": "2026.7.29-beta.2",
+  "version": "2026.7.30",
   "description": "OpenYida CLI - 宜搭低代码 AI 开发工具（安装即用，零配置）",
   "bin": {
     "openyida": "bin/yida.js",

package/yida-skills/skills/yida-create-form-page/SKILL.md

@@ -219,8 +219,8 @@ openyida create-form rule <appType> <formUuid> <rulesJsonOrFile>
 | `TextField` / `TextareaField` | 单行 / 多行文本 | 最常用文本字段 |
 | `NumberField` | 数字 | 金额、数量、分值 |
 | `DateField` / `CascadeDateField` | 日期 / 日期区间 | 流程表单常用 |
-| `SelectField` / `RadioField` | 单选 | 固定选项用 `dataSource` |
-| `CheckboxField` / `MultiSelectField` | 多选 | 固定选项用 `dataSource` |
+| `SelectField` / `RadioField` | 单选 | 创建字段 JSON 时必须提供 `dataSource`，不要省略或只写旧式 `options` |
+| `CheckboxField` / `MultiSelectField` | 多选 | 创建字段 JSON 时必须提供 `dataSource`，不要省略或只写旧式 `options` |
 | `EmployeeField` | 成员 | 细节见 [employee-field.md](references/employee-field.md) |
 | `DepartmentSelectField` | 部门 | 支持 `multiple` |
 | `AttachmentField` / `ImageField` | 附件 / 图片 | 表单内上传能力 |
@@ -244,7 +244,7 @@ openyida create-form rule <appType> <formUuid> <rulesJsonOrFile>
 
 - `appType` 必须来自已创建应用或用户提供
 - 字段类型必须使用标准组件名，如 `TextField`、`SelectField`
-- `SelectField`、`RadioField`、`CheckboxField`、`MultiSelectField` 固定选项必须提供 `dataSource`
+- `SelectField`、`MultiSelectField`、`RadioField`、`CheckboxField` 固定选项必须提供 `dataSource`；远程选项字段必须提供 `remoteDataSource` 或通过 `bind-datasource` 配置，不要生成无选项源的字段 JSON。
 - `TableField` 必须提供 `children`，且子表不能嵌套子表
 - `AssociationFormField` 必须提供 `associationForm`
 - update / add-option / bind-datasource / validation / rule 按字段 `label`、`fieldId` 或 `tableLabel + label` 解析并要求唯一命中；如果有重名字段，先看命令返回的 `diagnostics[].candidates`，可用 `tableLabel` 或 `fieldId` 缩小范围，仍不明确时再用 `get-schema --compact --resolve-fields`。

package/yida-skills/skills/yida-create-form-page/references/field-definition-guide.md

@@ -42,6 +42,8 @@
 | `children` | Object[] | 条件必填 | `TableField` / 展示布局组件必填 |
 | `associationForm` | Object | 条件必填 | `AssociationFormField` 必填 |
 
+选项类字段包括 `SelectField`、`MultiSelectField`、`RadioField`、`CheckboxField`。固定选项必须在字段 JSON 中提供非空 `dataSource`；不要省略选项源，也不要只写旧式 `options`。
+
 ## 展示/布局组件
 
 ### Divider