---
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 it before [`schema push`](/docs/tooling/cli/schema-push), or in CI on every commit, to catch a schema that would be rejected or would push something unintended.

Blocks, datasources, folders, and field plugins are read from the entry file’s exports, either directly or via an exported `schema` object. Only exported definitions are validated, and only exported definitions are pushed.

References resolve by name after the whole schema is collected, so forward and circular references are valid.

## 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` only filters which issues are displayed. 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 and nothing else, so it can be piped or redirected. All human-facing output (the title, progress, and errors) goes 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` only for a run with no errors; warnings alone keep it `true`. Every group carries a `ref` with the machine-readable identity of the entity the issues belong to. Use it instead of parsing `header`. The counts are always true totals, unaffected by `--level`.

## Pagination

-   [Previous: schema rollback](/docs/tooling/cli/schema-rollback)
-   [Next: signup](/docs/tooling/cli/signup)