---
title: "Validate schema file set"
method: POST
path: "/api/v1/compiler/validate"
tags: ["compiler"]
---

# Validate schema file set

`POST /api/v1/compiler/validate`

Validate a schema file set against a connection.

Checks all views, queries, and related schemas for correctness
and returns any errors or warnings found.

RLS: Filtered to current client (ClientRLSDB).

## Query parameters

- `source` string, nullable

## Headers

- `X-Kater-CLI-ID` string, nullable

## Request body

- ValidateRequest — Request model for validating a schema file set.
  - `auto_fix` boolean — Automatically fix broken refs caused by renames. Defaults to True.
  - `connection_ids` string[], nullable — Optional connection IDs to validate. If omitted, validates all connections.

## Response `200`

Successful Response

- ValidateResponse — Response model for schema validation.
  - `connection_results` ConnectionValidationResult[] — Per-connection validation results with dependency graphs
    - `connection_id` string, uuid, required — Connection UUID
    - `connection_name` string, required — Connection name
    - `dependency_graph` DependencyGraphResponse — Dependency graph between schema objects.
      - `edges` object, required — Edge relationships with UUID string keys
      - `nodes` object, required — UUID string to node mapping
    - `errors` CompilerErrorItem[] — Validation errors for this connection
      - `code` string, required — Machine-readable error code
      - `column` integer, nullable — Column number in the source file
      - `file` string, nullable — Source file path where the error occurred
      - `line` integer, nullable — Line number in the source file
      - `message` string, required — Human-readable error description
      - `ref` string, nullable — Reference to the source element (e.g. view or query name)
      - `remediation` string, nullable — Suggested fix for this error
    - `manifest` Manifest — Compilation manifest with all named objects.
      - `generated_at` string, required
      - `objects` object, required
      - `schema_version` string
    - `ref_fixes` RefFixItem[], nullable — Files auto-fixed due to renamed refs. None when no renames detected.
      - `file_path` string, required — Path to the modified file
      - `new_content` string, required — Full updated file content after fixes
      - `replacements` RefReplacementItem[], required — Individual ref replacements made in this file
        - `file_path` string, required — Path to the file containing the replaced ref
        - `line_number` integer, required — Line number where the replacement occurred
        - `new_ref` string, required — Updated reference string
        - `old_ref` string, required — Original reference string
    - `success` boolean, required — Whether this connection validated without errors
    - `warnings` CompilerErrorItem[] — Validation warnings for this connection
      - `code` string, required — Machine-readable error code
      - `column` integer, nullable — Column number in the source file
      - `file` string, nullable — Source file path where the error occurred
      - `line` integer, nullable — Line number in the source file
      - `message` string, required — Human-readable error description
      - `ref` string, nullable — Reference to the source element (e.g. view or query name)
      - `remediation` string, nullable — Suggested fix for this error
  - `errors` CompilerErrorItem[] — Validation errors
    - `code` string, required — Machine-readable error code
    - `column` integer, nullable — Column number in the source file
    - `file` string, nullable — Source file path where the error occurred
    - `line` integer, nullable — Line number in the source file
    - `message` string, required — Human-readable error description
    - `ref` string, nullable — Reference to the source element (e.g. view or query name)
    - `remediation` string, nullable — Suggested fix for this error
  - `request_id` string, nullable — Write-back request ID. Non-null when files were dispatched to CLI via WebSocket.
  - `success` boolean, required — Whether validation passed without errors
  - `warnings` CompilerErrorItem[] — Validation warnings
    - `code` string, required — Machine-readable error code
    - `column` integer, nullable — Column number in the source file
    - `file` string, nullable — Source file path where the error occurred
    - `line` integer, nullable — Line number in the source file
    - `message` string, required — Human-readable error description
    - `ref` string, nullable — Reference to the source element (e.g. view or query name)
    - `remediation` string, nullable — Suggested fix for this error

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `403` — Forbidden
- `404` — Not Found
- `422` — Validation Error
- `500` — Internal Server Error

## Changes

- **2026-02-26** `bef1f3e205dd` — 6 breaking, 4 info
  - response property `errors` list-of-types was widened by adding types `array` to media type `application/json` of response `400`
  - response property `errors` list-of-types was widened by adding types `array` to media type `application/json` of response `401`
  - response property `errors` list-of-types was widened by adding types `array` to media type `application/json` of response `403`
  - response property `errors` list-of-types was widened by adding types `array` to media type `application/json` of response `404`
  - …6 more
- **2026-02-15** `4037d7d3404b` — 5 info
  - added the optional property `connection_results/items/dependency_graph/anyOf[subschema #1: DependencyGraphResponse]/nodes/additionalProperties/column` to the response with the `200` status
  - added the optional property `connection_results/items/errors/items/column` to the response with the `200` status
  - added the optional property `connection_results/items/warnings/items/column` to the response with the `200` status
  - added the optional property `errors/items/column` to the response with the `200` status
  - …1 more
- **2026-02-10** `ffce131480d5` — 2 warning, 1 info
  - removed the optional property `dependency_graph` from the response with the `200` status
  - removed the optional property `manifest` from the response with the `200` status
  - added the optional property `connection_results` to the response with the `200` status
- …earlier changes not shown

[Full history](https://skmtc.dev/kater-ai/apis/kater-api/changes/api/v1/compiler/validate/post.md)

---

[API](https://skmtc.dev/kater-ai/apis/kater-api.md) · [All operations](https://skmtc.dev/kater-ai/apis/kater-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/kater-ai/kater-api/revisions/6a140b82e07c/schema)