OpenAPI default Values: Convenient for Docs, Dangerous for Validation

Quick answer: A default in OpenAPI documents what a server or client may assume when a property is absent, but it is not a validation instruction and it does not guarantee the running system actually behaves that way. The field is primarily a hint to documentation and tooling: a generated client or a mock can fill the value in, but the real server has its own logic, and a stale default in the spec can describe behavior that no longer exists. The safe rule is to treat defaults as documentation, verify them against actual behavior, and never let a mock or client rely on a default that the server does not genuinely honor.

Defaults cause trouble precisely because they look authoritative. A schema says a page size defaults to 20, so a mock returns 20 and the client is built around it, but the server actually defaults to 25. Tests pass against the mock and fail in production. Or a generated client injects the default into the request, changing the wire payload from "field omitted" to "field explicitly set," which can alter how the server interprets it. The distinction between documenting a default and enforcing one is the crux of the problem.

What default does and does not mean

Clarifying the semantics up front prevents a class of integration bugs.

Question	Answer
Is default a validation rule?	No; it does not constrain values
Must the server apply it?	The spec cannot force the server
Do mocks use it?	Many generators fill it in
Do clients send it?	Some inject it, changing the request
Is it shown in docs?	Yes, that is its main purpose

Where defaults mislead

Two concrete patterns account for most of the damage, and both are testable.

A mock that honors a default the server does not

The mock fills in a value on an omitted field, so the client never sends it and assumes a specific response, while the real server uses a different default. The fix is to verify the documented default against the live API and keep the spec honest.

A client that injects the default explicitly

# schema documents a default for absent pageSize
pageSize:
  type: integer
  default: 20
  minimum: 1
  maximum: 100

# a generator that injects the default changes omission into an explicit value
// request the server sees when the caller omitted pageSize
// risky form: { page: 1, pageSize: 20 }   <- default injected
// safer form: { page: 1 }                 <- omission preserved

For a server that distinguishes "omitted" from "explicitly set," injecting the default changes semantics. Configure the generator to leave omitted fields absent unless the value is genuinely user-supplied.

Keep defaults truthful and minimal

Use defaults only where the behavior is real and stable, and prove it with a contract or a live check that sends the field omitted and asserts the response. A test that omits the field and verifies the actual defaulted value is the most direct guard against spec drift.

it("applies the documented default when pageSize is omitted", async () => {
  const res = await client.get("/v1/orders", { params: { page: 1 } });
  // request omits pageSize; assert the real server, not an assumed value
  expect(res.request.pageSize).toBe(20);
  expect(res.data).toHaveLength(20);
});

Keeping the spec in a local-first workflow and validating defaults against the live API in CI means a default is a verified fact rather than a hopeful annotation. When in doubt, document the behavior in prose and omit the default keyword rather than shipping a value that tools will act on and the server may not honor.

Frequently asked questions

Should I set a default on every optional field?

No. Only document a default where the server genuinely applies one and it is stable. Sprinkling defaults on optional fields gives mocks and clients behavior the server may not have.

What is the difference between default and example?

An example is illustrative sample data with no behavioral implication, while a default suggests a value used when the field is absent. Some tools act on defaults, so reserve them for real behavior.

Can a default be used for request bodies?

It can document what the server assumes for an absent request field, but the client should not assume the server applies it without verification. Prefer explicit values for fields that materially affect the result.

How do I stop a generated client from injecting defaults?

Check the generator's configuration; most have an option to control whether defaults are emitted. Keep omitted fields absent so the server's own logic determines the value.

This is part of the OpenAPI Guide — start there for the full picture of modeling contracts accurately.