VS Code Extension for RIDDL¶

The RIDDL Language Support extension provides comprehensive development tools for the RIDDL language in Visual Studio Code, including intelligent code completion, real-time diagnostics, and code navigation.

Release Notes

Installation¶

Beta Program¶

The extension is currently in beta. To install:

Download the .vsix file from GitHub Release Assets
Open VS Code
Press Cmd+Shift+P (Mac) or Ctrl+Shift+P (Windows/Linux)
Type "Install from VSIX" and select it
Browse to the downloaded .vsix file
Click Install and reload VS Code

Or via command line:

code --install-extension /path/to/riddl-vscode-0.9.0-beta.vsix

VS Code Marketplace (Coming Soon)¶

When version 1.0 is released, installation will be simpler:

Open VS Code
Click the Extensions tab in the left sidebar
Search for "RIDDL"
Click Install

Requirements¶

VS Code 1.75.0 or later
No additional runtime dependencies (RIDDL parser is bundled)

Features¶

Syntax Highlighting¶

The extension provides rich syntax highlighting using both TextMate grammar (fast initial highlighting) and semantic tokens (context-aware refinement):

Element	Description
Keywords	`domain`, `context`, `entity`, `type`, `command`, `event`, etc.
Predefined Types	`String`, `Integer`, `Boolean`, `Timestamp`, `UUID`, etc.
Readability Words	`is`, `of`, `by`, `for`, `to`, `from`, `with`, `and`, etc.
Comments	Line (`//`) and block (`/* */`) comments
Strings	Quoted string literals with escape sequences
Documentation	Markdown lines starting with `\\|`

Code Completion (IntelliSense)¶

Press Ctrl+Space to trigger completion, or just start typing. The extension provides:

Keywords with Snippets¶

Over 50 keywords with intelligent snippets:

Keyword	Snippet Produces
`domain`	Full domain structure with braces
`context`	Context definition template
`entity`	Entity with state and handlers
`type`	Type definition
`command`	Command message definition
`event`	Event message definition
`handler`	Handler with `on` clause template
`saga`	Saga with steps template

Example: Type entity and press Tab:

entity Name is {
  // cursor here
}

Predefined Types¶

All RIDDL predefined types with documentation:

String, Integer, Number, Boolean, Decimal
Date, Time, DateTime, Timestamp, Duration
Id, UUID, URL, UserId
List, Set, Map, Sequence
And more...

Readability Words¶

Structural keywords that improve RIDDL readability:

is, of, by, for, to, from, with
and, or, not, in, on, at

Hover Documentation¶

Hover over any keyword, type, or readability word to see documentation:

Keywords: Comprehensive descriptions with usage notes
Types: Type-specific documentation with examples
Readability Words: Explanations of structural role
User Definitions: Location information (line/column)

Real-Time Diagnostics¶

The extension validates your RIDDL as you type:

Severity	Indicator	Examples
Error	Red squiggly	Syntax errors, undefined references
Warning	Yellow squiggly	Missing documentation, style issues
Info	Blue squiggly	Suggestions and hints

Diagnostics integrate with the VS Code Problems panel (Cmd+Shift+M).

Performance

Validation is debounced by 500ms to avoid excessive parsing while typing.

Go to Definition¶

Navigate to where a symbol is defined:

Press F12 with cursor on a symbol
Or Cmd + click (Mac) / Ctrl + click (Windows/Linux)

Works for:

Type definitions
Entity, context, domain references
Command, event, query references

Find All References¶

Find everywhere a symbol is used:

Press Shift+F12 with cursor on a symbol
Or right-click and select Find All References

Document Outline, Breadcrumbs and Go to Symbol¶

The extension publishes the definition hierarchy of the open file, built from the RIDDL parse tree rather than guessed from indentation. That drives three standard VS Code features at once:

Feature	How to reach it
Outline view	Explorer sidebar → Outline
Breadcrumbs	The bar above the editor
Go to Symbol	`Cmd`+`Shift`+`O` (Mac) / `Ctrl`+`Shift`+`O` (Windows/Linux)

Because it comes from the parse tree, the outline shows the real containment — domains holding contexts holding entities — and follows the file as you edit.

Handler Completeness Diagnostics¶

A handler that is empty, or whose body is nothing but prompt placeholders, is reported as a warning. It parses and it is valid RIDDL — it simply has not said what happens yet, which is easy to leave behind and hard to spot by eye.

Commands¶

Access commands via the Command Palette (Cmd+Shift+P / Ctrl+Shift+P):

RIDDL: Version Information¶

