postman-collection

postman-collection is the Node.js SDK behind the Postman Collection Format, giving developers a typed object model for requests, folders, headers, variables, auth, and responses that mirrors what Postman apps and the Newman CLI runtime consume natively. Instead of hand-rolling JSON that matches the Postman Collection schema, you construct Collection, Item, Request, and related classes directly and call toJSON() to export a spec-compliant file.

It’s the same library Postman itself uses internally, so it stays in lockstep with the official Collection Format v2.1 schema and is the standard way to programmatically generate, transform, or validate Postman collections outside the Postman app — for example in CI pipelines, custom API tooling, or Newman-based test runners.

What You Get

• Full object model for Collections, Folders, Items, Requests, Responses, Headers, and Variables matching Collection Format v2.1
• Bidirectional JSON conversion via constructors and toJSON(), so files stay compatible with Postman apps and Newman
• Built-in URL pattern matching, auth helpers, and variable substitution utilities
• TypeScript type definitions generated and published alongside the JS SDK
• Used internally by Postman itself, so behavior stays aligned with the official schema and app behavior

Common Use Cases

• Generating Postman collections programmatically from an OpenAPI spec or internal API registry
• Building custom CI tooling that reads, filters, or rewrites collection files before running them with Newman
• Validating or migrating collections between Collection Format schema versions
• Building developer tools or dashboards that need to parse and display Postman collection contents

Under The Hood

Architecture The SDK is organized under lib/collection (the core object model — Collection, Item, ItemGroup, Request, Response, Header, etc.), lib/superstring (Postman’s own string/variable substitution engine), lib/url-pattern, and lib/content-info, with index.js re-exporting the full public class list; each model class both parses a JSON shape in its constructor and serializes back via toJSON(), keeping the object model and the on-disk Collection Format schema in sync. Tech Stack Plain JavaScript (no TypeScript source, though .d.ts types are generated at build time via npm/build-types.js), with runtime dependencies including lodash, iconv-lite, liquid-json, file-type, and @faker-js/faker (used for Postman’s dynamic-variable/mock-data features). Code Quality The test/ directory is split into unit, system, and benchmark suites, run through nyc for coverage and reported to Codecov via CI; the codebase follows a consistent per-class-per-file layout and ships extensive JSDoc comments that feed the published API docs site. API Design The public API mirrors the Postman Collection JSON schema closely — constructing a new Collection(json) and calling .toJSON() round-trips losslessly — which keeps the learning curve low for anyone already familiar with Postman’s UI/schema, though the breadth of nested model classes (Item, ItemGroup, RequestBody, Auth, etc.) means non-trivial manipulation requires familiarity with the full Collection Format spec.