schema validate

Checks a local TypeScript schema for structural problems and unresolvable references. Run schema validate before 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.

Usage

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

# 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:

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.

{
  "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.