response-validation

name	response-validation
description	Validate API response structure and content. Detects schema drift, unexpected null values, and abnormal response sizes.

API response validation skill.

When to activate

• When an endpoint returns 2xx but the response content looks unexpected (wrong content type, empty body, unusual size)
• When the user asks to validate response format or schema

Check command

curl -s --max-time 10 <URL>

Capture the full response body for analysis.

Checks

1. Content-Type

Verify the response Content-Type matches what is expected. JSON APIs should return application/json. Use -i flag to see headers:

curl -s -i --max-time 10 <URL> | head -20

2. Valid JSON

If the endpoint is expected to return JSON, verify the body parses as valid JSON. Look for HTML error pages returned instead of JSON (common failure mode).

3. Expected fields

Compare the response structure against the last known structure stored in semantic memory (category: "response_schema"). Look for:

• Missing top-level fields that were previously present
• New unexpected top-level fields (informational, not an alert)

4. Null values

Check for null values in fields that were previously non-null. This can indicate upstream data pipeline failures.

5. Response size

Compare the response body size against the baseline from memory (category: "response_size"). Significant deviations (>50% smaller or >200% larger) may indicate issues.

MUST

• Show actual vs expected values when reporting issues
• Store the response structure in semantic memory (category: "response_schema") for future comparison
• Store the response size baseline in semantic memory (category: "response_size")

MUST NOT

• Alert on cosmetic differences (field ordering, extra whitespace)
• Alert on additional optional fields being added
• Flag response size changes for endpoints that return variable- length data (search results, paginated lists) without checking if the variance is normal