.zq project file format
Supported authored schema: 110. This reference describes editable .zq source projects. A project is a ZIP archive with JSON and optional media blobs. ZoneQ Studio remains the visual editor and preview surface.
Start with a complete project
Section titled “Start with a complete project”Schema 110 and CLI 0.6.0 are available in the repository; a matching standalone CLI has not been published. The published CLI 0.3.0 supports schema 105. The schema-105 examples remain available.
For the current source format, build the CLI from a repository checkout with Node 22 or newer, then download the Stripes example:
npm --prefix tools/project-format cinpm --prefix tools/project-format run buildnode tools/project-format/dist/cli.mjs extract stripes.zq --out my-project --fork# Edit my-project/project.json or add assets.node tools/project-format/dist/cli.mjs pack my-project --out my-project.zqnode tools/project-format/dist/cli.mjs validate my-project.zq --jsonOpen my-project.zq with File → Open File… in Studio. Inspect the Stage and graph, play at several times, and save if the result is right. validate checks structure and references; it cannot judge the image, motion, or sound.
extract preserves the project’s identity by default. Use --fork when creating a different project from an example. Keep the projectId stable when editing your own project.
Reference downloads
Section titled “Reference downloads”- Structural JSON Schema, version 110 defines serialized fields and variants.
- Node and kind catalog, version 110 lists layer, image operator, Binding Graph, and shader graph nodes with ports and defaults, plus blend, reference, particle, and Scene3D kinds.
- Complete operator node templates, version 110 contains serialized parameters and metadata; see parameter authoring.
- Example manifest with SHA-256 hashes identifies the downloads below.
The JSON Schema covers structure. The local validator also checks graph wiring, cross-object references, archive integrity, and rules a structural schema cannot express.
Project structure
Section titled “Project structure”Read Project structure and assets for ZIP layout, identity, asset references, and thumbnails. The CLI reference covers every command and the Portal download → upgrade → extract → edit → pack → validate workflow. Older Portal examples can be inspected after explicit local upgrade, without application source.
Compatibility
Section titled “Compatibility”CLI release 0.3.0 · Reference updated 2026-10-02.
| Surface | Schema support | Verification |
|---|---|---|
| Authoring reference and examples | 110 | Updated 2026-10-07; Repository format source and reference. The standalone CLI verification above identifies the published format-tool version. |
| CLI 0.3.0 | Extract, pack, validate: 105. Upgrade: 101, 102, 103, 104, 105 → 105 | Verified public standalone CLI download; npm registry publication is not used for this release — 2026-10-02 |
| Hosted Studio 1.0.0-beta.18, build 1092 | Reads 101, 102, 103, 104, 105; saves 105 | Verified hosted Studio and Player rendering — 2026-10-02 |
| Portal uploads | Current authored schema 105 | Verified live ordinary-account upload, processing and exact source download — 2026-10-02; revision a7f5e6b6a17a |
This is a dated release record, not live service status. Older Portal downloads retain their recorded source schema; upgrade before editing with the CLI. Details and evidence are in the release record. Entries marked unverified are not compatibility guarantees.
Read the schema and CLI changelog before editing an older file. If Studio reports a different expected schema, compare its displayed build with this table and reload to obtain the current hosted artifact. Report any remaining mismatch; do not change only the JSON version number.
Working examples
Section titled “Working examples”| Project | Demonstrates |
|---|---|
| Stripes | Image generator and exposed controls |
| Color Grade + Glow | Embedded image and layered processing |
| Audio-Reactive Glow | Audio source and parameter binding |
| Shared Texture Routing | Sharing a produced field across layers |
| Reflective 3D Skull | Scene3D resource, materials, lighting, and model asset |
| Particle Drift | Particle template and layer card |
Continue with Archive and assets, Layers, inputs, and bindings, Shaders, Scene3D, and particles, and Validation and portability.