Deprecation Notice Drafting Prompt for API Fields

This prompt is designed for developer relations engineers, API product managers, and platform teams who need to communicate a specific field-level deprecation to external or internal API consumers. The core job-to-be-done is transforming a technical deprecation decision—often a ticket or an internal spec change—into a structured, empathetic, and actionable communication that minimizes consumer friction, reduces support ticket volume, and provides a clear migration path. The ideal user has already made the decision to deprecate a field and possesses the technical details, such as the field path, the replacement field, and the planned timeline. The prompt requires this context to be provided as structured input.

Use this prompt when you have a single, well-defined field or a small, related set of fields to deprecate and you need to draft a notice for a developer blog, an email campaign, or an in-dashboard notification. It is particularly effective when the replacement is straightforward, such as a renamed field or a new enum value. The prompt's value lies in enforcing a consistent structure that includes a clear timeline, a side-by-side migration example, and a tone calibrated for a technical audience. For example, if you are deprecating user.firstName in favor of user.givenName, the prompt will guide the model to generate a notice with a concrete before-and-after code snippet, not just a vague instruction to 'update your code.'

Do not use this prompt for generating full API reference documentation, automated changelogs from a git diff, or internal engineering migration runbooks. It is not designed to analyze a schema diff to discover deprecations; it assumes the deprecation is a known fact. For high-risk or regulated contexts, such as deprecating a field used in financial transactions or healthcare data, the output of this prompt must be treated as a first draft that requires human review for legal and compliance accuracy. The prompt is a communication drafting tool, not a source of truth for the deprecation policy itself. After using this prompt, your next step should be to validate the generated notice against your internal deprecation policy and test the migration example yourself before publishing it to consumers.

Use the following prompt template to generate a structured, developer-friendly deprecation notice. The template is designed to produce a complete communication that includes the rationale, a clear timeline, a migration path with code examples, and a tone appropriate for maintaining trust with your API consumers. Before using it, gather the specific field path, the deprecated and replacement field names, the sunset date, and any relevant links to migration guides or changelogs.

codeCopy
You are a developer relations engineer for an API platform. Your task is to draft a clear, empathetic, and technically precise deprecation notice for an API field. The notice will be published in a developer changelog and emailed to affected consumers.

### INPUT
- **API Name and Version:** [API_NAME_AND_VERSION]
- **Deprecated Field Path:** [DEPRECATED_FIELD_PATH]
- **Replacement Field Path:** [REPLACEMENT_FIELD_PATH]
- **Deprecation Announcement Date:** [ANNOUNCEMENT_DATE]
- **Sunset Date (when the field will be removed or start returning errors):** [SUNSET_DATE]
- **Reason for Deprecation:** [REASON]
- **Link to Migration Guide:** [MIGRATION_GUIDE_URL]
- **Link to API Changelog:** [CHANGELOG_URL]

### CONSTRAINTS
- Write in a helpful, professional tone. Do not be alarmist.
- Clearly state the timeline with specific dates.
- Provide a concrete migration example showing the deprecated request/response and the new request/response.
- Explicitly state the breaking change date and what happens after that date (e.g., the field will return `null`, be removed, or cause a 400 error).
- Include a subject line suitable for an email.
- Do not invent features or timelines not provided in the input.

### OUTPUT_SCHEMA
{
  "email_subject": "string",
  "notice_body": "string (markdown formatted)",
  "migration_code_example": "string (markdown code block)",
  "key_dates": [
    {
      "event": "string",
      "date": "string"
    }
  ]
}

To adapt this template, replace each square-bracket placeholder with the concrete details from your API change. If the deprecation is non-breaking until the sunset date, ensure the CONSTRAINTS section reflects that by specifying the post-sunset behavior. For high-risk or widely-used fields, add a [CONSUMER_IMPACT_SUMMARY] placeholder and instruct the model to include a section on estimated consumer impact. After generating the notice, always have a human review it for technical accuracy and tone before publication.

This prompt is designed to be called from an internal developer portal, API changelog pipeline, or release automation system. The primary integration point is a schema diff event: when a field is marked deprecated: true in an OpenAPI spec or a GraphQL @deprecated directive is added, the system triggers this prompt with the field metadata, deprecation date, replacement guidance, and affected endpoint context. The prompt should not run on every schema change—only on newly detected deprecation annotations to avoid generating duplicate or stale notices.

Wire the prompt into an application harness that performs pre-generation validation and post-generation review. Before calling the model, validate that all required inputs are present: [FIELD_NAME], [API_VERSION], [DEPRECATION_DATE], [REPLACEMENT_GUIDANCE], and [AFFECTED_ENDPOINTS]. If any input is missing or the deprecation date is in the past, abort and log a structured error rather than generating a confusing notice. After generation, run the output through a schema validator that checks for required sections (timeline, replacement, migration example, contact link) and flags missing elements. For high-visibility APIs, route the draft to a human reviewer via a Slack notification or PR draft before publication. Log every generation with the input hash, model version, output, and review status for auditability.

Model choice matters for tone consistency. Use a model with strong instruction-following and developer-documentation fluency—GPT-4o or Claude 3.5 Sonnet are good defaults. Set temperature low (0.1–0.3) to reduce stylistic variance across notices. If your organization maintains a style guide or tone examples, include them in [TONE_EXAMPLES] as few-shot demonstrations. For teams publishing notices across multiple API products, cache the tone examples and brand constraints in a reusable prompt prefix to reduce token waste and improve consistency. Avoid using smaller or older models for this task—they tend to produce either overly casual language or robotic boilerplate that undermines developer trust.

Retry logic should be minimal. If the output fails schema validation, retry once with the validation errors appended to the prompt as [PREVIOUS_ERRORS]. If the second attempt also fails, escalate to a human writer rather than retrying indefinitely. Common failure modes include: omitting the migration code example, using vague timelines like 'soon,' failing to link to the replacement field's documentation, or generating a notice that sounds apologetic rather than informative. Your eval suite should include test cases for each of these failure modes, plus edge cases like fields with no direct replacement, fields deprecated across multiple API versions simultaneously, and fields used in webhook payloads where consumer impact is harder to assess.

For publication, integrate the validated output into your changelog CMS, developer email system, or API status page. If publishing to multiple channels, use the structured output fields ([MIGRATION_EXAMPLE], [TIMELINE], [REPLACEMENT_FIELD]) to format channel-specific versions rather than regenerating the entire notice. Store the generated notice alongside the schema change that triggered it so future audits can trace every deprecation communication back to its source diff. When the deprecation window closes and the field is removed, trigger a follow-up notice using a variant of this prompt with [NOTICE_TYPE] set to removal to close the communication loop with affected consumers.