schema validate

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

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 only filters which issues are displayed. 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 and nothing else, so it can be piped or redirected. All human-facing output (the title, progress, and errors) goes 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 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.