{"id":14428,"plugin_id":"plugin_asdk_app_6a6b12e06c5c8191ac5d5252fa5f92c8","kind":"skill","collection_source":null,"comparison_source":null,"observed_at":"2026-09-30T23:09:30.299Z","digest":"53e298297c5e89948e68ed89c3308329b622a9b34db3b9d4b17c385072e488e4","against":null,"payload":{"name":"collection-schema-v3","description":"The reference for the git-native v3 collection file format — one YAML file per request/folder/example under postman/collections/, plus postman/environments/. Read before writing, editing, or generating any file in either directory by hand, or before debugging a `collection lint` failure. Covers the HTTP request/example/definition schema, environment schema, and the YAML/naming rules that make files parse — GraphQL, gRPC, WebSocket, Socket.IO, MQTT, MCP, and LLM request schemas are non-HTTP protocols and live in reference/other_protocols.md, read only when a collection actually uses one.","included_files":[{"relative_path":"reference/environment.md","size_in_bytes":2109},{"relative_path":"reference/other_protocols.md","size_in_bytes":3454}],"skill_md_contents":"---\nname: collection-schema-v3\ndescription: The reference for the git-native v3 collection file format — one YAML file per request/folder/example under postman/collections/, plus postman/environments/. Read before writing, editing, or generating any file in either directory by hand, or before debugging a `collection lint` failure. Covers the HTTP request/example/definition schema, environment schema, and the YAML/naming rules that make files parse — GraphQL, gRPC, WebSocket, Socket.IO, MQTT, MCP, and LLM request schemas are non-HTTP protocols and live in reference/other_protocols.md, read only when a collection actually uses one.\n---\n\n# Collection Schema (v3, Git-Native)\n\n## Overview\n\nA v3 collection is a directory tree under `postman/collections/`, one file\nper entity — every request, every folder's metadata, every saved example is\nits own file. There is no single collection.json to open and edit; the\ndirectory structure itself *is* the collection.\n\n```text\npostman/collections/\n  bookstore api/\n    .resources/\n      definition.yaml (optional)\n      get all books.resources/\n        examples/\n          200 OK.example.yaml\n          400 Bad Request.example.yaml\n          500 Internal Server Error.example.yaml\n    get all books.request.yaml\n    get-book-by-id.request.yaml\n    add new book.request.yaml\n    authentication/\n      .resources/\n        definition.yaml (optional)\n      signup.request.yaml\n      login.request.yaml\n```\n\n- Every folder under `postman/collections/` is a collection; it can contain\n  subfolders and requests.\n- A folder or collection can have a `.resources/` directory — an optional\n  metadata directory for that scope. `.resources/definition.yaml` holds the\n  collection/folder's own metadata; request examples live under\n  `.resources/<request-name>.resources/examples/`.\n- Never place a request file inside a `.resources/` directory — those are\n  metadata-only.\n\n## Definition file (`.resources/definition.yaml`)\n\nOptional metadata for a collection or folder:\n\n- `$kind: \"collection\"` — required, even for a folder's definition.\n- `name` — optional, defaults to the filesystem folder name.\n- `description` — optional.\n- `variables` — array of `{key, value, description?, disabled?}`. `value`\n  must be a string; `disabled` a boolean.\n- `auth` — a single auth object `{type, credentials: [{key, value}, ...]}`,\n  or an array for multiAuth: `[{id, name, type, credentials, rules?}, ...]`.\n- `scripts` — array of `{type, code, language: \"text/javascript\"}`. `type`\n  is one of `http:beforeRequest`, `http:afterResponse`,\n  `graphql:beforeQuery`, `graphql:afterResponse`, `grpc:beforeInvoke`,\n  `grpc:onIncomingMessage`, `grpc:afterResponse`.\n- `order` — number, used for folder ordering.\n\n## HTTP request (`*.request.yaml`)\n\n- `$kind: \"http-request\"` — required.\n- `name` — optional (see naming rules below for when to include it).\n- `order` — number; only used for relative comparison, so space values out\n  (e.g. multiples of 1000) rather than packing them tight — a later\n  insertion between two requests shouldn't force renumbering every sibling.\n- `url` — string, with `{{varName}}` variable syntax.\n- `method` — `GET|POST|PUT|DELETE|PATCH|HEAD|OPTIONS`.\n- `headers` — array of `{key, value, description?, disabled?}`.\n- `queryParams` — array of `{key, value, description?, disabled?}`.\n- `pathVariables` — array of `{key, value, description?}`.\n- `body` — `{type, content}`; `type` required whenever `body` is present.\n  - Types: `json`, `formdata`, `urlencoded`, `text`, `xml`, `html`,\n    `javascript`, `file`, `none`.\n  - `json`/`text`/`xml`/`html`/`javascript`: `content` is a string.\n  - `formdata`: `content` is an array of\n    `{key, type: \"text\"|\"file\", value or src, contentType?, description?}`.\n  - `urlencoded`: `content` is an array of `{key, value, description?}`.\n- `auth` — `{type, credentials}`.\n- `settings` —\n  `{protocolVersion?, strictSSL?, followRedirects?, maxRedirects?, disabledSystemHeaders?}`.\n- `scripts` — array of `{type: \"beforeRequest\"|\"afterResponse\", code, language: \"text/javascript\"}`.\n- `examples` — optional, a relative path to the examples directory, e.g.\n  `./.resources/<request-name>.resources/examples/`.\n\n## HTTP example (`*.example.yaml`)\n\n- `$kind: \"http-example\"` — required.\n- `name` — optional.\n- `request: {url, method}`.\n- `response: {statusCode, statusText, headers: [{key, value}], body: {type, content}}`.\n- `order` — optional.\n\nSaved examples are what `collection ai-readiness` checks for — a request\nwith no examples scores worse for agent consumption even if perfectly\nvalid structurally.\n\n## Environments (`postman/environments/*.environment.yaml`)\n\nEnvironment files are v3 YAML but are not collection entities: they do not use\n`$kind`. Before creating or editing one by hand, read\n[reference/environment.md](reference/environment.md) for the schema, secret\nhandling, CLI-first edit commands, and a linted example.\n\n## YAML rules\n\nInvalid YAML breaks parsing silently in confusing ways — when in doubt,\nsingle-quote it:\n\n1. Single-quote any value containing `{{variables}}`:\n   `url: '{{base_url}}/users'` — never leave it unquoted.\n2. Single-quote values containing `: # & * ! [ ] { } > |`, e.g.\n   `name: 'Health check: v2'`.\n3. Multi-line content (JSON bodies, scripts, queries) uses a `|-` block\n   scalar:\n   ```yaml\n   body:\n     type: json\n     content: |-\n       {\n         \"name\": \"example\"\n       }\n   ```\n4. Quote strings that resemble booleans/numbers when a string is intended:\n   `value: \"true\"`, `value: \"123\"`.\n5. `order` must be a bare number, never quoted: `order: 1000`.\n6. Single-quote file paths and use forward slashes only:\n   `examples: './.resources/name.resources/examples'`.\n\n## Naming rules\n\n- `<request-name>` (the filename stem before `.request.yaml`) must not\n  contain `/ \\ : * ? \" < > |` — sanitize to `-`.\n- Include `name` in the file only when it differs from `<request-name>`\n  (e.g. `name: 'Health/check'` inside `Health-check.request.yaml`, since the\n  filename itself can't hold the `/`).\n- Filenames must be unique, case-insensitively, per directory.\n\n## Worked example: \"bookstore api\"\n\n`postman/collections/bookstore api/get all books.request.yaml`\n```yaml\n$kind: http-request\nmethod: GET\nurl: '{{base_url}}/books'\norder: 1000\n```\n\n`postman/collections/bookstore api/get-book-by-id.request.yaml`\n```yaml\n$kind: http-request\nname: 'get book by :id'\nmethod: GET\nurl: '{{base_url}}/books/:id'\norder: 2000\npathVariables:\n  - key: id\n    value: '1'\n```\n\n`postman/collections/bookstore api/add new book.request.yaml`\n```yaml\n$kind: http-request\nmethod: POST\nurl: '{{base_url}}/books'\norder: 3000\nheaders:\n  - key: Content-Type\n    value: application/json\nbody:\n  type: json\n  content: |-\n    {\n      \"title\": \"Example Book\",\n      \"author\": \"Jane Doe\"\n    }\n```\n\n`postman/collections/bookstore api/.resources/definition.yaml`\n```yaml\n$kind: collection\nname: Bookstore API\nvariables:\n  - key: base_url\n    value: 'https://api.bookstore.com/v1'\n```\n\n## Critical Rules\n\n1. **Every entity is its own file — there's no single collection.json to\n   open.** A request, its parent folder's metadata, and its saved examples\n   are three separate files, not sections of one document.\n2. **Unquoted `{{variables}}` or special characters are the most common way\n   a hand-written file fails to parse.** Single-quote per the YAML rules\n   above rather than debugging a cryptic lint error after the fact.\n3. **`order` is relative, not an index.** Don't renumber every sibling file\n   to insert one request — leave headroom (spacing of 1000) from the start.\n4. **This file covers HTTP only.** A collection using GraphQL, gRPC,\n   WebSocket, Socket.IO, MQTT, MCP, or LLM requests needs\n   [reference/other_protocols.md](reference/other_protocols.md) — don't\n   guess those schemas from the HTTP shape above, they diverge in real ways\n   (e.g. gRPC's `methodDescriptor`, LLM's `userPrompts`/`systemPrompts`).\n\n## Reference\n\n- [Other request protocols](reference/other_protocols.md) — GraphQL, gRPC,\n  WebSocket, Socket.IO, MQTT, MCP, and LLM request schemas.\n- [Environment schema](reference/environment.md) — v3 environment filenames,\n  fields, variable types, safe editing commands, and validation.\n"},"changes":[],"summary":"First saved snapshot. No earlier version is available for comparison.","summary_kind":"deterministic","summary_metadata":{}}