Schema Version Migration Prompt Template

This prompt is for platform engineers and data pipeline operators who need to migrate model-generated payloads from one schema version to another. Use it when a downstream consumer has upgraded its contract, but upstream models still produce the old shape. The prompt transforms field names, handles deprecated fields, populates new required fields with computed or default values, and applies a migration map you provide. It is not a schema designer or a general-purpose data mapper. It assumes you already know the source and target schemas and can supply a precise migration specification.

The ideal user has both the old and new schema definitions in hand and understands the semantic differences between them. You must provide a migration map that explicitly declares field renames, default values for new required fields, and a policy for deprecated fields (drop, rename, or archive). This prompt works best when the migration is deterministic and rule-based. Do not use it when the schema change requires business logic, external data lookups, or subjective interpretation of field semantics. For those cases, the migration logic belongs in application code, not in a prompt.

Before using this prompt, confirm that you have a validated migration map and a set of test payloads covering the old schema's edge cases. The prompt will not invent migration rules or guess field mappings. If your migration involves type coercion, enum normalization, or nested object flattening, consider chaining this prompt with the specialized repair prompts in the Schema Mismatch and Field Correction group. Always run the output through a schema validator against the target version and log any records that fail validation for human review.

This prompt template transforms a model's output from one schema version to another. It accepts a source payload, a migration map defining field renames and deprecations, and a target schema specifying new required fields. The model must produce a valid target-version payload while preserving all non-deprecated data and explicitly logging any data loss due to missing source fields for new requirements.

textCopy
You are a schema migration engine. Your task is to transform the provided [SOURCE_PAYLOAD] from schema version [SOURCE_VERSION] to schema version [TARGET_VERSION].

Follow these rules strictly:
1. Apply the field renames defined in [MIGRATION_MAP]. The map is a JSON object where keys are old field paths and values are new field paths.
2. Remove any fields listed in [DEPRECATED_FIELDS]. Log each removal with the field path and reason 'deprecated'.
3. For each field in [TARGET_REQUIRED_FIELDS] that is missing after migration, attempt to populate it using [DEFAULT_VALUE_RULES]. If no rule applies, set the field to null and log it as 'missing_required'.
4. Preserve all other fields and their values exactly as they appear in the source payload.
5. Do not invent, infer, or hallucinate any data not present in the source payload or default rules.

Output a valid JSON object with this structure:
{
  "migrated_payload": { ... },
  "migration_log": [
    {
      "field": "string",
      "action": "renamed" | "removed" | "default_applied" | "missing_required",
      "detail": "string"
    }
  ]
}

[SOURCE_PAYLOAD]:
[INPUT]

[MIGRATION_MAP]:
[MAP]

[DEPRECATED_FIELDS]:
[DEPRECATIONS]

[TARGET_REQUIRED_FIELDS]:
[REQUIRED]

[DEFAULT_VALUE_RULES]:
[DEFAULTS]

To adapt this template, replace each square-bracket placeholder with concrete data. [INPUT] should contain the raw model output as a JSON string. [MAP] should be a JSON object mapping old field paths to new ones, such as {"user.email": "user.contact.email"}. [DEPRECATIONS] is a JSON array of field paths to remove. [REQUIRED] is a JSON array of field paths that must exist in the target version. [DEFAULTS] is a JSON object mapping required field paths to their default values or computation rules. Before deploying, validate the output against your target schema and review the migration log for any missing_required entries that indicate data loss requiring human review.

The Schema Version Migration prompt is not a standalone script; it is a transformation step inside a broader data pipeline. The prompt receives a source record, a migration map, and a target schema version, and it returns a migrated record. The implementation harness is responsible for validating that the output conforms to the target schema, detecting data loss, and deciding whether to retry, fall back, or escalate. This prompt is high-risk because silent field corruption or data loss can propagate downstream into databases, APIs, and user-facing surfaces. The harness must treat every migration as a transaction with a clear success or failure outcome.

Wire the prompt into a pipeline stage that follows this sequence: (1) deserialize the source record and validate it against the source schema version; (2) assemble the prompt with the source record, the migration map (a JSON object defining field renames, type changes, default values, and deprecated-field handling rules), and the target schema version identifier; (3) call the model with a low temperature (0.0–0.1) and request structured JSON output matching the target schema; (4) validate the returned JSON against the target schema using a programmatic schema validator (not the model); (5) run a field-coverage check comparing source fields, migration map expectations, and output fields to detect dropped or hallucinated fields; (6) if validation fails, retry once with the validation error message injected into the prompt as additional context; (7) if the retry also fails, log the failure with the source record, migration map, and validation errors, then route to a dead-letter queue for human review. Do not silently drop records.

For observability, instrument the harness to emit metrics on migration success rate, retry rate, field-coverage delta (fields in source but not in output, and vice versa), and latency per record. Use structured logging to capture every migration attempt with a correlation ID that ties the source record, prompt version, model version, migration map version, and validation result together. This audit trail is essential for debugging migration failures and for compliance in regulated environments. When the migration map itself changes, treat it as a prompt version change and run regression tests against a golden dataset of known source records and expected target outputs before deploying the new map to production.

Model choice matters. Use a model with strong instruction-following and structured output capabilities (e.g., GPT-4o, Claude 3.5 Sonnet) for complex migrations involving nested field transformations or type coercion. For simple field-rename-only migrations, a smaller, faster model may suffice, but always validate the output programmatically regardless of model choice. Never rely on the model's self-reported confidence as the sole acceptance criterion. The harness, not the model, owns the final decision on whether a migrated record is valid and complete.