Deprecated endpoints/fields marked

Deprecated endpoints marked only in code comments — "legacy, use the new path" — are invisible to consumers reading the API schema or watching response headers. Tooling that scans for deprecated fields (OpenAPI linters, SDK generators, custom contract tests) cannot find what is not formally marked. iso-25010:2011 compatibility.interoperability is the direct casualty: consumers have no automated way to discover they are using a path scheduled for removal, and the migration window effectively starts the day removal happens rather than the day deprecation was intended.

Mark deprecated elements formally in the schema and in response headers, not only in code comments:

# OpenAPI -- deprecated endpoint with removal date:
/api/users/search:
  get:
    deprecated: true
    description: "Use GET /api/users?q= instead. Will be removed 2026-07-01."

# GraphQL -- deprecated field:
type User {
  fullName: String
  name: String @deprecated(reason: "Use fullName instead")
}

For REST, also add HTTP headers on every response from deprecated endpoints: Deprecation: true and Sunset: Sat, 01 Jul 2026 00:00:00 GMT. Tooling like spectral can enforce that all deprecated schema elements include a reason and a sunset date.