skip to content

File-Level Shape

3 roadmaps12 questions

Properties of the file as a whole: how its tree of entries nests and orders itself, which generation of the format an export was written in, and what an imported API definition turns into.

part ofAPI & DB clientsoverview, primer and where to startread it →
on this pageshow

explore

questions

12

In a saved Postman collection file, what makes an entry in `item` a folder rather than a request?

level: juniorimportance: must knowfreq 62%

answer

  1. Two kinds of entry, one array
  2. Look at what the entry carries
  3. A nested list, not a flag
  4. A request entry is a leaf
  5. SDK calls them Item and ItemGroup

basics

~10 s

A Postman collection entry is a folder when it carries its own item list instead of a request. One array holds both kinds, so folders nest inside folders with no separate structure.

solid answer

~40 s

The collection document declares a single recursive `item` array. Each entry in it is either a **request entry**, which carries a `request` object, or a **folder**, which carries its own `item` array instead. There is no separate folder table and no type flag: the presence of a nested `item` list is what makes the entry a folder, and because that nested list holds the same two kinds of entry, nesting is recursive to any depth. The SDK mirrors this — a request entry becomes an `Item`, a folder becomes an `ItemGroup`, and `Collection` is itself an `ItemGroup`, which is why the root and a folder behave alike. Both kinds carry a `name`, and both may carry `auth`, `event` and `variable`.

code

json · 23 lines
json
{
  "item": [
    {
      "name": "Sign in",
      "item": [
        {
          "name": "Login",
          "request": {
            "method": "POST",
            "url": "https://example.test/login"
          }
        }
      ]
    },
    {
      "name": "Health",
      "request": {
        "method": "GET",
        "url": "https://example.test/health"
      }
    }
  ]
}

go deeper

for a junior

Be ready to say, without hedging, that an entry is a folder when it carries its own item list and a request entry when it carries a request object.

for a middle

Explain that the array is recursive: a folder's list holds the same two kinds of entry, so the root and any folder are the same shape and take the same declarations.

for a senior

Show that you read collection files structurally — classifying entries by what they carry, and knowing that a walker recurses on the nested list rather than switching on names or depth.

for a principal

Own the consequence for tooling: any generator or transformer your team builds must treat the tree as recursive, because a one-level assumption breaks silently on the first nested folder.

## One array, two kinds of entry A **Postman collection** is a single JSON document. Below its `info` block, everything the collection contains lives in one array named `item`. That array is the whole tree: the requests, the folders, and the folders inside those folders are all entries in it, or entries in an `item` array nested inside one of its entries. There is no second array listing folders, no `folders` key, and no `type` discriminator on an entry. The document separates the two kinds **structurally**, by what the entry carries. ## What makes an entry a folder An entry is a **folder** when it carries its own `item` array. An entry is a **request entry** when it carries a `request` object instead. - Both kinds normally carry a `name`, the label a client displays and a runner reports. - A request entry's `request` holds the method, URL, headers and body for one call. - A folder's `item` holds more entries of exactly the same two kinds, which is what makes the structure recursive. - Both kinds may carry `auth`, `event` and `variable` — a folder is not a passive label, it is a place declarations can hang. - A folder can hold nothing: an empty `item` array is still a folder. - A request entry may carry `response`, its array of saved examples; a folder does not, because it has no request to exemplify. ## Recursion, and why the root behaves like a folder Because a folder's `item` array holds the same kind of entries as the collection's own `item` array, the two levels are the same shape. Depth is unbounded in the document's own terms: a folder inside a folder inside a folder is simply three nested `item` arrays. Nothing in the shape distinguishes level one from level five. The SDK makes that identity explicit. A request entry deserialises to an `Item`; a folder deserialises to an `ItemGroup`; and `Collection` is itself an `ItemGroup`. Code that walks a folder and code that walks the collection root are therefore the same code, and anything you can declare on a folder you can declare at the root. ## Folder entry versus request entry | Aspect | Folder | Request entry | |---|---|---| | Distinguishing key | carries `item` | carries `request` | | SDK type | `ItemGroup` | `Item` | | Children | more entries of the same two kinds | none | | May declare `auth` / `event` | yes | yes | | Saved examples (`response`) | no | yes | | What its position means | its whole subtree sits there | it sits there itself | ## Why the distinction matters in practice 1. **Reading a file or a diff.** To classify an entry, look for `item` versus `request` on that object. Nothing else in the entry tells you, so a reviewer skimming for a `type` value will misread the change. 2. **Generating a file.** A tool that emits an entry carrying neither key has produced something that is neither a folder nor a callable request, and no consumer can classify it. 3. **Writing tooling.** A walker must recurse when it sees `item` and stop when it sees `request`; it must not switch on a name, a depth counter or a flag. 4. **Placing declarations.** Because a folder is a real entry rather than a display grouping, moving a request into or out of one changes which entries are its ancestors — and ancestor-declared `auth` and `event` are found by walking up that chain with the SDK's `findInParents`. ## Common mistakes - Expecting a marker field that says "folder". The document has none; the shape is the marker. - Treating folders as a display convenience of a client rather than as structure carried by the file itself. - Assuming one entry could be both — carrying a `request` and nesting further entries under it. - Assuming nesting is limited to a single level, and writing a walker that only descends once.

  • Can one entry in a collection's `item` array carry both a `request` and a nested `item` list?
    No. An entry is one kind or the other: nesting lives on folders, which carry `item`, while a request entry carries `request` and is a leaf. A generator emitting both has produced an entry no consumer can classify, and nothing elsewhere in the document breaks the tie.
  • How deep can folders nest in a collection document?
    The shape imposes no limit — a folder's `item` array holds the same entries as the root's, so nesting is recursive. What limits depth in practice is legibility, plus the fact that each extra level adds another ancestor whose `auth` and `event` a descendant may inherit.

