# Archify Workflow Schema Version Policy: How to Migrate Between Versions

> Learn Archify's workflow schema version policy. Discover how to migrate between versions using explicit migration functions and ensure backward compatibility with schemaVersion.

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: migration-guide
- Published: 2026-09-11

---

**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`](https://github.com/tt-a1i/archify/blob/main/scripts/start-template.html) file constructs workflow receipts by hard-coding the current schema version:

```javascript
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`](https://github.com/tt-a1i/archify/blob/main/examples/checkout-platform-delta.html) file demonstrates strict validation before processing:

```javascript
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`](https://github.com/tt-a1i/archify/blob/main/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:

```javascript
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:

```javascript
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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/scripts/start-template.html) generates receipts with the current version, while [`examples/checkout-platform-delta.html`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/scripts/start-template.html) and documented in [`docs/skill-embedded-optional-update-notifier-design.md`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/scripts/start-template.html) where receipts are constructed, [`examples/checkout-platform-delta.html`](https://github.com/tt-a1i/archify/blob/main/examples/checkout-platform-delta.html) where validation occurs, and [`docs/skill-embedded-optional-update-notifier-design.md`](https://github.com/tt-a1i/archify/blob/main/docs/skill-embedded-optional-update-notifier-design.md) which documents the required value. Additionally, example receipts like [`generated/maka-regenerated.workflow.visual-check.json`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/examples/checkout-platform-delta.html) implementation returns `false` for any receipt where `schemaVersion !== 1`, preventing partial processing of incompatible data structures.