feat(spec,rest,lint): an import mapping target may name a declared part of a compound field

A target may name field.part when the field's stored value schema is a
closed object of optional strings (address); the import door assembles
the parts one row maps into one value before the engine sees the row.
An unknown part, a dotted path on a field with no parts, and a field
written both whole and by part stay refused at validate, the dry run
and the commit, naming the legal parts.

Claude-Session: https://claude.ai/code/session_01QcAS3qiYYZNezaxZxaUdMV
Co-authored-by: Claude <noreply@anthropic.com>

Author: claude

.changeset/20149-import-mapping-compound-parts.md

@@ -0,0 +1,56 @@
+---
+"@objectstack/spec": minor
+"@objectstack/rest": minor
+"@objectstack/lint": minor
+---
+
+feat(spec,rest,lint): an import mapping target may name a declared part of a compound field (`mailing_address.street`), and the importer assembles the parts into one value (#20149)
+
+Clause-②: yes
+
+**What was missing.** A mapping could write each source column to one flat
+field only, so nothing could build an `address` value from the separate
+street / city / state / postal code / country columns a spreadsheet carries.
+A dotted target such as `mailing_address.street` named no field and was
+refused at `objectstack validate`, on the dry run and on the commit.
+
+**What changes.**
+
+- `@objectstack/spec`: `ImportFieldMappingSchema.target` declares the part
+  path. A target may name `field.part` when `field` is a declared field whose
+  stored value schema is a closed object of optional strings (today:
+  `address`), and `part` is a key that schema declares: `street`, `city`,
+  `state`, `postalCode`, `country`, `countryCode`, `formatted`. The part names
+  are read from the value schema, never listed by hand. The one verdict,
+  `judgeImportMappingTarget`, answers the new `{ kind: 'part', field, part }`;
+  `indexImportMappingTargets` carries each compound field's parts on
+  `parts`; `unknownImportMappingTargets` gives each refused target a `reason`
+  (`unknown` or `collides`) and, for a dotted target, what its `head` names.
+  `location` is not compound for import: its parts are required numbers, so a
+  value assembled from text cells would be the wrong type.
+- `@objectstack/rest`: `applyMappingToRows` assembles every part target of a
+  row into one value under the field's key, before the engine sees the row,
+  whatever transform produced the part (`none`, `map`, `constant`, `join`,
+  each element of a `split`). A blank part cell (empty, whitespace or a
+  `nullValues` token) is left out, string parts are trimmed under
+  `trimWhitespace`, and a row whose parts are all blank leaves the field
+  unset, as a blank flat cell does. On an update the assembled value replaces
+  the stored one. The dry run and the commit judge the same assembled row.
+- `@objectstack/lint`: `mapping-target-field-unknown` accepts a declared part
+  and reports what stays refused, naming the legal parts each time.
+
+**Still refused, at `objectstack validate`, on the dry run and on the commit
+(`400 INVALID_FIELD`, before any row):**
+
+- a part the value does not declare (`mailing_address.stret`); the refusal
+  lists the declared parts;
+- a dotted path on a field with no parts (`full_name.first`). A dotted target
+  never traverses a reference (`account.name`): map the column to the
+  reference field with transform `lookup`;
+- a mapping that writes a field both whole and by part (`mailing_address` and
+  `mailing_address.street`): one row carries one value for the field. Map it
+  whole or by its parts, not both.
+
+**What to do.** Nothing, unless you want the capability: point each address
+column at `field.part`, for example `{ source: 'Zip', target:
+'mailing_address.postalCode' }`.

content/docs/data-modeling/import-mappings.mdx

@@ -103,7 +103,7 @@ Each `fieldMapping` entry:
 | Key | Type | What it does |
 |:---|:---|:---|
 | `source` | `string \| string[]` | Source column header(s). An array is only meaningful for `join`. |
-| `target` | `string \| string[]` | Target field name(s). An array is only meaningful for `split`. |
+| `target` | `string \| string[]` | Target field name(s), or `field.part` for a declared part of an address field (`mailing_address.street`; the parts are `street`, `city`, `state`, `postalCode`, `country`, `countryCode`, `formatted`). The parts one row maps are assembled into the field's one value: a blank part cell is left out, a row whose parts are all blank leaves the field unset, and on an update the assembled value replaces the stored one. A mapping writes a field whole or by its parts, never both. An array is only meaningful for `split`. |
 | `transform` | `TransformType` | Defaults to `'none'`. |
 | `params` | object | Configuration for the transform — `value`, `valueMap`, `separator`. |
 

packages/lint/src/validate-mapping-target-fields.test.ts

@@ -29,12 +29,12 @@ const mapping = (fieldMapping: unknown[], extra: Record<string, unknown> = {}) =
 });
 
 describe('validateMappingTargetFields', () => {
-  it('reports a target that names no field of the object, located at the mapping (the card\'s shape)', () => {
+  it('reports a target that names no field of the object, located at the mapping', () => {
     const findings = validateMappingTargetFields({
       objects: [contact],
       mappings: [mapping([
         { source: 'Name', target: 'full_name' },
-        { source: 'Street', target: 'mailing_address.street' },
+        { source: 'Mail', target: 'emial' },
       ])],
     });
     expect(findings).toHaveLength(1);
@@ -44,10 +44,85 @@ describe('validateMappingTargetFields', () => {
       where: 'mapping "contact_import" · object "crm_contact"',
       path: 'mappings[0].fieldMapping[1].target',
     });
-    // Names the target and the object, and says why a dotted path is not one.
-    expect(findings[0].message).toContain('"mailing_address.street"');
+    // Names the target and the object, and the closest name the object has.
+    expect(findings[0].message).toContain('"emial"');
     expect(findings[0].message).toContain('"crm_contact"');
-    expect(findings[0].message).toContain('"mailing_address" is a field of "crm_contact"');
+    expect(findings[0].message).toContain('Did you mean "email"?');
+  });
+
+  // [#20149] The card's shape, which #20150 pinned red here, is now a target:
+  // a declared part of a compound field. The flip is load-bearing: the whole
+  // address template is green, every part the value schema declares.
+  it('is green on a mapping that writes an address by its declared parts (the card\'s five columns and more)', () => {
+    expect(validateMappingTargetFields({
+      objects: [contact],
+      mappings: [mapping([
+        { source: 'Name', target: 'full_name' },
+        { source: 'Street', target: 'mailing_address.street' },
+        { source: 'City', target: 'mailing_address.city' },
+        { source: 'State', target: 'mailing_address.state' },
+        { source: 'Zip', target: 'mailing_address.postalCode' },
+        { source: 'Country', target: 'mailing_address.country' },
+        { source: 'x', target: 'mailing_address.countryCode', transform: 'constant', params: { value: 'US' } },
+        { source: ['Line 1', 'Line 2'], target: 'mailing_address.formatted', transform: 'join' },
+      ])],
+    })).toEqual([]);
+  });
+
+  it('refuses a part the address value does not declare, naming every part it does', () => {
+    const findings = validateMappingTargetFields({
+      objects: [contact],
+      mappings: [mapping([{ source: 'Street', target: 'mailing_address.stret' }])],
+    });
+    expect(findings.map((f) => f.path)).toEqual(['mappings[0].fieldMapping[0].target']);
+    expect(findings[0].rule).toBe(MAPPING_TARGET_FIELD_UNKNOWN);
+    expect(findings[0].message).toContain(
+      '"stret" is not a part of the address field "mailing_address": the parts a target may name on it are '
+      + 'street, city, state, postalCode, country, countryCode, formatted.',
+    );
+    expect(findings[0].message).toContain('Did you mean "street"?');
+    expect(findings[0].hint).toContain(
+      'or at a declared part of a compound field as field.part (mailing_address: street, city, state, postalCode, country, countryCode, formatted)',
+    );
+  });
+
+  it('refuses a dotted path on a field with no parts — and never reads it as a lookup traversal', () => {
+    const findings = validateMappingTargetFields({
+      objects: [{ ...contact, fields: { ...contact.fields, account: { type: 'lookup', reference: 'crm_account' } } }],
+      mappings: [mapping([
+        { source: 'First', target: 'full_name.first' },
+        { source: 'Account', target: 'account.name' },
+      ])],
+    });
+    expect(findings.map((f) => f.path)).toEqual([
+      'mappings[0].fieldMapping[0].target',
+      'mappings[0].fieldMapping[1].target',
+    ]);
+    expect(findings[0].message).toContain('The text field "full_name" is a field of "crm_contact" with no parts');
+    expect(findings[1].message).toContain('The lookup field "account" is a field of "crm_contact" with no parts');
+    expect(findings[1].message).toContain('Map the column to "account" with transform "lookup"');
+    // The part list rides along either way, so the author sees what IS a part.
+    expect(findings[0].hint).toContain('mailing_address: street, city');
+  });
+
+  it('refuses a part of a field the same mapping also writes whole — the two collide', () => {
+    const findings = validateMappingTargetFields({
+      objects: [contact],
+      mappings: [mapping([
+        { source: 'Address JSON', target: 'mailing_address' },
+        { source: 'Street', target: 'mailing_address.street' },
+      ])],
+    });
+    expect(findings).toHaveLength(1);
+    expect(findings[0]).toMatchObject({
+      rule: MAPPING_TARGET_FIELD_UNKNOWN,
+      path: 'mappings[0].fieldMapping[1].target',
+      hint: 'Map the field whole or by its parts, not both.',
+    });
+    expect(findings[0].message).toContain(
+      'writes the compound field "mailing_address" of object "crm_contact" both whole (fieldMapping[0].target) '
+      + 'and by its part "street" (fieldMapping[1].target)',
+    );
   });
 
   it('is green on the control mapping — declared fields only', () => {

packages/lint/src/validate-mapping-target-fields.ts

@@ -15,6 +15,17 @@
  * written, so the author meets the refusal at `os validate` rather than at the
  * first import.
  *
+ * ## A declared part of a compound field (#20149)
+ *
+ * A target may also name a declared PART of a compound field
+ * (`mailing_address.street`); the import endpoint assembles the parts one row
+ * maps into that field's one value. The shared verdict decides which fields
+ * are compound and which parts they declare, from the field's value schema.
+ * This rule reports what stays refused, and names the legal parts each time:
+ * a part the value does not declare (`mailing_address.stret`), a dotted path
+ * on a field with no parts (never a lookup traversal), and a part of a field
+ * the same mapping also writes whole (the two would collide on one value).
+ *
  * ## One verdict, two doors
  *
  * The verdict is not written here. It is `unknownImportMappingTargets`
@@ -46,11 +57,20 @@
  * them; the import door, which reads the registered object, still judges them.
  */
 
-import { indexImportMappingTargets, unknownImportMappingTargets } from '@objectstack/spec/data';
+import {
+  indexImportMappingTargets,
+  REFERENCE_VALUE_TYPES,
+  unknownImportMappingTargets,
+  type ImportMappingTargetHead,
+} from '@objectstack/spec/data';
 
 import { listNames, recordsOf, suggestName } from './object-graph.js';
 
-/** A `fieldMapping[].target` that names no field of the mapping's object. */
+/**
+ * A `fieldMapping[].target` the mapping cannot write on its object: it names no
+ * field and no declared part of a compound field, or it names a part of a field
+ * the same mapping also writes whole.
+ */
 export const MAPPING_TARGET_FIELD_UNKNOWN = 'mapping-target-field-unknown';
 
 export interface MappingTargetFieldFinding {
@@ -99,8 +119,10 @@ function extensionFieldsByTarget(stack: AnyRec): Map<string, AnyRec[]> {
 }
 
 /**
- * Report every import-mapping target that names no field of its object.
- * Returns findings (empty = clean).
+ * Report every import-mapping target its mapping cannot write on its object:
+ * one that names no field and no declared part of a compound field, and a
+ * part of a field the same mapping also writes whole. Returns findings
+ * (empty = clean).
  */
 export function validateMappingTargetFields(stack: AnyRec): MappingTargetFieldFinding[] {
   const findings: MappingTargetFieldFinding[] = [];
@@ -128,31 +150,80 @@ export function validateMappingTargetFields(stack: AnyRec): MappingTargetFieldFi
 
     const misses = unknownImportMappingTargets(mapping.fieldMapping, objectDef);
     if (misses.length === 0) continue; // clean, or skip 2
-    const known = indexImportMappingTargets(objectDef)?.names ?? new Set<string>();
+    const index = indexImportMappingTargets(objectDef);
+    const known = index?.names ?? new Set<string>();
+    const compound = index ? [...index.parts] : [];
     const mappingName = strName(mapping.name) ?? `#${mi}`;
+    const where = `mapping "${mappingName}" · object "${objectName}"`;
 
     for (const miss of misses) {
-      const dot = miss.target.indexOf('.');
-      const head = dot > 0 ? miss.target.slice(0, dot) : undefined;
-      const dotted = head !== undefined && known.has(head)
-        ? ` "${head}" is a field of "${objectName}", but a target names a whole field: a dotted path into a field's value is not a target.`
-        : '';
+      if (miss.reason === 'collides') {
+        const dot = miss.target.indexOf('.');
+        findings.push({
+          severity: 'error',
+          rule: MAPPING_TARGET_FIELD_UNKNOWN,
+          where,
+          path: `mappings[${mi}].${miss.path}`,
+          message:
+            `Import mapping "${mappingName}" writes the compound field "${miss.target.slice(0, dot)}" of object ` +
+            `"${objectName}" both whole (${miss.wholeAt}) and by its part "${miss.target.slice(dot + 1)}" ` +
+            `(${miss.path}). One row carries one value for a field, so the two collide, and the import endpoint ` +
+            `refuses this mapping before any row, on the dry run and the commit alike (INVALID_FIELD).`,
+          hint: 'Map the field whole or by its parts, not both.',
+        });
+        continue;
+      }
       findings.push({
         severity: 'error',
         rule: MAPPING_TARGET_FIELD_UNKNOWN,
-        where: `mapping "${mappingName}" · object "${objectName}"`,
+        where,
         path: `mappings[${mi}].${miss.path}`,
         message:
           `Import mapping "${mappingName}" writes target "${miss.target}", which names no field of ` +
           `object "${objectName}". The import endpoint refuses this mapping before any row, on the dry ` +
           `run and the commit alike (INVALID_FIELD), so it can import nothing.` +
-          dotted +
-          (dotted ? '' : suggestName(miss.target, known)),
+          (miss.head?.field ? dottedReason(miss.head, miss.target, objectName) : suggestName(miss.target, known)),
         hint:
           `Point the target at a field "${objectName}" declares, or at a column the platform provisions ` +
-          `on it. Addressable names: ${listNames(known)}.`,
+          `on it` +
+          (compound.length > 0
+            ? `, or at a declared part of a compound field as field.part (` +
+              compound.map(([field, parts]) => `${field}: ${parts.join(', ')}`).join('; ') + ')'
+            : '') +
+          `. Addressable names: ${listNames(known)}.`,
       });
     }
   }
   return findings;
 }
+
+/**
+ * Why a dotted target whose head names a field of the object is still no
+ * target (#20149): its part is not one the field's value declares, or the
+ * field has no parts at all.
+ */
+function dottedReason(head: ImportMappingTargetHead, target: string, objectName: string): string {
+  const field = head.type ? `the ${head.type} field "${head.name}"` : `"${head.name}"`;
+  if (head.parts) {
+    const part = target.slice(head.name.length + 1);
+    return (
+      ` "${part}" is not a part of ${field}: the parts a target may name on it are ` +
+      `${head.parts.join(', ')}.` + suggestName(part, head.parts)
+    );
+  }
+  if (head.type && REFERENCE_VALUE_TYPES.has(head.type)) {
+    return (
+      ` ${capitalize(field)} is a field of "${objectName}" with no parts: a dotted target never ` +
+      `traverses a reference. Map the column to "${head.name}" with transform "lookup", which resolves ` +
+      `the cell's display text to a record id.`
+    );
+  }
+  return (
+    ` ${capitalize(field)} is a field of "${objectName}" with no parts: only a compound field ` +
+    `(one whose value declares parts, such as an address) takes a part target.`
+  );
+}
+
+function capitalize(text: string): string {
+  return text.length > 0 ? text[0].toUpperCase() + text.slice(1) : text;
+}

packages/rest/src/import-coerce.ts

@@ -178,7 +178,12 @@ function coerceError(
 
 // ── blank / null handling ──────────────────────────────────────────
 
-function isBlank(value: unknown, nullValues?: string[]): boolean {
+/**
+ * Whether a cell is blank: absent, empty or whitespace, or one of the
+ * request's `nullValues`. Exported for the named mapping's compound-part
+ * assembly (#20149), which drops a blank part by this same rule.
+ */
+export function isBlank(value: unknown, nullValues?: string[]): boolean {
   if (value === null || value === undefined) return true;
   if (typeof value === 'string') {
     const s = value.trim();