Get completion and validation in your editor#

Panel documents are YAML, and Scenet publishes a JSON Schema for them. Any editor with a YAML language server can therefore offer completion, hover documentation and inline validation — with no Scenet-specific plugin at all.

The schema is generated from the compiler’s own pydantic models, so what your editor suggests cannot drift from what actually compiles. A test fails if the shipped copy goes stale.

Any editor, via a schema comment#

Put this on the first line of a panel document:

# yaml-language-server: $schema=https://creatoan.github.io/scenet/schemas/panel.schema.json
panel:
  size: [1000, 800]
cast:
  alice: {reference: alice}

For a multi-panel document use scene.schema.json instead, for an artwork contract — the *.art.yaml beside a picture, declaring the figures it draws — artwork.schema.json, and for a puppet of your own — the *.puppet.yaml a cast member names by its path — puppet.schema.json.

That URL always serves the schema of the latest release. To validate against the release you have installed instead, put its minor version in the path — each release’s schemas stay online under it:

Part of a panel document#
# yaml-language-server: $schema=https://creatoan.github.io/scenet/v0.11/schemas/panel.schema.json

dev/ in place of the version gives main’s, for language not released yet.

That comment is understood by the YAML language server used by VS Code, Neovim, Helix, Emacs (lsp-mode), IntelliJ and Zed, among others. You get:

  • Completion on every key, and on every enum value — all ten shot types, all four balloon kinds, all nine placement zones.

  • Hover documentation on every key: the line under each field of the models becomes its description in the schema, and the language reference’s card for the key opens with it. Hovering shot: says it is the tightest the camera may go, and that it steps back when the cast does not fit.

  • Inline errors for unknown keys, wrong types and out-of-range values, as you type.

The VS Code extension#

A small extension bundles the same schemas plus a side-by-side preview:

  1. Download scenet.vsix from the latest release.

  2. In VS Code: Extensions → ⋯ → Install from VSIX…

It contributes:

  • Schema association for *.panel.yaml, *.scene.yaml, *.art.yaml and *.puppet.yaml, so no $schema comment is needed.

  • Highlighting for .script comic scripts, the same as the playground’s: page and panel headings in Dark Horse’s layout and in French, @ directives, captions and CAP/NAME, sound effects, cues and their parentheticals, balloon numbers, dialogue apart from prose, and the front matter coloured as the YAML it is. It follows the compiler’s reading line for line, so a line coloured as dialogue is a line that compiles as dialogue.

  • The findings of scenet check, when a panel, scene or comic script is opened or saved: an actor not in the cast, an ordering cycle, a pose the puppet lacks, and every other rule in the catalogue, underlined where they are and listed under Problems with their rule, which opens the rule’s entry: why it happens, how to fix it, and an example. A comic-script finding underlines its line. A note, such as a balloon over the words a publisher asks for, is shown as information rather than as an error, since the document still compiles; the playground does the same. Set scenet.checkDeep to check with --deep as well, which costs a real compile on every save, and scenet.checkOnSave to turn checking off.

  • Scenet: Preview panel, which compiles the current document and shows the SVG beside it.

Both shell out to the scenet command, so they need the compiler installed. If it is not on your PATH, set scenet.executable — uv run scenet works, as does an absolute path. If it cannot be run, or fails, a notification says so once, rather than the Problems list staying quietly empty.

It depends on the Red Hat YAML extension, which VS Code will offer to install for you.

Findings the schema cannot see#

The schema catches typos and wrong types. It cannot catch an actor id in staging that is not in cast, an ordering cycle, or a pose the puppet does not have: those are what scenet check is for. Its SARIF output can be read by Microsoft’s SARIF Viewer extension, so you can see them in VS Code without the Scenet extension, or open a report CI wrote:

scenet check --format sarif -o scenet.sarif examples/gallery/01-two-characters.panel.yaml

Then open scenet.sarif in VS Code. The viewer opens its results panel, underlines each finding in its document, and lists it under Problems with its rule.

The viewer reads a file, so it shows the findings as they were when you ran the command. Run it again after a fix to see them go.

Generating the schema yourself#

scenet schema -o panel.schema.json
scenet schema --scene -o scene.schema.json
scenet schema --artwork -o artwork.schema.json
scenet schema --puppet -o puppet.schema.json

Each goes to stdout without -o. This is the same command CI runs, and the same one that produces the copies shipped in the extension.

From Python:

import json

from scenet.schema import panel_schema, scene_schema

schema = panel_schema()

assert schema["$defs"]["ShotType"]["enum"][0] == "long_shot"

# Each key says what it means -- which is where the hover text comes from.
assert "steps back" in schema["$defs"]["CameraSpec"]["properties"]["shot"]["description"]

document = json.dumps(schema, indent=2, sort_keys=True)

Not PanelIR.model_json_schema(). That describes the IR, which is the language after the frontend has rewritten its conveniences away, and it rejects nearly every document anyone actually writes: to the IR, alice left_of bob should have been an object, and - say: is a wrapper it has never heard of.

Why it is generated and not written#

A hand-written schema is a second definition of the language, and second definitions drift. Within a release or two the editor is suggesting a key the compiler rejects, or failing to suggest one it accepts, and nobody notices because nothing checks.

Here there is one definition — the pydantic models — and the schema is a projection of it. The prose in the models is the prose in your editor’s hover. The enum in the models is the enum in your completion list. Adding a construct to the language updates both by construction.

The one thing a projection of the models cannot know is the surface syntax: staging sentences, verb-tagged script entries, place:, and scene panels that state only what they change. Those are put back by scenet.schema, each beside a note of the frontend code it mirrors, and a test validates every document in examples/ against the shipped copy. Checking the schema against itself was not enough: it agreed with itself perfectly while rejecting 21 of the 22 gallery documents.