> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sightmap.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Sightmap JSON Schema: Editor Validation and CI Setup

> Configure editor feedback and CI validation for .sightmap/ files with the Sightmap v1 JSON Schema.

The Sightmap v1 JSON Schema defines the structure of `.sightmap/*.yaml` files. A validator checks the parsed YAML value against the schema. This page covers editor and CI setup; the [Schema reference](/reference/schema) documents each field.

The schema lives in the monorepo and has a stable `$id` URL.

|             |                                                                                                               |
| ----------- | ------------------------------------------------------------------------------------------------------------- |
| Spec stream | `1`                                                                                                           |
| Draft       | JSON Schema 2020-12                                                                                           |
| `$id`       | `https://raw.githubusercontent.com/sightmap/sightmap/main/spec/v1/sightmap.schema.json`                       |
| Source      | [`spec/v1/sightmap.schema.json`](https://github.com/sightmap/sightmap/blob/main/spec/v1/sightmap.schema.json) |

## yaml-language-server directive

Add this comment as the first line of a `.sightmap/*.yaml` file to enable schema-based validation, completion, and hover documentation in compatible editors:

```yaml first line of a .sightmap/ file theme={null}
# yaml-language-server: $schema=https://raw.githubusercontent.com/sightmap/sightmap/main/spec/v1/sightmap.schema.json
version: 1
views:
  - name: Home
    route: /
```

The [Red Hat YAML language server](https://github.com/redhat-developer/yaml-language-server) recognizes this directive.

## VS Code

<Steps>
  <Step title="Install the YAML extension">
    Install the [YAML extension by Red Hat](https://marketplace.visualstudio.com/items?itemName=redhat.vscode-yaml).
  </Step>

  <Step title="Map the schema">
    Either add the `# yaml-language-server: $schema=…` directive at the top of each file, or wire the schema globally in your workspace settings:

    ```json .vscode/settings.json theme={null}
    {
      "yaml.schemas": {
        "https://raw.githubusercontent.com/sightmap/sightmap/main/spec/v1/sightmap.schema.json": [
          ".sightmap/**/*.yaml",
          ".sightmap/**/*.yml"
        ]
      }
    }
    ```
  </Step>
</Steps>

## JetBrains (IntelliJ, WebStorm, PyCharm)

JetBrains IDEs provide a JSON Schema mappings UI:

1. **Settings → Languages & Frameworks → Schemas and DTDs → JSON Schema Mappings**
2. Add a mapping with the `$id` URL above as the schema URL. Map it to the `.sightmap/` directory or to patterns covering both `.yaml` and `.yml` files.

## Neovim

If your Neovim setup uses `yamlls`, configure the schema mapping or add the inline directive.

## Pinning and vendoring

The `$id` URL above tracks `main`, so its contents can change. For reproducible validation, use one of these options:

* **Pin to a commit or tag**: replace `main` in the raw URL with a commit SHA or tag.
* **Vendor the file**: copy `spec/v1/sightmap.schema.json` into your project and point the validator at the local copy. Update the copy with the tools that consume it.

<Note>
  The schema sets `additionalProperties: false` at every level, so a document that uses a field added in a newer schema revision fails validation against an older pinned copy. See the [versioning policy](/reference/versioning) for how schema evolution is coordinated.
</Note>

## CI validation

To validate YAML in CI, parse each file and pass the resulting value to a JSON Schema 2020-12 validator loaded with the Sightmap schema. The monorepo includes an [ajv](https://ajv.js.org/)-based checker that performs both steps. It validates examples and conformance inputs expected to be valid, and skips fixture inputs marked as intentionally invalid.

```bash from a checkout of sightmap/sightmap theme={null}
cd spec
npm ci
node scripts/validate-sightmap.mjs ../my-app/.sightmap
```

The script accepts one or more files or directories and exits non-zero on an unexpected parse or validation error.

<Tip>
  For corpus checks during authoring, `sightmap validate` checks the structure locally and `sightmap lint` adds style checks. See the [corpus commands](/cli/corpus).
</Tip>