migrate

Last updated on

Rewrites artifact files written for an earlier schema version so they follow the current one.

Usage

paradoc migrate <path> [options]

Arguments

Options

Description

Each artifact file names the schema version it follows in $schema, such as https://schema.paradoc.dev/2026-09-24.json. For each file, migrate reads that version, applies every migration step from it to the current version in order, and rewrites the file in place with the current $schema.

• A JSON file stays JSON and keeps its indentation. A YAML file stays YAML and keeps its comments.
• The migrated artifact must validate against the current version. If it does not, the file is left unchanged and the failure is reported.
• A step that cannot convert a value safely names the value, and the file is left unchanged.
• A file whose $schema names no published version (missing, the undated schema.json, an unpublished date, or another address) needs --from to name its version.
• A bundle's inline parts migrate with it, at any depth. A part without $schema follows its bundle. A part that declares an earlier version is first brought to its bundle's version, so a current bundle with an outdated part still migrates. A part that declares a later version than its bundle, or no published version, fails and names the part.
• In a directory, migrate reads every .json, .yaml, and .yml file outside node_modules and dist. Files that are not artifacts, such as package.json, are skipped. A file that cannot be parsed is reported, and the run continues.

Nothing else changes an artifact file's version: loading never migrates. Every other command that reads an artifact file, such as validate or render, refuses one that is not the current version and names this command.

Examples

Review the changes for a directory, then apply them:

paradoc migrate forms/ --dry-run
paradoc migrate forms/

Migrate a file that has no $schema:

paradoc migrate lease.yaml --from 2026-09-23

Output

migrated  forms/lease.yaml  2026-09-23 → 2026-09-24
current   forms/notice.json
failed    forms/intake.json: Cannot convert fields.stay.default = "PT": a duration must contain at least one date or time component, such as P1D or PT30M

1 migrated, 1 current, 1 failed  (schema version 2026-09-24)

The command exits with status 1 when any file fails.

See also

• Schemas - Schema versions and their addresses
• validate - Validate an artifact against the current schema