postman-collection-rs

Postman Collection serialization and deserialization library, written in Rust.

License

Overview

postman_collection provides typed Rust models for working with Postman Collection files. It deserializes collections from JSON, identifies the supported collection version, and serializes the typed model back to JSON. YAML parsing and serialization are available behind the optional yaml feature.

Current highlights:

typed support for Postman Collection v1.0.0, v2.0.0, and v2.1.0
version-specific models exposed as v1_0_0, v2_0_0, and v2_1_0
strict version detection through the top-level PostmanCollection enum
convenient parsing helpers: from_path, from_reader, from_str, and from_slice
JSON serialization with to_json
optional YAML parsing and serialization with the yaml feature
regression coverage for version dispatch, round-tripping, and representative schema branches

Supported Versions

This crate currently supports Postman Collection:

v1.0.0
v2.0.0
v2.1.0

Version detection follows the collection format:

v1.0.0 is detected from the legacy root collection shape.
v2.0.0 and v2.1.0 are detected from info.schema.

Collections that look like v2 but omit info.schema, or point at an unsupported schema version, fail to deserialize instead of being guessed into the wrong version module.

Install

JSON-only use (default):

[dependencies]
postman_collection = "0.3"

Enable YAML serialization:

[dependencies]
postman_collection = { version = "0.3", features = ["yaml"] }

Usage

fn main() -> postman_collection::Result<()> {
    let collection = postman_collection::from_path("path/to/postman-collection.json")?;
    println!(
        "Found {:?} collection named {}",
        collection.version(),
        collection.name()
    );
    Ok(())
}

If you need version-specific fields, match on PostmanCollection directly:

use postman_collection::{from_path, PostmanCollection};

fn main() -> postman_collection::Result<()> {
    match from_path("path/to/postman-collection.json")? {
        PostmanCollection::V1_0_0(spec) => println!("v1 collection: {}", spec.name),
        PostmanCollection::V2_0_0(spec) => println!("v2.0.0 collection: {}", spec.info.name),
        PostmanCollection::V2_1_0(spec) => println!("v2.1.0 collection: {}", spec.info.name),
    }

    Ok(())
}

See examples/printer.rs for a complete runnable example.

With the yaml feature enabled, parsing helpers also accept YAML input and you can serialize a parsed collection as YAML:

use postman_collection::{from_str, to_yaml};

fn main() -> postman_collection::Result<()> {
    let input = r#"{
        "info": {
            "name": "Example",
            "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
        },
        "item": []
    }"#;

    let collection = from_str(input)?;
    println!("{}", to_yaml(&collection)?);
    Ok(())
}

Current State

The crate currently focuses on:

accurate deserialization into version-specific Rust types
stable serialization back to JSON
optional YAML parsing and serialization for callers that opt into the yaml feature
explicit handling of collection version selection
preserving representative schema branches exercised by the bundled fixtures and regression tests

Examples of supported modeled areas include:

collection metadata and variables
folders and nested items
requests, headers, bodies, and URLs
responses and response metadata
auth helpers across the supported versions

Contribute

This project follows semver, conventional commits, and uses GitHub Actions plus release-plz for CI and releases.

Note

Inspired by softprops/openapi.

postman_collection 0.3.1