Value Provenance

## What a generated placeholder is A **generated placeholder** is a token you write into a Postman request whose value is *manufactured* while the request is being assembled, instead of being read out of something you saved earlier. The collection SDK ships a small family of them under a dollar-prefixed naming convention — `$guid`, `$timestamp`, `$isoTimestamp` and `$randomInt` — and you use one by writing it exactly like any other token: `{{$guid}}` in a URL, a header value, or a request body. When the request is built, a function answers that name and hands back a value. No key holding that value existed before the send, and none exists afterwards. That is the whole distinction this corner of the tool draws. A **stored** value has *provenance*: somebody typed a key and a value into a scope, the pair lives in a file or in the run's memory, and every read returns what was put there. A **generated** value has no key at all. It is produced, used once, and forgotten. ## The family the SDK registers - `$guid` — a fresh UUID per evaluation; the usual choice for a correlation identifier or an idempotency key. - `$timestamp` — the current clock reading as a Unix epoch value in seconds. - `$isoTimestamp` — the current instant in UTC, formatted as an ISO-8601 string. - `$randomInt` — a random integer. All four are registered by the SDK as **defaults** for substitution, and that registration is also what fixes their priority — covered below. ## Stored versus generated, side by side | | Stored variable | Generated placeholder | |---|---|---| | Where the value lives | a key and value in a scope | nowhere; a function produces it | | When it is produced | when you or a script set it | while the request is assembled | | Same value twice? | yes, until something changes it | no, each evaluation stands alone | | Visible in the saved file | as the key and value you saved | only as the literal token text | | Survives the run | yes, the scope keeps it | no, nothing is written back | ## Every occurrence is its own evaluation This catches people out more than anything else about the family: 1. Two `{{$guid}}` tokens in the *same* request are two evaluations and yield two different UUIDs. If a server wants one identifier echoed in a header and in the body, one generated token cannot supply both — capture the value into a variable once and reference that variable in both places. 2. Two iterations of the same request are two evaluations. Nothing carries over from the previous one. 3. Re-opening the collection tomorrow changes nothing about the file: the saved request still holds the literal token text, never yesterday's UUID. ## Registered as defaults, consulted last The generators are not privileged. They are registered as **substitutor defaults**, which means substitution first asks the variables the run actually holds and only falls through to a default when nothing held answers that name. The practical consequence is worth stating plainly: **a variable whose key is literally `$timestamp` shadows the `$timestamp` generator**, and `{{$timestamp}}` then returns that saved value on every send, silently. Nothing errors and nothing warns. If a placeholder that should change stops changing, that collision is the first thing to look for. ## Where generated values fit — and where they do not - **Good fit:** correlation and idempotency headers, unique e-mail addresses or usernames so a repeated registration run does not collide, cache-busting query parameters, any body field the server needs only to be unique. - **Poor fit:** anything you must also assert on. A check comparing a response field against an expected constant cannot expect a value invented microseconds earlier, unless the script captured what was sent. - **Poor fit:** anything that must be byte-identical across two requests without an explicit capture step in between. - **Meaningless:** a generated token pasted into a saved example — the example records text, and the value it stood for never existed as data. ## What this is not A generated placeholder is **not** a hidden variable: it never shows up in a variable list, it cannot be exported, and there is no seed you can pin to make a run reproduce yesterday's values. Nor is the subject the same as *how a token is expanded at all* — the pattern that recognises a brace token, the repeated passes that let a nested token resolve, and the fate of a token nobody answers are a separate mechanism with its own rules. This material is about **where the answer comes from** once something does answer: a saved value with provenance, or a function with none.