fastapi-response-contract-boundarylisted

# FastAPI Response Contract Boundary Use this skill to keep strict FastAPI response models without letting old or external data crash user-facing endpoints. ## Workflow 1. Reproduce with the real API first. - Create or identify a real row that triggers the endpoint. - Capture the HTTP status and backend traceback. - If test data is created, clean it through the public deletion path and verify database counts. 2. Check official docs before code edits. - FastAPI response model validation/filtering behavior. - Pydantic v2 model validation, field defaults, and validators. - SQLAlchemy/ORM serialization docs only when the fix touches ORM loading or mapped attributes. 3. Locate the contract boundary. - Input schema: rejects invalid new writes. - Stored data: may contain legacy or externally written JSON. - Service serializer: should normalize legacy stored data before FastAPI validates the response. - Response schema: should remain strict unless the product contract truly changed. 4. Do not "fix" by removing `response_model`. - A 500 from `ResponseValidationError` is a useful release gate. - Keep strict response models and make returned data conform to them. - Prefer one service-level normalizer over scattered endpoint patches. 5. Normalize legacy JSON deliberately. - Fill missing required response fields with explicit safe defaults such as `target_window`, `legacy_signal`, or `unknown`. - Drop or coerce invalid optional fields su