@fluentcommerce/fc-connect-sdk 0.1.48 → 0.1.52

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

@@ -1,462 +1,464 @@
-# Module 3: Schema Validation
-
-**Ensure mapping correctness before deployment**
-
-**Level:** Intermediate
-**Time:** 30 minutes
-**Prerequisites:** [Module 2: Quick Start](./mapping-02-quick-start.md)
-
----
-
-## Learning Objectives
-
-After completing this module, you will:
-
-- ✅ Introspect your Fluent Commerce GraphQL schema
-- ✅ Validate mappings against the schema
-- ✅ Identify and fix common schema violations
-- ✅ Understand schema validation best practices
-
----
-
-## Why Schema Validation Matters
-
-All GraphQL examples in this documentation are validated against the Fluent Commerce schema documented in [`docs/schema/fluent-commerce-schema.json`](../../../04-REFERENCE/schema/fluent-commerce-schema.json). However, **your specific Fluent Commerce environment may have different field names, types, or requirements**.
-
-Using incorrect field names leads to:
-
-- ❌ Mapping failures at runtime
-- ❌ Silent data loss (fields not saved)
-- ❌ Cryptic error messages from Fluent API
-- ❌ Failed integrations
-
----
-
-## Step 1: Introspect Your Schema
-
-Generate a schema file specific to your environment:
-
-### Using npx (No Installation)
-
-```bash
-npx fc-connect introspect-schema \
-  --endpoint https://YOUR_ACCOUNT.api.fluentcommerce.com/graphql \
-  --output schema.json
-```
-
-### What You Get
-
-The generated `schema.json` contains:
-
-- ✅ All available mutations (`createOrder`, `upsertInventoryPosition`, etc.)
-- ✅ Required vs optional fields for each mutation input
-- ✅ Field types (`String!`, `Int`, `Float`, `DateTime`, etc.)
-- ✅ Available query fields
-- ✅ Enum values (`OrderType`, `EntityType`, etc.)
-
----
-
-## Step 2: Validate Your Mapping
-
-Before deploying your connector, validate your mapping against the schema:
-
-```bash
-# Validate ingestion mapping
-npx fc-connect validate-schema \
-  --mapping config/field-mappings.json \
-  --schema schema.json
-
-# Validate extraction mapping
-npx fc-connect validate-schema \
-  --mapping config/extraction-mappings.json \
-  --schema schema.json
-```
-
-### What Gets Validated
-
-The validator checks:
-
-- ✅ All target fields exist in the mutation input
-- ✅ Required fields are mapped
-- ✅ Field types match (`String` → `String!`, `Int` → `Int!`)
-- ✅ Source paths are valid
-- ✅ Resolvers are compatible with target types
-
----
-
-## Example: Schema-Validated Order Mapping
-
-### ✅ CORRECT - Validated Against Schema
-
-```json
-{
-  "direction": "ingest",
-  "sourceFormat": "xml",
-  "mutation": "createOrder",
-  "comment": "✅ Validated against Fluent Commerce schema",
-
-  "fields": {
-    "ref": {
-      "source": "order@id",
-      "required": true,
-      "comment": "✅ Maps to CreateOrderInput.ref (String! required)"
-    },
-    "type": {
-      "source": "order@type",
-      "resolver": "custom.mapOrderType",
-      "comment": "✅ Maps to CreateOrderInput.type (OrderType! enum required)"
-    },
-    "retailer": {
-      "fields": {
-        "id": {
-          "value": "1",
-          "comment": "✅ CreateOrderInput.retailer (RetailerInput! required)"
-        }
-      }
-    },
-    "totalPrice": {
-      "source": "order.total",
-      "resolver": "sdk.parseFloat",
-      "required": true,
-      "comment": "✅ Maps to CreateOrderInput.totalPrice (Float! required)"
-    },
-    "customer": {
-      "fields": {
-        "id": {
-          "resolver": "custom.lookupCustomerByEmail",
-          "comment": "✅ CreateOrderInput.customer (CustomerInput! required - lookup by email)"
-        }
-      }
-    },
-    "items": {
-      "source": "order.items.item",
-      "isArray": true,
-      "comment": "✅ Maps to CreateOrderInput.items ([OrderItemInput]! required)",
-      "fields": {
-        "ref": {
-          "source": "$.@id",
-          "required": true,
-          "comment": "✅ OrderItemInput.ref (String! required)"
-        },
-        "productRef": {
-          "source": "$.productId",
-          "required": true,
-          "comment": "✅ OrderItemInput.productRef (String! required)"
-        },
-        "quantity": {
-          "source": "$.qty",
-          "resolver": "sdk.parseInt",
-          "required": true,
-          "comment": "✅ OrderItemInput.quantity (Int! required)"
-        },
-        "price": {
-          "source": "$.unitPrice",
-          "resolver": "sdk.parseFloat",
-          "required": true,
-          "comment": "✅ OrderItemInput.price (Float! required)"
-        },
-        "totalPrice": {
-          "resolver": "custom.calculateItemTotal",
-          "required": true,
-          "comment": "✅ OrderItemInput.totalPrice (Float! required)"
-        },
-        "currency": {
-          "source": "order.currency",
-          "required": true,
-          "comment": "✅ OrderItemInput.currency (String! required)"
-        }
-      }
-    }
-  }
-}
-```
-
-### ❌ WRONG - Not Validated
-
-```json
-{
-  "direction": "ingest",
-  "mutation": "createOrder",
-  "fields": {
-    "orderRef": {
-      // ❌ Field doesn't exist - should be "ref"
-      "source": "order@id"
-    },
-    "customerEmail": {
-      // ❌ Wrong path - should be "customer.id" not nested email
-      "source": "customer@email"
-    },
-    "amount": {
-      // ❌ Field doesn't exist - should be "totalPrice"
-      "source": "total"
-    }
-  }
-}
-```
-
-### Validation Errors
-
-```
-❌ Field "orderRef" does not exist in CreateOrderInput
-   Expected: "ref" (String! required)
-
-❌ Field "customerEmail" does not exist in CreateOrderInput
-   Expected: "customer.id" (ID! required) or "customer.email" (String)
-
-❌ Field "amount" does not exist in CreateOrderInput
-   Expected: "totalPrice" (Float! required)
-
-❌ Missing required field: "type" (OrderType! required)
-❌ Missing required field: "retailer.id" (ID! required)
-❌ Missing required field: "customer.id" (ID! required)
-❌ Missing required field: "items" ([OrderItemInput]! required)
-❌ Missing required field: "currency" (String! required)
-```
-
----
-
-## Best Practices
-
-### 1. Always Add Schema Comments
-
-Document which schema field each mapping targets:
-
-```json
-{
-  "productRef": {
-    "source": "sku",
-    "comment": "✅ Maps to InventoryPositionInput.productRef (String! required)"
-  }
-}
-```
-
-### 2. Validate Before Deployment
-
-Run schema validation as part of your CI/CD:
-
-```bash
-# Add to package.json scripts
-{
-  "scripts": {
-    "validate-mappings": "fc-connect-validate-schema --mapping config/field-mappings.json --schema schema.json"
-  }
-}
-
-# Run before deployment
-npm run validate-mappings
-```
-
-### 3. Keep Schema Updated
-
-Re-introspect when Fluent Commerce API updates:
-
-```bash
-# Quarterly or when API changes
-npx fc-connect introspect-schema --endpoint $FLUENT_URL --output schema.json
-```
-
-### 4. Reference Schema in Documentation
-
-Link to schema for each example:
-
-```markdown
-See `docs/schema/fluent-commerce-schema.json` → types.Mutation.createOrder
-```
-
-### 5. Test with Sample Data
-
-Validate mappings work before processing real data:
-
-```typescript
-// Test mapping with canonical example
-const testData = require('./docs/guides/examples/test-data/canonical-order.json');
-const result = await mapper.mapWithNodes(testData);
-assert(result.success, 'Mapping should succeed with canonical data');
-```
-
----
-
-## Schema Reference Files
-
-This repository includes:
-
-### 📄 fluent-commerce-schema.json
-
-**Location:** `docs/schema/fluent-commerce-schema.json`
-
-**Contains:**
-
-- All mutations and queries
-- Input types and required fields
-- Enum values
-- Connection types for pagination
-- Scalar types (DateTime, JSON)
-- Example queries validated against schema
-
-### 📄 canonical-order.json
-
-**Location:** `docs/guides/examples/test-data/canonical-order.json`
-
-**Contains:**
-
-- Validated structure for order ingestion
-- Real-world field names (ORD-2025-001, SKU-WM-001)
-- Complete with customer, items, payments
-
-### 📄 canonical-inventory.json
-
-**Location:** `docs/guides/examples/test-data/canonical-inventory.json`
-
-**Contains:**
-
-- Validated structure for inventory sync
-- WMS-style quantity breakdown (on-hand, available, reserved)
-- Real location (WH-001 - Springfield Distribution Center)
-
----
-
-## Common Schema Pitfalls
-
-| Issue                      | ❌ Wrong                        | ✅ Correct                             |
-| -------------------------- | ------------------------------- | -------------------------------------- |
-| **Field name typo**        | `customerEmail` (doesn't exist) | `customer.email` (exists)              |
-| **Wrong field type**       | String → Int                    | Use `resolver: "sdk.parseInt"`         |
-| **Missing required field** | Omit `retailer.id`              | Include all required fields            |
-| **Wrong enum value**       | `type: "REGULAR"` (not in enum) | `type: "STANDARD"` (in OrderType enum) |
-| **Incorrect nesting**      | `items.productRef`              | Use `isArray: true` with nested `fields` config |
-| **Missing array marker**   | `items.fields`                  | Use `"isArray": true` in field config            |
-
----
-
-## Validation Workflow
-
-```mermaid
-graph TD
-    A[Create Mapping Config] --> B[Introspect Schema]
-    B --> C[Validate Mapping]
-    C --> D{Valid?}
-    D -->|Yes| E[Deploy Connector]
-    D -->|No| F[Fix Errors]
-    F --> C
-    E --> G[Test with Sample Data]
-    G --> H{Success?}
-    H -->|Yes| I[Production Deployment]
-    H -->|No| J[Debug & Fix]
-    J --> G
-```
-
----
-
-## Practice Exercise
-
-**Task:** Validate this inventory mapping configuration:
-
-```json
-{
-  "direction": "ingest",
-  "mutation": "upsertInventoryPosition",
-  "fields": {
-    "skuRef": {
-      "source": "sku",
-      "required": true
-    },
-    "warehouse": {
-      "source": "location",
-      "required": true
-    },
-    "quantity": {
-      "source": "qty",
-      "resolver": "sdk.parseInt",
-      "required": true
-    }
-  }
-}
-```
-
-**Questions:**
-
-1. What schema errors will validation find?
-2. How would you fix them?
-
-<details>
-<summary>Click to see answers</summary>
-
-**Errors Found:**
-
-1. ❌ Field "skuRef" doesn't exist → Should be "productRef"
-2. ❌ Field "warehouse" doesn't exist → Should be "locationRef"
-3. ❌ Field "quantity" doesn't exist → Should be "qty"
-4. ❌ Missing required field "ref"
-
-**Fixed Mapping:**
-
-```json
-{
-  "direction": "ingest",
-  "mutation": "upsertInventoryPosition",
-  "fields": {
-    "ref": {
-      "source": "sku",
-      "required": true,
-      "comment": "✅ UpsertInventoryPositionInput.ref (String! required)"
-    },
-    "productRef": {
-      "source": "sku",
-      "required": true,
-      "comment": "✅ UpsertInventoryPositionInput.productRef (String! required)"
-    },
-    "locationRef": {
-      "source": "location",
-      "required": true,
-      "comment": "✅ UpsertInventoryPositionInput.locationRef (String! required)"
-    },
-    "qty": {
-      "source": "qty",
-      "resolver": "sdk.parseInt",
-      "required": true,
-      "comment": "✅ UpsertInventoryPositionInput.qty (Int! required)"
-    }
-  }
-}
-```
-
-</details>
-
----
-
-## Key Takeaways
-
-1. **Always validate before deployment** - Catch errors early
-2. **Use schema comments** - Document field mappings
-3. **Keep schema updated** - Re-introspect quarterly
-4. **Test with canonical data** - Validate mappings work
-5. **Reference schema files** - Link to schema documentation
-
----
-
-## Next Steps
-
-Now that you can validate mappings, you're ready to see real-world examples:
-
-→ Continue to [Module 4: Use Cases](./mapping-04-use-cases.md)
-
-**Alternative paths:**
-
-- Jump to [Advanced Patterns](./mapping-05-advanced-patterns.md) for complex transformations
-- Review [API Reference](./mapping-07-api-reference.md) for complete documentation
-
----
-
-[← Back to Quick Start](./mapping-02-quick-start.md) | [Next: Use Cases →](./mapping-04-use-cases.md)
-
-
-
-
-
-
-
-
-
-
-
-
+# Module 3: Schema Validation
+
+**Ensure mapping correctness before deployment**
+
+**Level:** Intermediate
+**Time:** 30 minutes
+**Prerequisites:** [Module 2: Quick Start](./mapping-02-quick-start.md)
+
+---
+
+## Learning Objectives
+
+After completing this module, you will:
+
+- ✅ Introspect your Fluent Commerce GraphQL schema
+- ✅ Validate mappings against the schema
+- ✅ Identify and fix common schema violations
+- ✅ Understand schema validation best practices
+
+---
+
+## Why Schema Validation Matters
+
+All GraphQL examples in this documentation are validated against the Fluent Commerce schema documented in [`docs/schema/fluent-commerce-schema.json`](../../../04-REFERENCE/schema/fluent-commerce-schema.json). However, **your specific Fluent Commerce environment may have different field names, types, or requirements**.
+
+Using incorrect field names leads to:
+
+- ❌ Mapping failures at runtime
+- ❌ Silent data loss (fields not saved)
+- ❌ Cryptic error messages from Fluent API
+- ❌ Failed integrations
+
+---
+
+## Step 1: Introspect Your Schema
+
+Generate a schema file specific to your environment:
+
+### Using npx (No Installation)
+
+```bash
+npx fc-connect introspect-schema \
+  --endpoint https://YOUR_ACCOUNT.api.fluentcommerce.com/graphql \
+  --output schema.json
+```
+
+### What You Get
+
+The generated `schema.json` contains:
+
+- ✅ All available mutations (`createOrder`, `upsertInventoryPosition`, etc.)
+- ✅ Required vs optional fields for each mutation input
+- ✅ Field types (`String!`, `Int`, `Float`, `DateTime`, etc.)
+- ✅ Available query fields
+- ✅ Enum values (`OrderType`, `EntityType`, etc.)
+
+---
+
+## Step 2: Validate Your Mapping
+
+Before deploying your connector, validate your mapping against the schema:
+
+```bash
+# Validate ingestion mapping
+npx fc-connect validate-schema \
+  --mapping config/field-mappings.json \
+  --schema schema.json
+
+# Validate extraction mapping
+npx fc-connect validate-schema \
+  --mapping config/extraction-mappings.json \
+  --schema schema.json
+```
+
+### What Gets Validated
+
+The validator checks:
+
+- ✅ All target fields exist in the mutation input
+- ✅ Required fields are mapped
+- ✅ Field types match (`String` → `String!`, `Int` → `Int!`)
+- ✅ Source paths are valid
+- ✅ Resolvers are compatible with target types
+
+---
+
+## Example: Schema-Validated Order Mapping
+
+### ✅ CORRECT - Validated Against Schema
+
+```json
+{
+  "direction": "ingest",
+  "sourceFormat": "xml",
+  "mutation": "createOrder",
+  "comment": "✅ Validated against Fluent Commerce schema",
+
+  "fields": {
+    "ref": {
+      "source": "order@id",
+      "required": true,
+      "comment": "✅ Maps to CreateOrderInput.ref (String! required)"
+    },
+    "type": {
+      "source": "order@type",
+      "resolver": "custom.mapOrderType",
+      "comment": "✅ Maps to CreateOrderInput.type (OrderType! enum required)"
+    },
+    "retailer": {
+      "fields": {
+        "id": {
+          "value": "1",
+          "comment": "✅ CreateOrderInput.retailer (RetailerInput! required)"
+        }
+      }
+    },
+    "totalPrice": {
+      "source": "order.total",
+      "resolver": "sdk.parseFloat",
+      "required": true,
+      "comment": "✅ Maps to CreateOrderInput.totalPrice (Float! required)"
+    },
+    "customer": {
+      "fields": {
+        "id": {
+          "resolver": "custom.lookupCustomerByEmail",
+          "comment": "✅ CreateOrderInput.customer (CustomerInput! required - lookup by email)"
+        }
+      }
+    },
+    "items": {
+      "source": "order.items.item",
+      "isArray": true,
+      "comment": "✅ Maps to CreateOrderInput.items ([OrderItemInput]! required)",
+      "fields": {
+        "ref": {
+          "source": "$.@id",
+          "required": true,
+          "comment": "✅ OrderItemInput.ref (String! required)"
+        },
+        "productRef": {
+          "source": "$.productId",
+          "required": true,
+          "comment": "✅ OrderItemInput.productRef (String! required)"
+        },
+        "quantity": {
+          "source": "$.qty",
+          "resolver": "sdk.parseInt",
+          "required": true,
+          "comment": "✅ OrderItemInput.quantity (Int! required)"
+        },
+        "price": {
+          "source": "$.unitPrice",
+          "resolver": "sdk.parseFloat",
+          "required": true,
+          "comment": "✅ OrderItemInput.price (Float! required)"
+        },
+        "totalPrice": {
+          "resolver": "custom.calculateItemTotal",
+          "required": true,
+          "comment": "✅ OrderItemInput.totalPrice (Float! required)"
+        },
+        "currency": {
+          "source": "order.currency",
+          "required": true,
+          "comment": "✅ OrderItemInput.currency (String! required)"
+        }
+      }
+    }
+  }
+}
+```
+
+### ❌ WRONG - Not Validated
+
+```json
+{
+  "direction": "ingest",
+  "mutation": "createOrder",
+  "fields": {
+    "orderRef": {
+      // ❌ Field doesn't exist - should be "ref"
+      "source": "order@id"
+    },
+    "customerEmail": {
+      // ❌ Wrong path - should be "customer.id" not nested email
+      "source": "customer@email"
+    },
+    "amount": {
+      // ❌ Field doesn't exist - should be "totalPrice"
+      "source": "total"
+    }
+  }
+}
+```
+
+### Validation Errors
+
+```
+❌ Field "orderRef" does not exist in CreateOrderInput
+   Expected: "ref" (String! required)
+
+❌ Field "customerEmail" does not exist in CreateOrderInput
+   Expected: "customer.id" (ID! required) or "customer.email" (String)
+
+❌ Field "amount" does not exist in CreateOrderInput
+   Expected: "totalPrice" (Float! required)
+
+❌ Missing required field: "type" (OrderType! required)
+❌ Missing required field: "retailer.id" (ID! required)
+❌ Missing required field: "customer.id" (ID! required)
+❌ Missing required field: "items" ([OrderItemInput]! required)
+❌ Missing required field: "currency" (String! required)
+```
+
+---
+
+## Best Practices
+
+### 1. Always Add Schema Comments
+
+Document which schema field each mapping targets:
+
+```json
+{
+  "productRef": {
+    "source": "sku",
+    "comment": "✅ Maps to InventoryPositionInput.productRef (String! required)"
+  }
+}
+```
+
+### 2. Validate Before Deployment
+
+Run schema validation as part of your CI/CD:
+
+```bash
+# Add to package.json scripts
+{
+  "scripts": {
+    "validate-mappings": "fc-connect-validate-schema --mapping config/field-mappings.json --schema schema.json"
+  }
+}
+
+# Run before deployment
+npm run validate-mappings
+```
+
+### 3. Keep Schema Updated
+
+Re-introspect when Fluent Commerce API updates:
+
+```bash
+# Quarterly or when API changes
+npx fc-connect introspect-schema --endpoint $FLUENT_URL --output schema.json
+```
+
+### 4. Reference Schema in Documentation
+
+Link to schema for each example:
+
+```markdown
+See `docs/schema/fluent-commerce-schema.json` → types.Mutation.createOrder
+```
+
+### 5. Test with Sample Data
+
+Validate mappings work before processing real data:
+
+```typescript
+// Test mapping with canonical example
+const testData = require('./docs/guides/examples/test-data/canonical-order.json');
+const result = await mapper.mapWithNodes(testData);
+assert(result.success, 'Mapping should succeed with canonical data');
+```
+
+---
+
+## Schema Reference Files
+
+This repository includes:
+
+### 📄 fluent-commerce-schema.json
+
+**Location:** `docs/schema/fluent-commerce-schema.json`
+
+**Contains:**
+
+- All mutations and queries
+- Input types and required fields
+- Enum values
+- Connection types for pagination
+- Scalar types (DateTime, JSON)
+- Example queries validated against schema
+
+### 📄 canonical-order.json
+
+**Location:** `docs/guides/examples/test-data/canonical-order.json`
+
+**Contains:**
+
+- Validated structure for order ingestion
+- Real-world field names (ORD-2025-001, SKU-WM-001)
+- Complete with customer, items, payments
+
+### 📄 canonical-inventory.json
+
+**Location:** `docs/guides/examples/test-data/canonical-inventory.json`
+
+**Contains:**
+
+- Validated structure for inventory sync
+- WMS-style quantity breakdown (on-hand, available, reserved)
+- Real location (WH-001 - Springfield Distribution Center)
+
+---
+
+## Common Schema Pitfalls
+
+| Issue                      | ❌ Wrong                        | ✅ Correct                             |
+| -------------------------- | ------------------------------- | -------------------------------------- |
+| **Field name typo**        | `customerEmail` (doesn't exist) | `customer.email` (exists)              |
+| **Wrong field type**       | String → Int                    | Use `resolver: "sdk.parseInt"`         |
+| **Missing required field** | Omit `retailer.id`              | Include all required fields            |
+| **Wrong enum value**       | `type: "REGULAR"` (not in enum) | `type: "STANDARD"` (in OrderType enum) |
+| **Incorrect nesting**      | `items.productRef`              | Use `isArray: true` with nested `fields` config |
+| **Missing array marker**   | `items.fields`                  | Use `"isArray": true` in field config            |
+
+---
+
+## Validation Workflow
+
+```mermaid
+graph TD
+    A[Create Mapping Config] --> B[Introspect Schema]
+    B --> C[Validate Mapping]
+    C --> D{Valid?}
+    D -->|Yes| E[Deploy Connector]
+    D -->|No| F[Fix Errors]
+    F --> C
+    E --> G[Test with Sample Data]
+    G --> H{Success?}
+    H -->|Yes| I[Production Deployment]
+    H -->|No| J[Debug & Fix]
+    J --> G
+```
+
+---
+
+## Practice Exercise
+
+**Task:** Validate this inventory mapping configuration:
+
+```json
+{
+  "direction": "ingest",
+  "mutation": "upsertInventoryPosition",
+  "fields": {
+    "skuRef": {
+      "source": "sku",
+      "required": true
+    },
+    "warehouse": {
+      "source": "location",
+      "required": true
+    },
+    "quantity": {
+      "source": "qty",
+      "resolver": "sdk.parseInt",
+      "required": true
+    }
+  }
+}
+```
+
+**Questions:**
+
+1. What schema errors will validation find?
+2. How would you fix them?
+
+<details>
+<summary>Click to see answers</summary>
+
+**Errors Found:**
+
+1. ❌ Field "skuRef" doesn't exist → Should be "productRef"
+2. ❌ Field "warehouse" doesn't exist → Should be "locationRef"
+3. ❌ Field "quantity" doesn't exist → Should be "qty"
+4. ❌ Missing required field "ref"
+
+**Fixed Mapping:**
+
+```json
+{
+  "direction": "ingest",
+  "mutation": "upsertInventoryPosition",
+  "fields": {
+    "ref": {
+      "source": "sku",
+      "required": true,
+      "comment": "✅ UpsertInventoryPositionInput.ref (String! required)"
+    },
+    "productRef": {
+      "source": "sku",
+      "required": true,
+      "comment": "✅ UpsertInventoryPositionInput.productRef (String! required)"
+    },
+    "locationRef": {
+      "source": "location",
+      "required": true,
+      "comment": "✅ UpsertInventoryPositionInput.locationRef (String! required)"
+    },
+    "qty": {
+      "source": "qty",
+      "resolver": "sdk.parseInt",
+      "required": true,
+      "comment": "✅ UpsertInventoryPositionInput.qty (Int! required)"
+    }
+  }
+}
+```
+
+</details>
+
+---
+
+## Key Takeaways
+
+1. **Always validate before deployment** - Catch errors early
+2. **Use schema comments** - Document field mappings
+3. **Keep schema updated** - Re-introspect quarterly
+4. **Test with canonical data** - Validate mappings work
+5. **Reference schema files** - Link to schema documentation
+
+---
+
+## Next Steps
+
+Now that you can validate mappings, you're ready to see real-world examples:
+
+→ Continue to [Module 4: Use Cases](./mapping-04-use-cases.md)
+
+**Alternative paths:**
+
+- Jump to [Advanced Patterns](./mapping-05-advanced-patterns.md) for complex transformations
+- Review [API Reference](./mapping-07-api-reference.md) for complete documentation
+
+---
+
+[← Back to Quick Start](./mapping-02-quick-start.md) | [Next: Use Cases →](./mapping-04-use-cases.md)
+
+
+
+
+
+
+
+
+
+
+
+
+
+