Required Field Addition Impact Prompt

This prompt is for API platform engineers, backend developers, and technical product managers who need to assess the downstream impact of adding a new required field to an existing API request schema. The job-to-be-done is producing a structured impact analysis that identifies every client integration that will break, evaluates default-value strategies, flags conflicts with partial-update (PATCH) semantics, and recommends a rollout sequence. Use this prompt when you have a concrete schema change proposal, access to the current OpenAPI or GraphQL specification, and a list of known internal and external consumers. The output should feed directly into an architecture decision record, a migration plan, or a breaking-change communication to consumers.

Do not use this prompt for general API design brainstorming, for changes that are purely additive (new optional fields), or for assessing endpoint removal or type changes—those scenarios have their own dedicated playbooks in this pillar. This prompt is also insufficient when you lack consumer inventory data; the analysis quality depends on knowing which clients call the affected endpoints and how they deserialize responses. If consumer usage data is unavailable, pair this prompt with the API Consumer Impact Analysis Prompt first to build the consumer surface map, then return here for the required-field-specific assessment. For high-risk production APIs where a breaking change could cause revenue loss or regulatory exposure, always route the final output through human review and require explicit sign-off before implementation.

The prompt template below expects several inputs: the current API specification, the proposed change (field name, type, location, new required constraint), a consumer inventory, and any existing deprecation or versioning policies. The output schema is a structured impact report with severity classification per consumer, default-value options with trade-offs, PATCH endpoint conflict analysis, and a phased rollout recommendation. Before using this prompt in a CI/CD gate or automated pipeline, build a regression test suite with known breaking and non-breaking changes to calibrate false-positive and false-negative rates. The eval criteria should check that every listed consumer is addressed, that default-value strategies account for null-vs-absent distinctions, and that the rollout sequence does not strand any consumer without a migration window.

This prompt template is designed to produce a structured impact analysis when an API team proposes adding a required field to an existing request schema. It forces the model to reason about client breakage, default value strategies, partial-update endpoint conflicts, and rollout sequencing before generating a report. Use this template as the core instruction set in your AI coding agent or review pipeline, adapting the placeholders to your specific API context.

textCopy
You are an API compatibility analyst. Your task is to evaluate the impact of adding a required field to an existing API request schema.

## Input
- **Schema Diff:** [SCHEMA_DIFF]
- **Affected Endpoints:** [AFFECTED_ENDPOINTS]
- **Known Consumers:** [KNOWN_CONSUMERS]
- **Current Default Behavior:** [CURRENT_DEFAULT_BEHAVIOR]
- **Rollout Constraints:** [ROLLOUT_CONSTRAINTS]

## Analysis Requirements
1. **Client Breakage Assessment**
   - Identify every client integration that will break if the field is made required without a default.
   - Classify breakage severity: `BLOCKING` (request rejected), `SEMANTIC` (field missing causes incorrect behavior), or `NONE` (client already sends the field).

2. **Default Value Strategy**
   - Propose a default value if one is feasible. Evaluate the default against these criteria:
     - Does it preserve existing behavior for clients that omit the field?
     - Does it risk data corruption or incorrect processing?
     - Is it distinguishable from an intentionally-set value?
   - If no safe default exists, state why explicitly.

3. **Partial-Update Endpoint Conflict Check**
   - For each endpoint that supports `PATCH` or partial updates, determine whether the new required field creates a conflict.
   - Flag any endpoint where a partial update could fail because the field is absent from the stored resource.

