Schema Version Migration Repair Prompt

This prompt is for platform and integration engineers who maintain API contracts that evolve over time. The job-to-be-done is migrating an AI-generated structured output that was produced for an older schema version (v1) into a payload that conforms to a newer schema version (v2). You use this prompt when your inference pipeline has a cached response, a stored completion, or a queued message that was valid under a previous contract but will be rejected by the current downstream parser, database, or API gateway. The prompt takes the original output, the old schema, the new schema, and a migration specification that defines field renames, structural changes, and new required fields with their safe defaults.

Do not use this prompt when the original output is semantically incorrect or hallucinated—this is a structural migration, not a content repair. If the v1 output contains factual errors, missing citations, or low-confidence fields, route it through a separate repair or escalation prompt first. Also avoid this prompt when the schema change is so large that a full regeneration from source context would be more reliable than a migration; the prompt works best for incremental contract changes such as renaming customer_id to account_id, moving address from a flat field to a nested location object, or injecting a new version field with a constant default. The reader is expected to have both schema versions and a migration spec ready before invoking this prompt.

Before wiring this into production, define your validation step: the migrated output must pass the v2 schema validator. If it fails, the retry loop should feed the validation errors back into the prompt with the original v1 output still available as context. Set a hard retry budget—typically 2 attempts—because structural migrations are deterministic and repeated failures indicate a migration spec mismatch, not a model error. Always log the migration diff for auditability, and if the prompt cannot produce valid v2 output after the retry budget, escalate to a human with the original payload, both schemas, and the failed migration attempts.

This prompt template is designed for platform teams evolving API contracts. It takes a structured payload generated for an older schema version and migrates it to a newer version by renaming fields, restructuring nested objects, and injecting new required fields with safe defaults. The template is self-contained and can be copied directly into your repair harness or retry loop. All dynamic inputs are represented as square-bracket placeholders that your application must populate before sending the request to the model.

textCopy
You are a schema migration repair agent. Your task is to transform a structured output that was generated for an older schema version into a payload that conforms to a newer schema version.

## MIGRATION SPECIFICATION
[MIGRATION_SPEC]

## SOURCE PAYLOAD (OLD SCHEMA)
[SOURCE_PAYLOAD]

## OUTPUT SCHEMA (NEW VERSION)
[OUTPUT_SCHEMA]

## INSTRUCTIONS
1. Parse the SOURCE PAYLOAD and identify all fields, nested objects, and arrays.
2. Apply the MIGRATION SPECIFICATION to rename fields, restructure nested objects, and add or remove fields as specified.
3. For any new required fields in the OUTPUT SCHEMA that have no corresponding source data, inject a safe default value based on the field type:
   - String: empty string ""
   - Number: 0
   - Boolean: false
   - Array: empty array []
   - Object: empty object {}
   - Nullable: null
4. Preserve all semantic content from the SOURCE PAYLOAD. Do not drop or alter data unless the MIGRATION SPECIFICATION explicitly requires it.
5. Validate the migrated payload against the OUTPUT SCHEMA. If any required field is still missing after applying defaults, flag it in the migration report.
6. Output a JSON object with two top-level keys:
   - "migrated_payload": the fully migrated and validated payload
   - "migration_report": an object containing:
     - "fields_renamed": array of {old_name, new_name} for each renamed field
     - "fields_added": array of field names that were injected with defaults
     - "fields_removed": array of field names that were dropped per the migration spec
     - "defaults_applied": array of {field, default_value, reason} for each injected default
     - "warnings": array of strings describing any issues that could not be resolved
     - "confidence": one of "high", "medium", or "low" indicating overall migration confidence

## CONSTRAINTS
- Do not modify the OUTPUT SCHEMA itself.
- Do not invent data for new required fields beyond safe type-appropriate defaults.
- If the MIGRATION SPECIFICATION is ambiguous for a particular field, apply the most conservative interpretation and flag it in warnings.
- If the SOURCE PAYLOAD contains fields not mentioned in the MIGRATION SPECIFICATION, preserve them unless the OUTPUT SCHEMA prohibits additional properties.
- Return only valid JSON. No markdown fences, no commentary outside the JSON object.

To adapt this template for your environment, replace each square-bracket placeholder with the appropriate content before sending the request. [MIGRATION_SPEC] should contain a clear, structured description of every field rename, structural change, and new field requirement. This can be a JSON object mapping old paths to new paths, a natural-language changelog, or a structured diff. [SOURCE_PAYLOAD] is the original structured output that failed validation against the new schema. [OUTPUT_SCHEMA] is the target JSON Schema, TypeScript interface, or Pydantic model definition that the migrated payload must satisfy. For high-risk migrations involving financial, healthcare, or compliance data, always route the migration_report with confidence below "high" to a human reviewer before accepting the migrated payload into downstream systems.

The Schema Version Migration Repair Prompt is designed to sit inside a post-generation repair loop, not as a standalone endpoint. After a model produces output against an older schema version, your application should validate that output against the expected current schema. If validation fails with errors indicating version drift—such as missing required fields, renamed properties, or structural mismatches—the harness routes the invalid payload and the migration specification into this repair prompt. The prompt returns a migrated payload that must pass validation against the new schema before the application accepts it.

Wire the prompt into a retry pipeline with a strict budget. On the first validation failure, extract the error messages and compare them against your known migration spec. If the errors match expected version-change patterns, call the repair prompt with [ORIGINAL_OUTPUT], [CURRENT_SCHEMA], and [MIGRATION_SPEC]. Validate the repaired output against [CURRENT_SCHEMA] using a JSON Schema validator like Ajv or Pydantic. If validation passes, log the repair event with the original and migrated payloads for audit. If validation fails again, increment a retry counter and re-invoke the repair prompt with the new validation errors appended to [PREVIOUS_ERRORS]. Stop after three attempts and escalate to a human review queue with the full repair history.

Critical safety checks must run before accepting any migrated output. Compare the semantic content of the original and migrated payloads using a field-level diff. If the repair prompt injected defaults for new required fields, flag those fields for downstream consumers so they know the values were not present in the original data. For high-risk domains such as finance, healthcare, or legal, require human approval on any migration that modified more than a configurable percentage of fields or injected defaults into required fields. Log every migration attempt—successful or failed—with the model version, prompt version, migration spec version, and validation result for observability and debugging. Never silently accept a repaired payload without validation, and never retry indefinitely.