Skip to main content
A sandbox response is built from the spec, never invented. When the spec says nothing about a value, the sandbox falls back through a fixed list of sources and tells you which one it used. The point is that a client which reads the body, not just the status, meets values it would accept from the real provider.

​
Source order

For every field in a response, the first source that applies wins:
  1. A recording. When the agent has recorded the real provider answering this request, the recorded response is served, or shapes the created resource, before anything below is consulted. Every such field is noted recorded. Redaction tokens in it are served as stored, never un-redacted. See Precedence.
  2. The request. A field the caller sent with the same name is echoed back. amount: 5000 in the request is amount: 5000 in the response.
  3. The spec’s example or default on that property.
  4. An enum member declared for the property.
  5. A format: date-time, email, uuid, uri and the rest produce a value of that shape.
  6. A naming convention, listed below.
  7. A seeded random value. A dictionary word for strings, a number in range, a coin flip for booleans.
Every choice is deterministic under the sandbox seed, so the same request on the same sandbox answers the same bytes.

​
Conventions

Applied only when a recording, the request, an example, an enum or a format has not already decided the value. Names are matched after converting camelCase to snake_case, so createdAt and created_at are the same field. The id of a created resource is the key the store filed it under, so reading it back by that id works. When the spec types id as an integer, the key is numeric.

​
Validation

required fields and declared types on the request schema are enforced on create and modify, through $ref. Two fields are never required on input: id, which the sandbox assigns, and any property the spec marks readOnly: true. When the spec declares nothing, nothing is enforced and the sandbox does not invent a requirement; a rule can supply it.

​
Seeing where a value came from

requests --explain prints one synth line per field the sandbox had to choose:
The request fields won over the conventions for amount and currency, status came from the spec’s enum, and the store key replaced the synthesised id so the resource can be read back.

​
The realism line

import and sandbox list print how many response fields would still fall through to a random word:
A spec with hundreds of undocumented string fields prints a large number and the first three names. The number goes down as the spec gains examples, as rules supply values, and as the sandbox learns from recorded traffic. It is the first measure of how truthful a sandbox is; the second is scored against what the provider actually sent, once the agent has recorded some. See Truthfulness.