YAML Structure Reference

This page documents the structure of OpenCollection YAML files used in Bruno.

Top-Level Structure

A Bruno YAML request file contains the following top-level sections:

info:        # Request metadata (name, type, seq, tags)
http:        # HTTP request configuration
runtime:     # Scripts and assertions
settings:    # Request settings
docs:        # Request documentation

info

Store metadata about your request.

info:
  name: Get Users
  type: http
  seq: 1
  tags:
    - smoke
    - regression

Field	Type	Description
`name`	string	The display name of the request
`type`	string	The request type (`http` for HTTP requests, `folder` for folders)
`seq`	number	Sequence number that determines sort position in the UI
`tags`	array	Optional tags for filtering requests during collection runs

http

The HTTP request configuration.

http:
  method: post
  url: https://api.example.com/users
  params:
    query: [...]
    path: [...]
  headers: [...]
  body:
    type: json
    data: "..."
  auth:
    type: basic
    basic:
      username: admin
      password: secret

http.method

The HTTP method. Supported values: GET, POST, PUT, PATCH, DELETE, OPTIONS, HEAD, TRACE, CONNECT (uppercase).

http.params

Parameters as an array of objects with a type field to distinguish query vs path parameters.

params:
  - name: filter
    value: active
    type: query
    description: Filter results by status
  - name: limit
    value: "10"
    type: query
    description: Maximum number of results to return
  - name: id
    value: "123"
    type: path

Field	Type	Description
`name`	string	The parameter name
`value`	string	The parameter value
`type`	string	Either `query` or `path`
`disabled`	boolean	Whether the parameter is disabled (optional)
`description`	string	Human-readable description of the parameter’s purpose (optional)

http.headers

Request headers as an array of objects.

headers:
  - name: Content-Type
    value: application/json
    description: Tells the server the format of the request body
  - name: Authorization
    value: Bearer {{token}}
    description: Bearer token obtained after login
    disabled: true

Field	Type	Description
`name`	string	The header name
`value`	string	The header value
`disabled`	boolean	Whether the header is disabled (optional)
`description`	string	Human-readable description of the header’s purpose (optional)

http.body

The request body configuration.

body:
  type: json
  data: |-
    {
      "name": "John Doe"
    }

Body Type	Description
`json`	JSON body
`text`	Plain text body
`xml`	XML body
`form-urlencoded`	Form URL-encoded data
`multipart-form`	Multipart form data
`graphql`	GraphQL query

http.auth

Authentication configuration. Credentials are specified directly under the auth object. Use inherit to inherit authentication from the parent folder or collection.

# Inherit from parent
auth: inherit

# Bearer token
auth:
  type: bearer
  token: "{{token}}"

# Basic authentication
auth:
  type: basic
  username: admin
  password: secret

# API Key
auth:
  type: apikey
  key: x-api-key
  value: "{{api-key}}"
  placement: header

# OAuth 1.0
auth:
  type: oauth1
  consumerKey: "{{consumer_key}}"
  consumerSecret: "{{consumer_secret}}"
  accessToken: "{{access_token}}"
  accessTokenSecret: "{{token_secret}}"
  signatureMethod: HMAC-SHA1
  version: "1.0"
  placement: header
  includeBodyHash: false

Supported auth types: none, inherit, basic, bearer, apikey, digest, oauth1, oauth2, awsv4, ntlm, wsse.

runtime

The runtime section contains scripts and assertions that execute during the request lifecycle.

runtime.scripts

JavaScript code to run at different points in the request lifecycle.

runtime:
  scripts:
    - type: before-request
      code: |-
        // Runs before the request
        console.log('before-request');
        req.setHeader("X-Timestamp", Date.now());
    - type: after-response
      code: |-
        // Runs after the response
        console.log('after-response');
        bru.setVar("token", res.body.token);
    - type: tests
      code: |-
        test("should return 200", function() {
          expect(res.status).to.equal(200);
        });

Script Type	Description
`before-request`	Runs before the request is sent
`after-response`	Runs after the response is received
`tests`	Test assertions using the Chai assertion library

runtime.assertions

Declarative assertions without writing JavaScript code.

runtime:
  assertions:
    - expression: res.status
      operator: eq
      value: "200"
    - expression: res.body.name
      operator: isString

Field	Type	Description
`expression`	string	The value to evaluate (e.g., `res.status`, `res.body.name`)
`operator`	string	The comparison operator (`eq`, `neq`, `isString`, `isNumber`, etc.)
`value`	string	The expected value (for comparison operators)

settings

Request-level settings.

