> ## Documentation Index
> Fetch the complete documentation index at: https://bruno-a6972042-mintlify-f61698fc.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

```yaml theme={null}
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.

```yaml theme={null}
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.

```yaml theme={null}
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.

```yaml theme={null}
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.

```yaml theme={null}
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.

```yaml theme={null}
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.

```yaml theme={null}
# 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.

```yaml theme={null}
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.

```yaml theme={null}
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.

```yaml theme={null}
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.

```yaml theme={null}
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.

```yaml theme={null}
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`                                 |

<Note>
  The `scripts.moduleWhitelist` and `scripts.filesystemAccess` settings from `bruno.json` have no equivalent in `opencollection.yml`. See [Whitelisting Modules](/testing/script/whitelisting-modules) for how these settings work in the Bru format.
</Note>

## 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.

```yaml theme={null}
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        |