Terminal
Terminal/Skill
Reference for the YAML file format Postman collections use on disk, with one file per request, folder, and example.
By Postman
Works with
npx skills add postmanlabs/postman-plugin --skill collection-schema-v3A v3 collection is a directory tree under postman/collections/, one file
per entity — every request, every folder's metadata, every saved example is
its own file. There is no single collection.json to open and edit; the
directory structure itself is the collection.
postman/collections/
bookstore api/
.resources/
definition.yaml (optional)
get all books.resources/
examples/
200 OK.example.yaml
400 Bad Request.example.yaml
500 Internal Server Error.example.yaml
get all books.request.yaml
get-book-by-id.request.yaml
add new book.request.yaml
authentication/
.resources/
definition.yaml (optional)
signup.request.yaml
login.request.yaml
postman/collections/ is a collection; it can contain
subfolders and requests..resources/ directory — an optional
metadata directory for that scope. .resources/definition.yaml holds the
collection/folder's own metadata; request examples live under
.resources/<request-name>.resources/examples/..resources/ directory — those are
metadata-only..resources/definition.yaml)Optional metadata for a collection or folder:
$kind: "collection" — required, even for a folder's definition.name — optional, defaults to the filesystem folder name.description — optional.variables — array of {key, value, description?, disabled?}. value
must be a string; disabled a boolean.auth — a single auth object {type, credentials: [{key, value}, ...]},
or an array for multiAuth: [{id, name, type, credentials, rules?}, ...].scripts — array of {type, code, language: "text/javascript"}. type
is one of http:beforeRequest, http:afterResponse,
graphql:beforeQuery, graphql:afterResponse, grpc:beforeInvoke,
grpc:onIncomingMessage, grpc:afterResponse.order — number, used for folder ordering.*.request.yaml)$kind: "http-request" — required.name — optional (see naming rules below for when to include it).order — number; only used for relative comparison, so space values out
(e.g. multiples of 1000) rather than packing them tight — a later
insertion between two requests shouldn't force renumbering every sibling.url — string, with {{varName}} variable syntax.method — GET|POST|PUT|DELETE|PATCH|HEAD|OPTIONS.headers — array of {key, value, description?, disabled?}.queryParams — array of {key, value, description?, disabled?}.pathVariables — array of {key, value, description?}.body — {type, content}; type required whenever body is present.
json, formdata, urlencoded, text, xml, html,
javascript, file, none.json/text/xml/html/javascript: content is a string.formdata: content is an array of
{key, type: "text"|"file", value or src, contentType?, description?}.urlencoded: content is an array of {key, value, description?}.auth — {type, credentials}.settings —
{protocolVersion?, strictSSL?, followRedirects?, maxRedirects?, disabledSystemHeaders?}.scripts — array of {type: "beforeRequest"|"afterResponse", code, language: "text/javascript"}.examples — optional, a relative path to the examples directory, e.g.
./.resources/<request-name>.resources/examples/.*.example.yaml)$kind: "http-example" — required.name — optional.request: {url, method}.response: {statusCode, statusText, headers: [{key, value}], body: {type, content}}.order — optional.Saved examples are what collection ai-readiness checks for — a request
with no examples scores worse for agent consumption even if perfectly
valid structurally.
postman/environments/*.environment.yaml)Environment files are v3 YAML but are not collection entities: they do not use
$kind. Before creating or editing one by hand, read
reference/environment.md for the schema, secret
handling, CLI-first edit commands, and a linted example.
Invalid YAML breaks parsing silently in confusing ways — when in doubt, single-quote it:
{{variables}}:
url: '{{base_url}}/users' — never leave it unquoted.: # & * ! [ ] { } > |, e.g.
name: 'Health check: v2'.|- block
scalar:
body:
type: json
content: |-
{
"name": "example"
}
value: "true", value: "123".order must be a bare number, never quoted: order: 1000.examples: './.resources/name.resources/examples'.<request-name> (the filename stem before .request.yaml) must not
contain / \ : * ? " < > | — sanitize to -.name in the file only when it differs from <request-name>
(e.g. name: 'Health/check' inside Health-check.request.yaml, since the
filename itself can't hold the /).postman/collections/bookstore api/get all books.request.yaml
$kind: http-request
method: GET
url: '{{base_url}}/books'
order: 1000
postman/collections/bookstore api/get-book-by-id.request.yaml
$kind: http-request
name: 'get book by :id'
method: GET
url: '{{base_url}}/books/:id'
order: 2000
pathVariables:
- key: id
value: '1'
postman/collections/bookstore api/add new book.request.yaml
$kind: http-request
method: POST
url: '{{base_url}}/books'
order: 3000
headers:
- key: Content-Type
value: application/json
body:
type: json
content: |-
{
"title": "Example Book",
"author": "Jane Doe"
}
postman/collections/bookstore api/.resources/definition.yaml
$kind: collection
name: Bookstore API
variables:
- key: base_url
value: 'https://api.bookstore.com/v1'
{{variables}} or special characters are the most common way
a hand-written file fails to parse. Single-quote per the YAML rules
above rather than debugging a cryptic lint error after the fact.order is relative, not an index. Don't renumber every sibling file
to insert one request — leave headroom (spacing of 1000) from the start.methodDescriptor, LLM's userPrompts/systemPrompts).