Model Merge Tool User Guide

Overview

The Model Merge Tool allows you to combine properties from multiple DataFlood schemas into a single unified schema. This is useful for creating composite models, consolidating related schemas, or building complex data structures from simpler components.

Key Features

  • Visual Drag-and-Drop: Intuitive interface for selecting and merging properties
  • Conflict Resolution: Automatic detection and resolution of naming conflicts
  • Type Compatibility: Validates type compatibility during merge
  • Statistical Model Preservation: Maintains string models and histograms
  • Preview Mode: See the merged result before saving
  • Selective Merging: Choose specific properties to include

Interface Layout

┌─────────────────────────────────────────────────────────┐
│                    Model Merge Tool                     │
├──────────────────┬─────────────────┬──────────────────┤
│                  │                  │                  │
│  Source Model 1  │   Merge Area    │  Source Model 2  │
│                  │                  │                  │
│  ┌─ Properties   │  ┌─ Merged      │  ┌─ Properties   │
│  ├─ customerId   │  ├─ customerId  │  ├─ userId      │
│  ├─ name         │  ├─ name        │  ├─ username    │
│  ├─ email        │  ├─ email       │  ├─ email       │
│  └─ address      │  ├─ address     │  └─ profile     │
│                  │  ├─ userId      │                  │
│                  │  └─ profile     │                  │
│                  │                  │                  │
├──────────────────┴─────────────────┴──────────────────┤
│ [Load Model 1] [Load Model 2] [Preview] [Save Merged]  │
└─────────────────────────────────────────────────────────┘

Getting Started

Opening the Merge Tool

  1. From Menu

    Tools → Model Merge

  2. From Toolbar Click the "Merge" icon

  3. From Project Tree Right-click multiple models → "Merge Selected"

Loading Source Models

Method 1: Load from Files

  1. Click "Load Model 1" button
  2. Select first schema file
  3. Click "Load Model 2" button
  4. Select second schema file

Method 2: Drag from Project Tree

  1. Drag first model to left panel
  2. Drag second model to right panel

Method 3: From Open Tabs

  1. Right-click on tab → "Send to Merge Tool"
  2. Choose position (Model 1 or Model 2)

Merging Properties

Basic Merge Operations

Drag and Drop

  1. Select property from source model
  2. Drag to merge area
  3. Drop in desired position

Context Menu

  1. Right-click property in source
  2. Select "Add to Merged Model"
  3. Configure if needed

Select Multiple

  1. Ctrl+Click to select multiple properties
  2. Drag selection to merge area
  3. All selected properties are added

Handling Conflicts

Name Conflicts

When properties have the same name but different definitions:

  1. Automatic Detection

    • Conflicting properties highlighted in yellow
    • Warning icon appears

  2. Resolution Options

    • Keep Both: Rename one property
    • Replace: Use one definition
    • Merge: Combine compatible definitions
    • Custom: Manually edit

Example:

// Model 1: email
{
  "type": "string",
  "format": "email",
  "maxLength": 100
}

// Model 2: email
{
  "type": "string",
  "format": "email",
  "maxLength": 255
}

// Merged (with merge option)
{
  "type": "string",
  "format": "email",
  "maxLength": 255  // Takes larger constraint
}

Type Conflicts

When properties have incompatible types:

  1. Warning Display

    • Red highlight on conflicting properties
    • Error message in status bar

  2. Resolution

    • Choose one type
    • Create union type (if supported)
    • Skip property

Advanced Merging

Nested Object Merging

Merge nested structures:

  1. Shallow Merge

    • Drag entire object property
    • Maintains structure

  2. Deep Merge

    • Expand nested objects
    • Selectively merge sub-properties
    • Combine nested structures

Example:

// Model 1: address
{
  "type": "object",
  "properties": {
    "street": {"type": "string"},
    "city": {"type": "string"}
  }
}

// Model 2: address
{
  "type": "object",
  "properties": {
    "city": {"type": "string"},
    "country": {"type": "string"}
  }
}

// Deep Merged
{
  "type": "object",
  "properties": {
    "street": {"type": "string"},
    "city": {"type": "string"},
    "country": {"type": "string"}
  }
}

Array Merging

Combine array definitions:

// Model 1: tags
{
  "type": "array",
  "items": {"type": "string"},
  "maxItems": 5
}

// Model 2: tags  
{
  "type": "array",
  "items": {"type": "string"},
  "maxItems": 10
}

// Merged
{
  "type": "array",
  "items": {"type": "string"},
  "maxItems": 10  // Takes larger limit
}

Statistical Model Handling

String Model Merging

When merging string properties with statistical models:

  1. Vocabulary Combination

    • Combines value frequencies
    • Merges pattern lists
    • Recalculates entropy

  2. Pattern Merging

    // Model 1 patterns: ["Llll", "Llll Llll"]
// Model 2 patterns: ["LLLL", "Llll-Llll"]
// Merged patterns: ["Llll", "Llll Llll", "LLLL", "Llll-Llll"]

  3. Character Distribution

    • Weighted average of distributions
    • Preserves character probabilities