4. **Rollout Sequencing**
   - Propose a phased rollout plan with these stages (skip any that don't apply):
     - **Stage 0: Optional with default** (backward-compatible, no client changes required)
     - **Stage 1: Optional with deprecation warning** (clients warned but not broken)
     - **Stage 2: Required with default** (new clients must send; old clients get default)
     - **Stage 3: Required without default** (breaking change, all clients must migrate)
   - For each stage, specify the minimum duration and the trigger for advancing to the next stage.

5. **Migration Guidance per Consumer**
   - For each known consumer, provide specific migration steps, estimated effort, and the latest stage they must complete migration by.

## Output Format
Return a JSON object with this exact schema:
{
  "analysis_id": "string",
  "breaking_change": true|false,
  "client_breakage": [
    {
      "consumer": "string",
      "severity": "BLOCKING|SEMANTIC|NONE",
      "explanation": "string"
    }
  ],
  "default_value_strategy": {
    "feasible": true|false,
    "proposed_default": "string|null",
    "risks": ["string"],
    "distinguishable_from_intent": true|false
  },
  "partial_update_conflicts": [
    {
      "endpoint": "string",
      "conflict": "string",
      "mitigation": "string"
    }
  ],
  "rollout_plan": [
    {
      "stage": 0|1|2|3,
      "description": "string",
      "min_duration": "string",
      "advance_trigger": "string"
    }
  ],
  "consumer_migration": [
    {
      "consumer": "string",
      "steps": ["string"],
      "estimated_effort": "string",
      "deadline_stage": 0|1|2|3
    }
  ],
  "risk_summary": "string"
}

## Constraints
- Do not assume clients will update immediately. Always include a transition period.
- If the field collects PII or sensitive data, flag it in `risk_summary`.
- If the field changes business logic (not just validation), escalate the severity.
- If no consumers are provided, state that the analysis is incomplete and recommend consumer discovery before proceeding.

After copying this template, replace each square-bracket placeholder with real data from your API gateway logs, client registries, and schema registries. If you lack consumer data, run a consumer discovery step first—this prompt will flag incomplete input rather than guessing. For high-risk APIs (payments, health, auth), add a [RISK_LEVEL] parameter and route the output to a human reviewer before any rollout decision. Wire the output JSON into your CI pipeline as a gating check: if breaking_change is true and no rollout plan exists, block the merge.

This prompt is designed to be called programmatically as part of a schema review or CI/CD gate, not as a one-off chat interaction. The core integration pattern is: detect a diff in an OpenAPI or protobuf specification, extract the change context, hydrate the prompt template, call the model, parse the structured output, and feed the results into a review queue or automated check. The prompt expects a specific input shape—the field definition, the endpoint context, and the existing consumer surface—so your harness must assemble these from your API registry, linting tools, or gateway logs before invoking the model.

Input Assembly: Use a spec diff tool (e.g., openapi-diff, buf breaking) to detect that a field has been added and marked as required. Extract the full field schema, the parent request body or parameters object, the endpoint's HTTP method and path, and a list of known consumers from your API gateway or developer portal. If consumer data is unavailable, the harness should flag this as a limitation in the output rather than silently omitting it. Model Choice: Use a model with strong structured output support (GPT-4o, Claude 3.5 Sonnet, or Gemini 1.5 Pro) and enforce JSON mode or function calling with the impact_assessment schema. Set temperature=0 for deterministic, reviewable output. Validation and Retries: Parse the model's JSON output and validate it against the expected schema. If validation fails, retry once with the validation error appended to the prompt as a correction hint. If the second attempt fails, escalate to a human reviewer with the raw output and error details. Logging and Audit: Log the full prompt, model response, parsed output, and validation result to your observability platform. Tag each run with the spec version, change ID, and reviewer so that every impact assessment is traceable to a specific schema change.

Integration Points: Wire this prompt into your pull request workflow for spec repositories. When a PR modifies an OpenAPI file, run the spec diff, detect required-field additions, and invoke the prompt. Post the structured impact analysis as a PR comment and block the merge if the risk score exceeds a configurable threshold (e.g., HIGH). For teams without automated spec repositories, integrate with your API gateway's schema registry or a manual review form that hydrates the prompt from a structured input UI. What to Avoid: Do not use this prompt for runtime request validation—it analyzes schema design intent, not live traffic. Do not skip the consumer surface assembly step; an impact analysis without consumer context is a syntax check, not a risk assessment. Do not treat the model's output as an automated approval; always require human sign-off for HIGH or CRITICAL risk findings before the schema change proceeds to implementation.