ReferenceIntermediate4-6 min reference
API Schema Validation
Asserting an exact value (status === "active") is brittle; asserting the shape (status is one of a known enum, id is a UUID, total is a number) is robust and catches whole classes of regressions. This sheet is the quick reference for schema-based assertions and the drift they catch. For the spec format itself, see the OpenAPI / Swagger sheet.
What a schema check covers
| Dimension | Example assertion |
|---|---|
| Presence | required: ["id", "email", "createdAt"] |
| Type | email is string, total is number, items is array |
| Format | string with format: email / uuid / date-time |
| Enum | status ∈ ["active","pending","closed"] |
| Range | minimum, maximum, minLength, maxLength |
| Nullability | field may be null vs must be present |
| No extras | additionalProperties: false catches leaked fields |
JSON Schema keywords worth knowing
| Keyword | Means |
|---|---|
required | Fields that must exist |
type | string number integer boolean object array null |
enum | Allowed value set |
format | Semantic string format |
additionalProperties: false | Reject unexpected fields (drift!) |
$ref | Reuse a shared schema |
oneOf / anyOf | Polymorphic / union shapes |
What it catches that value-assertions miss
- A new field leaking PII into the response (
additionalProperties: false). - A type silently changing (
"123"string vs123number) after a refactor. - A required field disappearing on one code path.
- An enum gaining an undocumented value — contract drift between spec and code.
Common mistakes
- Asserting one exact value instead of the shape (brittle, low coverage).
- Allowing
additionalProperties, so leaked/extra fields pass silently. - Validating only
200bodies — error bodies have schemas too. - Letting the schema and the OpenAPI spec diverge; generate one from the other.
// Related resources