Skip to content

Developer Schema and Validation

Vivek Sarin edited this page Nov 20, 2026 · 2 revisions

Schema and validation

FlowMotion has three places that describe its formats. They must agree:

  1. The JSON Schema for YAML diagrams and storyboards. Editors such as VS Code (through yaml-language-server) use it for completion and hover help.
  2. The runtime checks in the parsers. These decide whether a diagram is valid when it is drawn.
  3. The editor support in the plugin. It shows errors while you type, and it offers completion, hover help, rename, and go to definition.

When you add or change a field, update all three and the authoring reference. That reference is the canonical human/AI entry point; parsers and schemas from the matching revision remain the executable evidence.

Files

File Role
src/schema/types.ts The subset of JSON Schema that FlowMotion uses. It is draft-07 compatible
src/schema/common.ts The display options shared by diagrams and storyboards (height, width, mode, and so on)
src/schema/diagram.ts The schema for YAML diagrams
src/schema/story.ts The schema for storyboards
src/schema/schemas.ts Exports both schemas. This is the entry point for the build
src/schema/validate.ts lintSource returns the issues in a source, with positions. srcOf finds the src: path of an embed. The "did you mean" hint uses the closest known key
src/schema/complete.ts Completion (completeAt), hover documentation (docsAt), item snippets (ITEM_SNIPPETS), definitions (definitionAt), and rename (renameAt)
src/schema/format.ts formatSource tidies a source
src/schema/blocks.ts findBlocks finds the ```flowmotion fences in a note
src/schema/index.ts Re-exports the schemas and lintSource for other code

Generated files

npm run schema (run by npm run build) bundles schemas.ts with esbuild and writes two files:

  • schema/diagram.schema.json
  • schema/storyboard.schema.json

Do not edit the JSON by hand. Change the TypeScript and run the script again. Commit the regenerated files with the change.

Limits and shared values

The values below are defined once, in src/core/types.ts, and used by both the schema and the parsers:

Name Value Meaning
LIMITS.nodes 200 Nodes per diagram
LIMITS.flows 400 Flows per diagram
LIMITS.events 1000 Events per diagram
LIMITS.label 120 Characters per label
LIMITS.duration 60000 Milliseconds per step
SHAPES, LINES, ENDS see the file The allowed shapes, line styles, and arrowheads
COLOR regular expression Accepts hex colours, rgb, hsl, and named colours. Safe for SVG attributes
SAFE_HREF regular expression Accepts http, https, obsidian://, and # links only

Adding a field

  1. Add the field to the schema object in src/schema/diagram.ts or src/schema/story.ts. Give it a description, so that hover help works.
  2. Add the runtime check in the parser (src/core/parse.ts, src/story/parse.ts). Use the LIMITS and the shared values where they apply.
  3. Run npm run schema.
  4. Add a test to test/schema.test.ts and a parsing test in the matching test file.
  5. Update the authoring reference, the related user-facing topic page, and the cookbook when its examples are affected.
  6. Validate complete cookbook definitions with lintSource and buildModel; inspect visual output when behavior changes.

Error reporting

  • A problem is reported with its position in the source. The position lets the editor underline the right text.
  • Where a fix is clear, the issue carries a suggested replacement. The plugin turns it into a quick fix.
  • Diagnostics in a note come from lintSource, through src/obsidian/language.ts. See Obsidian plugin.

Related pages

Clone this wiki locally