postman_collection

Postman collections in Dart:

• Typed models for the v2.1 collection format, generated by swagger_to_dart from Postman's official v2.1.0 JSON Schema.
• A converter from every Postman format to OpenAPI 3.1, plus JSON Schema inference from saved JSON examples.

Pure Dart (web included). Only package:postman_collection/io.dart, which reads v3 collection directories, needs dart:io.

To generate Dart models and API clients from a collection, point swagger_to_dart at it: it uses this package's converter.

Installation

dart pub add postman_collection

Parse a collection into typed models

import 'dart:convert';
import 'dart:io';

import 'package:postman_collection/postman_collection.dart';

void main() {
  final json = jsonDecode(File('api.postman_collection.json').readAsStringSync());
  final collection = PostmanCollection.fromJson(json as Map<String, dynamic>);

  for (final item in collection.item) {
    switch (item) {
      case PostmanItemsItem(value: final request):
        print('request ${request.name}');
      case PostmanItemsItemGroup(value: final folder):
        print('folder ${folder.name} (${folder.item.length} items)');
    }
  }

  // Back to JSON: keys the schema defines survive the round trip.
  print(jsonEncode(collection.toJson()));
}

Wherever the official schema says "one of", the model is a sealed class to switch on. The models read v2.1; for v1, v2.0 or the Postman API envelope, call normalizePostmanCollection(json) first.

The models are strict

The models follow the official v2.1 schema exactly:

• They throw on exports that break it, for example "version": 3 (the schema allows an object or a string), a header without value, or any other shape the schema does not allow. Real-world exports often do. For those, use postmanToOpenApi: it reads raw JSON leniently and warns instead of throwing.
• toJson writes only what the schema defines. fromJson silently drops everything else, including fields Postman itself writes:
  • the saved response name and _postman_previewlanguage;
  • info._exporter_id and info._collection_link.
• Unknown enum values decode to unknown. An auth type such as jwt re-encodes as "unknown", and its attributes (the jwt key) are lost.

Generated models

Every definition of the official schema has a model, prefixed Postman (class_prefix: Postman). Inline objects are named after where they appear.

Schema	Dart type
collection (root)	PostmanCollection
info	PostmanInfo
item | item-group	sealed PostmanItems: PostmanItemsItem(PostmanItem), PostmanItemsItemGroup(PostmanItemGroup)
item / item-group	PostmanItem / PostmanItemGroup
request (object | string)	sealed PostmanRequest: PostmanRequestObject(PostmanRequestObjectValue), PostmanRequestString
request method	String (the schema allows any method)
request header (list | string)	sealed PostmanRequestObjectValueHeader
request body	PostmanRequestObjectValueBody, mode: PostmanRequestObjectValueBodyMode, file: PostmanRequestObjectValueBodyFile
urlencoded item / formdata item	PostmanUrlEncodedParameter / sealed PostmanFormParameter: PostmanFormParameterText(PostmanFormParameterTextValue), PostmanFormParameterFile(PostmanFormParameterFileValue); file src is sealed PostmanFormParameterFileValueSrc
url (object | string)	sealed PostmanUrl: PostmanUrlObject(PostmanUrlObjectValue), PostmanUrlString
url host, path, path segment, query item	sealed PostmanHost, sealed PostmanUrlObjectValuePath, sealed PostmanUrlObjectValuePathListValueItem (…ObjectValue for {type, value}), PostmanQueryParam
auth / auth-attribute	PostmanAuth (type: PostmanAuthType) / PostmanAuthAttribute
response	PostmanResponse; its header is sealed PostmanHeaders of PostmanHeadersListValueItem
header, cookie, certificate, proxy-config	PostmanHeader, PostmanCookie, PostmanCertificate (PostmanCertificateKey, PostmanCertificateCert), PostmanProxyConfig
event, script	PostmanEvent, PostmanScript (exec: sealed PostmanScriptExec)
variable	PostmanVariable (type: PostmanVariableType)
description (object | string | null)	sealed PostmanDescription: PostmanDescriptionObject(PostmanDescriptionObjectValue), PostmanDescriptionString
version (object | string)	sealed PostmanVersion: PostmanVersionObject(PostmanVersionObjectValue), PostmanVersionString
*-list definitions	typedefs: PostmanHeaderList, PostmanEventList, PostmanVariableList, PostmanCookieList, PostmanCertificateList
protocol-profile-behavior	typedef PostmanProtocolProfileBehavior = Map<String, dynamic>

Values the schema leaves untyped are dynamic: auth-attribute and variable value, noauth, certificate src, description version, version meta, and responseTime (null, string or number).

Convert to OpenAPI

import 'package:postman_collection/postman_collection.dart';

final openApi = postmanToOpenApi(json, onWarning: print);

postmanToOpenApi accepts every JSON version and never throws on real exports that break the schema (unknown auth types, null header values, headers or URLs given as strings, …): it warns instead. Output is OpenAPI 3.1.1, or 3.2.0 when a request uses QUERY or a method 3.1 cannot express.

• Requests become operations, tagged by their folder path (Parent / Child); same method and path merge into one operation.
• URL, query and header values, bodies and saved responses become parameters, request bodies and responses, with JSON Schemas inferred from the JSON examples (inferJsonSchema).
• Collection variables resolve {{var}} and give examples and server defaults; auth becomes security schemes, never with the secret values.

Other helpers: isPostmanCollection(json), normalizePostmanCollection(json) (any version to v2.1), inferJsonSchema(samples).

v3 collection directories

Postman's current app format (v3) is a directory of YAML files (*.request.yaml, *.example.yaml, .resources/definition.yaml).

import 'package:postman_collection/io.dart';
import 'package:postman_collection/postman_collection.dart';

final v21 = readPostmanCollectionDirectory('path/to/collection');
final openApi = postmanToOpenApi(v21);

Without dart:io (web), pass the files yourself: postmanCollectionFromV3Files({'Users/Get user.request.yaml': yaml, …}).

Supported versions

Format	Typed models	postmanToOpenApi
v2.1.0 (collection.json)	yes	yes
v2.0.0	after normalizePostmanCollection	yes
v1.0.0	after normalizePostmanCollection	yes
Postman API envelope {collection: …}	after normalizePostmanCollection	yes
v3.0.0 directory (YAML)	after readPostmanCollectionDirectory	yes

HTTP and GraphQL requests are converted; gRPC, WebSocket, Socket.IO, MQTT, MCP and LLM requests are skipped with a warning.

Recording dio requests

0.x shipped dio/retrofit helpers. 1.0.0 has no dio dependency; the example has a dio Interceptor recipe that builds PostmanItems from RequestOptions with the models above.

Regenerating the models

The models in lib/src/models are generated, not hand-written: run make models (swagger_to_dart with swagger_to_dart.yaml, then build_runner). CI fails when they drift.

License

MIT. See LICENSE.