OpenCollection YAML Format

Starting with Bruno 3.0.0, you can save your API request data using YAML (.yml) files as an alternative to the .bru format. This YAML format follows the OpenCollection specification, an open specification created by Bruno for defining executable API collections.

Why OpenCollection YAML?

OpenCollection combines the power of an open specification with the industry-standard YAML format:

Open Specification

• Community-driven standard — OpenCollection is an open specification created by Bruno, designed to be transparent and extensible
• No vendor lock-in — Your API collections are stored in a well-documented, open format that you fully own and control
• Interoperability — Build tooling, integrations, and workflows around a documented specification

Industry-Standard YAML Format

• Universal format — YAML is one of the most widely adopted data serialization formats, used across the software industry
• Zero learning curve — If you’ve worked with Kubernetes, Docker Compose, GitHub Actions, or countless other tools, you already know YAML
• Human-readable — Clean, intuitive syntax that’s easy to read, write, and review in pull requests

Seamless Tooling Integration

Since everything is stored in standard YAML, you can leverage the entire ecosystem of existing tools:

• IDE support — Native syntax highlighting in VS Code, JetBrains IDEs, Vim, and virtually any editor without additional extensions
• Linting & validation — Use tools like yamllint, prettier, or custom JSON Schema validators
• Git integration — GitHub, GitLab, and Bitbucket provide built-in YAML syntax highlighting and diff views for pull requests
• Scripting & automation — Parse and manipulate collections with standard YAML libraries in any programming language (Python, Node.js, Go, etc.)
• CI/CD pipelines — Easily integrate with existing pipeline tools that already understand YAML

OpenCollection vs OpenAPI

OpenCollection and OpenAPI serve complementary purposes:

OpenAPI	OpenCollection
Defines what your API is — the contract, schema, and structure	Defines how to use your API — scenarios, workflows, and execution
API endpoints and HTTP methods	Business workflows and sequences
Request and response schemas	Pre-request scripts and tests
Authentication requirements	Environment variables and secrets
Data types and validation rules	Runnable, shareable collections

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

Learn more about OpenCollection at opencollection.com and view the full specification at spec.opencollection.com.

Quick Example

Here’s what a simple POST request looks like in YAML format:

info:
  name: Create User
  type: http
  seq: 1

http:
  method: POST
  url: https://api.example.com/users
  body:
    type: json
    data: |-
      {
        "name": "John Doe",
        "email": "[e-mail]"
      }
  auth: inherit

runtime:
  scripts:
    - type: tests
      code: |-
        test("should return 201", function() {
          expect(res.status).to.equal(201);
        });

settings:
  encodeUrl: true

Compare this to the equivalent .bru file:

meta {
  name: Create User
  type: http
  seq: 1
}

post {
  url: https://api.example.com/users
  body: json
  auth: inherit
}

body:json {
  {
    "name": "John Doe",
    "email": "[e-mail]"
  }
}

tests {
  test("should return 201", function() {
    expect(res.status).to.equal(201);
  });
}

File Storage

When using YAML format, your collections will be stored with .yml file extensions instead of .bru. The folder structure uses opencollection.yml as the collection root file:

my-collection/
├── opencollection.yml   # Collection configuration (YAML format)
├── environments/
│   └── development.yml
├── users/
│   ├── folder.yml       # Folder configuration
│   ├── create-user.yml
│   ├── get-user.yml
│   └── delete-user.yml
└── orders/
    └── create-order.yml

Compare this to the .bru format structure which uses bruno.json:

my-collection/
├── bruno.json           # Collection configuration (Bru format)
├── collection.bru       # Collection-level settings
├── environments/
│   └── development.bru
├── users/
│   ├── folder.bru       # Folder configuration
│   ├── create-user.bru
│   ├── get-user.bru
│   └── delete-user.bru
└── orders/
    └── create-order.bru

Cross-collection drag and drop

When you drag a request from one collection to another that uses a different format (for example, .bru to .yml or vice versa), Bruno automatically converts the request file to the target collection’s format. This lets you move individual requests between format types without any manual conversion.

Moving folders between collections with different formats is not supported. Only individual requests are converted automatically during cross-collection moves.

Migration

Bruno supports both .bru and .yml formats, so you can migrate your collections gradually. Both formats can coexist within the same collection during the transition period.

Migrate a collection with the header pill

Bruno shows a Migrate to YML pill in the collection header for collections that are still stored in .bru format. Click the pill to open the migration modal, or dismiss it with the X to hide the prompt for that collection. Dismissals are remembered per collection.

The migration modal converts all files in the collection:

• Request files change from .bru to .yml.
• Environment files are rewritten in YAML.
• bruno.json is replaced with opencollection.yml.

Open tabs for the collection close and the collection reloads once the migration finishes.

Unsaved changes

If any drafts exist when you start the migration, the modal switches to an Unsaved changes step that lists up to five affected items across the collection, folders, requests, and collection environments. Resolve the drafts before Bruno migrates the files:

• Save all writes every draft to disk in one batch, then starts the migration automatically.
• Discard all drops the pending changes, then starts the migration.

Transient requests (requests that have never been saved to disk) can’t be batch-saved. Save each one manually from the modal so the migration can continue.

Resources

• OpenCollection Specification
• OpenCollection JSON Schema