@@ -0,0 +1,10 @@
+---
+'@objectstack/spec': patch
+---
+
+fix(spec): the `ImportRequest.matchFields` describe says a multi-value or structured field is refused as a match key
+
+Clause-②: no
+Metadata-protocol: none
+
+The `matchFields` describe of `ImportRequestSchema` (the body of `POST /data/:object/import` and `POST /data/:object/import/jobs`, which ships in the published JSON schema and the generated API reference) did not say that an `update` / `upsert` whose match key names a field that holds a list or a structured value is refused at the import door with `400 INVALID_REQUEST` before any row. A caller picking `matchFields` from the describe learnt it only from the refusal. The describe now names the refusal; the fields it covers (a `multiple: true` select, radio, lookup, user, file or image field, a `multiselect`, `checkboxes` or `tags` field, or a `json`, `composite`, `repeater`, `record`, `location`, `address` or `vector` field, the population the spec's `isMultiValueField` and `STRUCTURED_JSON_TYPES` define); that a named mapping's `upsertKey` used as the key is judged the same way; the remedy (match on single-value fields); and the runner's answer for a caller that reaches it without the door (a mapping's connector pull): every row failed with `VALIDATION_ERROR`. Text only: no schema, accepted value or server answer changes.
@@ -53,7 +53,7 @@ const result = CreateImportJobRequestSchema.parse(data);
 | **mappingName** | `string` | optional | Name of a registered `mapping` metadata artifact to apply; the server resolves it (org-scoped rows first, then env-wide) and projects columns through it. Mutually exclusive with an inline `mapping` — supplying both is refused (400 CONFLICTING_MAPPING). |
 | **dryRun** | `boolean` | optional (default: `false`) | Validate + coerce every row without persisting. The verdict is the engine's own write-path validation, with one boundary an author should know: a preview runs NO automations. Hooks never fire in a dry run — a preview that executed user-authored side effects (mail, outbound calls, writes to other objects) would be the retired `validateOnly` defect in a new spelling. So a dry run with `runAutomations: true` can report `required` for a field a `beforeInsert` hook would populate during the real import; for hook-derived fields the real write is authoritative. |
 | **writeMode** | `Enum<'insert' \| 'update' \| 'upsert'>` | optional (default: `"insert"`) | insert / update / upsert semantics |
