Repository navigation
Developer Schema and Validation
Vivek Sarin edited this page Nov 20, 2026
·
2 revisions
FlowMotion has three places that describe its formats. They must agree:
-
The JSON Schema for YAML diagrams and storyboards. Editors such as VS Code (through
yaml-language-server) use it for completion and hover help. - The runtime checks in the parsers. These decide whether a diagram is valid when it is drawn.
- 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.
| 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 |
npm run schema (run by npm run build) bundles schemas.ts with esbuild and writes two files:
schema/diagram.schema.jsonschema/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.
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 |
- Add the field to the schema object in
src/schema/diagram.tsorsrc/schema/story.ts. Give it adescription, so that hover help works. - Add the runtime check in the parser (
src/core/parse.ts,src/story/parse.ts). Use theLIMITSand the shared values where they apply. - Run
npm run schema. - Add a test to
test/schema.test.tsand a parsing test in the matching test file. - Update the authoring reference, the related user-facing topic page, and the cookbook when its examples are affected.
- Validate complete cookbook definitions with
lintSourceandbuildModel; inspect visual output when behavior changes.
- 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, throughsrc/obsidian/language.ts. See Obsidian plugin.
© 2026 @vrsarin. FlowMotion documentation.