skip to content

In a Postman collection's formdata body, what does an entry's type field mean, and what is contentType for?

level: middleimportance: should knowfreq 38%

answer

  1. The payload is a list of parts, not a string
  2. Each part says where its value comes from
  3. One part can label itself independently
  4. text is inline, file is a reference

basics

~10 s

A formdata entry declares type as text or file: text carries its value inline, file names a file to attach. An entry's contentType labels that one part of the form, not the whole request.

solid answer

~40 s

With `mode` set to `formdata`, the payload under `body.formdata` is a list of entries rather than one string. Each entry has a `key` and a `type` of `text` or `file`: a `text` entry carries its value inline in the document, while a `file` entry references a file rather than inlining its bytes. An entry may also carry its own `contentType`, and its scope is exactly that one part — it is not a default for the other entries and not the request's own declared `Content-Type`. `urlencoded` is the simpler neighbour: key and value text pairs, no attachments, no per-entry labelling. Pick `formdata` when a field carries a file or needs its own label; otherwise `urlencoded` is the smaller document and the smaller diff.

code

json · 7 lines
json
{
  "mode": "formdata",
  "formdata": [
    { "key": "note", "type": "text", "value": "monthly upload" },
    { "key": "report", "type": "file", "contentType": "text/csv" }
  ]
}

go deeper

for a junior

Be ready to say that a form body is a list of entries and that each entry's type is text or file. Knowing text is inline and file is a reference covers the screening version.

for a middle

Explain the scopes: type says where a part's value comes from, and contentType labels that one part only. Contrast it with urlencoded, whose entries are plain key and value text pairs.

for a senior

Show the operational consequence. File entries make a run depend on the filesystem it runs on, so a shared collection needs a story for where those files come from before anyone blames the server.

for a principal

Own the convention for shared collections: when attachments are allowed, how their sources are provisioned for every runner, and whether requests should prefer the simpler payload shape to keep documents and reviews small.

## A `formdata` payload is a list of parts When a stored request declares `mode` as `formdata`, its payload sits under `body.formdata` and is a **list of entries**, not a single string. Each entry is one part of the form: it carries a `key` — the field name — plus a declaration of what kind of value that field holds. The **collection format** declares these fields; the list is ordered as written. The two things worth knowing about an entry are its `type` and its `contentType`, and they answer different questions. ## `type`: is this part text, or a file? An entry's `type` is `text` or `file`, and it decides where the value comes from: - **`text`** — the entry carries its value inline, in the document. What you read in the file is what that part sends. - **`file`** — the entry names a file to attach rather than inlining its bytes. The document stays small and portable; the bytes live outside it. That difference has a practical consequence people meet the hard way. A `text` entry travels wherever the collection travels. A `file` entry travels as a reference, so a request that works on the machine that authored it can fail elsewhere for a reason that has nothing to do with the server: the referenced file simply is not there. When a form body "works locally and not on the shared runner", the entry types are the first thing to read. ## `contentType`: a label on one part An entry may also carry its own `contentType`. Its scope is exactly one part of the form body — the part it sits on — and nothing wider. It is not a default for the other entries, and it is not the request's own `Content-Type` header, which is declared in the header list and is a different statement about a different thing. This per-part labelling is the reason `formdata` exists as a distinct mode rather than as a variant of the simpler one. A form body can legitimately mix parts of unlike kinds — a short text field beside an attached document — and each part can say what it is on its own terms. ## `formdata` next to `urlencoded` | aspect | `urlencoded` | `formdata` | |---|---|---| | payload key | `body.urlencoded` | `body.formdata` | | entry shape | key and value text pairs | key plus a `text` or `file` entry | | per-entry `type` | not part of the entry | `text` or `file` | | per-entry `contentType` | not used — entries are text pairs | yes, labelling that one part | | can attach a file | no | yes | The choice between them is usually settled by one question: **does any field carry a file, or need its own label?** If yes, the payload is `formdata`. If every field is a short text pair, `urlencoded` is the simpler document and the simpler diff. ## Reading a form body in review 1. Confirm `mode` says `formdata` — the key alone proves nothing, because a payload key that `mode` does not name is inert. 2. Walk the entries and note each `key` and `type`. The `file`-typed entries are your portability risk. 3. Note any `contentType` and remember its scope is that entry only. 4. Read the request's header list separately. A header declared there is a statement about the request; an entry's `contentType` is a statement about one part. ## Common misreadings - Treating an entry's `contentType` as the request's content type. It is not; the two live in different places and describe different scopes. - Assuming a `file` entry embeds its bytes in the collection document. It does not — that is what keeps the document portable and what makes the reference a dependency. - Assuming `urlencoded` can carry an attachment if you set the right header. The shape is chosen by `mode`, not by a header. - Reading `type` as a validation rule — required, optional, string, number. It is a source declaration: inline value, or file reference. ## Where this subject stops How a server interprets a particular media type, and how it negotiates among several, is HTTP's own subject. How an API *description* declares a multipart payload and its encodings is a different artefact with different field names. How a test harness in another language turns an object into a payload belongs to that harness. What lives here is narrow and precise: `formdata` is a list of parts, each part declares `text` or `file`, and a part may label itself with its own `contentType`.

  • Why can a formdata request pass on the machine that authored it and fail on a shared runner?
    Because a `file`-typed entry references a file rather than inlining its bytes. The document travels; the bytes do not. On another machine the reference may point at nothing, and the request fails for a reason unrelated to the server. Text entries never have this problem, since their values live in the document.
  • When would you choose urlencoded over formdata for a request?
    When every field is a short text pair and nothing needs its own label. `urlencoded` entries are key/value pairs, so the document is smaller and diffs are easier to read. Reach for `formdata` only when a field carries a file or when parts of unlike kinds need labelling individually.

saying these in an interview costs you the question

  • Treats an entry's contentType as the request's content type
  • Thinks a file entry embeds the file's bytes in the document
  • Says urlencoded can attach a file with the right header
  • Reads type as a validation rule rather than a source declaration
  • Assumes one entry's contentType defaults the other entries