How to use AI to transform legacy API response schemas into modern typed structures

What this does

Legacy APIs often return flat JSON structures with inconsistent field names, untyped arrays, and ambiguous datetime formats. Modern frontend and backend codebases prefer strict TypeScript interfaces, Zod schemas, or Pydantic models that enforce types at runtime. This guide explains how to use an AI assistant to analyze sample legacy response payloads and generate modern typed structures that are drop-in replacements for the original parsing logic.

Steps

1. Collect and save the sample legacy responses into a JSON file (fixtures/legacy-responses.json), keeping each response type (success, error, paginated) as a separate top-level key.
2. Create a prompt for the AI that includes the sample payloads, the target typing library, and the desired naming conventions (e.g., camelCase for TypeScript, snake_case for Python).
3. Ask the AI to produce a complete typed structure: TypeScript interfaces with Zod schemas, or Python dataclasses with Pydantic models. Require that every field has a type and that arrays are typed with element schemas.
4. Review the generated types against the original payloads. Check that no fields are dropped and that all nested objects are represented.
5. Write a conversion function that parses the legacy JSON using the generated schema, catching validation errors and producing a clear message when a field is missing or has the wrong type.
6. Integrate the conversion function into the data access layer so all downstream code consumes the modern typed structure.
7. Add unit tests using the sample payloads to confirm the conversion works end-to-end.

Verification

# Verify Pydantic models parse all sample payloads without validation errors
python3 -c "
from pydantic import ValidationError
from schemas.legacy_converter import LegacyResponse
import json, sys
with open('fixtures/legacy-responses.json') as f:
    data = json.load(f)
for key, payload in data.items():
    try:
        result = LegacyResponse.parse(key, payload)
        print(f'OK: {key}')
    except ValidationError as e:
        print(f'FAIL: {key} - {e}')
        sys.exit(1)
"
# Expected: OK: success_response\nOK: error_response\nOK: paginated_response

Common failures

• Sample payloads do not cover all edge cases. The generated schema will be incomplete. Always include error responses, empty arrays, and null field cases in the sample file.
• Legacy fields use inconsistent types (string sometimes, integer other times). Pass a note to the AI specifying the union type to use (string | number) and ask it to add a validation helper.
• The AI generates a schema that is valid but diverges from the project's naming style. Add explicit style instructions to the prompt (e.g., "All keys must be snake_case") before regenerating.
• The conversion function loses information on fields that the legacy API sends but the schema ignores. Enable strict mode in Zod or Pydantic to surface unknown fields as errors rather than silently discarding them.
• Version mismatch - The installed package or runtime differs from the command shown; check the version first and rerun the smallest verification command.
• Local environment drift - Another service, virtual environment, model, or path is being used; print the active binary path and configuration before changing the guide steps.

Related guides

• Build a type-safe API client using an AI assistant that reads your OpenAPI spec
• Use AI to convert legacy comments into idiomatic framework documentation