A folder entry is like a directory listing that happens to contain further listings; a request entry is a file at the end of a path.

saying these in an interview costs you the question

  • Claims a type field on the entry marks it as a folder
  • Says folders are display-only and carry no declarations
  • Believes a separate folders array lists the folders
  • Says one entry can hold both a request and nested items
  • Assumes nesting is limited to a single level
open as a page

In a Postman collection file, what determines the order of the entries inside a folder?

level: middleimportance: must knowfreq 52%

basics

~10 s

Order is position in the item array and nothing else. A collection document carries no ordering key beside its entries, so reordering means moving the JSON object itself.

open as a page

In an older-generation Postman collection export, how were the requests and their display sequence stored?

level: middleimportance: must knowfreq 62%

basics

~20 s

An older export kept every request in one flat list and expressed sequence in sibling arrays of identifiers: order for the requests, and folders_order for the folders. Sequence was data alongside the content, not position within it.

open as a page

In a Postman collection imported from OpenAPI, why do request values look faked while saved examples do not?

level: middleimportance: must knowfreq 50%

basics

~10 s

The converter treats the two sides differently: requestParametersResolution defaults to Schema, so request values are faked from types, while exampleParametersResolution defaults to Example, so saved examples reuse the definition's own example values.

open as a page

When Postman imports an OpenAPI definition, what does the converter's folderStrategy option decide?

level: middleimportance: must knowfreq 58%

basics

~20 s

folderStrategy tells Postman's OpenAPI converter how to group generated requests into folders: one folder per URL path, or one folder per tag an operation declares. The definition carries no folder tree, so the importer invents one.

open as a page

In a saved Postman collection file, which field identifies the generation of the collection format used?

level: juniorimportance: should knowfreq 40%

basics

~20 s

The info block's schema field holds a URL naming the collection format generation the export was written against. Reading that URL is how any tool, or any reviewer, decides which structural shape to expect from the rest of the file.

open as a page

In a Postman collection generated from an OpenAPI definition, where do the request names come from?

level: juniorimportance: should knowfreq 42%

basics

~10 s

Request names in an imported collection come from the converter's requestNameSource option. Its default takes the operation's human-readable summary text and falls back to the operation's identifier when no summary exists.

open as a page

How does a request nested inside folders in a Postman collection reach `auth` or `event` declared on an ancestor?

level: middleimportance: should knowfreq 45%

basics

~10 s

Because entries nest, a folder is an ancestor of everything inside it. The SDK locates an ancestor-declared auth or event by walking up the parent chain from the entry with findInParents.

open as a page

In an older Postman collection export, how were tests and preRequestScript stored, and how are they converted?

level: middleimportance: should knowfreq 44%

basics

~20 s

An older export stored each script as one plain string under tests or preRequestScript. The collection transformer's converter-v1-to-v2.js splits that string on newlines into an event entry whose script.exec array holds one line per element.

open as a page

What behaviour can change in a Postman collection when a tool sorts or re-nests entries in `item`?

level: seniorimportance: should knowfreq 32%

basics

~10 s

Two things, neither visible as a field diff: order is array position, so sorting rewrites the declared sequence, and nesting decides ancestors, so a move changes which folder auth and event a request inherits.

open as a page

Your repository holds a years-old exported Postman collection; how do you upgrade it and verify nothing was lost?

level: seniorimportance: should knowfreq 36%

basics

~20 s

Read the file's declared generation first, convert it with the collection transformer rather than by hand, then review the conversion as a diff and re-run the collection, checking that every old script string reappears as exec lines.

open as a page

When an OpenAPI operation offers several media types, what does Postman's importer put in the request body?

level: seniorimportance: should knowfreq 36%

basics

~20 s

One body only. A collection request holds a single body in a single mode, so an operation offering several media types loses all but one on import, and preferredRequestBodyType is the converter option deciding which survives.

open as a page