Bi-Directional Sync

Keep Your Spec and Project in Perfect Sync

Tigrister's bi-directional sync is a unique feature that keeps your OpenAPI spec and project state synchronized. Edit in the code editor or visual designer - changes flow both ways automatically.

Key Concepts
  • • Change Detection - Tracks modifications across all spec sections
  • • Change Application - Applies detected changes to project state
  • • Conflict Resolution - Handles simultaneous edits intelligently
  • • Extension Preservation - Keeps x-tigrister-* fields intact

How Bi-Directional Sync Works

The sync system monitors changes from multiple sources and keeps everything consistent.

Sync Flow
Code Editor
Visual Designer
Import
Project Actions
Change Detection
Compare old vs new spec state
ChangeSet Created
Categorized by section (paths, schemas, etc.)
Apply Changes
Update project modules, endpoints, environments
Spec ↔ Project Synchronized

Change Sources

Changes can originate from four different sources, each tracked independently:

editorCode Editor

Direct YAML/JSON edits in the Monaco editor. Changes are parsed and synced on save or when switching views.

visualVisual Designer

Form-based edits to paths, parameters, schemas. Each field change triggers targeted updates to the spec.

importImport

Loading a new spec from file or URL. Replaces the entire spec and triggers full project synchronization.

projectProject Actions

Creating endpoints, moving modules, or other project-level operations. Changes reflect back to the spec.

Tracked Sections

The sync system monitors changes across all major OpenAPI sections:

SectionSync TargetChange Types
infoProject name, descriptionupdate
serversEnvironment variablesadd, update, delete
tagsModule organizationadd, update, delete
pathsEndpoints (method, URL, params)add, update, delete
schemasComponent schemasadd, update, delete
securitySchemesAuth configurationadd, update, delete
securityDefault auth requirementsupdate
webhooksWebhook definitionsadd, update, delete

Change Detection

The system compares old and new spec states to generate a detailed ChangeSet.

ChangeSet Structure
interface ChangeSet {
timestamp: number;
source: 'editor' | 'visual' | 'import' | 'project';
hasChanges: boolean;
changes: ChangeEntry[];
summary: {
// Counts per section
paths: { added: number; updated: number; deleted: number };
schemas: { added: number; updated: number; deleted: number };
// ... etc
};
}
Individual Change Entry
interface ChangeEntry {
section: 'info' | 'servers' | 'paths' | 'schemas' | ...;
type: 'add' | 'update' | 'delete';
key: string; // e.g., "/users", "Pet", "BearerAuth"
oldValue?: unknown;
newValue?: unknown;
nestedChanges?: ChangeEntry[]; // For operation params
}

Conflict Resolution

When both sides modify the same item, Tigrister detects and resolves conflicts.

Conflict Detection

A conflict occurs when the same section:keyis modified in both source and target with different values.

Conflict detected:
Section: paths
Key: /users:get
Editor: Changed summary
Visual: Changed parameters
Resolution Strategies
  • source-winsEditor changes take precedence (default)
  • target-winsVisual/project changes take precedence
  • mergeDeep merge both changes when possible
  • askPrompt user to choose
Smart Resolution Logic
update vs delete→Prefer update (preserve the item)
paths conflict→Attempt deep merge
schemas conflict→Attempt deep merge
other sections→Source wins (editor priority)
Auto-Resolution

Tigrister can automatically resolve all conflicts using a chosen strategy:

autoResolveConflicts(conflicts, strategy)
// Returns ConflictResolution[] for all conflicts
// strategy: 'source-wins' | 'target-wins' | 'merge'
Deep Merge Behavior

When using the merge strategy for paths/schemas:

  • •Source properties are preserved (take precedence)
  • •Target properties fill in gaps (where source is undefined)
  • •Nested objects are recursively merged
  • •Arrays are not merged (source array wins)

Sync Options

Customize sync behavior with these options:

interface SyncOptions {
// Which sections to sync (default: all)
sections?: ChangeSection[];
// Keep x-tigrister-* extensions (default: true)
preserveExtensions?: boolean;
// How to handle conflicts (default: 'source-wins')
conflictStrategy?: 'source-wins' | 'target-wins' | 'merge' | 'ask';
// Remove items not in source (default: false)
deleteOrphans?: boolean;
}

preserveExtensions

When enabled, x-tigrister-* extensions (like assertions, auth configs) survive import and sync operations.

deleteOrphans

When enabled, items in the project that don't exist in the spec will be removed. Use with caution during import.

Team Workflows

Bi-directional sync enables effective team collaboration patterns.

1Spec-First Development

Design team defines API in code editor → Sync creates endpoints → QA team tests in Area Mode

Code Editor→Sync→Area Mode
2Visual Prototyping

Product defines endpoints in Visual Designer → Changes sync to spec → Developers export for codegen

Visual Designer→Sync→Export
3Live Import Update

Backend deploys new spec → Import updated spec → Sync merges with existing tests

Import→Merge Sync→Tests Preserved

Understanding Sync Results

Every sync operation returns a detailed result:

interface SyncResult {
success: boolean;
error?: string;
changeSet: ChangeSet;
conflicts?: SyncConflict[];
appliedChanges: number;
skippedChanges: number;
}

Success

All changes applied without conflicts.appliedChanges > 0

Partial

Some changes skipped due to conflicts.skippedChanges > 0

Failed

Sync failed completely.error contains details.

Sync Best Practices

Work in One View at a Time

Avoid simultaneous edits in code editor and visual designer to prevent conflicts.

Save Before Switching

Always save your changes before switching between editor views to ensure sync runs.

Use Extension Preservation

Keep preserveExtensions enabled to retain test assertions and auth configs.

Be Cautious with deleteOrphans

Only enable when importing a complete replacement spec. Otherwise you may lose project data.

Review Conflict Summaries

When conflicts occur, check the summary to understand what was merged or skipped.

Related Topics
→ Import→ Visual Designer→ Code Editor→ Tigrister Extensions→ Troubleshooting
Preview & Try It OutVersion Conversion