Archify Workflow Schema Version Policy: How to Migrate Between Versions

Archify uses a mandatory schemaVersion integer field in every workflow receipt to track structural changes, requiring explicit migration functions when upgrading from older versions to ensure backward compatibility.

The workflow schema version policy in the tt-a1i/archify repository governs how JSON receipts—metadata documents generated during comparison, repair, and other operations—evolve over time. Every receipt includes a top-level schemaVersion field that signals its structural format, allowing consumers to validate compatibility and apply transformations when necessary. As implemented in the current main branch, this policy enforces strict version checking and provides clear migration patterns for handling schema updates.

Understanding the Workflow Schema Version Policy

Archify treats workflow receipts as immutable versioned documents. The policy defines three core rules:

• Integer versioning: The schemaVersion field uses whole numbers starting at 1. Future releases increment this value when fields are added, renamed, or restructured.
• Fail-fast validation: Consumers must reject receipts with unknown schemaVersion values rather than attempting partial parsing.
• Backward compatibility: Newer code must support older schema versions through explicit migration functions, but older code cannot safely process newer schemas.

The current canonical version is 1, as defined in the receipt generation logic and documentation.

Source Code Implementation

The workflow schema version policy is enforced across three critical files in the repository.

Receipt Generation in start-template.html

The scripts/start-template.html file constructs workflow receipts by hard-coding the current schema version:

const receipt = {
  schemaVersion: 1,
  command: 'compare',
  completeness: 'complete',
  changes: detectedChanges,
  // additional payload fields...
};

This ensures all newly created receipts carry the correct version identifier for downstream consumers.

Consumer Validation in checkout-platform-delta.html

The examples/checkout-platform-delta.html file demonstrates strict validation before processing:

if (!receipt || receipt.schemaVersion !== 1 ||
    receipt.command !== 'compare' ||
    receipt.completeness !== 'complete' ||
    !receipt.changes) {
  return false;   // Reject malformed or outdated receipts
}

This pattern prevents runtime errors by surfacing version mismatches immediately.

Documentation in skill-embedded-optional-update-notifier-design.md

The docs/skill-embedded-optional-update-notifier-design.md file specifies the required value for the schema version field, establishing the contract that all implementations must follow when generating or consuming workflow receipts.

How to Migrate Between Workflow Schema Versions

When a new schema version (e.g., 2) is introduced, follow this structured migration process:

1. Detect the incoming version before processing:

const CURRENT_VERSION = 1;  // Update when schema changes

function ensureLatestSchema(receipt) {
  if (receipt.schemaVersion === CURRENT_VERSION) {
    return receipt;
  }
  if (receipt.schemaVersion > CURRENT_VERSION) {
    throw new Error(`Unsupported future schema version: ${receipt.schemaVersion}`);
  }
  return migrateReceipt(receipt, CURRENT_VERSION);
}

2. Implement a pure migration function that transforms legacy structures:

function migrateReceipt(receipt, targetVersion) {
  // Migrate from version 1 to 2
  if (receipt.schemaVersion === 1 && targetVersion === 2) {
    return {
      ...receipt,
      schemaVersion: 2,
      createdAt: new Date().toISOString(),  // New required field
      steps: receipt.stepList || receipt.steps,  // Normalize field names
      // Remove deprecated fields if necessary
    };
  }
  throw new Error(`Migration from ${receipt.schemaVersion} to ${targetVersion} not implemented`);
}

3. Update all receipt producers to emit the new schemaVersion value, modifying files like scripts/start-template.html to use schemaVersion: 2.

4. Add unit tests feeding legacy receipt fixtures through the migration path to verify structural correctness.

Summary

• Archify workflow receipts use a schemaVersion integer starting at 1 to track structural changes.
• The scripts/start-template.html generates receipts with the current version, while examples/checkout-platform-delta.html validates it.
• Migration requires detecting version mismatches, implementing pure transformation functions, and updating producers.
• Consumers must fail fast when encountering unknown schema versions to prevent data corruption.

Frequently Asked Questions

What is the current workflow schema version in Archify?

The current workflow schema version is 1. This value is hard-coded in scripts/start-template.html and documented in docs/skill-embedded-optional-update-notifier-design.md. All receipts generated by the current main branch contain "schemaVersion": 1.

How does Archify handle backward compatibility?

Archify requires explicit migration functions to maintain backward compatibility. When a consumer encounters a receipt with an older schemaVersion, it must pass the object through a migration function that transforms it to the current structure before processing. Consumers cannot safely ignore unknown fields and must reject versions newer than their supported range.

Where is the schema version defined in the codebase?

The schema version is defined in three locations: scripts/start-template.html where receipts are constructed, examples/checkout-platform-delta.html where validation occurs, and docs/skill-embedded-optional-update-notifier-design.md which documents the required value. Additionally, example receipts like generated/maka-regenerated.workflow.visual-check.json demonstrate the field in practice.

What happens if I try to use an unsupported schema version?

If a consumer encounters a receipt with a schemaVersion it does not recognize—whether older than supported minimums or newer than the current implementation—the code should throw an error or return false immediately. The examples/checkout-platform-delta.html implementation returns false for any receipt where schemaVersion !== 1, preventing partial processing of incompatible data structures.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}