@uipath/data-fabric-tool 1.201.0-preview.115 → 1.201.0-preview.121

package/src/commands/entities.ts

@@ -20,7 +20,11 @@ import type {
 import { EntityFieldDataType } from "@uipath/uipath-typescript";
 import { type Command, Option } from "commander";
 import { readJsonInput } from "../utils/input";
-import { fail, requireDestructiveConfirmation } from "../utils/output";
+import {
+    fail,
+    failInvalidArgument,
+    requireDestructiveConfirmation,
+} from "../utils/output";
 import { connectOrFail } from "../utils/sdk-client";
 import {
     findInvalidFieldConstraints,
@@ -110,30 +114,29 @@ const ENTITIES_GET_EXAMPLES: CommandExample[] = [
         Output: {
             Code: "EntitySchema",
             Data: {
-                id: "a1b2c3d4-0000-0000-0000-000000000001",
-                name: "Invoice",
-                displayName: "Invoice",
-                entityType: "Standard",
-                description: "Invoice records",
-                isRbacEnabled: false,
-                fields: [
+                Id: "a1b2c3d4-0000-0000-0000-000000000001",
+                Name: "Invoice",
+                DisplayName: "Invoice",
+                EntityType: "Standard",
+                Description: "Invoice records",
+                IsRbacEnabled: false,
+                Fields: [
                     {
-                        id: "f1000000-0000-0000-0000-000000000002",
-                        name: "amount",
-                        displayName: "Amount",
-                        fieldDataType: { name: "DECIMAL" },
-                        sqlType: {
-                            name: "DECIMAL",
-                            decimalPrecision: 2,
-                            minValue: 0,
-                            maxValue: 999999,
+                        Id: "f1000000-0000-0000-0000-000000000002",
+                        Name: "amount",
+                        DisplayName: "Amount",
+                        FieldDataType: {
+                            Name: "DECIMAL",
+                            DecimalPrecision: 2,
+                            MinValue: 0,
+                            MaxValue: 999999,
                         },
-                        isRequired: true,
-                        isUnique: false,
-                        isEncrypted: false,
-                        isRbacEnabled: false,
-                        isPrimaryKey: false,
-                        isSystemField: false,
+                        IsRequired: true,
+                        IsUnique: false,
+                        IsEncrypted: false,
+                        IsRbacEnabled: false,
+                        IsPrimaryKey: false,
+                        IsSystemField: false,
                     },
                 ],
             },
@@ -150,7 +153,7 @@ const ENTITIES_DELETE_EXAMPLES: CommandExample[] = [
         Output: {
             Code: "EntityDeleted",
             Data: {
-                ID: "a1b2c3d4-0000-0000-0000-000000000001",
+                Id: "a1b2c3d4-0000-0000-0000-000000000001",
                 Reason: "test entity cleanup",
             },
         },
@@ -164,13 +167,13 @@ const ENTITIES_CREATE_EXAMPLES: CommandExample[] = [
             "CHOICE_SET_SINGLE/CHOICE_SET_MULTIPLE require 'choiceSetId' (from 'df choice-sets list'). " +
             "RELATIONSHIP requires 'referenceEntityId' (UUID of the target entity, from 'df entities list') and 'referenceFieldId' (UUID of the field on the target entity, from 'df entities get <target-id>'). " +
             "Note: a RELATIONSHIP column on a record always stores the target record's UUID 'Id' (regardless of which 'referenceFieldId' configured the join) — see 'df records insert' for how to write the value. " +
-            "FILE fields take only 'fieldName' and 'type' — the server auto-wires the internal attachment reference; populate them later with 'uip df files upload <entity-id> <record-id> <field-name> --file <path>'. " +
+            "FILE fields take only 'name' and 'type' — the server auto-wires the internal attachment reference; populate them later with 'uip df files upload <entity-id> <record-id> <field-name> --file <path>'. " +
             "MULTILINE_MAX holds very large text ('lengthLimit' = UTF-16 byte budget, 1-131072; default max ~65,536 chars). Not filterable/sortable; 'records list'/'query' return a size marker — full content via 'records get'. Tenant-gated by the 'MultilineMax' feature flag.",
         Command:
-            'uip df entities create Expense --body \'{"displayName":"Expense","fields":[{"fieldName":"category","type":"CHOICE_SET_SINGLE","choiceSetId":"c1d2e3f4-0000-0000-0000-000000000001","isRequired":true},{"fieldName":"tags","type":"CHOICE_SET_MULTIPLE","choiceSetId":"c1d2e3f4-0000-0000-0000-000000000002"},{"fieldName":"submitter","type":"RELATIONSHIP","referenceEntityId":"a1b2c3d4-0000-0000-0000-000000000010","referenceFieldId":"f1000000-0000-0000-0000-000000000100","isRequired":true},{"fieldName":"receipt","type":"FILE"},{"fieldName":"notes","type":"MULTILINE_MAX"}]}\'',
+            'uip df entities create Expense --body \'{"displayName":"Expense","fields":[{"name":"category","type":"CHOICE_SET_SINGLE","choiceSetId":"c1d2e3f4-0000-0000-0000-000000000001","isRequired":true},{"name":"tags","type":"CHOICE_SET_MULTIPLE","choiceSetId":"c1d2e3f4-0000-0000-0000-000000000002"},{"name":"submitter","type":"RELATIONSHIP","referenceEntityId":"a1b2c3d4-0000-0000-0000-000000000010","referenceFieldId":"f1000000-0000-0000-0000-000000000100","isRequired":true},{"name":"receipt","type":"FILE"},{"name":"notes","type":"MULTILINE_MAX"}]}\'',
         Output: {
             Code: "EntityCreated",
-            Data: { ID: "a1b2c3d4-0000-0000-0000-000000000004" },
+            Data: { Id: "a1b2c3d4-0000-0000-0000-000000000004" },
         },
     },
     {
@@ -181,10 +184,47 @@ const ENTITIES_CREATE_EXAMPLES: CommandExample[] = [
             "CHOICE_SET_* fields resolve scope from 'choiceSetId' and must not pass 'referenceFolderKey'. " +
             "Get target entity/field IDs from 'df entities list --folder-key <key>' and 'df entities get <id> --folder-key <key>'; get choice-set IDs from 'df choice-sets list --folder-key <key>' (omit '--folder-key' for tenant-level choice sets).",
         Command:
-            'uip df entities create OrderLine --folder-key f1000000-0000-0000-0000-000000000050 --body \'{"displayName":"Order Line","fields":[{"fieldName":"purchaseOrder","type":"RELATIONSHIP","referenceEntityId":"a1b2c3d4-0000-0000-0000-000000000010","referenceFieldId":"f1000000-0000-0000-0000-000000000100","referenceFolderKey":"f1000000-0000-0000-0000-000000000060","isRequired":true},{"fieldName":"userType","type":"CHOICE_SET_SINGLE","choiceSetId":"c1d2e3f4-0000-0000-0000-000000000077"}]}\'',
+            'uip df entities create OrderLine --folder-key f1000000-0000-0000-0000-000000000050 --body \'{"displayName":"Order Line","fields":[{"name":"purchaseOrder","type":"RELATIONSHIP","referenceEntityId":"a1b2c3d4-0000-0000-0000-000000000010","referenceFieldId":"f1000000-0000-0000-0000-000000000100","referenceFolderKey":"f1000000-0000-0000-0000-000000000060","isRequired":true},{"name":"userType","type":"CHOICE_SET_SINGLE","choiceSetId":"c1d2e3f4-0000-0000-0000-000000000077"}]}\'',
         Output: {
             Code: "EntityCreated",
-            Data: { ID: "a1b2c3d4-0000-0000-0000-000000000005" },
+            Data: { Id: "a1b2c3d4-0000-0000-0000-000000000005" },
+        },
+    },
+];
+
+const ENTITIES_UPDATE_EXAMPLES: CommandExample[] = [
+    {
+        Description:
+            "Add a field. addFields uses the flat write shape: name + type, plus optional lengthLimit, minValue, maxValue, decimalPrecision, displayName, description, isRequired, isUnique, choiceSetId, referenceEntityId, referenceFieldId, and referenceFolderKey. A field object copied from 'df entities get' is accepted in addFields and normalized, but do not replay a full 'entities get' entity object as the update body.",
+        Command:
+            'uip df entities update a1b2c3d4-0000-0000-0000-000000000001 --body \'{"addFields":[{"name":"note","type":"STRING","lengthLimit":200}]}\'',
+        Output: {
+            Code: "EntityUpdated",
+            Data: { Id: "a1b2c3d4-0000-0000-0000-000000000001" },
+        },
+    },
+    {
+        Description:
+            "Update field metadata. updateFields uses field IDs from 'df entities get <entity-id>' and accepts metadata such as displayName, description, isRequired, isRbacEnabled, isEncrypted, isHiddenField, defaultValue, and constraints. Do not paste a full copied field object here; pass 'id' plus only the flat write-shape properties being changed. It cannot change a field's type or isUnique setting.",
+        Command:
+            'uip df entities update a1b2c3d4-0000-0000-0000-000000000001 --body \'{"updateFields":[{"id":"f1000000-0000-0000-0000-000000000002","displayName":"Amount (USD)","isRequired":true}]}\'',
+        Output: {
+            Code: "EntityUpdated",
+            Data: { Id: "a1b2c3d4-0000-0000-0000-000000000001" },
+        },
+    },
+    {
+        Description:
+            "Remove fields. removeFields uses field names, not field IDs, and requires --yes with --reason because the field values are deleted.",
+        Command:
+            'uip df entities update a1b2c3d4-0000-0000-0000-000000000001 --body \'{"removeFields":[{"name":"oldColumn"}]}\' --yes --reason "quarterly cleanup"',
+        Output: {
+            Code: "EntityUpdated",
+            Data: {
+                Id: "a1b2c3d4-0000-0000-0000-000000000001",
+                RemovedFields: ["oldColumn"],
+                Reason: "quarterly cleanup",
+            },
         },
     },
 ];
@@ -194,6 +234,7 @@ const VALID_FIELD_TYPES_LIST = [...VALID_FIELD_TYPES].join(", ");
 
 function hasInvalidFieldType(fields: unknown[]): boolean {
     return fields.some((f) => {
+        if (typeof f !== "object" || f === null) return false;
         const field = f as Record<string, unknown>;
         return (
             field.type !== undefined &&
@@ -209,6 +250,7 @@ const KNOWN_UPDATE_KEYS = [
     "displayName",
     "description",
     "isRbacEnabled",
+    "isAnalyticsEnabled",
 ] as const;
 
 function pickKnownUpdateKeys(
@@ -221,6 +263,187 @@ function pickKnownUpdateKeys(
     return out as EntityUpdateByIdOptions;
 }
 
+const ADD_FIELDS_ARRAY_INSTRUCTIONS =
+    'Example: {"addFields":[{"name":"title","type":"STRING"}]}';
+const UPDATE_FIELDS_ARRAY_INSTRUCTIONS =
+    'Example: {"updateFields":[{"id":"<fieldId>","displayName":"New Name"}]}';
+const REMOVE_FIELDS_ARRAY_INSTRUCTIONS =
+    'Example: {"removeFields":[{"name":"oldField"}]}';
+const ADD_FIELDS_FIELD_NAME_INSTRUCTIONS =
+    'Use the flat write shape, for example {"name":"title","type":"STRING"}. A field copied from "df entities get" is also accepted inside addFields and normalized.';
+const UPDATE_FIELDS_ID_INSTRUCTIONS =
+    'Use "df entities get <entityId>" to find field IDs. Example: {"id":"<fieldId>","displayName":"Total Amount","isRequired":true}';
+const REMOVE_FIELDS_FIELD_NAME_INSTRUCTIONS =
+    'Example: {"removeFields":[{"name":"oldField"}]}';
+
+function isObjectRecord(value: unknown): value is Record<string, unknown> {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function readKey(
+    record: Record<string, unknown>,
+    camelKey: string,
+    pascalKey: string,
+): unknown {
+    return record[camelKey] ?? record[pascalKey];
+}
+
+function readObjectKey(
+    record: Record<string, unknown>,
+    camelKey: string,
+    pascalKey: string,
+): Record<string, unknown> | undefined {
+    const value = readKey(record, camelKey, pascalKey);
+    return isObjectRecord(value) ? value : undefined;
+}
+
+function setIfDefined(
+    target: Record<string, unknown>,
+    key: string,
+    value: unknown,
+): void {
+    if (value !== undefined) target[key] = value;
+}
+
+function readId(value: unknown): unknown {
+    if (!isObjectRecord(value)) return undefined;
+    return value.id ?? value.Id ?? value.ID;
+}
+
+function readFieldTypeMetadata(
+    field: Record<string, unknown>,
+): Record<string, unknown> | undefined {
+    return readObjectKey(field, "fieldDataType", "FieldDataType");
+}
+
+function readConstraint(
+    field: Record<string, unknown>,
+    fieldTypeMetadata: Record<string, unknown> | undefined,
+    camelKey: string,
+    pascalKey: string,
+): unknown {
+    return (
+        readKey(field, camelKey, pascalKey) ??
+        (fieldTypeMetadata === undefined
+            ? undefined
+            : readKey(fieldTypeMetadata, camelKey, pascalKey))
+    );
+}
+
+function normalizeAddFieldShape(field: unknown): unknown {
+    if (!isObjectRecord(field)) return field;
+    if (field.name !== undefined || field.type !== undefined) return field;
+
+    const readName = readKey(field, "name", "Name");
+    const fieldTypeMetadata = readFieldTypeMetadata(field);
+    if (typeof readName !== "string" || fieldTypeMetadata === undefined) {
+        return field;
+    }
+
+    const normalized: Record<string, unknown> = { name: readName };
+    setIfDefined(
+        normalized,
+        "type",
+        readKey(fieldTypeMetadata, "name", "Name"),
+    );
+
+    for (const [writeKey, pascalKey] of [
+        ["displayName", "DisplayName"],
+        ["description", "Description"],
+        ["isRequired", "IsRequired"],
+        ["isUnique", "IsUnique"],
+        ["isRbacEnabled", "IsRbacEnabled"],
+        ["isEncrypted", "IsEncrypted"],
+        ["isHiddenField", "IsHiddenField"],
+        ["defaultValue", "DefaultValue"],
+    ] as const) {
+        setIfDefined(normalized, writeKey, readKey(field, writeKey, pascalKey));
+    }
+
+    for (const [writeKey, pascalKey] of [
+        ["lengthLimit", "LengthLimit"],
+        ["maxValue", "MaxValue"],
+        ["minValue", "MinValue"],
+        ["decimalPrecision", "DecimalPrecision"],
+    ] as const) {
+        setIfDefined(
+            normalized,
+            writeKey,
+            readConstraint(field, fieldTypeMetadata, writeKey, pascalKey),
+        );
+    }
+
+    setIfDefined(
+        normalized,
+        "choiceSetId",
+        readKey(field, "choiceSetId", "ChoiceSetId") ??
+            readId(readKey(field, "referenceChoiceSet", "ReferenceChoiceSet")),
+    );
+    setIfDefined(
+        normalized,
+        "referenceEntityId",
+        readKey(field, "referenceEntityId", "ReferenceEntityId") ??
+            readId(readKey(field, "referenceEntity", "ReferenceEntity")),
+    );
+    setIfDefined(
+        normalized,
+        "referenceFieldId",
+        readKey(field, "referenceFieldId", "ReferenceFieldId") ??
+            readId(readKey(field, "referenceField", "ReferenceField")),
+    );
+    setIfDefined(
+        normalized,
+        "referenceFolderKey",
+        readKey(field, "referenceFolderKey", "ReferenceFolderKey"),
+    );
+
+    return normalized;
+}
+
+function normalizeAddFields(addFields: unknown[]): unknown[] {
+    return addFields.map((field) => normalizeAddFieldShape(field));
+}
+
+function hasMissingStringField(fields: unknown[], key: string): boolean {
+    return fields.some((field) => {
+        if (!isObjectRecord(field)) return true;
+        const value = field[key];
+        return typeof value !== "string" || value.trim() === "";
+    });
+}
+
+function getUpdateArray(
+    input: Record<string, unknown>,
+    key: "addFields" | "updateFields" | "removeFields",
+    instructions: string,
+    issues: ValidationError[],
+): unknown[] | undefined {
+    const value = input[key];
+    if (value === undefined) return undefined;
+    if (Array.isArray(value)) return value;
+    issues.push({
+        message: `'${key}' must be an array`,
+        instructions,
+    });
+    return undefined;
+}
+
+function combineValidationIssues(
+    issues: ValidationError[],
+): ValidationError | null {
+    if (issues.length === 0) return null;
+    if (issues.length === 1) return issues[0];
+
+    return {
+        message: `Update body validation failed: ${issues
+            .map((issue) => issue.message)
+            .join("; ")}`,
+        instructions: issues
+            .map((issue, index) => `${index + 1}. ${issue.instructions}`)
+            .join("\n"),
+    };
+}
+
 // Run every check that applies to a `fields` / `addFields` payload:
 // name rules and UI-broken-type substitution. The SDK-enum type check
 // stays inline at the call site because it needs `hasInvalidFieldType`
@@ -380,9 +603,12 @@ export const registerEntitiesCommand = (program: Command) => {
         )
         .option(
             "-f, --file <path>",
-            "Path to JSON file with entity definition (fields array required; displayName, description, isRbacEnabled optional)",
+            "Path to JSON file with entity definition (fields array required; displayName, description, isRbacEnabled, isAnalyticsEnabled optional). A field object copied from 'df entities get' is also accepted and normalized to the write shape.",
+        )
+        .option(
+            "--body <json>",
+            "Inline JSON entity definition. A field object copied from 'df entities get' is also accepted and normalized to the write shape.",
         )
-        .option("--body <json>", "Inline JSON entity definition")
         .option(
             "--folder-key <key>",
             "Folder key (GUID) of the target folder (for folder-scoped entities)",
@@ -413,7 +639,7 @@ export const registerEntitiesCommand = (program: Command) => {
                 ) {
                     return fail(
                         "Entity definition must be a JSON object",
-                        "Provide a JSON object with a 'fields' array and optional displayName, description, isRbacEnabled.",
+                        "Provide a JSON object with a 'fields' array and optional displayName, description, isRbacEnabled, isAnalyticsEnabled.",
                     );
                 }
 
@@ -425,17 +651,20 @@ export const registerEntitiesCommand = (program: Command) => {
                     );
                 }
 
+                definition.fields = normalizeAddFields(
+                    definition.fields as unknown[],
+                );
+
                 const hasInvalidField = (definition.fields as unknown[]).some(
                     (f) =>
                         typeof f !== "object" ||
                         f === null ||
-                        typeof (f as Record<string, unknown>).fieldName !==
-                            "string",
+                        typeof (f as Record<string, unknown>).name !== "string",
                 );
                 if (hasInvalidField) {
                     return fail(
-                        "Each field must include a 'fieldName' string",
-                        'Example: {"fieldName":"title","type":"STRING"}',
+                        "Each field must include a 'name' string",
+                        'Example: {"name":"title","type":"STRING"}',
                     );
                 }
 
@@ -471,6 +700,10 @@ export const registerEntitiesCommand = (program: Command) => {
                     ...(definition.isRbacEnabled !== undefined && {
                         isRbacEnabled: definition.isRbacEnabled as boolean,
                     }),
+                    ...(definition.isAnalyticsEnabled !== undefined && {
+                        isAnalyticsEnabled:
+                            definition.isAnalyticsEnabled as boolean,
+                    }),
                     ...(options.folderKey !== undefined && {
                         folderKey: options.folderKey,
                     }),
@@ -511,11 +744,11 @@ export const registerEntitiesCommand = (program: Command) => {
         )
         .option(
             "-f, --file <path>",
-            "Path to JSON file with update options (addFields, updateFields, removeFields, displayName, description, isRbacEnabled)",
+            "Path to JSON file with update options. Field shapes: addFields [{name,type,...}], updateFields [{id,...}], removeFields [{name}]. Do not paste a full copied field object into updateFields; pass id plus only changed flat properties. Also accepts the entity metadata keys displayName, description, isRbacEnabled and isAnalyticsEnabled.",
         )
         .option(
             "--body <json>",
-            "Inline JSON update options (use `-` to read from stdin)",
+            "Inline JSON update options (use `-` to read from stdin). Field shapes: addFields [{name,type,...}], updateFields [{id,...}], removeFields [{name}]. Do not paste a full copied field object into updateFields; pass id plus only changed flat properties. Also accepts the entity metadata keys displayName, description, isRbacEnabled and isAnalyticsEnabled.",
         )
         .option(
             "-y, --yes",
@@ -532,6 +765,7 @@ export const registerEntitiesCommand = (program: Command) => {
             "--folder-key <key>",
             "Folder key (GUID) of the folder containing the entity (for folder-scoped entities)",
         )
+        .examples(ENTITIES_UPDATE_EXAMPLES)
         .trackedAction(
             processContext,
             async (id: string, options: UpdateEntityOptions) => {
@@ -544,7 +778,7 @@ export const registerEntitiesCommand = (program: Command) => {
                 );
 
                 if (parseError) {
-                    return fail(
+                    return failInvalidArgument(
                         "Error parsing update options",
                         parseError.message,
                     );
@@ -555,157 +789,165 @@ export const registerEntitiesCommand = (program: Command) => {
                     parsed === null ||
                     Array.isArray(parsed)
                 ) {
-                    return fail(
+                    return failInvalidArgument(
                         "Update options must be a JSON object",
-                        "Provide a JSON object with addFields, updateFields, removeFields, displayName, description, or isRbacEnabled.",
+                        "Provide a JSON object with addFields, updateFields, removeFields, displayName, description, isRbacEnabled, or isAnalyticsEnabled.",
                     );
                 }
 
                 const input = parsed as Record<string, unknown>;
-                const metadataErr = validateSchemaMetadata(input, "Entity");
-                if (metadataErr)
-                    return fail(metadataErr.message, metadataErr.instructions);
-
-                if (
-                    input.addFields !== undefined &&
-                    !Array.isArray(input.addFields)
-                ) {
-                    return fail(
-                        "'addFields' must be an array",
-                        'Example: {"addFields":[{"fieldName":"title","type":"STRING"}]}',
-                    );
+                if (Array.isArray(input.addFields)) {
+                    input.addFields = normalizeAddFields(input.addFields);
                 }
 
-                if (
-                    input.updateFields !== undefined &&
-                    !Array.isArray(input.updateFields)
-                ) {
-                    return fail(
-                        "'updateFields' must be an array",
-                        'Example: {"updateFields":[{"id":"<fieldId>","displayName":"New Name"}]}',
-                    );
-                }
+                const validationIssues: ValidationError[] = [];
 
-                if (
-                    input.removeFields !== undefined &&
-                    !Array.isArray(input.removeFields)
-                ) {
-                    return fail(
-                        "'removeFields' must be an array",
-                        'Example: {"removeFields":[{"fieldName":"oldField"}]}',
-                    );
+                if (input.name !== undefined) {
+                    validationIssues.push({
+                        message: "Entity name cannot be changed after creation",
+                        instructions:
+                            "Remove 'name' from the update body. The entity name is immutable — only 'displayName' and 'description' can be changed. To use a different name, create a new entity.",
+                    });
                 }
 
-                let trimmedReason: string | undefined;
-                let removedFieldNames: string[] = [];
-                const hasRemove =
-                    Array.isArray(input.removeFields) &&
-                    input.removeFields.length > 0;
-
-                if (hasRemove) {
-                    const removeFields = input.removeFields as unknown[];
-                    const hasInvalidRemove = removeFields.some((f) => {
-                        if (typeof f !== "object" || f === null) return true;
-                        const fn = (f as Record<string, unknown>).fieldName;
-                        return typeof fn !== "string" || fn.trim() === "";
+                const hasMetadataUpdate = [
+                    "description",
+                    "isRbacEnabled",
+                    "isAnalyticsEnabled",
+                ].some((key) => input[key] !== undefined);
+                if (hasMetadataUpdate && input.displayName === undefined) {
+                    validationIssues.push({
+                        message:
+                            "'displayName' is required when updating entity metadata",
+                        instructions:
+                            'Include the current displayName in the body alongside description/isRbacEnabled/isAnalyticsEnabled — get it with \'df entities get <entityId>\'. Example: {"displayName":"<current-display-name>","description":"<new-description>"}.',
                     });
-                    if (hasInvalidRemove) {
-                        return fail(
-                            "Each field in removeFields must include a non-empty 'fieldName' string",
-                            'Example: {"removeFields":[{"fieldName":"oldField"}]}',
-                        );
-                    }
+                }
 
-                    const reason = requireDestructiveConfirmation(
-                        options,
-                        `remove fields from entity '${id}'`,
-                        'Pass --reason "<text>" to record why fields are being removed.',
-                    );
-                    if (reason === null) return;
-                    trimmedReason = reason;
+                const metadataErr = validateSchemaMetadata(input, "Entity");
+                if (metadataErr) validationIssues.push(metadataErr);
 
-                    removedFieldNames = (
-                        removeFields as { fieldName: string }[]
-                    ).map((f) => f.fieldName);
-                }
+                const addFields = getUpdateArray(
+                    input,
+                    "addFields",
+                    ADD_FIELDS_ARRAY_INSTRUCTIONS,
+                    validationIssues,
+                );
+                const updateFields = getUpdateArray(
+                    input,
+                    "updateFields",
+                    UPDATE_FIELDS_ARRAY_INSTRUCTIONS,
+                    validationIssues,
+                );
+                const removeFields = getUpdateArray(
+                    input,
+                    "removeFields",
+                    REMOVE_FIELDS_ARRAY_INSTRUCTIONS,
+                    validationIssues,
+                );
 
-                if (Array.isArray(input.addFields)) {
-                    const hasInvalidField = (input.addFields as unknown[]).some(
-                        (f) => {
-                            if (typeof f !== "object" || f === null)
-                                return true;
-                            const fn = (f as Record<string, unknown>).fieldName;
-                            return typeof fn !== "string" || fn.trim() === "";
-                        },
+                let addFieldNames: string[] = [];
+                if (addFields !== undefined) {
+                    const hasInvalidAddFieldsShape = hasMissingStringField(
+                        addFields,
+                        "name",
                     );
-                    if (hasInvalidField) {
-                        return fail(
-                            "Each field in addFields must include a non-empty 'fieldName' string",
-                            'Example: {"fieldName":"title","type":"STRING"}',
+                    if (hasInvalidAddFieldsShape) {
+                        validationIssues.push({
+                            message:
+                                "Each field in addFields must include a non-empty 'name' string",
+                            instructions: ADD_FIELDS_FIELD_NAME_INSTRUCTIONS,
+                        });
+                    } else {
+                        addFieldNames = (addFields as { name: string }[]).map(
+                            (field) => field.name,
                         );
+
+                        if (hasInvalidFieldType(addFields)) {
+                            validationIssues.push({
+                                message: "Invalid field type in addFields",
+                                instructions: `Valid types: ${VALID_FIELD_TYPES_LIST}`,
+                            });
+                        }
+
+                        const addErr = validateFieldsPayload(addFields);
+                        if (addErr) validationIssues.push(addErr);
                     }
+                }
 
-                    if (hasInvalidFieldType(input.addFields as unknown[])) {
-                        return fail(
-                            "Invalid field type in addFields",
-                            `Valid types: ${VALID_FIELD_TYPES_LIST}`,
-                        );
+                let removedFieldNames: string[] = [];
+                if (removeFields !== undefined) {
+                    if (hasMissingStringField(removeFields, "name")) {
+                        validationIssues.push({
+                            message:
+                                "Each field in removeFields must include a non-empty 'name' string",
+                            instructions: REMOVE_FIELDS_FIELD_NAME_INSTRUCTIONS,
+                        });
+                    } else {
+                        removedFieldNames = (
+                            removeFields as { name: string }[]
+                        ).map((field) => field.name);
                     }
+                }
 
-                    const addErr = validateFieldsPayload(
-                        input.addFields as unknown[],
+                if (addFieldNames.length > 0 && removedFieldNames.length > 0) {
+                    const removedNamesLower = new Set(
+                        removedFieldNames.map((name) => name.toLowerCase()),
                     );
-                    if (addErr)
-                        return fail(addErr.message, addErr.instructions);
-
-                    const addNames = (
-                        input.addFields as { fieldName: string }[]
-                    ).map((f) => f.fieldName);
-                    if (removedFieldNames.length > 0) {
-                        const removedNamesLower = new Set(
-                            removedFieldNames.map((name) => name.toLowerCase()),
-                        );
-                        const conflict = addNames.find((name) =>
-                            removedNamesLower.has(name.toLowerCase()),
-                        );
-                        if (conflict !== undefined) {
-                            return fail(
-                                `Field '${conflict}' appears in both addFields and removeFields`,
+                    const conflict = addFieldNames.find((name) =>
+                        removedNamesLower.has(name.toLowerCase()),
+                    );
+                    if (conflict !== undefined) {
+                        validationIssues.push({
+                            message: `Field '${conflict}' appears in both addFields and removeFields`,
+                            instructions:
                                 "A single update cannot add and remove the same field. Split into two calls if you need to recreate it.",
-                            );
-                        }
+                        });
                     }
                 }
 
-                if (Array.isArray(input.updateFields)) {
-                    const hasInvalidField = (
-                        input.updateFields as unknown[]
-                    ).some((f) => {
-                        if (typeof f !== "object" || f === null) return true;
-                        const fid = (f as Record<string, unknown>).id;
-                        return typeof fid !== "string" || fid.trim() === "";
-                    });
-                    if (hasInvalidField) {
-                        return fail(
-                            "Each field in updateFields must include a non-empty 'id' string",
-                            'Use \'df entities get <entityId>\' to find field IDs. Example: {"id":"<fieldId>","displayName":"Total Amount","isRequired":true}',
-                        );
+                if (updateFields !== undefined) {
+                    const hasInvalidUpdateFieldsShape = hasMissingStringField(
+                        updateFields,
+                        "id",
+                    );
+                    if (hasInvalidUpdateFieldsShape) {
+                        validationIssues.push({
+                            message:
+                                "Each field in updateFields must include a non-empty 'id' string",
+                            instructions: UPDATE_FIELDS_ID_INSTRUCTIONS,
+                        });
+                    } else {
+                        const updateErr =
+                            findIsUniqueInUpdateFields(updateFields);
+                        if (updateErr) validationIssues.push(updateErr);
+
+                        const updateMetadataErr =
+                            findInvalidFieldMetadata(updateFields);
+                        if (updateMetadataErr)
+                            validationIssues.push(updateMetadataErr);
                     }
+                }
 
-                    const updateErr = findIsUniqueInUpdateFields(
-                        input.updateFields as unknown[],
+                const validationErr = combineValidationIssues(validationIssues);
+                if (validationErr) {
+                    return failInvalidArgument(
+                        validationErr.message,
+                        validationErr.instructions,
                     );
-                    if (updateErr)
-                        return fail(updateErr.message, updateErr.instructions);
+                }
+
+                let trimmedReason: string | undefined;
+                const hasRemove = removedFieldNames.length > 0;
 
-                    const updateMetadataErr = findInvalidFieldMetadata(
-                        input.updateFields as unknown[],
+                if (hasRemove) {
+                    const reason = requireDestructiveConfirmation(
+                        options,
+                        `remove fields from entity '${id}'`,
+                        'Pass --reason "<text>" to record why fields are being removed.',
                     );
-                    if (updateMetadataErr)
-                        return fail(
-                            updateMetadataErr.message,
-                            updateMetadataErr.instructions,
-                        );
+                    if (reason === null) return;
+                    trimmedReason = reason;
                 }
 
                 const sdk = await connectOrFail(options.tenant);