---
title: schema validate
description: Checks a local TypeScript schema for structural problems and unresolvable references.
url: https://www.storyblok.com/docs/tooling/cli/schema/validate
---

# schema validate

Checks a local TypeScript schema for structural problems and unresolvable references. Run `schema validate` before [`schema push`](/docs/tooling/cli/schema/push), or in CI on every commit, to catch rejected schema or unintended changes.

The command uses blocks, datasources, folders, and field plugins from the entry file’s exports, either directly or via an exported `schema` object. It only validates and pushes exported definitions.

The CLI resolves references by name after it loads the complete schema, supporting forward and circular references.

## Prerequisites

An entry file that exports schema definitions authored with [`@storyblok/schema`](/docs/libraries/js/schema).

## Usage

```bash
storyblok schema validate <entry-file> [flags]
```

## Arguments

| Argument | Type | Description |
| --- | --- | --- |
| Entry file | string | _Required._ Path to the TypeScript file that exports the schema. |

## Flags

| Flag | Type | Description |
| --- | --- | --- |
| `--level` | string | _Optional._ Display threshold: `error` hides warnings, `warning` shows everything. Defaults to `warning`. |
| `--format` | string | _Optional._ Output format: `pretty` or `json`. Defaults to `pretty`. |

`--level` filters the displayed issues. It never changes the exit code or the reported totals.

## Examples

```bash
# Validate a local schema
storyblok schema validate src/schema/schema.ts

# Fail only on errors and hide warnings
storyblok schema validate src/schema/schema.ts --level error

# Emit a machine-readable report
storyblok schema validate src/schema/schema.ts --format json > schema-report.json
```

Output:

```text
hero (block)
  ✖ unresolved_allow   blocks.hero.body.allow: Field "body" allows unknown block "gallery".
✖ 1 error, 0 warnings across 1 of 12 entities
```

## JSON output

With `--format json`, the command writes a single JSON object to `stdout`, so you can pipe or redirect the output. The title, progress, and errors print to `stderr`.

```json
{
  "ok": false,
  "unit": "entities",
  "unitsTotal": 12,
  "unitsWithIssues": 1,
  "errors": 1,
  "warnings": 0,
  "fetchFailures": 0,
  "listFailed": false,
  "groups": [
    {
      "header": "hero (block)",
      "ref": { "kind": "block", "name": "hero" },
      "issues": [
        {
          "severity": "error",
          "code": "unresolved_allow",
          "path": ["blocks", "hero", "body", "allow"],
          "entity": "block:hero",
          "message": "Field \"body\" allows unknown block \"gallery\"."
        }
      ]
    }
  ]
}
```

`ok` is `true` when the run has no errors. Each group includes a `ref` that identifies the affected entity. Use it instead of parsing `header`. Counts are always unfiltered totals, regardless of `--level`.

## Pagination

-   [Previous: rollback](/docs/tooling/cli/schema/rollback)
-   [Next: Reference](/docs/tooling/cli/stories/find)