-| **matchFields** | `string[] \| string[][]` | optional | Fields that identify an existing record (required for update/upsert). Either one key set (`['email']`), or an ordered list of key sets (`[['credit_code'], ['country', 'registration_no']]`) for a sheet whose rows are identified in different ways: each row is matched by the first set whose fields are all non-blank on that row, and only by that set. A row blank on every set fails with `BLANK_MATCH_KEY` instead of being created or skipped, so `skipBlankMatchKey` cannot be combined with key sets. A set that matches more than one record fails the row with `AMBIGUOUS_MATCH`, as one key set does. Rows of one import that carry the same key (the key set each row is matched by, with its cell values as coerced, so an option label and its value are one key) all fail with `DUPLICATE_MATCH_KEY`, naming every row that carries it, and none of them is written, on a dry run as on the import: keep one row per key. |
+| **matchFields** | `string[] \| string[][]` | optional | Fields that identify an existing record (required for update/upsert). Either one key set (`['email']`), or an ordered list of key sets (`[['credit_code'], ['country', 'registration_no']]`) for a sheet whose rows are identified in different ways: each row is matched by the first set whose fields are all non-blank on that row, and only by that set. A row blank on every set fails with `BLANK_MATCH_KEY` instead of being created or skipped, so `skipBlankMatchKey` cannot be combined with key sets. A set that matches more than one record fails the row with `AMBIGUOUS_MATCH`, as one key set does. Rows of one import that carry the same key (the key set each row is matched by, with its cell values as coerced, so an option label and its value are one key) all fail with `DUPLICATE_MATCH_KEY`, naming every row that carries it, and none of them is written, on a dry run as on the import: keep one row per key. In `update` / `upsert`, a key (this field, or the named mapping's `upsertKey` it falls back to) naming a field that holds a list or a structured value — a `multiple: true` select, radio, lookup, user, file or image field, a `multiselect`, `checkboxes` or `tags` field, or a `json`, `composite`, `repeater`, `record`, `location`, `address` or `vector` field, the population `isMultiValueField` and `STRUCTURED_JSON_TYPES` define — is refused with `400 INVALID_REQUEST` before any row is matched or written, on a dry run as on the import, naming each such field (match on single-value fields: a code, a name, an email); a caller that hands rows to the import runner without this door (a mapping's connector pull) gets every row failed with `VALIDATION_ERROR` and the same refusal instead. |
 | **runAutomations** | `boolean` | optional (default: `true`) | Fire triggers/hooks for each imported row. ON by default, and opting out must be explicit: automations always ran on import historically (the engine ignored this flag until this flag was honoured), so omitting the key runs them. This matches platform convention (Salesforce fires triggers on import by default). Only the system principal (an in-process caller such as a seed or migration job) may send `runAutomations: false`, because it takes the object's triggers and metadata-bound hooks, its approvals and record freezes among them, off every row: the import doors refuse it from every other caller, every signed-in user and administrator included, with `403 PERMISSION_DENIED` before any row is read. One boundary: a `dryRun` preview runs NO automations whatever this flag says. |
 | **treatAsHistorical** | `boolean` | optional (default: `false`) | Import as established historical facts. Two effects, both off by default so a normal import is unchanged: (1) skip the state_machine rule so mid-lifecycle rows (e.g. already-closed tickets, closed_won deals) are not rejected by initialStates; and (2) preserve the original audit timeline — keep the supplied created_at / updated_at / updated_by and author-declared business readonly fields (e.g. closed_at, resolved_by) instead of stamping-now / stripping them. Undoing a historical import mirrors (2): the captured pre-import values are restored verbatim rather than re-stamped. Only the system principal (an in-process caller such as a seed or migration job) may send `treatAsHistorical: true`: the import doors refuse it from every other caller, every signed-in user and administrator included, with `403 PERMISSION_DENIED` before any row is read. |
 | **trimWhitespace** | `boolean` | optional (default: `true`) | Trim leading/trailing whitespace from string cells |
