Contract-first generation
One human-readable schema. Type-safe code across your stack.
VDL lets teams write compact contracts that humans can review and machines can validate. From one .vdl file, generate type-safe models, RPC clients and servers, schemas, docs, and custom artifacts for multiple languages.
Open source, deterministic, and designed for normal development and CI workflows.
How it works
Readable contract to type-safe outputs
A VDL project starts with declarations, not framework code. The analyzer enforces the model, then plugins generate the files each application needs.
.vdl
source files
Plugin
transforms IR
Code
type-safe outputs
Write contracts that are easy to read in code review
Validate references, naming, spreads, literals, and required type relationships
Generate type-safe code for frontend, backend, services, and tooling
What VDL gives you
Readable
contracts for humans
Type-safe
generated code
Multi-lang
plugin outputs
CI-ready
format and checks
The core idea
Keep the contract simple. Move the output logic into plugins.
VDL separates what your systems agree on from how each toolchain consumes it. The source stays readable, while generated artifacts stay precise and type-safe.
Describe the shared model
Use type, enum, const, include, docstrings, arrays, maps, inline objects, references, and spreads to describe the contract itself in a review-friendly format.
Add domain intent
Use annotations such as @rpc, @event, @deprecated, or your own team-specific tags without changing the language grammar.
Generate type-safe outputs
Official and custom easy to write plugins receive the resolved IR and generate language-specific code, schemas, docs, or internal artifacts.
Workflow
A straightforward path from schema to artifacts
The day-to-day loop is intentionally small: write the contract, configure plugins, and generate checked output.
01
Install the CLI
Install VDL with the shell installer, Homebrew, PowerShell, npm, Docker, or release binaries.
02
Model the contract
Create readable .vdl files for shared types, HTTP RPC operations, event payloads, documentation, and metadata.
03
Run generation
Point vdl.config.vdl at your schema and plugins, then run vdl generate locally or in CI.
Use cases
Use VDL anywhere systems need to agree on data
VDL is most useful when several parts of a product need the same contract, but each part needs it in its own language or format.
Share types across apps
Generate type-safe models for frontend, backend, workers, and microservices from the same source contract.
Build type-safe HTTP RPC
Model request and response shapes once, then generate typed clients, servers, and OpenAPI documents for frontend-to-backend communication.
Coordinate microservices
Keep service boundaries explicit with shared schemas, generated packages, and stable contracts that can be checked in CI.
Document and validate data
Generate JSON Schema, schema explorers, metadata exports, and documentation from docstrings and resolved types.
Standardize event contracts
Use @event declarations to generate subject builders and catalogs for event-driven systems.
Private team artifacts
Write custom plugins for your framework conventions, templates, catalogs, policies, or platform-specific glue code.
Read next
Choose the next step that matches your goal
The documentation starts with concepts, then moves into installation, configuration, plugin usage, and reference details.
Overview
About VDL
Understand the project philosophy, the plugin-first model, and common use cases.
Read overviewLanguage
Start Here
Learn the VDL syntax in order, from files and comments to naming and validation.
Learn syntaxProject setup
Project Configuration
Configure vdl.config.vdl, plugin sources, output directories, remotes, hooks, and lock files.
Configure generationExtension
Creating Plugins
Build custom JavaScript or TypeScript plugins that consume the resolved VDL IR.
Write a pluginReady to try it
Install VDL, write one schema, and generate your first outputs.
Start small: define a type, add a plugin, and run the generator. The same workflow scales to shared models, RPC services, event contracts, documentation, and private platform tooling.
Generated files are regular files: inspect them, test them, commit them, or regenerate them in CI.