New fields are additive with defaults
Why it matters
Adding a required field without a default to an existing request schema is an immediate breaking change: every existing consumer who does not send the new field starts receiving 400 errors without any version bump or deprecation notice. iso-25010:2011 compatibility.interoperability and maintainability.modifiability are both violated — the API's stability promise is broken the moment a required field lands in production. The failure mode is insidious because it appears as a client error (400), making it look like the consumer sent a bad request when the real cause is a server-side contract change.
Severity rationale
High because adding a required field without a default immediately breaks all existing consumers without a version bump, causing silent client-side failures.
Remediation
Follow the additive-only rule within a version: every new request field must be optional with a sensible default. In Zod:
// Before -- adding a required field (BREAKING):
const OrderSchema = z.object({
items: z.array(ItemSchema),
shippingMethod: z.string(), // required, no default -- breaks existing clients
})
// After -- additive with default (safe):
const OrderSchema = z.object({
items: z.array(ItemSchema),
shippingMethod: z.string().default('standard'), // optional with fallback
})
The non-breaking rules: new optional request fields with defaults, new response fields (add only, never remove), new endpoints, new optional query parameters. Any change that removes, renames, or makes previously-optional fields required requires a major version bump.
DetectionPro
The detection method for this pattern is part of AuditBuffet Pro.
The full method (what to look for, pass and fail conditions, and how results get reported) ships inside the API Design Audit. The pattern definition, severity rationale, and remediation remain openly licensed under CC-BY-4.0.
External references
- iso-25010:2011 · compatibility.interoperability — Interoperability — additive-only changes prevent silent consumer breakage
- iso-25010:2011 · maintainability.modifiability
Taxons
History
- 2026-04-18·v1.0.0·Initial import from api-design·automated