Histogram Merging

For numeric properties with histograms:

  1. Bin Combination

    • Merges overlapping bins
    • Adjusts frequencies
    • Maintains distribution shape

  2. Range Extension

    // Model 1: 0-100
// Model 2: 50-200
// Merged: 0-200 with adjusted bins

Configuration Options

Merge Settings

Access via Settings button or Edit → Merge Preferences:

{
  "conflictResolution": "prompt|auto|manual",
  "preserveRequired": true,
  "mergeStatisticalModels": true,
  "combineEnums": true,
  "extendRanges": true,
  "deepMerge": false
}

Conflict Resolution Modes

Prompt Mode (Default)

  • Ask for each conflict
  • Show resolution options
  • Preview result

Auto Mode

  • Apply rules automatically
  • Use larger constraints
  • Combine vocabularies
  • Log decisions

Manual Mode

  • Flag conflicts only
  • Require manual resolution
  • Full control

Preview and Validation

Preview Panel

Before saving, preview the merged schema:

  1. Click "Preview" button
  2. Review merged structure
  3. Check for warnings/errors
  4. Test with sample generation

Validation Checks

Automatic validation includes:

  • Property name uniqueness
  • Type compatibility
  • Constraint consistency
  • Required field conflicts
  • Statistical model validity

Test Generation

Generate sample documents to verify:

  1. Click "Test Generate"
  2. Review sample outputs
  3. Adjust merge if needed
  4. Regenerate to confirm

Saving Merged Schema

Save Options

  1. Save As New

    • File → Save As
    • Choose location and name
    • Preserves source models

  2. Replace Existing

    • File → Save
    • Overwrites current file
    • Confirm before replacing

  3. Add to Project

    • Automatically adds to project
    • Updates project references

Export Options

  • DataFlood Model: Full model with statistical models
  • Standard DataFlood Model: Standard DataFlood Model
  • TypeScript: Interface definitions
  • Documentation: Markdown documentation

Use Cases

Combining Related Entities

Merge customer and user schemas:

Customer Schema + User Schema = Complete Profile Schema
- customerId      - userId        - customerId
- billing         - username      - userId
- orders          - preferences   - billing
                                  - orders
                                  - username
                                  - preferences

Building Composite Models

Create order schema from components:

Product + Customer + Payment = Order
- productId       - customerId    - orderId
- price          - shipping      - products[]
- inventory      - contact       - customer
                 - cardInfo      - payment
                                - shipping
                                - total

Schema Evolution

Merge old and new versions:

Schema v1 + Schema v2 Updates = Schema v2 Complete
- Preserve existing fields
- Add new fields
- Update constraints
- Maintain compatibility

Best Practices

Before Merging

  1. Review source schemas
  2. Identify common properties
  3. Plan conflict resolution
  4. Consider final structure

During Merge

  1. Start with required fields
  2. Handle conflicts immediately
  3. Test frequently
  4. Document decisions

After Merging

  1. Validate thoroughly
  2. Generate test data
  3. Review statistical models
  4. Update documentation

Tips and Tricks

Keyboard Shortcuts

Shortcut Action
Ctrl+M Open merge tool
Drag Move properties
Shift+Drag Copy properties
Delete Remove from merged
Ctrl+Z Undo merge action
F5 Validate merged schema
Ctrl+G Test generate

Quick Actions

  • Double-click: Add property to merged
  • Right-click: Context menu
  • Ctrl+Click: Multi-select
  • Alt+Drag: Clone property

Performance Tips

  • Merge simple properties first
  • Handle complex nested objects separately
  • Use preview before large merges
  • Save incrementally

Troubleshooting

Common Issues

Properties Won't Merge

  • Check type compatibility
  • Verify no circular references
  • Ensure valid JSON structure

Lost Statistical Models

  • Enable "Preserve Models" in settings
  • Check model compatibility
  • Manually re-add if needed

Merge Tool Crashes

  • Reduce schema complexity
  • Check for corrupted schemas
  • Clear merge cache
  • Restart application

Validation Errors

  • Review conflict resolutions
  • Check required fields
  • Verify constraint logic
  • Test with small samples

Advanced Features

Batch Merging

Merge multiple schemas at once:

  1. Select multiple schemas in project
  2. Right-click → "Batch Merge"
  3. Configure merge order
  4. Apply common rules
  5. Review and save results

Merge Templates

Save merge configurations:

  1. Configure merge settings
  2. Save as template
  3. Apply to similar merges
  4. Share with team

Scripted Merging

Use merge rules file:

{
  "rules": [
    {
      "property": "email",
      "action": "use-first"
    },
    {
      "property": "address",
      "action": "deep-merge"
    }
  ]
}

Integration

With Model Editor

  • Send merged schema to editor
  • Continue refinement
  • Add missing properties

With Tides Editor

  • Use merged schema in sequences
  • Create relationships
  • Test generation flows

With CLI

  • Export for command-line use
  • Batch process merges
  • Automate workflows

Next Steps