In an OpenAPI document, how do you describe a multipart/form-data upload and what does encoding control?

## The shape of a multipart declaration Multipart bodies are not parameters. They are a `requestBody` with a `multipart/form-data` key in the `content` map, and their Media Type Object holds two things that matter: `schema` and `encoding`. The `schema` is an object. **Each property becomes one part**, and the part's `name` in its `Content-Disposition` header is the property name. So a schema with properties `metadata` and `file` produces a body with a `metadata` part and a `file` part. `required` on the schema marks which parts must be present. ## How a part's content type is chosen OpenAPI infers a default `Content-Type` for each part from the property's schema: - an **object** property defaults to `application/json` - a **binary** string defaults to `application/octet-stream` - other **primitives** default to `text/plain` - an **array** takes its default from the type of its items That inference covers the common cases: a JSON metadata part and an opaque file part need nothing extra. ## The encoding object When the inference is wrong or insufficient, the Media Type Object's `encoding` map takes over. It is keyed by **property name** — the keys must exist in the schema's `properties` — and each value may set: - **`contentType`** — the part's media type, overriding the inferred default. This is how you say the `avatar` part must be `image/png` or `image/jpeg` rather than generic octets. - **`headers`** — a map of additional headers for that part (`Content-Disposition` and `Content-Type` are excluded, being determined by the multipart rules and `contentType`). - **`style`**, **`explode`**, **`allowReserved`** — these mirror the query-parameter serialization keywords, and they apply when the body is `application/x-www-form-urlencoded`, not to multipart parts. Seeing them on a multipart encoding entry is a smell. ## Binary content, 3.0 versus 3.1 This is the version-sensitive part of the answer. In **OpenAPI 3.0** binary payloads are written as `type: string` with `format: binary` (and `format: byte` for base64-encoded text). In **OpenAPI 3.1** the Schema Object is full JSON Schema 2020-12, which has its own vocabulary for this: `contentMediaType` and `contentEncoding` describe the content of a string, and the 3.0 `format: binary` convention is superseded. 3.1 also lets a media type entry omit `schema` altogether, meaning the body is simply that media type's bytes. A candidate who states one spelling without noticing it is version-bound has missed the part of the question that interviewers are probing, because a 3.0 document run through 3.1 tooling is exactly where uploads break. ## Multiple files under one field An array-typed property means the part repeats: a schema property `files` of `type: array` with binary items produces several parts all named `files`. This is the standard way to describe a multi-file upload, and it is worth calling out because generated clients differ in whether they expose it as a list argument or as repeated single-file calls. ## What the declaration does and does not do The document describes the wire format so that generators, mock servers, request validators and documentation renderers agree. It does not enforce anything at runtime — a size limit, an allowed-extension list or a virus scan are server concerns, not spec fields. You can *document* a size limit in `description`, and some teams add `maxLength` on the schema, but no consumer of the document is obliged to enforce it. Interviewers listen for this distinction: a candidate who claims the spec restricts upload size has confused description with enforcement. ## Practical checklist - One `multipart/form-data` entry under `content`, object schema, one property per part. - `required` on the schema for the parts that must be present. - `encoding.<property>.contentType` wherever the inferred type is too loose to be useful to a client. - The binary spelling that matches your document's OpenAPI version, stated consistently across the whole document. - Array properties for repeated parts. - Remember the operation almost always needs `requestBody.required: true` as well — it defaults to `false`.