OpenCollection

The open format for API collections

OpenCollection is a plain-YAML specification for executable API collections: requests, environments, variables, authentication, scripts and tests. Bruno created it, develops it in the open, and stores every collection in it.

DownloadRead the specification
Open specification · Plain YAML · Published JSON Schema
orders/create-order.yml
info:
  name: Create Order
  type: http
  seq: 2
 
http:
  method: POST
  url: "{{baseUrl}}/orders"
  headers:
    - name: Authorization
      value: Bearer {{token}}
  body:
    type: json
    data: |-
      { "sku": "BRU-001", "quantity": 2 }
 
runtime:
  scripts:
    - type: tests
      code: |-
        test("creates the order", () => {
          expect(res.status).to.equal(201);
        });

Everything a collection needs, in files you can read

OpenCollection describes the working set an API team actually keeps: not just which endpoints exist, but the concrete requests, the environments they run against, and the checks that prove they work.

Requests

HTTP, GraphQL, gRPC and WebSocket requests with their method, URL, params, headers and body, exactly as you would send them.

Environments and variables

Local, staging and production as separate files. Variables resolve at run time, and secrets stay out of the repo.

Authentication

Bearer, basic, API key, OAuth 2.0, AWS Signature and more, set once on the collection and inherited down the tree.

Scripts and tests

Pre-request and post-response scripts, assertions and tests live next to the request they belong to.

Folders or a single file

A collection can be a tree of small files that diff cleanly in Git, or one bundled YAML file you can hand to anyone.

A published JSON Schema

Validate collections in CI, generate types, or build your own tooling against a schema that is documented and versioned.

OpenAPI describes the API. OpenCollection runs it.

The two specifications are complementary. Most teams keep both: the contract in OpenAPI, and the runnable collection that exercises it in OpenCollection.

OpenAPI

What does this API look like?

Endpoints, methods and parameters
Request and response schemas
Authentication requirements
Generated reference docs and SDKs

OpenCollection

How do I call it, and did it work?

Concrete requests with real headers and bodies
Environments, variables and secrets
Scripts, assertions and tests
Runnable from an API client, a CLI or CI

OpenAPI tells you the shape of the door. OpenCollection shows you how to walk through it.

How Bruno uses it

Bruno is the reference implementation. Since Bruno 4.0, every new collection is OpenCollection YAML by default, and every Bruno surface reads the same files.

The desktop app, CLI, IDE extension, docs generator and mock server all read one set of files
Collections live in your repository, so review, history and access control are Git's job
Postman, Insomnia and OpenAPI import through the same schema
Existing .bru collections convert with the built-in migration
OpenCollection YAML in the Bruno docsSee the Bruno products
orders-api
orders-api/
├── opencollection.yml      # collection root
├── environments/
│   ├── local.yml
│   └── production.yml
├── orders/
│   ├── folder.yml              # folder settings
│   ├── create-order.yml
│   └── get-order.yml
└── users/
    └── get-user.yml

Build on it

The format is not tied to Bruno. Any tool can read, write, validate or convert OpenCollection files using the published schema and packages.

opencollection.com

The project home: an overview of the format and how it sits beside OpenAPI.

Specification

The human-readable spec, with every object and field described.

Schema explorer

Browse the JSON Schema interactively, type by type.

GitHub

The schema, TypeScript types and converters, published as MIT-licensed npm packages.

OpenCollection is a Bruno-built, community-supported project. The specification is free for anyone to implement.

Collections you own, in a format anyone can read

Download Bruno and your first collection is OpenCollection YAML from the start. No account, no sync, no export step.

Download
Free and open source · macOS, Windows & Linux · No account needed