Differences between Postman Collections and the collection format

Gbadebo Bello

March 28, 2023

The collection format specification defines the structure of Postman Collections that we know and love—providing all the information we need about a collection, including the requests, authorizations, HTTP headers, and even example responses to specific requests. Here is how you can work with the underlying collection format to get more out of your collections.

Related: Postman Collection best practices

Auto-generated request headers

When you navigate to the Headers section of your workbench, you will notice that some headers have already been added by default at Postman’s recommendation. If you hover over the Info icon next to one of these headers, you will see a brief description of that header’s purpose. These headers are included at request runtime and are never part of the exported collection’s JSON.

Variables and environments

Variables in Postman Collections have different scopes, and the scope in which they are declared determines their precedence. When a collection that makes use of a variable is exported, it’s important to note that only collection variable declarations will be included in the exported collection’s JSON. This is because the collection format specification only supports collection variables, which are declared within the collection scope of your workbench in Postman.

Global and environment variables, in contrast, are provided by the Postman client to enable developers to work across multiple scopes. When you export a collection that uses a global or environment variable, the reference to that variable will be included, but the declaration of the variable won’t be included because it isn’t part of that collection.

Cookies

When working with cookies in Postman, you can add them to your request headers using the cookie key. Cookies aren’t part of the request object in the collection format specification, which is why they aren’t represented as a unique object in the exported collection. They are instead included in the request headers.

Scripting

Scripting in Postman has a lot of advantages, and the collection format specification provides even more options and capabilities. Much like collections in Postman, the collection format specification supports two types of events: pre-request events and test events. In Postman, a collection or a request can only have one pre-request and test script pair. In contrast, the collection format specification allows you to put multiple events in an event list, which is basically an array of events. This enables you to not only define multiple pre-request and test scripts, but also enable or disable any one of them depending on your use case. It also makes it easier to manage version control for the exported script.

Scripts in exported collections are wrapped in an event object, where each event has its own unique script. The script object in an event has an src object, which is a URL. This allows you to host scripts externally and reference these scripts in the exported collection. While Postman does not support external referencing of the script, the collection format specification does support it.

Learn more about the collection format specification

Check out the documentation for the collection format here. You’ll learn about the different units of a collection, as well as the tooling that makes it easy to work with and build functionality on top of the collection format specification.