Skip to content

riddlc - The RIDDL Compiler

riddlc is the command-line compiler for RIDDL. It parses, validates, and transforms RIDDL specifications.

Quick Start

# Validate a RIDDL file
riddlc validate mymodel.riddl

# Show help
riddlc help

# Show version
riddlc version

Key Features

  • Syntax validation - Verify RIDDL files are syntactically correct
  • Semantic validation - Check references, types, and containment rules
  • BAST serialization - Convert to binary format for faster loading
  • Style checking - Optional warnings for convention violations
  • Reformatting - Standardize RIDDL source layout

Documentation Generation

Hugo documentation generation and diagram generation have been moved to the riddl-gen repository. Use Synapify for integrated documentation generation with AI assistance.

Documentation

Section Description
Installation Download or build from source
Command Reference Full command and option documentation
Configuration Using HOCON configuration files
Compilation Understanding the compilation process
GitHub Actions CI/CD integration

Example Usage

Basic Validation

riddlc validate mymodel.riddl

Verbose Output with Timing

riddlc validate --verbose --show-times mymodel.riddl

Using Configuration File

riddlc from riddl.conf validate

Generate BAST for Faster Loading

riddlc bastify mymodel.riddl

Search the Model

riddlc find searches the resolved model, so it sees definitions the way the compiler does rather than as text:

riddlc find mymodel.riddl -- -type entity -name 'Order*'

See find for the full predicate and action vocabulary, including the editing actions.

Fail a Build on Warnings

riddlc validate mymodel.riddl --fail-on warning

Diagnostics as Data

Every message carries a stable rule id, and --json emits them for tooling:

riddlc validate mymodel.riddl --json | jq -r '.[].rule' | sort | uniq -c | sort -rn

Common Workflows

Development Cycle

  1. Edit RIDDL source files
  2. Run riddlc validate to check for errors
  3. Fix any issues reported
  4. Repeat

CI/CD Pipeline

- name: Validate RIDDL
  run: riddlc validate --warnings-are-fatal src/main/riddl/model.riddl

Using with sbt

See sbt-riddl for sbt integration.

Getting Help

# General help
riddlc help

# Help for specific command
riddlc help validate

Build Information

Check your installed version:

riddlc info

Output:

[info] About riddlc:
[info]            name: riddlc
[info]         version: 1.1.2
[info]   documentation: https://riddl.tech
[info]       copyright: © 2019-2026 Ossum Inc.
[info]        licenses: Apache License, Version 2.0
[info]    organization: Ossum Inc.
[info]   scala version: 3.3.7

Resources