Skip to content

Validation and portability

Supported authored schema: 110. The local CLI checks both the editable ZIP and the project it contains:

Terminal window
node tools/project-format/dist/cli.mjs validate my-project.zq
node tools/project-format/dist/cli.mjs validate my-project --json

The JSON response includes ok: true, schemaVersion: 110, issues: [], and simulation: { capability, definitions, instances, diagnostics } on success. A failure returns ok: false, issue objects with path and message, and a nonzero exit code. pack runs the same checks before writing output. It refreshes manifest size and hash fields for files already listed in project.json; validate only inspects and never rewrites them.

The CLI runs Studio’s current load checker and the shared strict project and archive contract: version, required fields, named kinds, graph wiring and references, simulation declarations and supported kernel source, asset manifests, blob sizes and hashes, allowed archive entries, and ZIP limits. Structurally valid JSON can still have an invalid cross-reference. Local simulation inspection remains available when execution is disabled; production Portal uploads separately require enabled simulation support.

After validation, open the .zq in Studio. Check the Stage at more than one time, inspect diagnostics, test exposed controls and media replacement, and save/reopen. A valid file does not prove that the composition is visually useful or that every optional host can run it.

Projects with cameras, microphones, display capture, controllers, or network Sources contain authored intent but depend on runtime permission, connectivity, and host capability. Their streams are not embedded in the .zq. OBS, Wallpaper, Android, and offline export may have narrower rules than Studio/Player; verify the intended host before distribution.

The public reference is versioned with ZoneQ’s project schema. An older bundle may open through Studio’s migration path, but new files should target the current reference and pass the current CLI. The CLI and its assets run locally; validation does not upload project bytes.