# Insomnia File Schema

[`insomnia.schema.5.1.json`](./insomnia.schema.5.1.json) is a [JSON Schema](https://json-schema.org/)
(draft 2020-12) describing the **Insomnia v5 file format** — the `.yaml` files you
get when you export a collection, design document, environment or mock server, and
the files Insomnia reads and writes in Git-backed repositories.

Use it to validate and autocomplete Insomnia files in your editor or CI, and to give
AI agents a precise contract for the files they generate.

> The schema is **generated** from Insomnia's source of truth (the Zod schema in
> [`packages/insomnia/src/common/import-v5-parser.ts`](../packages/insomnia/src/common/import-v5-parser.ts)).
> Do not edit the schema files by hand — see [Regenerating](#regenerating).

## Versioning

Each schema version is published as its own immutable file,
`insomnia.schema.<version>.json` (e.g. `insomnia.schema.5.1.json`). Bumping the schema
adds a new file next to the existing ones, so every version stays addressable and no
published URL ever changes meaning. The current version is defined by
`INSOMNIA_SCHEMA_VERSION` in
[`schema-version.ts`](../packages/insomnia/src/common/insomnia-schema-migrations/schema-version.ts).

Reference the specific version you target — when the schema bumps, update the version in
the URL to move forward.

## Stable URL

The schema is published as a raw file on the default branch:

```
https://raw.githubusercontent.com/Kong/insomnia/develop/schemas/insomnia.schema.5.1.json
```

This is the value of the schema's `$id` and the URL you should reference below. To pin
a specific app version, swap `develop` for a release tag (e.g. `core@12.0.0`).

## What it covers

A single top-level `type` field discriminates the five file kinds:

| `type`                          | File kind                       |
| ------------------------------- | ------------------------------- |
| `collection.insomnia.rest/5.0`  | Request collection              |
| `spec.insomnia.rest/5.0`        | API spec / design document      |
| `mock.insomnia.rest/5.0`        | Mock server                     |
| `environment.insomnia.rest/5.0` | Global environment              |
| `mcpClient.insomnia/5.0`        | MCP client                      |

## Usage

### VS Code (YAML extension)

Install the [YAML extension](https://marketplace.visualstudio.com/items?itemName=redhat.vscode-yaml)
and map your Insomnia files to the schema in `.vscode/settings.json`:

```jsonc
{
  "yaml.schemas": {
    "https://raw.githubusercontent.com/Kong/insomnia/develop/schemas/insomnia.schema.5.1.json": [
      "**/*.insomnia.yaml",
      ".insomnia/**/*.yml"
    ]
  }
}
```

You can also point a single file at the schema with an inline modeline comment:

```yaml
# yaml-language-server: $schema=https://raw.githubusercontent.com/Kong/insomnia/develop/schemas/insomnia.schema.5.1.json
type: collection.insomnia.rest/5.0
name: My Collection
```

### Command line / CI

Validate a file with any JSON Schema validator. Example with
[`ajv-cli`](https://github.com/ajv-validator/ajv-cli) (the file is YAML, so convert it
first — e.g. with [`yq`](https://github.com/mikefarah/yq)):

```bash
curl -sO https://raw.githubusercontent.com/Kong/insomnia/develop/schemas/insomnia.schema.5.1.json
yq -o=json '.' my-collection.insomnia.yaml > my-collection.json
ajv validate --spec=draft2020 -s insomnia.schema.5.1.json -d my-collection.json
```

### Node.js

```js
import Ajv2020 from 'ajv/dist/2020.js';
import addFormats from 'ajv-formats';
import { readFileSync } from 'node:fs';
import YAML from 'yaml';

const schema = JSON.parse(readFileSync('insomnia.schema.5.1.json', 'utf8'));
const ajv = addFormats(new Ajv2020({ allErrors: true, strict: false }));
const validate = ajv.compile(schema);

const data = YAML.parse(readFileSync('my-collection.insomnia.yaml', 'utf8'));
if (!validate(data)) {
  console.error(validate.errors);
  process.exit(1);
}
```

### AI agents

When asking an agent to author or edit an Insomnia file, give it the schema URL as the
contract to follow and validate against:

> Generate an Insomnia collection that conforms to the JSON Schema at
> `https://raw.githubusercontent.com/Kong/insomnia/develop/schemas/insomnia.schema.5.1.json`.
> The top-level `type` must be `collection.insomnia.rest/5.0`.

## Regenerating

The schema is regenerated from the Zod source and committed. CI fails if the committed
file drifts from the source (see [`.github/workflows/test.yml`](../.github/workflows/test.yml)).
After changing the Zod schema, run:

```bash
npm run generate:schema -w insomnia
```

and commit the updated files in `schemas/`.