settings:
  encodeUrl: true
  timeout: 0
  followRedirects: true
  maxRedirects: 5

Field	Type	Description
`encodeUrl`	boolean	Whether to URL-encode the request URL
`timeout`	number	Request timeout in milliseconds (0 = no timeout)
`followRedirects`	boolean	Whether to follow HTTP redirects
`maxRedirects`	number	Maximum number of redirects to follow

docs

Request-level documentation in Markdown format.

docs: |-
  # User Creation API

  This endpoint creates a new user in the system.

  ## Required Fields
  - name: User's full name
  - email: User's email address

Collection Root File (`opencollection.yml`)

The opencollection.yml file at the root of a collection replaces bruno.json. It holds the collection name, collection-level request defaults, configuration, and Bruno-specific extensions.

opencollection: 1.0.0

info:
  name: My Collection
  version: "1"

request:            # Collection-level defaults inherited by requests
  headers:
    - name: X-Api-Version
      value: "2"
  auth:
    type: bearer
    bearer:
      token: "{{token}}"
  scripts:
    - type: before-request
      code: |-
        console.log("runs before every request");

config:             # Proxy, client certificates, and protobuf settings
  protobuf:
    protoFiles:
      - type: file
        path: ./protos/service.proto
    importPaths:
      - path: ./protos

extensions:
  bruno:            # Bruno-specific settings
    ignore:
      - node_modules
      - .git
    presets:
      request:
        type: http
        url: https://api.example.com
    scripts:
      flow: sequential
      additionalContextRoots:
        - ../libs

docs: |-
  Collection-level documentation in Markdown.

Section	Description
`opencollection`	OpenCollection spec version
`info`	Collection metadata: `name` and optional `version`
`request`	Collection-level defaults: `headers`, `auth`, `variables`, and `scripts` (equivalent to `collection.bru` in the Bru format)
`config`	Collection configuration: `proxy`, `clientCertificates`, and `protobuf`
`extensions.bruno`	Bruno-specific settings: `ignore`, `presets`, and `scripts` (`flow`, `additionalContextRoots`)
`docs`	Collection-level documentation in Markdown

Mapping from `bruno.json`

`bruno.json` field	`opencollection.yml` equivalent
`name`	`info.name`
`version`	`info.version`
`ignore`	`extensions.bruno.ignore`
`presets`	`extensions.bruno.presets`
`scripts.flow`	`extensions.bruno.scripts.flow`
`scripts.additionalContextRoots`	`extensions.bruno.scripts.additionalContextRoots`
`proxy`	`config.proxy`
`clientCertificates`	`config.clientCertificates`
`protobuf`	`config.protobuf`

The scripts.moduleWhitelist and scripts.filesystemAccess settings from bruno.json have no equivalent in opencollection.yml. See Whitelisting Modules for how these settings work in the Bru format.

Environment Files

Environments are stored as .yml files in the environments folder of the collection (for example, environments/development.yml). Each file contains the environment name and its variables.

name: development
variables:
  - name: host
    value: http://localhost:8787
    description: Base URL for the local server
  - name: port
    value:
      type: number
      data: "8080"
  - name: legacyFlag
    value: "true"
    disabled: true
  - secret: true
    name: apiKey

Field	Type	Description
`name`	string	The display name of the environment
`variables`	array	The environment’s variables

Each entry in variables supports:

Field	Type	Description
`name`	string	The variable name
`value`	string or object	The value. Use an object with `type` (`number`, `boolean`, `object`) and `data` for typed values
`description`	string	Optional description
`disabled`	boolean	Set to `true` to disable the variable
`secret`	boolean	Set to `true` to mark the variable as a secret. Secret values are not written to the file

Getting Started

Core Features

API Tools

Developer Tools

License Management

Advanced Guides

YAML Structure Reference

Top-Level Structure

info

http

http.method

http.params

http.headers

http.body

http.auth

runtime

runtime.scripts

runtime.assertions

settings

docs

Collection Root File (`opencollection.yml`)

Mapping from `bruno.json`

Environment Files

​Top-Level Structure

​info

​http

​http.method

​http.params

​http.headers

​http.body

​http.auth

​runtime

​runtime.scripts

​runtime.assertions

​settings

​docs

​Collection Root File (opencollection.yml)

​Mapping from bruno.json

​Environment Files

Top-Level Structure

info

http

http.method

http.params

http.headers

http.body

http.auth

runtime

runtime.scripts

runtime.assertions

settings

docs

Collection Root File (`opencollection.yml`)

Mapping from `bruno.json`

Environment Files