Shows RIDDL build information including:

RIDDL library version
Build date
Scala/sbt versions
Feature list
Documentation links

RIDDL: Parse Current File¶

Parses the active .riddl file and displays:

Full AST structure (JSON format)
Parse errors with locations

Useful for debugging complex syntax issues.

RIDDL: Validate Current File¶

Runs full validation (syntax + semantic) and shows:

Error count
Warning count
Info message count
Detailed messages with locations

RIDDL: Translate to Output Format¶

Placeholder for future translation features. Shows available riddlc commands.

Keyboard Shortcuts¶

Extension Commands¶

Shortcut	Command
`Cmd`+`Shift`+`P` / `Ctrl`+`Shift`+`P`	Open Command Palette (type "RIDDL" to filter)

Code Navigation¶

Shortcut	Action
`F12`	Go to Definition
`Shift`+`F12`	Find All References
`Cmd` + click / `Ctrl` + click	Go to Definition
`Ctrl`+`Space`	Trigger code completion

Editor Features¶

Shortcut	Action
`Cmd`+`/` / `Ctrl`+`/`	Toggle line comment (`//`)
`Shift`+`Alt`+`A`	Toggle block comment (`/* */`)
`Cmd`+`Shift`+`[` / `Ctrl`+`Shift`+`[`	Fold region
`Cmd`+`Shift`+`]` / `Ctrl`+`Shift`+`]`	Unfold region

Built-in RIDDL Editor Features¶

The extension configures these editor behaviors:

Auto-closing brackets: {, [, (, ", and triple backticks
Bracket matching: All bracket types highlighted
Code folding: Fold on braces and //region markers
Smart indentation: Automatic indent after opening brackets

Output Panel¶

Commands write results to the RIDDL output channel:

Open View > Output (or Cmd+Shift+U)
Select RIDDL from the dropdown

Output includes:

Command results with formatting
Numbered error/warning messages
Clean text (ANSI codes stripped)

File Association¶

The extension automatically activates for files with the .riddl extension:

Language ID: riddl
File Icon: Custom RIDDL icon (light and dark variants)
Content Type: Text with RIDDL grammar

Configuration¶

The extension works out-of-the-box with sensible defaults. No user configuration is required.

Editor Settings for RIDDL¶

You can customize VS Code editor settings specifically for RIDDL files:

{
  "[riddl]": {
    "editor.tabSize": 2,
    "editor.insertSpaces": true,
    "editor.formatOnSave": false,
    "editor.wordWrap": "on"
  }
}

Semantic Highlighting¶

Semantic highlighting is enabled by default. To disable:

{
  "editor.semanticHighlighting.enabled": false
}

Usage Tips¶

Efficient Editing¶

Use snippets: Type a keyword and press Tab for full structure
Hover for docs: Check documentation without leaving the editor
Navigate quickly: F12 to jump to definitions, Alt+Left to go back
Check Problems panel: Cmd+Shift+M for all issues at a glance

Working with Large Models¶

Use folding: Collapse sections you're not editing
Split editor: Work on multiple files side-by-side
Use includes: Break large models into smaller files

// main.riddl
domain MyProject is {
  include "contexts/orders.riddl"
  include "contexts/inventory.riddl"
}

Understanding Errors¶

Error messages include file location:

[orders.riddl:42:15] Error: Undefined reference to type 'CustomerID'

This means: orders.riddl, line 42, column 15.

Click the error in the Problems panel to jump directly to the location.

Validation Source Labels¶

Diagnostics show their source:

RIDDL - Parse/syntax errors
RIDDL (validation) - Semantic validation errors/warnings
RIDDL (info) - Informational messages

Troubleshooting¶

Extension Not Activating¶

Verify file has .riddl extension
Check Output > Extension Host for errors
Try Developer: Reload Window

No Syntax Highlighting¶

Check file type in status bar (should show "RIDDL")
Verify extension is enabled in Extensions panel
Try disabling other extensions that might conflict

Slow Performance¶

Large files may take longer to parse
Semantic highlighting has 500ms debounce
Check for syntax errors that might confuse the parser

Errors Not Showing¶

Check Problems panel is visible (Cmd+Shift+M)
Verify the file has been saved (diagnostics run on save)
Look for parse errors that might prevent full validation

Authoring RIDDL¶

For tips on writing effective RIDDL source files, see the Authoring RIDDL Sources guide.

Support¶

Bug Reports: GitHub Issues
Questions: support@ossuminc.com
Contributing: GitHub Repository

License¶

Apache License 2.0