Skip to main content
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 documents each field. The schema lives in the monorepo and has a stable $id URL.

​
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:
first line of a .sightmap/ file
The Red Hat YAML language server recognizes this directive.

​
VS Code

1

Install the YAML extension

Install the YAML extension by Red Hat.
2

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:
.vscode/settings.json

​
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.
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 for how schema evolution is coordinated.

​
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-based checker that performs both steps. It validates examples and conformance inputs expected to be valid, and skips fixture inputs marked as intentionally invalid.
from a checkout of sightmap/sightmap
The script accepts one or more files or directories and exits non-zero on an unexpected parse or validation error.
For corpus checks during authoring, sightmap validate checks the structure locally and sightmap lint adds style checks. See the corpus commands.