@@ -311,7 +311,7 @@ Type: `{ sourceField: string; targetField: string; targetLabel?: string; transfo
 | **mappingName** | `string` | optional | Name of a registered `mapping` metadata artifact to apply; the server resolves it (org-scoped rows first, then env-wide) and projects columns through it. Mutually exclusive with an inline `mapping` — supplying both is refused (400 CONFLICTING_MAPPING). |
 | **dryRun** | `boolean` | optional (default: `false`) | Validate + coerce every row without persisting. The verdict is the engine's own write-path validation, with one boundary an author should know: a preview runs NO automations. Hooks never fire in a dry run — a preview that executed user-authored side effects (mail, outbound calls, writes to other objects) would be the retired `validateOnly` defect in a new spelling. So a dry run with `runAutomations: true` can report `required` for a field a `beforeInsert` hook would populate during the real import; for hook-derived fields the real write is authoritative. |
 | **writeMode** | `Enum<'insert' \| 'update' \| 'upsert'>` | optional (default: `"insert"`) | insert / update / upsert semantics |
-| **matchFields** | `string[] \| string[][]` | optional | Fields that identify an existing record (required for update/upsert). Either one key set (`['email']`), or an ordered list of key sets (`[['credit_code'], ['country', 'registration_no']]`) for a sheet whose rows are identified in different ways: each row is matched by the first set whose fields are all non-blank on that row, and only by that set. A row blank on every set fails with `BLANK_MATCH_KEY` instead of being created or skipped, so `skipBlankMatchKey` cannot be combined with key sets. A set that matches more than one record fails the row with `AMBIGUOUS_MATCH`, as one key set does. Rows of one import that carry the same key (the key set each row is matched by, with its cell values as coerced, so an option label and its value are one key) all fail with `DUPLICATE_MATCH_KEY`, naming every row that carries it, and none of them is written, on a dry run as on the import: keep one row per key. |
+| **matchFields** | `string[] \| string[][]` | optional | Fields that identify an existing record (required for update/upsert). Either one key set (`['email']`), or an ordered list of key sets (`[['credit_code'], ['country', 'registration_no']]`) for a sheet whose rows are identified in different ways: each row is matched by the first set whose fields are all non-blank on that row, and only by that set. A row blank on every set fails with `BLANK_MATCH_KEY` instead of being created or skipped, so `skipBlankMatchKey` cannot be combined with key sets. A set that matches more than one record fails the row with `AMBIGUOUS_MATCH`, as one key set does. Rows of one import that carry the same key (the key set each row is matched by, with its cell values as coerced, so an option label and its value are one key) all fail with `DUPLICATE_MATCH_KEY`, naming every row that carries it, and none of them is written, on a dry run as on the import: keep one row per key. In `update` / `upsert`, a key (this field, or the named mapping's `upsertKey` it falls back to) naming a field that holds a list or a structured value — a `multiple: true` select, radio, lookup, user, file or image field, a `multiselect`, `checkboxes` or `tags` field, or a `json`, `composite`, `repeater`, `record`, `location`, `address` or `vector` field, the population `isMultiValueField` and `STRUCTURED_JSON_TYPES` define — is refused with `400 INVALID_REQUEST` before any row is matched or written, on a dry run as on the import, naming each such field (match on single-value fields: a code, a name, an email); a caller that hands rows to the import runner without this door (a mapping's connector pull) gets every row failed with `VALIDATION_ERROR` and the same refusal instead. |
 | **runAutomations** | `boolean` | optional (default: `true`) | Fire triggers/hooks for each imported row. ON by default, and opting out must be explicit: automations always ran on import historically (the engine ignored this flag until this flag was honoured), so omitting the key runs them. This matches platform convention (Salesforce fires triggers on import by default). Only the system principal (an in-process caller such as a seed or migration job) may send `runAutomations: false`, because it takes the object's triggers and metadata-bound hooks, its approvals and record freezes among them, off every row: the import doors refuse it from every other caller, every signed-in user and administrator included, with `403 PERMISSION_DENIED` before any row is read. One boundary: a `dryRun` preview runs NO automations whatever this flag says. |
 | **treatAsHistorical** | `boolean` | optional (default: `false`) | Import as established historical facts. Two effects, both off by default so a normal import is unchanged: (1) skip the state_machine rule so mid-lifecycle rows (e.g. already-closed tickets, closed_won deals) are not rejected by initialStates; and (2) preserve the original audit timeline — keep the supplied created_at / updated_at / updated_by and author-declared business readonly fields (e.g. closed_at, resolved_by) instead of stamping-now / stripping them. Undoing a historical import mirrors (2): the captured pre-import values are restored verbatim rather than re-stamped. Only the system principal (an in-process caller such as a seed or migration job) may send `treatAsHistorical: true`: the import doors refuse it from every other caller, every signed-in user and administrator included, with `403 PERMISSION_DENIED` before any row is read. |
 | **trimWhitespace** | `boolean` | optional (default: `true`) | Trim leading/trailing whitespace from string cells |
 
@@ -307,7 +307,16 @@ export const ImportRequestSchema = lazySchema(() => z.object({
       'import that carry the same key (the key set each row is matched by, with its cell values ' +
       'as coerced, so an option label and its value are one key) all fail with ' +
       '`DUPLICATE_MATCH_KEY`, naming every row that carries it, and none of them is written, on a ' +
-      'dry run as on the import: keep one row per key.',
+      'dry run as on the import: keep one row per key. In `update` / `upsert`, a key (this field, or the ' +
+      'named mapping\'s `upsertKey` it falls back to) naming a field that holds a list or a structured ' +
+      'value — a `multiple: true` select, radio, lookup, user, file or image field, a `multiselect`, ' +
+      '`checkboxes` or `tags` field, or a `json`, `composite`, `repeater`, `record`, `location`, ' +
+      '`address` or `vector` field, the population `isMultiValueField` and `STRUCTURED_JSON_TYPES` ' +
+      'define — is refused with `400 INVALID_REQUEST` before any row is matched or written, on a dry run ' +
+      'as on the import, naming each such field (match on single-value fields: a code, a name, an email); ' +
+      'a caller that hands rows to ' +
+      'the import runner without this door (a mapping\'s connector pull) gets every row failed with ' +
+      '`VALIDATION_ERROR` and the same refusal instead.',
     ),
   runAutomations: z.boolean().default(true)
     .describe(