@postman/postman-plugin 0.5.0 → 0.6.0-rc.0

package/skills/collection-schema-v3/reference/http.md

@@ -13,7 +13,7 @@ Optional metadata for a collection or folder:
 - `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}, ...]}`,
+- `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`,
@@ -47,17 +47,59 @@ Optional metadata for a collection or folder:
 - `examples` — optional, a relative path to the examples directory, e.g.
   `./.resources/<request-name>.resources/examples/`.
 
+When editing query parameters, update both places they are recorded: the
+query string in `url` and the entries in `queryParams`. Their names and values
+must match; lint reports a mismatch as `FMT209`. For example, `q=shoes&page=2`
+is represented as:
+
+```yaml
+url: '{{base_url}}/search?q=shoes&page=2'
+queryParams:
+  - key: q
+    value: shoes
+  - key: page
+    value: '2'
+```
+
 ## HTTP example (`*.example.yaml`)
 
-- `$kind: "http-example"` — required.
-- `name` — optional.
-- `request: {url, method}`.
-- `response: {statusCode, statusText, headers: [{key, value}], body: {type, content}}`.
-- `order` — optional.
+`http-example` requires `$kind` and `response`, and `response` requires `body`:
+
+```yaml
+$kind: http-example
+name: 200 OK
+request:
+  method: POST
+  url: https://api.example.com/orders
+  headers:
+    - key: Content-Type
+      value: application/json
+  body:
+    type: json
+    content: '{"sku":"A1"}'
+response:
+  statusCode: 200
+  statusText: OK
+  headers:
+    - key: Content-Type
+      value: application/json
+  body:
+    type: json
+    content: '{"id":"o_1"}'
+order: 1000
+```
+
+For a saved `204 No Content` example, the YAML schema still requires a
+`response.body` object. Represent the absence of response content with
+`body: {type: text, content: ''}`. This describes the saved example file;
+it does not add content to the HTTP response.
 
-Saved examples are what `collection ai-readiness` checks for — a request
-with no examples scores worse for agent consumption even if perfectly
-valid structurally.
+Response `body.type` accepts only `text`, `json`, `xml`, `html`, `javascript`
+and `yaml`. For a form-encoded response, use `type: text` with a
+matching `Content-Type` header. Request bodies do have `urlencoded`.
+
+Saved examples feed **ai-readiness**, documentation, and mocks; a structurally
+valid example still needs to agree with the contract.
 
 ## Environments (`postman/environments/*.environment.yaml`)
 
@@ -66,10 +108,106 @@ Environment files are v3 YAML but are not collection entities: they do not use
 [reference/environment.md](environment.md) for the schema, secret
 handling, CLI-first edit commands, and a linted example.
 
