@fluentcommerce/fc-connect-sdk 0.1.54 → 0.1.56

package/docs/02-CORE-GUIDES/mapping/graphql-mutation-mapping/modules/graphql-mutation-mapping-03-schema-validation.md

@@ -1,569 +1,569 @@
-# Schema Validation & Mapping Generation (CLI Tools)
-
-[← Back to GraphQL Mutation Mapping Guide](../graphql-mutation-mapping-readme.md)
-
-**Module 3 of 13** | **Level**: Beginner | **Time**: 15 minutes
-
----
-
-## Overview
-
-**IMPORTANT:** The GraphQL Mutation Mapper does **NOT** perform automatic schema validation at runtime. Schema validation is a **manual, pre-deployment step** using CLI tools.
-
-This module explains:
-1. How to **generate mapping configurations** from GraphQL mutations (starter templates)
-2. How to **validate** mappings before deployment
-3. How to **analyze coverage** to ensure all fields are mapped
-
----
-
-## CLI Tools Overview
-
-| Tool | Purpose | When to Use |
-|------|---------|-------------|
-| `introspect-schema` | Download GraphQL schema | First step - get schema file |
-| `generate-mutation-mapping` | **Generate mapping config** from mutation | **Start here** - creates template |
-| `validate-schema` | Validate mapping against schema | Before deployment - catch errors |
-| `analyze-coverage` | Check field coverage | Ensure all important fields mapped |
-
----
-
-## Step 1: Generate Mapping Configuration (Starter)
-
-### Create Your First Mapping Automatically
-
-Instead of writing mapping configs from scratch, **generate them** from your GraphQL mutation:
-
-```bash
-# 1. Save your GraphQL mutation to a file
-cat > createOrder.graphql <<'EOF'
-mutation CreateOrder($input: CreateOrderInput!) {
-  createOrder(input: $input) {
-    id
-    ref
-    status
-  }
-}
-EOF
-
-# 2. Generate mapping configuration
-npx fc-connect generate-mutation-mapping \
-  --file createOrder.graphql \
-  --output mappings/order-mapping.json \
-  --source-format xml
-```
-
-**Generated Output (`mappings/order-mapping.json`):**
-```json
-{
-  "version": "1.0",
-  "mutation": "createOrder",
-  "operationName": "CreateOrder",
-  "sourceFormat": "xml",
-  "schemaValidation": true,
-  "arguments": {
-    "input": {
-      "_type": "CreateOrderInput!",
-      "_comment": "Generated from GraphQL mutation - customize paths below",
-
-      "ref": {
-        "source": "CHANGE_ME",
-        "required": true,
-        "_comment": "String! - Order reference number"
-      },
-
-      "type": {
-        "source": "CHANGE_ME",
-        "required": true,
-        "_comment": "String! - Order type (STANDARD, etc)"
-      },
-
-      "retailer": {
-        "fields": {
-          "id": {
-            "value": "${FLUENT_RETAILER_ID}",
-            "_comment": "Use environment variable"
-          }
-        }
-      },
-
-      "customer": {
-        "fields": {
-          "ref": {
-            "source": "CHANGE_ME",
-            "required": true
-          },
-          "email": {
-            "source": "CHANGE_ME",
-            "required": false
-          }
-        }
-      },
-
-      "totalPrice": {
-        "source": "CHANGE_ME",
-        "resolver": "sdk.parseFloat",
-        "required": true,
-        "_comment": "Float! - Total order amount"
-      },
-
-      "items": {
-        "_array": true,
-        "_type": "[OrderItemInput]!",
-        "source": "CHANGE_ME",
-        "_comment": "Array of order line items",
-
-        "ref": {
-          "source": "CHANGE_ME",
-          "required": true
-        },
-        "quantity": {
-          "source": "CHANGE_ME",
-          "resolver": "sdk.parseInt",
-          "required": true
-        }
-      }
-    }
-  },
-  "returnFields": ["id", "ref", "status"]
-}
-```
-
-**Now customize the `CHANGE_ME` paths** to match your XML/JSON source:
-
-```json
-{
-  "arguments": {
-    "input": {
-      "ref": {
-        "source": "order@order-no",  // XML: order element, order-no attribute
-        "required": true
-      },
-      "customer": {
-        "fields": {
-          "ref": {
-            "source": "customer.customer-no",  // XML: nested customer/customer-no
-            "required": true
-          },
-          "email": {
-            "source": "customer.customer-email"
-          }
-        }
-      },
-      "totalPrice": {
-        "source": "totals.order-total.gross-price",  // XML: nested path
-        "resolver": "sdk.parseFloat",
-        "required": true
-      },
-      "items": {
-        "_array": true,
-        "source": "product-lineitems.product-lineitem",  // XML array path
-
-        "ref": {
-          "source": "product-id"  // Relative to each lineitem
-        },
-        "quantity": {
-          "source": "quantity",
-          "resolver": "sdk.parseInt"
-        }
-      }
-    }
-  }
-}
-```
-
----
-
-## Step 2: Introspect GraphQL Schema
-
-Before validation, download your GraphQL schema:
-
-```bash
-# Basic introspection
-npx fc-connect introspect-schema \
-  --url https://YOUR_ACCOUNT.api.fluentcommerce.com/graphql \
-  --output fluent-schema.json
-
-# With authentication
-npx fc-connect introspect-schema \
-  --url https://YOUR_ACCOUNT.api.fluentcommerce.com/graphql \
-  --header "Authorization: Bearer YOUR_TOKEN" \
-  --output fluent-schema.json
-```
-
-**What you get (`fluent-schema.json`):**
-```json
-{
-  "data": {
-    "__schema": {
-      "mutationType": { "name": "Mutation" },
-      "types": [
-        {
-          "kind": "INPUT_OBJECT",
-          "name": "CreateOrderInput",
-          "inputFields": [
-            {
-              "name": "ref",
-              "type": {
-                "kind": "NON_NULL",
-                "ofType": { "kind": "SCALAR", "name": "String" }
-              }
-            },
-            {
-              "name": "type",
-              "type": {
-                "kind": "NON_NULL",
-                "ofType": { "kind": "SCALAR", "name": "String" }
-              }
-            },
-            {
-              "name": "totalPrice",
-              "type": {
-                "kind": "NON_NULL",
-                "ofType": { "kind": "SCALAR", "name": "Float" }
-              }
-            },
-            {
-              "name": "items",
-              "type": {
-                "kind": "NON_NULL",
-                "ofType": {
-                  "kind": "LIST",
-                  "ofType": {
-                    "kind": "INPUT_OBJECT",
-                    "name": "OrderItemInput"
-                  }
-                }
-              }
-            }
-          ]
-        }
-      ]
-    }
-  }
-}
-```
-
----
-
-## Step 3: Validate Mapping Against Schema
-
-```bash
-npx fc-connect validate-schema \
-  --mapping mappings/order-mapping.json \
-  --schema fluent-schema.json
-```
-
-**✅ Successful Validation:**
-```
-✓ Mapping validation successful
-✓ All field names exist in schema
-✓ All required fields are mapped
-✓ No type mismatches detected
-✓ Array configurations are correct
-```
-
-**❌ Failed Validation:**
-```
-✗ Validation errors found:
-
-1. Field 'orderNumber' not found in CreateOrderInput
-   → Did you mean 'ref'?
-   → Available fields: ref, type, retailer, customer, totalPrice, items
-
-2. Required field 'type' is not marked as required in mapping
-   → Add "required": true to field configuration
-
-3. Field 'totalPrice' expects Float but source provides String
-   → Add "resolver": "sdk.parseFloat" to convert type
-
-4. Array field 'items' missing _array marker
-   → Add "_array": true to field configuration
-```
-
----
-
-## Step 4: Analyze Field Coverage
-
-Check if you're missing important fields:
-
-```bash
-npx fc-connect analyze-coverage \
-  --mapping mappings/order-mapping.json \
-  --schema fluent-schema.json
-```
-
-**Output:**
-```
-Field Coverage Analysis
-=======================
-Mutation: createOrder
-Input Type: CreateOrderInput
-
-Total available fields: 25
-Mapped fields: 8
-Coverage: 32%
-
-✓ MAPPED FIELDS (8):
-  ✓ ref (String!) - REQUIRED
-  ✓ type (String!) - REQUIRED
-  ✓ retailer (RetailerLink!)
-  ✓ customer (CustomerLink)
-  ✓ totalPrice (Float!)
-  ✓ currency (String!)
-  ✓ items ([OrderItemInput]!)
-  ✓ createdOn (DateTime)
-
-⚠ UNMAPPED FIELDS - High Priority (5):
-  ⚠ status (String) - Order status
-  ⚠ paymentInfo (PaymentInput) - Payment details
-  ⚠ shippingAddress (AddressInput) - Delivery address
-  ⚠ billingAddress (AddressInput) - Billing address
-  ⚠ attributes ([AttributeInput]) - Custom attributes
-
-ℹ UNMAPPED FIELDS - Optional (12):
-  ℹ notes (String) - Order notes
-  ℹ tags ([String]) - Order tags
-  ℹ metadata (JSON) - Custom metadata
-  ... (9 more)
-
-Recommendation: Consider mapping high-priority fields
-```
-
----
-
-## Common Validation Errors & Fixes
-
-### Error 1: Field Name Mismatch
-
-**Validation Error:**
-```
-Field 'orderNumber' not found in CreateOrderInput
-  → Did you mean 'ref'?
-```
-
-**Problem in Mapping:**
-```json
-{
-  "orderNumber": { "source": "order@order-no" }  // ❌ Wrong field name
-}
-```
-
-**Fix:**
-```json
-{
-  "ref": { "source": "order@order-no" }  // ✅ Correct field name
-}
-```
-
----
-
-### Error 2: Missing Required Field
-
-**Validation Error:**
-```
-Required field 'type' is not mapped
-```
-
-**Problem:**
-```json
-{
-  "ref": { "source": "order@order-no" }
-  // Missing 'type' field - REQUIRED in schema
-}
-```
-
-**Fix:**
-```json
-{
-  "ref": { "source": "order@order-no", "required": true },
-  "type": { "value": "STANDARD", "required": true }  // ✅ Added
-}
-```
-
----
-
-### Error 3: Type Mismatch
-
-**Validation Error:**
-```
-Field 'totalPrice' expects Float but mapping may provide String
-  → Add resolver to convert type
-```
-
-**Problem:**
-```json
-{
-  "totalPrice": { "source": "order.total" }  // Returns String "123.45"
-}
-```
-
-**Fix:**
-```json
-{
-  "totalPrice": {
-    "source": "order.total",
-    "resolver": "sdk.parseFloat"  // ✅ Convert String → Float
-  }
-}
-```
-
----
-
-### Error 4: Missing Array Marker
-
-**Validation Error:**
-```
-Field 'items' is an array but missing _array marker
-```
-
-**Problem:**
-```json
-{
-  "items": {
-    "source": "lineItems",
-    "ref": { "source": "productId" }
-  }
-}
-```
-
-**Fix:**
-```json
-{
-  "items": {
-    "_array": true,  // ✅ Added
-    "source": "lineItems",
-    "ref": { "source": "productId" },
-    "quantity": { "source": "qty", "resolver": "sdk.parseInt" }
-  }
-}
-```
-
----
-
-## Complete Example Workflow
-
-```bash
-# 1. Create GraphQL mutation file
-cat > createOrder.graphql <<'EOF'
-mutation CreateOrder($input: CreateOrderInput!) {
-  createOrder(input: $input) {
-    id
-    ref
-    status
-  }
-}
-EOF
-
-# 2. Generate starter mapping configuration
-npx fc-connect generate-mutation-mapping \
-  --file createOrder.graphql \
-  --output mappings/order-mapping.json \
-  --source-format xml
-
-# 3. Customize the generated mapping
-# Edit mappings/order-mapping.json - replace CHANGE_ME with actual XML paths
-
-# 4. Introspect GraphQL schema
-npx fc-connect introspect-schema \
-  --url https://my-account.api.fluentcommerce.com/graphql \
-  --output fluent-schema.json
-
-# 5. Validate mapping
-npx fc-connect validate-schema \
-  --mapping mappings/order-mapping.json \
-  --schema fluent-schema.json
-
-# 6. Check coverage
-npx fc-connect analyze-coverage \
-  --mapping mappings/order-mapping.json \
-  --schema fluent-schema.json
-
-# 7. Fix any errors, then repeat steps 5-6 until validation passes
-```
-
----
-
-## Pre-Deployment Checklist
-
-Before deploying your mapping to production:
-
-- [ ] ✅ Mapping generated from GraphQL mutation (`generate-mutation-mapping`)
-- [ ] ✅ Schema introspected and saved (`introspect-schema`)
-- [ ] ✅ Mapping validated against schema (`validate-schema`)
-- [ ] ✅ Field coverage analyzed (`analyze-coverage`)
-- [ ] ✅ All validation errors fixed
-- [ ] ✅ High-priority unmapped fields reviewed
-- [ ] ✅ Test with sample XML/JSON data
-- [ ] ✅ Verify mutation execution in GraphQL playground
-- [ ] ✅ Run integration tests in staging environment
-
----
-
-## CI/CD Integration
-
-Add to your CI pipeline:
-
-```yaml
-# .github/workflows/validate-mappings.yml
-name: Validate GraphQL Mappings
-
-on: [push, pull_request]
-
-jobs:
-  validate:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v2
-
-      - name: Install SDK
-        run: npm install -g @fluentcommerce/fc-connect-sdk
-
-      - name: Introspect Schema
-        run: |
-          fc-connect introspect-schema \
-            --url ${{ secrets.FLUENT_GRAPHQL_URL }} \
-            --header "Authorization: Bearer ${{ secrets.FLUENT_TOKEN }}" \
-            --output fluent-schema.json
-
-      - name: Validate All Mappings
-        run: |
-          for mapping in mappings/*.json; do
-            echo "Validating $mapping..."
-            fc-connect validate-schema \
-              --mapping "$mapping" \
-              --schema fluent-schema.json
-          done
-
-      - name: Check Coverage (Fail if < 80%)
-        run: |
-          for mapping in mappings/*.json; do
-            fc-connect analyze-coverage \
-              --mapping "$mapping" \
-              --schema fluent-schema.json \
-              --min-coverage 80
-          done
-```
-
----
-
-## Key Takeaways
-
-✅ **Start with generation** - Use `generate-mutation-mapping` for templates
-✅ **Schema validation is MANUAL** - Not automatic at runtime
-✅ **Use CLI tools before deployment** - Catch errors early
-✅ **Coverage analysis is critical** - Ensure important fields are mapped
-✅ **Integrate with CI/CD** - Validate on every commit
-✅ **Keep schema up-to-date** - Re-introspect when GraphQL schema changes
-
----
-
-## Navigation
-
-[← Previous: Quick Start](../../../auto-pagination/modules/auto-pagination-02-quick-start.md) | [Back to Guide](../graphql-mutation-mapping-readme.md) | [Next: Mapping Patterns →](./graphql-mutation-mapping-04-mapping-patterns.md)
-
-## Related Documentation
-
-- [CLI Tools Documentation](../../../../../bin/readme.md) - Complete CLI tools reference
-- [Module 05: Configuration Reference](./graphql-mutation-mapping-05-configuration-reference.md) - Mapping configuration structure
-- [Module 06: Path Syntax](./graphql-mutation-mapping-06-path-syntax.md) - XML/JSON path expressions
+# Schema Validation & Mapping Generation (CLI Tools)
+
+[← Back to GraphQL Mutation Mapping Guide](../graphql-mutation-mapping-readme.md)
+
+**Module 3 of 13** | **Level**: Beginner | **Time**: 15 minutes
+
+---
+
+## Overview
+
+**IMPORTANT:** The GraphQL Mutation Mapper does **NOT** perform automatic schema validation at runtime. Schema validation is a **manual, pre-deployment step** using CLI tools.
+
+This module explains:
+1. How to **generate mapping configurations** from GraphQL mutations (starter templates)
+2. How to **validate** mappings before deployment
+3. How to **analyze coverage** to ensure all fields are mapped
+
+---
+
+## CLI Tools Overview
+
+| Tool | Purpose | When to Use |
+|------|---------|-------------|
+| `introspect-schema` | Download GraphQL schema | First step - get schema file |
+| `generate-mutation-mapping` | **Generate mapping config** from mutation | **Start here** - creates template |
+| `validate-schema` | Validate mapping against schema | Before deployment - catch errors |
+| `analyze-coverage` | Check field coverage | Ensure all important fields mapped |
+
+---
+
+## Step 1: Generate Mapping Configuration (Starter)
+
+### Create Your First Mapping Automatically
+
+Instead of writing mapping configs from scratch, **generate them** from your GraphQL mutation:
+
+```bash
+# 1. Save your GraphQL mutation to a file
+cat > createOrder.graphql <<'EOF'
+mutation CreateOrder($input: CreateOrderInput!) {
+  createOrder(input: $input) {
+    id
+    ref
+    status
+  }
+}
+EOF
+
+# 2. Generate mapping configuration
+npx fc-connect generate-mutation-mapping \
+  --file createOrder.graphql \
+  --output mappings/order-mapping.json \
+  --source-format xml
+```
+
+**Generated Output (`mappings/order-mapping.json`):**
+```json
+{
+  "version": "1.0",
+  "mutation": "createOrder",
+  "operationName": "CreateOrder",
+  "sourceFormat": "xml",
+  "schemaValidation": true,
+  "arguments": {
+    "input": {
+      "_type": "CreateOrderInput!",
+      "_comment": "Generated from GraphQL mutation - customize paths below",
+
+      "ref": {
+        "source": "CHANGE_ME",
+        "required": true,
+        "_comment": "String! - Order reference number"
+      },
+
+      "type": {
+        "source": "CHANGE_ME",
+        "required": true,
+        "_comment": "String! - Order type (STANDARD, etc)"
+      },
+
+      "retailer": {
+        "fields": {
+          "id": {
+            "value": "${FLUENT_RETAILER_ID}",
+            "_comment": "Use environment variable"
+          }
+        }
+      },
+
+      "customer": {
+        "fields": {
+          "ref": {
+            "source": "CHANGE_ME",
+            "required": true
+          },
+          "email": {
+            "source": "CHANGE_ME",
+            "required": false
+          }
+        }
+      },
+
+      "totalPrice": {
+        "source": "CHANGE_ME",
+        "resolver": "sdk.parseFloat",
+        "required": true,
+        "_comment": "Float! - Total order amount"
+      },
+
+      "items": {
+        "_array": true,
+        "_type": "[OrderItemInput]!",
+        "source": "CHANGE_ME",
+        "_comment": "Array of order line items",
+
+        "ref": {
+          "source": "CHANGE_ME",
+          "required": true
+        },
+        "quantity": {
+          "source": "CHANGE_ME",
+          "resolver": "sdk.parseInt",
+          "required": true
+        }
+      }
+    }
+  },
+  "returnFields": ["id", "ref", "status"]
+}
+```
+
+**Now customize the `CHANGE_ME` paths** to match your XML/JSON source:
+
+```json
+{
+  "arguments": {
+    "input": {
+      "ref": {
+        "source": "order@order-no",  // XML: order element, order-no attribute
+        "required": true
+      },
+      "customer": {
+        "fields": {
+          "ref": {
+            "source": "customer.customer-no",  // XML: nested customer/customer-no
+            "required": true
+          },
+          "email": {
+            "source": "customer.customer-email"
+          }
+        }
+      },
+      "totalPrice": {
+        "source": "totals.order-total.gross-price",  // XML: nested path
+        "resolver": "sdk.parseFloat",
+        "required": true
+      },
+      "items": {
+        "_array": true,
+        "source": "product-lineitems.product-lineitem",  // XML array path
+
+        "ref": {
+          "source": "product-id"  // Relative to each lineitem
+        },
+        "quantity": {
+          "source": "quantity",
+          "resolver": "sdk.parseInt"
+        }
+      }
+    }
+  }
+}
+```
+
+---
+
+## Step 2: Introspect GraphQL Schema
+
+Before validation, download your GraphQL schema:
+
+```bash
+# Basic introspection
+npx fc-connect introspect-schema \
+  --url https://YOUR_ACCOUNT.api.fluentcommerce.com/graphql \
+  --output fluent-schema.json
+
+# With authentication
+npx fc-connect introspect-schema \
+  --url https://YOUR_ACCOUNT.api.fluentcommerce.com/graphql \
+  --header "Authorization: Bearer YOUR_TOKEN" \
+  --output fluent-schema.json
+```
+
+**What you get (`fluent-schema.json`):**
+```json
+{
+  "data": {
+    "__schema": {
+      "mutationType": { "name": "Mutation" },
+      "types": [
+        {
+          "kind": "INPUT_OBJECT",
+          "name": "CreateOrderInput",
+          "inputFields": [
+            {
+              "name": "ref",
+              "type": {
+                "kind": "NON_NULL",
+                "ofType": { "kind": "SCALAR", "name": "String" }
+              }
+            },
+            {
+              "name": "type",
+              "type": {
+                "kind": "NON_NULL",
+                "ofType": { "kind": "SCALAR", "name": "String" }
+              }
+            },
+            {
+              "name": "totalPrice",
+              "type": {
+                "kind": "NON_NULL",
+                "ofType": { "kind": "SCALAR", "name": "Float" }
+              }
+            },
+            {
+              "name": "items",
+              "type": {
+                "kind": "NON_NULL",
+                "ofType": {
+                  "kind": "LIST",
+                  "ofType": {
+                    "kind": "INPUT_OBJECT",
+                    "name": "OrderItemInput"
+                  }
+                }
+              }
+            }
+          ]
+        }
+      ]
+    }
+  }
+}
+```
+
+---
+
+## Step 3: Validate Mapping Against Schema
+
+```bash
+npx fc-connect validate-schema \
+  --mapping mappings/order-mapping.json \
+  --schema fluent-schema.json
+```
+
+**✅ Successful Validation:**
+```
+✓ Mapping validation successful
+✓ All field names exist in schema
+✓ All required fields are mapped
+✓ No type mismatches detected
+✓ Array configurations are correct
+```
+
+**❌ Failed Validation:**
+```
+✗ Validation errors found:
+
+1. Field 'orderNumber' not found in CreateOrderInput
+   → Did you mean 'ref'?
+   → Available fields: ref, type, retailer, customer, totalPrice, items
+
+2. Required field 'type' is not marked as required in mapping
+   → Add "required": true to field configuration
+
+3. Field 'totalPrice' expects Float but source provides String
+   → Add "resolver": "sdk.parseFloat" to convert type
+
+4. Array field 'items' missing _array marker
+   → Add "_array": true to field configuration
+```
+
+---
+
+## Step 4: Analyze Field Coverage
+
+Check if you're missing important fields:
+
+```bash
+npx fc-connect analyze-coverage \
+  --mapping mappings/order-mapping.json \
+  --schema fluent-schema.json
+```
+
+**Output:**
+```
+Field Coverage Analysis
+=======================
+Mutation: createOrder
+Input Type: CreateOrderInput
+
+Total available fields: 25
+Mapped fields: 8
+Coverage: 32%
+
+✓ MAPPED FIELDS (8):
+  ✓ ref (String!) - REQUIRED
+  ✓ type (String!) - REQUIRED
+  ✓ retailer (RetailerLink!)
+  ✓ customer (CustomerLink)
+  ✓ totalPrice (Float!)
+  ✓ currency (String!)
+  ✓ items ([OrderItemInput]!)
+  ✓ createdOn (DateTime)
+
+⚠ UNMAPPED FIELDS - High Priority (5):
+  ⚠ status (String) - Order status
+  ⚠ paymentInfo (PaymentInput) - Payment details
+  ⚠ shippingAddress (AddressInput) - Delivery address
+  ⚠ billingAddress (AddressInput) - Billing address
+  ⚠ attributes ([AttributeInput]) - Custom attributes
+
+ℹ UNMAPPED FIELDS - Optional (12):
+  ℹ notes (String) - Order notes
+  ℹ tags ([String]) - Order tags
+  ℹ metadata (JSON) - Custom metadata
+  ... (9 more)
+
+Recommendation: Consider mapping high-priority fields
+```
+
+---
+
+## Common Validation Errors & Fixes
+
+### Error 1: Field Name Mismatch
+
+**Validation Error:**
+```
+Field 'orderNumber' not found in CreateOrderInput
+  → Did you mean 'ref'?
+```
+
+**Problem in Mapping:**
+```json
+{
+  "orderNumber": { "source": "order@order-no" }  // ❌ Wrong field name
+}
+```
+
+**Fix:**
+```json
+{
+  "ref": { "source": "order@order-no" }  // ✅ Correct field name
+}
+```
+
+---
+
+### Error 2: Missing Required Field
+
+**Validation Error:**
+```
+Required field 'type' is not mapped
+```
+
+**Problem:**
+```json
+{
+  "ref": { "source": "order@order-no" }
+  // Missing 'type' field - REQUIRED in schema
+}
+```
+
+**Fix:**
+```json
+{
+  "ref": { "source": "order@order-no", "required": true },
+  "type": { "value": "STANDARD", "required": true }  // ✅ Added
+}
+```
+
+---
+
+### Error 3: Type Mismatch
+
+**Validation Error:**
+```
+Field 'totalPrice' expects Float but mapping may provide String
+  → Add resolver to convert type
+```
+
+**Problem:**
+```json
+{
+  "totalPrice": { "source": "order.total" }  // Returns String "123.45"
+}
+```
+
+**Fix:**
+```json
+{
+  "totalPrice": {
+    "source": "order.total",
+    "resolver": "sdk.parseFloat"  // ✅ Convert String → Float
+  }
+}
+```
+
+---
+
+### Error 4: Missing Array Marker
+
+**Validation Error:**
+```
+Field 'items' is an array but missing _array marker
+```
+
+**Problem:**
+```json
+{
+  "items": {
+    "source": "lineItems",
+    "ref": { "source": "productId" }
+  }
+}
+```
+
+**Fix:**
+```json
+{
+  "items": {
+    "_array": true,  // ✅ Added
+    "source": "lineItems",
+    "ref": { "source": "productId" },
+    "quantity": { "source": "qty", "resolver": "sdk.parseInt" }
+  }
+}
+```
+
+---
+
+## Complete Example Workflow
+
+```bash
+# 1. Create GraphQL mutation file
+cat > createOrder.graphql <<'EOF'
+mutation CreateOrder($input: CreateOrderInput!) {
+  createOrder(input: $input) {
+    id
+    ref
+    status
+  }
+}
+EOF
+
+# 2. Generate starter mapping configuration
+npx fc-connect generate-mutation-mapping \
+  --file createOrder.graphql \
+  --output mappings/order-mapping.json \
+  --source-format xml
+
+# 3. Customize the generated mapping
+# Edit mappings/order-mapping.json - replace CHANGE_ME with actual XML paths
+
+# 4. Introspect GraphQL schema
+npx fc-connect introspect-schema \
+  --url https://my-account.api.fluentcommerce.com/graphql \
+  --output fluent-schema.json
+
+# 5. Validate mapping
+npx fc-connect validate-schema \
+  --mapping mappings/order-mapping.json \
+  --schema fluent-schema.json
+
+# 6. Check coverage
+npx fc-connect analyze-coverage \
+  --mapping mappings/order-mapping.json \
+  --schema fluent-schema.json
+
+# 7. Fix any errors, then repeat steps 5-6 until validation passes
+```
+
+---
+
+## Pre-Deployment Checklist
+
+Before deploying your mapping to production:
+
+- [ ] ✅ Mapping generated from GraphQL mutation (`generate-mutation-mapping`)
+- [ ] ✅ Schema introspected and saved (`introspect-schema`)
+- [ ] ✅ Mapping validated against schema (`validate-schema`)
+- [ ] ✅ Field coverage analyzed (`analyze-coverage`)
+- [ ] ✅ All validation errors fixed
+- [ ] ✅ High-priority unmapped fields reviewed
+- [ ] ✅ Test with sample XML/JSON data
+- [ ] ✅ Verify mutation execution in GraphQL playground
+- [ ] ✅ Run integration tests in staging environment
+
+---
+
+## CI/CD Integration
+
+Add to your CI pipeline:
+
+```yaml
+# .github/workflows/validate-mappings.yml
+name: Validate GraphQL Mappings
+
+on: [push, pull_request]
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+
+      - name: Install SDK
+        run: npm install -g @fluentcommerce/fc-connect-sdk
+
+      - name: Introspect Schema
+        run: |
+          fc-connect introspect-schema \
+            --url ${{ secrets.FLUENT_GRAPHQL_URL }} \
+            --header "Authorization: Bearer ${{ secrets.FLUENT_TOKEN }}" \
+            --output fluent-schema.json
+
+      - name: Validate All Mappings
+        run: |
+          for mapping in mappings/*.json; do
+            echo "Validating $mapping..."
+            fc-connect validate-schema \
+              --mapping "$mapping" \
+              --schema fluent-schema.json
+          done
+
+      - name: Check Coverage (Fail if < 80%)
+        run: |
+          for mapping in mappings/*.json; do
+            fc-connect analyze-coverage \
+              --mapping "$mapping" \
+              --schema fluent-schema.json \
+              --min-coverage 80
+          done
+```
+
+---
+
+## Key Takeaways
+
+✅ **Start with generation** - Use `generate-mutation-mapping` for templates
+✅ **Schema validation is MANUAL** - Not automatic at runtime
+✅ **Use CLI tools before deployment** - Catch errors early
+✅ **Coverage analysis is critical** - Ensure important fields are mapped
+✅ **Integrate with CI/CD** - Validate on every commit
+✅ **Keep schema up-to-date** - Re-introspect when GraphQL schema changes
+
+---
+
+## Navigation
+
+[← Previous: Quick Start](../../../auto-pagination/modules/auto-pagination-02-quick-start.md) | [Back to Guide](../graphql-mutation-mapping-readme.md) | [Next: Mapping Patterns →](./graphql-mutation-mapping-04-mapping-patterns.md)
+
+## Related Documentation
+
+- [CLI Tools Documentation](../../../../../bin/readme.md) - Complete CLI tools reference
+- [Module 05: Configuration Reference](./graphql-mutation-mapping-05-configuration-reference.md) - Mapping configuration structure
+- [Module 06: Path Syntax](./graphql-mutation-mapping-06-path-syntax.md) - XML/JSON path expressions