@fluentcommerce/fc-connect-sdk 0.1.54 → 0.1.56

package/docs/02-CORE-GUIDES/mapping/graphql-mutation-mapping/modules/graphql-mutation-mapping-06-path-syntax.md

@@ -1,464 +1,464 @@
-# Path Syntax
-
-[← Back to GraphQL Mutation Mapping Guide](../graphql-mutation-mapping-readme.md)
-
-**Module 6 of 13** | **Level**: Intermediate | **Time**: 15 minutes
-
----
-
-## Path Syntax Overview
-
-**How it works:** XMLPathResolver automatically handles XML parser internals (`#text` wrappers, `@` attribute prefixes). You write natural paths - the SDK handles complexity.
-
-## Naming Conventions for XML Attributes
-
-**Choose ONE convention per project and use it consistently throughout your XML and mappings.**
-
-### Recommended: Kebab-Case (XML Standard)
-
-This is the most common convention in XML and SFCC integrations:
-
-```xml
-<order order-no="ORD-123" customer-id="CUST-456">
-  <line-item item-id="ITEM-001" product-ref="SKU-001" />
-  <shipping-address postal-code="62701" />
-</order>
-```
-
-```json
-{
-  "ref": { "source": "order@order-no" },
-  "customerId": { "source": "order@customer-id" },
-  "items": {
-    "source": "order.line-item",
-    "isArray": true,
-    "fields": {
-      "itemId": { "source": "$.@item-id" },
-      "productRef": { "source": "$.@product-ref" }
-    }
-  }
-}
-```
-
-**✅ Pros:**
-- XML industry standard
-- Works well with SFCC, SAP, Oracle systems
-- Easy to read in XML
-- Matches most external API specs
-
-### Alternative: CamelCase (Modern APIs)
-
-Used by modern REST APIs and some e-commerce platforms:
-
-```xml
-<order orderNo="ORD-123" customerId="CUST-456">
-  <lineItem itemId="ITEM-001" productRef="SKU-001" />
-  <shippingAddress postalCode="62701" />
-</order>
-```
-
-```json
-{
-  "ref": { "source": "order@orderNo" },
-  "customerId": { "source": "order@customerId" },
-  "items": {
-    "source": "order.lineItem",
-    "isArray": true,
-    "fields": {
-      "itemId": { "source": "$.@itemId" },
-      "productRef": { "source": "$.@productRef" }
-    }
-  }
-}
-```
-
-**✅ Pros:**
-- Matches JavaScript/TypeScript conventions
-- No need for quotes in JavaScript objects
-- Easier to type (no hyphens)
-
-### ⚠️ IMPORTANT: Never Mix Conventions
-
-```json
-// ❌ BAD - Inconsistent naming
-{
-  "ref": { "source": "order@order-no" },      // kebab-case
-  "customerId": { "source": "order@customerId" },  // camelCase
-  "total": { "source": "order@OrderTotal" }    // PascalCase
-}
-
-// ✅ GOOD - Consistent kebab-case throughout
-{
-  "ref": { "source": "order@order-no" },
-  "customerId": { "source": "order@customer-id" },
-  "total": { "source": "order@order-total" }
-}
-```
-
-**Best Practice**: If integrating with an existing system (like SFCC), match their naming convention. If building from scratch, choose kebab-case for XML standard compliance.
-
-### XML Paths
-
-```json
-{
-  "sourceFormat": "xml",
-  "arguments": {
-    "input": {
-      "ref": "order@order-no",                               // Attribute
-      "email": "customer.customer-email",                    // Element
-      "sku": "product-lineitems.product-lineitem[0].product-id",  // Array index
-      "allSkus": "product-lineitems.product-lineitem.*.product-id" // Wildcard
-    }
-  }
-}
-```
-
-**XML Path Syntax Quick Reference:**
-
-| Pattern | Example | Description |
-|---------|---------|-------------|
-| `element` | `order-date` | Get element value |
-| `element@attr` | `order@order-no` | Get attribute value |
-| `parent.child` | `customer.email` | Nested element |
-| `array[0]` | `items[0].sku` | Array index |
-| `array.*` | `items.*.sku` | All items |
-| `element[attr=val]` | `item[type=product]` | Filter by attribute |
-
-**Key Point:** No need to include `#text` in your paths. XMLPathResolver automatically handles XML parser internals.
-
-## Versori Platform Compatibility
-
-**XMLPathResolver now supports both raw XML strings AND pre-parsed objects** (like from Versori webhooks) with automatic detection:
-
-```typescript
-// Scenario 1: Raw XML string (standalone scripts)
-const xmlString = '<order order-no="12345"><customer>John</customer></order>';
-mapper.map(xmlString);  // ✅ Auto-parses XML
-
-// Scenario 2: Versori pre-parsed object (Versori webhooks)
-const versoriData = { order: { $: { 'order-no': '12345' }, customer: 'John' } };
-mapper.map(versoriData);  // ✅ Handles $ attribute structure
-
-// SAME mapping config works for BOTH!
-```
-
-**Attribute Format Support:**
-- ✅ **Versori format**: `{ $: { 'order-no': '12345' } }` - Versori platform auto-parsing
-- ✅ **Standard format**: `{ '@order-no': '12345' }` - SDK XMLParser output
-- ✅ **User writes**: `order@order-no` - Works for all formats!
-
-**Benefits:**
-- Same mapping configuration works in Versori platform and standalone scripts
-- Keep `sourceFormat: "xml"` accurate (source IS XML, even if pre-parsed)
-- No need to convert objects back to strings for parsing
-- Automatic detection - no configuration changes needed
-
-## XML Attribute Access (CRITICAL)
-
-When accessing XML attributes, use `@` **WITHOUT a dot before it**:
-
-```json
-{
-  "customerId": { "source": "customer@id" },
-  "orderId": { "source": "order@orderNumber" },
-  "itemRef": { "source": "lineItem@itemId" }
-}
-```
-
-**Common Mistakes:**
-- ❌ WRONG: `"customer.@id"` (extra dot breaks path)
-- ❌ WRONG: `"customer['@id']"` (bracket notation not needed)
-- ❌ WRONG: `"order.items.item.@id"` (dot before @ in nested path)
-- ✅ CORRECT: `"customer@id"` (no dot before @)
-- ✅ CORRECT: `"order.items.item@id"` (no dot before @, even in nested paths)
-
-**Why:** The SDK's XMLPathResolver handles attribute access internally. Adding a dot before `@` treats `@attribute` as a nested element name instead of an XML attribute, causing path resolution to fail.
-
-**Real-world examples across different systems:**
-
-| System Type | Example XML | Correct Path | Wrong Path |
-|-------------|-------------|--------------|------------|
-| **E-commerce** | `<product sku="ABC-123">` | `product@sku` | `product.@sku` |
-| **Orders** | `<order orderNumber="ORD-456">` | `order@orderNumber` | `order.@orderNumber` |
-| **Inventory** | `<item id="ITEM-789">` | `item@id` | `item.@id` |
-| **ERP** | `<material materialNumber="MAT-001">` | `material@materialNumber` | `material.@materialNumber` |
-| **Invoices** | `<invoice invoiceId="INV-2024-001">` | `invoice@invoiceId` | `invoice.@invoiceId` |
-| **POS** | `<transaction transactionId="TXN-12345">` | `transaction@transactionId` | `transaction.@transactionId` |
-
-**XML Example with Multiple Attributes:**
-```xml
-<order orderNumber="ORD-12345" status="OPEN">
-  <customer customerId="CUST-001" tier="PREMIUM">
-    <email>customer@example.com</email>
-  </customer>
-  <items>
-    <item id="ITEM-1" sku="PROD-ABC">
-      <quantity>5</quantity>
-    </item>
-  </items>
-</order>
-```
-
-**Correct Mapping Configuration:**
-```json
-{
-  "ref": { "source": "order@orderNumber" },
-  "status": { "source": "order@status" },
-  "customer.id": { "source": "order.customer@customerId" },
-  "customer.tier": { "source": "order.customer@tier" },
-  "customer.email": { "source": "order.customer.email" },
-  "items": {
-    "source": "order.items.item",
-    "isArray": true,
-    "fields": {
-      "ref": { "source": "$.@id" },
-      "sku": { "source": "$.@sku" },
-      "quantity": { "source": "$.quantity" }
-    }
-  }
-}
-```
-
-**Key Takeaways:**
-- **Attributes**: Use `@` directly → `element@attribute`
-- **Nested elements**: Use `.` → `parent.child.grandchild`
-- **Attributes in nested paths**: Dot up to element, then `@` → `parent.child@attribute`
-- **Never combine**: `element.@attribute` will always fail
-
-## Common Mistakes
-
-### Mistake #1: Dot Before @ Symbol
-
-```json
-// ❌ WRONG - Extra dot before @
-{
-  "orderId": { "source": "order.@id" },
-  "customerId": { "source": "customer.@customer-no" }
-}
-
-// ✅ CORRECT - No dot before @
-{
-  "orderId": { "source": "order@id" },
-  "customerId": { "source": "customer@customer-no" }
-}
-```
-
-**Why it fails**: The SDK treats `@id` as a nested element name, not an XML attribute.
-
-### Mistake #2: Mixing Naming Conventions
-
-```json
-// ❌ INCONSISTENT - Mix of kebab-case and camelCase
-{
-  "orderRef": { "source": "order@order-no" },
-  "customerId": { "source": "customer@customerId" }
-}
-
-// ✅ CONSISTENT - Choose one convention
-{
-  "orderRef": { "source": "order@order-no" },
-  "customerId": { "source": "customer@customer-id" }
-}
-```
-
-**Why it matters**: XML sources should use consistent attribute naming. Pick kebab-case (XML standard) or camelCase (modern APIs) and stick with it.
-
-### Mistake #3: Forgetting Array Context Symbol
-
-```json
-// ❌ WRONG - Missing $ for relative path in array
-{
-  "items": {
-    "source": "order.items.item",
-    "isArray": true,
-    "fields": {
-      "ref": { "source": "@id" }  // Missing $ - will fail
-    }
-  }
-}
-
-// ✅ CORRECT - Use $ for current array item
-{
-  "items": {
-    "source": "order.items.item",
-    "isArray": true,
-    "fields": {
-      "ref": { "source": "$.@id" }  // $ means "current item"
-    }
-  }
-}
-```
-
-**Why it fails**: Without `$.`, the mapper looks for `@id` at the root level, not in the current array item.
-
-### Mistake #4: Incorrect Nested Path to Attribute
-
-```xml
-<order>
-  <customer customer-id="123">
-    <email>john@example.com</email>
-  </customer>
-</order>
-```
-
-```json
-// ❌ WRONG - Missing intermediate element
-{
-  "customerId": { "source": "order@customer-id" }
-}
-
-// ✅ CORRECT - Include full path to element with attribute
-{
-  "customerId": { "source": "order.customer@customer-id" }
-}
-```
-
-**Why it fails**: The attribute `customer-id` is on the `<customer>` element, not `<order>`. Must specify full path.
-
-### Mistake #5: Using Bracket Notation for Attributes
-
-```json
-// ❌ WRONG - Bracket notation not supported
-{
-  "orderId": { "source": "order['@id']" }
-}
-
-// ✅ CORRECT - Use @ directly
-{
-  "orderId": { "source": "order@id" }
-}
-```
-
-**Why it fails**: The SDK's path resolver uses `@` syntax, not JavaScript bracket notation.
-
-## JSON Paths
-
-```json
-{
-  "sourceFormat": "json",
-  "arguments": {
-    "input": {
-      "ref": "order.orderNo",                 // Property
-      "email": "customer.email",              // Nested property
-      "sku": "productLineItems[0].productId", // Array index
-      "allSkus": "productLineItems.*.productId" // Wildcard
-    }
-  }
-}
-```
-
-## Path Syntax Examples
-
-### Basic Paths
-
-**XML:**
-```xml
-<order>
-  <orderNumber>ORD-123</orderNumber>
-  <customer>
-    <email>customer@example.com</email>
-  </customer>
-</order>
-```
-
-```json
-{
-  "ref": { "source": "order.orderNumber" },
-  "email": { "source": "order.customer.email" }
-}
-```
-
-**JSON:**
-```json
-{
-  "order": {
-    "orderNumber": "ORD-123",
-    "customer": {
-      "email": "customer@example.com"
-    }
-  }
-}
-```
-
-```json
-{
-  "ref": { "source": "order.orderNumber" },
-  "email": { "source": "order.customer.email" }
-}
-```
-
-### Array Paths
-
-**XML:**
-```xml
-<order>
-  <items>
-    <item>
-      <sku>PROD-1</sku>
-      <quantity>5</quantity>
-    </item>
-    <item>
-      <sku>PROD-2</sku>
-      <quantity>3</quantity>
-    </item>
-  </items>
-</order>
-```
-
-```json
-{
-  "firstSku": { "source": "order.items.item[0].sku" },
-  "allSkus": { "source": "order.items.item.*.sku" }
-}
-```
-
-**JSON:**
-```json
-{
-  "order": {
-    "items": [
-      { "sku": "PROD-1", "quantity": 5 },
-      { "sku": "PROD-2", "quantity": 3 }
-    ]
-  }
-}
-```
-
-```json
-{
-  "firstSku": { "source": "order.items[0].sku" },
-  "allSkus": { "source": "order.items.*.sku" }
-}
-```
-
-### Attribute Paths (XML Only)
-
-```xml
-<order orderNumber="ORD-123" status="OPEN">
-  <customer customerId="CUST-001">
-    <name>John Doe</name>
-  </customer>
-</order>
-```
-
-```json
-{
-  "ref": { "source": "order@orderNumber" },
-  "status": { "source": "order@status" },
-  "customerId": { "source": "order.customer@customerId" },
-  "customerName": { "source": "order.customer.name" }
-}
-```
-
----
-
-## Navigation
-
-[← Previous: Configuration Reference](./graphql-mutation-mapping-05-configuration-reference.md) | [Back to Guide](../graphql-mutation-mapping-readme.md) | [Next: Array Handling →](./graphql-mutation-mapping-07-array-handling.md)
-
-## Related Documentation
-
-- [Module 07: Array Handling](./graphql-mutation-mapping-07-array-handling.md) - Array mapping patterns
-- [Module 09: Advanced Patterns](./graphql-mutation-mapping-09-advanced-patterns.md) - Advanced path techniques
-- [XMLPathResolver API Reference](../../../api-reference/modules/api-reference-04-graphql-mapping.md#xmlpathresolver) - Implementation details
-- [JSONPathResolver API Reference](../../../api-reference/modules/api-reference-04-graphql-mapping.md#jsonpathresolver) - Implementation details
+# Path Syntax
+
+[← Back to GraphQL Mutation Mapping Guide](../graphql-mutation-mapping-readme.md)
+
+**Module 6 of 13** | **Level**: Intermediate | **Time**: 15 minutes
+
+---
+
+## Path Syntax Overview
+
+**How it works:** XMLPathResolver automatically handles XML parser internals (`#text` wrappers, `@` attribute prefixes). You write natural paths - the SDK handles complexity.
+
+## Naming Conventions for XML Attributes
+
+**Choose ONE convention per project and use it consistently throughout your XML and mappings.**
+
+### Recommended: Kebab-Case (XML Standard)
+
+This is the most common convention in XML and SFCC integrations:
+
+```xml
+<order order-no="ORD-123" customer-id="CUST-456">
+  <line-item item-id="ITEM-001" product-ref="SKU-001" />
+  <shipping-address postal-code="62701" />
+</order>
+```
+
+```json
+{
+  "ref": { "source": "order@order-no" },
+  "customerId": { "source": "order@customer-id" },
+  "items": {
+    "source": "order.line-item",
+    "isArray": true,
+    "fields": {
+      "itemId": { "source": "$.@item-id" },
+      "productRef": { "source": "$.@product-ref" }
+    }
+  }
+}
+```
+
+**✅ Pros:**
+- XML industry standard
+- Works well with SFCC, SAP, Oracle systems
+- Easy to read in XML
+- Matches most external API specs
+
+### Alternative: CamelCase (Modern APIs)
+
+Used by modern REST APIs and some e-commerce platforms:
+
+```xml
+<order orderNo="ORD-123" customerId="CUST-456">
+  <lineItem itemId="ITEM-001" productRef="SKU-001" />
+  <shippingAddress postalCode="62701" />
+</order>
+```
+
+```json
+{
+  "ref": { "source": "order@orderNo" },
+  "customerId": { "source": "order@customerId" },
+  "items": {
+    "source": "order.lineItem",
+    "isArray": true,
+    "fields": {
+      "itemId": { "source": "$.@itemId" },
+      "productRef": { "source": "$.@productRef" }
+    }
+  }
+}
+```
+
+**✅ Pros:**
+- Matches JavaScript/TypeScript conventions
+- No need for quotes in JavaScript objects
+- Easier to type (no hyphens)
+
+### ⚠️ IMPORTANT: Never Mix Conventions
+
+```json
+// ❌ BAD - Inconsistent naming
+{
+  "ref": { "source": "order@order-no" },      // kebab-case
+  "customerId": { "source": "order@customerId" },  // camelCase
+  "total": { "source": "order@OrderTotal" }    // PascalCase
+}
+
+// ✅ GOOD - Consistent kebab-case throughout
+{
+  "ref": { "source": "order@order-no" },
+  "customerId": { "source": "order@customer-id" },
+  "total": { "source": "order@order-total" }
+}
+```
+
+**Best Practice**: If integrating with an existing system (like SFCC), match their naming convention. If building from scratch, choose kebab-case for XML standard compliance.
+
+### XML Paths
+
+```json
+{
+  "sourceFormat": "xml",
+  "arguments": {
+    "input": {
+      "ref": "order@order-no",                               // Attribute
+      "email": "customer.customer-email",                    // Element
+      "sku": "product-lineitems.product-lineitem[0].product-id",  // Array index
+      "allSkus": "product-lineitems.product-lineitem.*.product-id" // Wildcard
+    }
+  }
+}
+```
+
+**XML Path Syntax Quick Reference:**
+
+| Pattern | Example | Description |
+|---------|---------|-------------|
+| `element` | `order-date` | Get element value |
+| `element@attr` | `order@order-no` | Get attribute value |
+| `parent.child` | `customer.email` | Nested element |
+| `array[0]` | `items[0].sku` | Array index |
+| `array.*` | `items.*.sku` | All items |
+| `element[attr=val]` | `item[type=product]` | Filter by attribute |
+
+**Key Point:** No need to include `#text` in your paths. XMLPathResolver automatically handles XML parser internals.
+
+## Versori Platform Compatibility
+
+**XMLPathResolver now supports both raw XML strings AND pre-parsed objects** (like from Versori webhooks) with automatic detection:
+
+```typescript
+// Scenario 1: Raw XML string (standalone scripts)
+const xmlString = '<order order-no="12345"><customer>John</customer></order>';
+mapper.map(xmlString);  // ✅ Auto-parses XML
+
+// Scenario 2: Versori pre-parsed object (Versori webhooks)
+const versoriData = { order: { $: { 'order-no': '12345' }, customer: 'John' } };
+mapper.map(versoriData);  // ✅ Handles $ attribute structure
+
+// SAME mapping config works for BOTH!
+```
+
+**Attribute Format Support:**
+- ✅ **Versori format**: `{ $: { 'order-no': '12345' } }` - Versori platform auto-parsing
+- ✅ **Standard format**: `{ '@order-no': '12345' }` - SDK XMLParser output
+- ✅ **User writes**: `order@order-no` - Works for all formats!
+
+**Benefits:**
+- Same mapping configuration works in Versori platform and standalone scripts
+- Keep `sourceFormat: "xml"` accurate (source IS XML, even if pre-parsed)
+- No need to convert objects back to strings for parsing
+- Automatic detection - no configuration changes needed
+
+## XML Attribute Access (CRITICAL)
+
+When accessing XML attributes, use `@` **WITHOUT a dot before it**:
+
+```json
+{
+  "customerId": { "source": "customer@id" },
+  "orderId": { "source": "order@orderNumber" },
+  "itemRef": { "source": "lineItem@itemId" }
+}
+```
+
+**Common Mistakes:**
+- ❌ WRONG: `"customer.@id"` (extra dot breaks path)
+- ❌ WRONG: `"customer['@id']"` (bracket notation not needed)
+- ❌ WRONG: `"order.items.item.@id"` (dot before @ in nested path)
+- ✅ CORRECT: `"customer@id"` (no dot before @)
+- ✅ CORRECT: `"order.items.item@id"` (no dot before @, even in nested paths)
+
+**Why:** The SDK's XMLPathResolver handles attribute access internally. Adding a dot before `@` treats `@attribute` as a nested element name instead of an XML attribute, causing path resolution to fail.
+
+**Real-world examples across different systems:**
+
+| System Type | Example XML | Correct Path | Wrong Path |
+|-------------|-------------|--------------|------------|
+| **E-commerce** | `<product sku="ABC-123">` | `product@sku` | `product.@sku` |
+| **Orders** | `<order orderNumber="ORD-456">` | `order@orderNumber` | `order.@orderNumber` |
+| **Inventory** | `<item id="ITEM-789">` | `item@id` | `item.@id` |
+| **ERP** | `<material materialNumber="MAT-001">` | `material@materialNumber` | `material.@materialNumber` |
+| **Invoices** | `<invoice invoiceId="INV-2024-001">` | `invoice@invoiceId` | `invoice.@invoiceId` |
+| **POS** | `<transaction transactionId="TXN-12345">` | `transaction@transactionId` | `transaction.@transactionId` |
+
+**XML Example with Multiple Attributes:**
+```xml
+<order orderNumber="ORD-12345" status="OPEN">
+  <customer customerId="CUST-001" tier="PREMIUM">
+    <email>customer@example.com</email>
+  </customer>
+  <items>
+    <item id="ITEM-1" sku="PROD-ABC">
+      <quantity>5</quantity>
+    </item>
+  </items>
+</order>
+```
+
+**Correct Mapping Configuration:**
+```json
+{
+  "ref": { "source": "order@orderNumber" },
+  "status": { "source": "order@status" },
+  "customer.id": { "source": "order.customer@customerId" },
+  "customer.tier": { "source": "order.customer@tier" },
+  "customer.email": { "source": "order.customer.email" },
+  "items": {
+    "source": "order.items.item",
+    "isArray": true,
+    "fields": {
+      "ref": { "source": "$.@id" },
+      "sku": { "source": "$.@sku" },
+      "quantity": { "source": "$.quantity" }
+    }
+  }
+}
+```
+
+**Key Takeaways:**
+- **Attributes**: Use `@` directly → `element@attribute`
+- **Nested elements**: Use `.` → `parent.child.grandchild`
+- **Attributes in nested paths**: Dot up to element, then `@` → `parent.child@attribute`
+- **Never combine**: `element.@attribute` will always fail
+
+## Common Mistakes
+
+### Mistake #1: Dot Before @ Symbol
+
+```json
+// ❌ WRONG - Extra dot before @
+{
+  "orderId": { "source": "order.@id" },
+  "customerId": { "source": "customer.@customer-no" }
+}
+
+// ✅ CORRECT - No dot before @
+{
+  "orderId": { "source": "order@id" },
+  "customerId": { "source": "customer@customer-no" }
+}
+```
+
+**Why it fails**: The SDK treats `@id` as a nested element name, not an XML attribute.
+
+### Mistake #2: Mixing Naming Conventions
+
+```json
+// ❌ INCONSISTENT - Mix of kebab-case and camelCase
+{
+  "orderRef": { "source": "order@order-no" },
+  "customerId": { "source": "customer@customerId" }
+}
+
+// ✅ CONSISTENT - Choose one convention
+{
+  "orderRef": { "source": "order@order-no" },
+  "customerId": { "source": "customer@customer-id" }
+}
+```
+
+**Why it matters**: XML sources should use consistent attribute naming. Pick kebab-case (XML standard) or camelCase (modern APIs) and stick with it.
+
+### Mistake #3: Forgetting Array Context Symbol
+
+```json
+// ❌ WRONG - Missing $ for relative path in array
+{
+  "items": {
+    "source": "order.items.item",
+    "isArray": true,
+    "fields": {
+      "ref": { "source": "@id" }  // Missing $ - will fail
+    }
+  }
+}
+
+// ✅ CORRECT - Use $ for current array item
+{
+  "items": {
+    "source": "order.items.item",
+    "isArray": true,
+    "fields": {
+      "ref": { "source": "$.@id" }  // $ means "current item"
+    }
+  }
+}
+```
+
+**Why it fails**: Without `$.`, the mapper looks for `@id` at the root level, not in the current array item.
+
+### Mistake #4: Incorrect Nested Path to Attribute
+
+```xml
+<order>
+  <customer customer-id="123">
+    <email>john@example.com</email>
+  </customer>
+</order>
+```
+
+```json
+// ❌ WRONG - Missing intermediate element
+{
+  "customerId": { "source": "order@customer-id" }
+}
+
+// ✅ CORRECT - Include full path to element with attribute
+{
+  "customerId": { "source": "order.customer@customer-id" }
+}
+```
+
+**Why it fails**: The attribute `customer-id` is on the `<customer>` element, not `<order>`. Must specify full path.
+
+### Mistake #5: Using Bracket Notation for Attributes
+
+```json
+// ❌ WRONG - Bracket notation not supported
+{
+  "orderId": { "source": "order['@id']" }
+}
+
+// ✅ CORRECT - Use @ directly
+{
+  "orderId": { "source": "order@id" }
+}
+```
+
+**Why it fails**: The SDK's path resolver uses `@` syntax, not JavaScript bracket notation.
+
+## JSON Paths
+
+```json
+{
+  "sourceFormat": "json",
+  "arguments": {
+    "input": {
+      "ref": "order.orderNo",                 // Property
+      "email": "customer.email",              // Nested property
+      "sku": "productLineItems[0].productId", // Array index
+      "allSkus": "productLineItems.*.productId" // Wildcard
+    }
+  }
+}
+```
+
+## Path Syntax Examples
+
+### Basic Paths
+
+**XML:**
+```xml
+<order>
+  <orderNumber>ORD-123</orderNumber>
+  <customer>
+    <email>customer@example.com</email>
+  </customer>
+</order>
+```
+
+```json
+{
+  "ref": { "source": "order.orderNumber" },
+  "email": { "source": "order.customer.email" }
+}
+```
+
+**JSON:**
+```json
+{
+  "order": {
+    "orderNumber": "ORD-123",
+    "customer": {
+      "email": "customer@example.com"
+    }
+  }
+}
+```
+
+```json
+{
+  "ref": { "source": "order.orderNumber" },
+  "email": { "source": "order.customer.email" }
+}
+```
+
+### Array Paths
+
+**XML:**
+```xml
+<order>
+  <items>
+    <item>
+      <sku>PROD-1</sku>
+      <quantity>5</quantity>
+    </item>
+    <item>
+      <sku>PROD-2</sku>
+      <quantity>3</quantity>
+    </item>
+  </items>
+</order>
+```
+
+```json
+{
+  "firstSku": { "source": "order.items.item[0].sku" },
+  "allSkus": { "source": "order.items.item.*.sku" }
+}
+```
+
+**JSON:**
+```json
+{
+  "order": {
+    "items": [
+      { "sku": "PROD-1", "quantity": 5 },
+      { "sku": "PROD-2", "quantity": 3 }
+    ]
+  }
+}
+```
+
+```json
+{
+  "firstSku": { "source": "order.items[0].sku" },
+  "allSkus": { "source": "order.items.*.sku" }
+}
+```
+
+### Attribute Paths (XML Only)
+
+```xml
+<order orderNumber="ORD-123" status="OPEN">
+  <customer customerId="CUST-001">
+    <name>John Doe</name>
+  </customer>
+</order>
+```
+
+```json
+{
+  "ref": { "source": "order@orderNumber" },
+  "status": { "source": "order@status" },
+  "customerId": { "source": "order.customer@customerId" },
+  "customerName": { "source": "order.customer.name" }
+}
+```
+
+---
+
+## Navigation
+
+[← Previous: Configuration Reference](./graphql-mutation-mapping-05-configuration-reference.md) | [Back to Guide](../graphql-mutation-mapping-readme.md) | [Next: Array Handling →](./graphql-mutation-mapping-07-array-handling.md)
+
+## Related Documentation
+
+- [Module 07: Array Handling](./graphql-mutation-mapping-07-array-handling.md) - Array mapping patterns
+- [Module 09: Advanced Patterns](./graphql-mutation-mapping-09-advanced-patterns.md) - Advanced path techniques
+- [XMLPathResolver API Reference](../../../api-reference/modules/api-reference-04-graphql-mapping.md#xmlpathresolver) - Implementation details
+- [JSONPathResolver API Reference](../../../api-reference/modules/api-reference-04-graphql-mapping.md#jsonpathresolver) - Implementation details