+## Auth
+
+`auth` is available on a collection, a folder, a request and an example. It has two
+shapes. No auth:
+
+```yaml
+auth:
+  type: noauth
+```
+
+Anything else takes `type` plus `credentials`:
+
+```yaml
+auth:
+  type: bearer
+  credentials:
+    - key: token
+      value: '{{TOKEN}}'
+```
+
+`type` is one of `basic`, `bearer`, `apikey`, `digest`, `oauth1`, `oauth2`, `jwt`,
+`awsv4`, `hawk`, `ntlm`, `asap`, `edgegrid`, `azure`, `sasl`, `inherit`. Use `inherit`
+to take the parent folder's or collection's auth explicitly; omitting `auth` entirely
+does the same thing.
+
+`credentials` keys are the same names the Postman app shows for that auth type —
+`username`/`password` for `basic`, `token` for `bearer`, `key`/`value`/`in` for
+`apikey`, `accessKey`/`secretKey`/`region`/`service` for `awsv4`. A structurally
+valid credential entry does not establish that the server will authenticate it.
+`credentials` is an array of `{key, value}` entries.
+
+## Request body
+
+`body` is one shape chosen by `type` — write that branch's keys and nothing else.
+
+```yaml
+body: {type: none}
+```
+```yaml
+body:
+  type: json          # or text, xml, html, javascript
+  content: |-
+    {"id": 1}
+```
+```yaml
+body:
+  type: urlencoded
+  content:
+    - key: grant_type
+      value: client_credentials
+```
+```yaml
+body:
+  type: formdata
+  content:
+    - key: file
+      type: file
+      src: ./payload.bin
+    - key: note
+      type: text
+      value: hello
+      contentType: text/plain
+```
+```yaml
+body:
+  type: file
+  content:
+    src: ./upload.bin       # an object with src, not a bare path
+```
+
+Choose `body.type` to match the payload and contract. JSON `content` is a string;
+a block scalar keeps it readable without turning it into a YAML object.
+A *response* body inside an example has a narrower type list:
+see [HTTP examples](#http-example-exampleyaml).
+
+## Scripts
+
+```yaml
+scripts:
+  - type: afterResponse
+    code: |-
+      pm.test('ok', () => pm.response.to.have.status(200));
+```
+
+`type` is `beforeRequest` or `afterResponse` on a request, and protocol-prefixed on a
+collection or folder (`http:beforeRequest`, `http:afterResponse`,
+`graphql:beforeQuery`, `grpc:beforeInvoke`, …). A script entry may also carry
+`language`, `packages`, and `requests`. `language` takes exactly one value,
+**`text/javascript`** — `language: javascript` is a hard error,
+`Invalid input: expected "text/javascript"`. Omitting it is fine.
+
+The v2.1 `event:` field is not the v3 `scripts:` field. A script's `type` also
+depends on its scope; moving it between a request and a definition requires checking
+the type as well as the code. See the main skill's verification guidance for
+checking that the intended script behavior survives the edit.
+
 ## YAML rules
 
-Invalid YAML breaks parsing silently in confusing ways — when in doubt,
-single-quote it:
+YAML parsing and scalar coercion can change a field's meaning before schema
+validation. Preserve the type the field expects:
 
 1. Single-quote any value containing `{{variables}}`:
    `url: '{{base_url}}/users'` — never leave it unquoted.

package/skills/collection-schema-v3/reference/other_protocols.md

@@ -1,86 +1,232 @@
-# Non-HTTP request schemas (v3)
-
-Read this only when a collection actually contains one of these request
-types — for the common case, the HTTP schema in the parent
-[SKILL.md](../SKILL.md) is the one that applies.
-
-## GraphQL request
-
-- `$kind: "graphql-request"` — required.
-- `url` — string.
-- `order` — optional.
-- `query` — string (the GraphQL query).
-- `variables` — string (a YAML string containing a JSON object).
-- `headers` — array of `{key, value, description?, disabled?}`.
-- `auth` — `{type, credentials}`.
-- `settings` — `{disabledSystemHeaders?}`.
-- `scripts` — array of `{type: "beforeQuery"|"afterResponse", code, language}`.
-
-## gRPC request
-
-- `$kind: "grpc-request"` — required.
-- `url` — string.
-- `order` — optional.
-- `methodPath` — string.
-- `methodDescriptor` — string.
-- `message` — `{content: string (JSON)}`.
-- `metadata` — array of `{key, value, description?}`.
-- `auth` — `{type, credentials}`.
-- `settings` —
-  `{secureConnection?, strictSSL?, maxResponseMessageSize?, includeDefaultFields?, connectionTimeout?}`.
-- `scripts` — array of `{type: "beforeInvoke"|"afterResponse", code, language}`.
-
-## WebSocket request
-
-- `$kind: "websocket-request"` — required.
-- `url` — string.
-- `order` — optional.
-- `headers` — array of `{key, value, description?, disabled?}`.
-- `queryParams` — array of `{key, value, description?, disabled?}`.
-- `settings` — `{handshakeTimeout?, retryCount?, retryDelay?, maxPayload?, strictSSL?}`.
-
-## Socket.IO request
-
-- `$kind: "socket.io-request"` — required.
-- `url` — string.
-- `order` — optional.
-- `headers` — array of `{key, value}`.
-- `queryParams` — array of `{key, value}`.
-- `events` — array of `{name, description?, subscribeOnConnect: boolean}`.
-- `settings` — `{version?, path?, handshakeTimeout?, retryCount?, retryDelay?, strictSSL?}`.
-
-## MQTT request
-
-- `$kind: "mqtt-request"` — required.
-- `url` — string.
-- `order` — optional.
-- `clientId` — string.
-- `version` — `4 | 5`.
-- `topics` — array of
-  `{name, qos: 0|1|2, subscribe: boolean, description?, settings: {noLocal?, retainAsPublished?, retainHandling?, subscriptionIdentifier?}}`.
-- `lastWill` — `{topic, payload, qos, retain, type: "text"|"json", properties: {messageExpiryInterval?, contentType?}}`.
-- `properties` —
-  `{sessionExpiryInterval?, receiveMaximum?, maximumPacketSize?, requestResponseInformation?, userProperties: [{key, value}]}`.
-- `settings` — `{cleanSession?, keepAlive?, autoReconnect?, connectionTimeout?, strictSSL?}`.
-
-## MCP request
-
-- `$kind: "mcp-request"` — required.
-- `transport` — `"sse" | "stdio"`.
-- `order` — optional.
-- SSE shape: `{url, headers?, message, auth?, settings: {strictSSL?, requestTimeout?, sessionTimeout?}}`.
-- STDIO shape: `{command, env: [{key, value}], message, auth?, settings: {requestTimeout?}}`.
-
-## LLM request
-
-- `$kind: "llm-request"` — required.
-- `url` — string.
-- `order` — optional.
-- `config` — `{model, provider}`.
-- `userPrompts` — array of `{id, value, timestamp, active, type: "text"}`.
-- `systemPrompts` — array of `{id, value, timestamp, active, type: "text"}`.
-- `mcpConfig` — optional string (JSON config).
-- `enabledTools` — optional array of strings.
-- `auth` — `{type, credentials}`.
-- `settings` —
-  `{temperature?, maxToken?, streamResponse?, responseFormatJSON?, topP?, presencePenalty?, frequencyPenalty?, maxSteps?, streamTools?}`.
+# Other protocol schemas
+
+Consult the section for the request kind being changed. Non-HTTP protocols have
+different body, script, and settings shapes; structural validity does not establish
+that the configured service or provider is available.
+
+Shared [auth](http.md#auth), [body](http.md#request-body), and
+[script](http.md#scripts) shapes are documented with HTTP where they apply.
+
+- [Request kinds](#request-kinds): GraphQL, gRPC, WebSocket, Socket.IO, MQTT, MCP, LLM
+- [Messages](#messages) and [examples](#examples)
+
+## Request kinds
+
+`$kind` is required on these request kinds, and it is the *only* required field except on
+`mcp-request`, which also requires `transport`. So for every other kind a half-written
+request can pass structural checks without being executable. Only `*.request.yaml`
+files are discovered as requests; the right fields in a differently named file
+do not make it runnable. Each kind has its own settings; HTTP settings do not
+apply to every protocol. Common metadata fields `id`, `name`, `description` and `order`
+are available on all of them and omitted below.
+
+### `graphql-request`
+
+`url`, `query`, `variables` (a **string** of JSON), `headers`, `auth`, `schema`,
+`scripts`, `examples`, `settings`.
+
+There is **no `queryParams`** — put query-string parameters in the `url`.
+
+`settings`: `disabledSystemHeaders`.
+
+`schema` is one shape chosen by `source`:
+
+```yaml
+schema: {source: none}
+```
+```yaml
+schema: {source: auto}
+```
+```yaml
+schema:
+  source: file
+  location: ./schema.graphql
+```
+```yaml
+schema:
+  source: api
+  apiId: <id>
+  versionId: <id>          # releaseId optional
+```
+```yaml
+schema:
+  source: specification
+  specificationId: <id>
+```
+
+### `grpc-request`
+
+`url`, `methodPath` (e.g. `helloworld.Greeter/SayHello`), `methodDescriptor` (an inline
+proto definition), `message` (`{content}`), `metadata` (per-call headers as
+`{key, value}` array entries), `auth`, `schema`, `scripts`, `examples`, `settings`.
+
+`settings`: `secureConnection`, `strictSSL`, `serverNameOverride`,
+`maxResponseMessageSize`, `includeDefaultFields`, `connectionTimeout`.
+
+### `websocket-request`
+
+`url`, `headers`, `queryParams`, `messages`, `examples`, `settings`.
+
+`messages` and `examples` are **strings** — relative paths to directories, not arrays.
+An array fails with `Invalid input: expected string, received array`.
+
+`settings`: `handshakeTimeout`, `retryCount`, `maxPayload`, `retryDelay`, `strictSSL`.
+
+### `socket.io-request`
+
+`url`, `headers`, `queryParams`, `events`, `messages`, `examples`, `settings`.
+
+```yaml
+events:
+  - name: chat:message
+    subscribeOnConnect: true
+    description: Inbound chat traffic
+```
+
+`settings`: `version` (the **strings** `'2'`, `'3'`, `'4'`), `path`,
+`handshakeTimeout`, `retryCount`, `retryDelay`, `strictSSL`. Bare `version: 4` is
+rejected — `Invalid option: expected one of "2"|"3"|"4" (path: /settings/version)`.
+
+### `mqtt-request`
+
+`url`, `clientId`, `version`, `topics`, `lastWill`, `properties`, `auth`, `messages`,
+`examples`, `settings`.
+
+`version` is a **number**, either `4` or `5`, and it sits at the top level rather than
+in `settings`. Do not quote it — that is the opposite of `socket.io-request`, whose
+`settings.version` is the string `'2'`, `'3'` or `'4'`.
+
+```yaml
+topics:
+  - name: sensors/+/temp
+    qos: 1                 # a number: 0, 1 or 2
+    subscribe: true
+lastWill:
+  topic: status/client
+  payload: offline
+  type: text
+  qos: 0
+  retain: true
+```
+
+`properties`: `sessionExpiryInterval`, `receiveMaximum`, `maximumPacketSize`,
+`requestResponseInformation`, `userProperties`.
+
+`settings`: `cleanSession`, `keepAlive`, `autoReconnect`, `connectionTimeout`,
+`strictSSL`.
+
+### `mcp-request`
+
+Requires `$kind` **and** `transport`, which selects the legal keys. Common to both:
+`message`, `auth`.
+
+| `transport` | Its keys | `settings` |
+|---|---|---|
+| `stdio` | `command`, `env` (`{key, value}` array entries) | `version`, `requestTimeout` |
+| `sse` | `url`, `headers` | `version`, `requestTimeout`, `strictSSL`, `sessionTimeout` |
+
+There are no other transports. `message` is a JSON-RPC envelope as a **string**;
+`{{variables}}` interpolate inside it.
+
+```yaml
+$kind: mcp-request
+transport: stdio           # command + env; no url
+command: uvx some-mcp-server
+env:
+  - key: API_KEY
+    value: '{{KEY}}'
+message: |-
+  {"method": "tools/call", "params": {"name": "do_thing", "arguments": {}}}
+order: 1000
+```
+
+```yaml
+$kind: mcp-request
+transport: sse             # url + headers; no command
+url: https://mcp.example.com/sse
+headers:
+  - key: Authorization
+    value: 'Bearer {{KEY}}'
+message: |-
+  {"method": "tools/list"}
+```
+
+### `llm-request`
+
+`url`, `config`, `userPrompts`, `systemPrompts`, `mcpConfig`, `enabledTools`,
+`clientTools`, `auth`, `settings`.
+
+`config` takes `model` and `provider`, both free-form strings. Schema validation
+does not establish that the configured provider or model is available at run time.
+
+Prompt entries are `{id, value, timestamp, active, contentType}`. The content
+format is expressed by `contentType`; `type` is not a prompt-entry field.
+`timestamp` is numeric, and `active` is boolean.
+
+`mcpConfig` is a **string containing a JSON array**, not nested YAML and not
+`mcp.json`'s `mcpServers` object. `clientTools`, for tools the model may call with no
+MCP server behind them, is `[{id, tools: [{id}]}]`.
+
+For example, a prompt and a stdio MCP tool configuration use different scalar
+shapes within the same request:
+
+```yaml
+userPrompts:
+  - id: '1'
+    value: Summarise the last 10 orders
+    timestamp: 1758412800000
+    active: true
+    contentType: text
+mcpConfig: |-
+  [
+    {
+      "name": "orders",
+      "config": {"command": "uvx", "args": ["orders-mcp-server"]},
+      "enabled": true,
+      "disabledTools": []
+    }
+  ]
+```
+
+`settings`: `temperature`, `maxToken`, `maxSteps`, `topP`, `topK`, `seed`,
+`presencePenalty`, `frequencyPenalty`, `repetitionPenalty`, `contextWindow`,
+`streamResponse`, `streamTools`, `responseFormatJSON`. If a tool chain stops early,
+distinguish a step limit from a tool or provider failure before changing `maxSteps`;
+the limit also bounds execution cost and duration.
+
+## Messages
+
+A `messages` directory holds `*.message.yaml` files. Each kind has different required
+fields; a valid WebSocket message is not automatically a valid MQTT message.
+
+```yaml
+$kind: websocket-message      # requires content + contentType
+content: '{"op":"subscribe"}'
+contentType: json             # text | json | xml | html | hex | base64
+```
+
+```yaml
+$kind: socket.io-message      # requires eventName + args
+eventName: chat:message
+acknowledgement: true
+args:
+  - content: '{"text":"hi"}'
+    contentType: json
+```
+
+```yaml
+$kind: mqtt-message           # requires content + contentType + topic
+topic: sensors/1/temp
+content: '21.5'
+contentType: text             # text | json | hex | base64
+qos: 1
+retain: false
+```
+
+## Examples
+
+Examples live in `.resources/<request-name>.resources/examples/*.example.yaml`, with
+`$kind` matching the request's protocol — `graphql-example`,
+`grpc-example`, `websocket-example`, `socket.io-example`, `mqtt-example`. An
+`*-example` kind is rejected in a `*.request.yaml`, and a `*-request` kind is rejected
+in a `*.example.yaml`.

package/skills/datasets/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: datasets
-description: Use when a collection needs queried or joined test inputs, a reusable named view, spreadsheet worksheet data, live database rows, or script access through pm.datasets(). Chooses between a simple iteration file and a dataset while preserving query semantics, portability, and credential boundaries. Use for requests such as "run this collection over database rows".
+description: Use when creating or repairing dataset manifests, or when a collection needs queried or joined test inputs, a reusable named view, spreadsheet worksheet data, live database rows, or script access through pm.datasets(). Chooses between a simple iteration file and a dataset while preserving query semantics, portability, and credential boundaries. Use for requests such as "run this collection over database rows".
 ---
 
 # Datasets
@@ -43,15 +43,16 @@ stay with `collection run -d`; a dataset should earn its extra configuration.
 
 Create a local manifest with `postman dataset create <path.dataset.yaml>
 --name <name>`, then attach sources with `dataset source add`. Source commands
-supply IDs and validation that hand-written entries can miss. Existing-dataset
-commands accept a local path or workspace ID; `list` needs a local path for
+supply IDs and validation that hand-written entries can miss. When inspecting
+or repairing manifest fields, consult [Dataset YAML](reference/schema.md).
+Existing-dataset commands accept a local path or workspace ID; `list` needs a local path for
 local discovery, while workspace create/list use `--workspace`.
 
 File sources are copied into `data_dir` unless `--ref-only` is used. That option
 records absolute paths and makes the dataset machine-specific. For a workspace
 dataset, adding `--file` alone registers a local filesystem source; `--upload`
-is what uploads bytes. Use **bootstrap**'s workspace sync when publishing the
-whole project; there is no separate `dataset push`.
+is what uploads bytes. Datasets are pushed along with the workspace; there is
+no separate `dataset push`.
 
 For spreadsheet sources, use the worksheet-aware guidance in
 [Spreadsheet sources](reference/spreadsheets.md). For ordinary source names,

package/skills/datasets/reference/schema.md

@@ -0,0 +1,51 @@
+# Dataset YAML
+
+Consult this reference when inspecting or repairing manifest fields. Source and
+view commands can supply generated IDs when creating new entries.
+
+```
+postman/datasets/users/
+├── users.dataset.yaml
+└── .resources/
+    └── rows.json
+```
+
+```yaml
+type: dataset                 # not $kind
+name: "Users"
+id: 3f2b6c1e-9d4a-4f81-bc37-5e0a71d9c402     # uuid4
+data_dir: .resources
+sources:
+  - from: embedded_datasource
+    datasource:
+      name: Records
+      id: 8a1d0e77-5c62-4b19-9f03-2d6e4a8b7c15
+      format: json            # this example uses a JSON file
+      source_type: static     # static for files, dynamic for databases
+      location:
+        type: local_filesystem
+        value: rows.json      # relative to data_dir
+views:
+  - from: embedded_view
+    view:
+      name: Records_default_view
+      id: c94e5b20-71af-4d36-8e52-0b7c6d1934fa
+      query: SELECT id, name FROM Records ORDER BY id
+```
+
+`sources` and `views` are optional — `type`, `name`, `id` and `data_dir` alone is a
+valid dataset, and is what `postman dataset create <path> --name X` writes.
+
+For example, a MySQL source sets `format: mysql`, `source_type: dynamic`,
+`ingest: false`, a `dsKey` and a `slug`, with `location.type: mysql`, `location.value`
+a DSN and `location.table` the table name.
+
+A view's `query` is SQL over the source `name`, not over the file name.
+
+There is no `dataset lint`. `postman dataset get <path>` checks the structure offline.
+`postman dataset query <path> -q "<sql>"` runs SQL against the source, which also proves
+the data parses and the query resolves — note the `-q` flag is required.
+
+Connector support and credential handling depend on the installed CLI. Use the
+**datasets** skill's connector and credential guidance when changing a source;
+the MySQL example above is not a complete list of supported connectors.

package/skills/flows/SKILL.md

@@ -49,7 +49,6 @@ result that says nothing about the caller's actual workflow.
    and reports. Connector blocks need `--workspace` even for a local file;
    otherwise failure occurs inside the graph. An access denial across several
    workspaces points toward credentials or entitlement, not an empty flow list.
-   Use **bootstrap** for unresolved CLI/authentication setup.
 
 Read [command options](reference/flow_cli_flags.md) for inputs, reporters,
 dataset iteration, and flag collisions; check installed subcommand `-h` before

package/skills/performance-testing/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: performance-testing
-description: Use when load-testing or benchmarking an API with concurrent virtual users and latency or error thresholds. Reuses a collection to probe a chosen failure mode and distinguishes target limits from load-generator limits. Use for requests such as "load test this API".
+description: Use when load-testing or benchmarking an API with concurrent virtual users and latency or error thresholds, or when importing or migrating a JMeter `.jmx` plan or a Gatling simulation (Java/Kotlin/Scala/JS/TS) into a Postman collection plus a `postman performance run` configuration. Reuses a collection to probe a chosen failure mode and distinguishes target limits from load-generator limits. Use for requests such as "load test this API", "import my JMeter plan", or "convert my Gatling project to Postman".
 ---
 
 # Performance Testing
@@ -47,6 +47,19 @@ and which JMeter features have no equivalent here — think-time timers,
 concurrent thread groups, and non-HTTP (JDBC/FTP/LDAP/Java) samplers are
 reported, never faked.
 
+## Importing from Gatling
+
+Have a Gatling project (a Java/Kotlin/Scala/JS/TS `Simulation`) instead of a
+collection? Convert it by following `references/gatling-import/README.md`, then
+treat the result as the collection above. There is no importer to run — you read
+the source and build the collection, environment, `run.sh` and gap report, using
+the files next to that README as the algorithm (`mapping.md`, `injection.md`,
+`feeders.md`, `unsupported.md`). The gap report marks what mapped exactly, what
+was approximated, and what has no equivalent — WebSocket/SSE and other non-HTTP
+steps, arrival-rate (open-model) injection, think-time pauses, throttling and
+retries are reported, never faked. Open-model injection is converted to VUs via
+Little's law with the arithmetic shown, not guessed.
+
 ## Verification
 
 Report the workload, runner, achieved traffic, latency and error metrics,