collection-schema-v3

Collection Schema (v3, Git-Native)

Overview

A 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

• Every folder under postman/collections/ is a collection; it can contain subfolders and requests.
• A folder or collection can have a .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/.
• Never place a request file inside a .resources/ directory — those are metadata-only.

Definition file (.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.