JSON Schema Violation Self-Correction Prompt

Use this prompt when your application consumes a JSON payload that has already failed downstream schema validation. The typical user is an integration engineer or backend developer whose service receives data from an AI model, an external API, or an internal microservice, and that data is rejected by a strict schema validator. The job-to-be-done is not to generate new data, but to repair an existing, invalid payload so it can be ingested without manual intervention. This prompt is designed for a specific recovery loop: you have the original invalid JSON, the target JSON Schema, and the exact validator error message. You need a corrected payload that passes validation while preserving as much of the original semantic content as possible.

This prompt is not a general-purpose JSON fixer. Do not use it when you lack a formal schema to validate against, as the model will have no objective target for correction. It is also inappropriate for cases where the data loss risk is unacceptable without human review, such as financial transaction records or clinical data, unless a human-approval step gates the corrected output. Avoid using this prompt when the root cause is a systemic schema mismatch between two services; that requires a schema evolution or mapping solution, not a per-message repair. The ideal context is a high-volume data pipeline where a small percentage of records fail validation and manual repair is cost-prohibitive, but where a semantic-diff check can catch dangerous alterations before the corrected record proceeds.

Before wiring this into production, you must implement a harness that validates the corrected output against the original schema and performs a semantic-diff to detect dropped fields, altered enumerations, or changed data types that could corrupt downstream analytics. If the retry budget is exhausted or the semantic-diff flags a high-risk change, the record should be routed to a dead-letter queue for human review, not silently corrected. The next step is to copy the prompt template, insert your schema and error context, and build the validation loop described in the Implementation Harness section.

This prompt template is designed to be injected into a retry or self-correction loop when a downstream JSON Schema validator rejects a model-generated or ingested payload. It forces the model to act as a precise repair engine, not a creative writer. The template uses square-bracket placeholders for the three critical inputs: the invalid JSON, the target schema, and the exact validator error. The instructions are structured to prevent the model from dropping fields, altering data types silently, or introducing new keys that violate the schema. Use this prompt as the core of a recovery harness that validates the output before accepting it.

textCopy
You are a JSON repair specialist. Your task is to correct a JSON payload that failed validation against a provided JSON Schema.

## INPUTS
- Invalid JSON: [INVALID_JSON]
- Target JSON Schema: [TARGET_SCHEMA]
- Validator Error Message: [VALIDATOR_ERROR]

## CONSTRAINTS
1. Output ONLY the corrected JSON object. Do not include explanations, markdown fences, or any text outside the JSON.
2. Preserve all semantic data from the original payload. Do not drop fields unless they are explicitly disallowed by the schema and cannot be mapped.
3. If a required field is missing, infer a sensible default based on the field's type (e.g., empty string for string, 0 for integer, null for nullable types) and add a "_repair_note" field at the root level explaining the imputation.
4. If a field has the wrong data type, attempt to coerce it to the correct type (e.g., string "123" to integer 123). If coercion is impossible, use the type-appropriate default and note the coercion failure in "_repair_note".
5. If an enum constraint is violated, map the value to the closest valid enum member if unambiguous. If ambiguous, choose the first valid enum member and document the choice in "_repair_note".
6. Do not add any new keys that are not defined in the schema.
7. The "_repair_note" field must be an array of strings, each describing one repair action taken. If no repairs were needed, this field should be an empty array.

## TASK
Apply the constraints to the invalid JSON using the target schema and the validator error as guidance. Output the fully repaired JSON object.

To adapt this template for your environment, replace the placeholders with your actual data. The [INVALID_JSON] should be the raw string that failed validation. The [TARGET_SCHEMA] should be the complete JSON Schema object, not just a schema reference. The [VALIDATOR_ERROR] should be the exact error string from your validator library (e.g., ajv, jsonschema). For high-risk data pipelines, always run the model's output through the same validator before accepting it. If the repaired payload fails validation again, increment a retry counter and consider escalating to a human operator after a configured threshold, rather than looping indefinitely. The _repair_note field is critical for auditability; log it alongside the corrected payload so data engineers can review automated imputation decisions.

This prompt is designed to sit inside a retry handler—not as a first-pass generator. The typical integration point is a try/catch block around a JSON parsing or schema validation step. When jsonschema.validate() or an equivalent library raises a ValidationError, the harness captures the invalid JSON string, the exact error message, and the full JSON Schema definition. These three artifacts become the inputs to the prompt. The prompt is then invoked as a secondary model call, and its output must pass through the same validator before being accepted. This pattern decouples the primary generation logic from the repair logic, keeping the main prompt focused on its task while the recovery prompt handles schema compliance.

Validation and retry loop: The harness must enforce a strict retry budget—typically 2-3 attempts. After each corrected output, re-run the original schema validator. If the output still fails, feed the new error back into the prompt along with the previous attempt's output and the original invalid JSON. This gives the model a history of what it tried and why it failed. If the budget is exhausted, the harness should escalate rather than retry indefinitely: log the full failure trace, quarantine the record to a dead-letter queue, and optionally trigger a human review notification. For high-throughput pipelines, consider a circuit breaker that stops retries if the failure rate exceeds a threshold (e.g., 5% of records in a batch).

Semantic-diff check: Schema compliance alone is not enough. A model could satisfy the schema by silently dropping fields, coercing values to defaults, or fabricating placeholder data. After the corrected JSON passes schema validation, run a field-level diff against the original invalid payload. Compare every key present in the original against the repaired output. Flag any field that was present in the original but is missing or has a materially different value in the repair. This diff should be logged as structured metadata alongside the repair decision. If the diff reveals data loss above a configured tolerance, escalate for human review rather than silently accepting the loss.

Model choice and latency: Self-correction prompts benefit from models with strong instruction-following and JSON manipulation capabilities. For high-throughput ETL pipelines, prefer a fast, cost-effective model for the primary generation and reserve a more capable model (e.g., GPT-4, Claude 3.5 Sonnet) for the repair step only when failures occur. This keeps the happy path cheap and fast while investing compute only on the small fraction of records that fail validation. Log the model ID, latency, and token usage for every repair attempt to monitor cost and performance over time.

Audit and observability: Every repair attempt must produce an audit record containing: the original invalid payload, the schema version, the validator error, the corrected payload (if successful), the semantic-diff result, the retry count, the model used, and a timestamp. This audit trail is essential for debugging schema evolution issues, identifying upstream data quality problems, and demonstrating compliance in regulated pipelines. Do not discard the original invalid record—store it alongside the repair for post-hoc analysis. If your pipeline processes PII or sensitive data, ensure the audit log respects your data retention and redaction policies.