Varavel Definition Language

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.

Get started See available plugins

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

contracts for humans
Readable
generated code
Type-safe
plugin outputs
Multi-lang
format and checks
CI-ready

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 @httpRpc, @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.

  • Install the CLI

    Install VDL with the shell installer, Homebrew, PowerShell, npm, Docker, or release binaries.

    Install VDL

  • Model the contract

    Create readable .vdl files for shared types, HTTP RPC operations, event payloads, documentation, and metadata.

    Learn the language

  • Run generation

    Point vdl.config.vdl at your schema and plugins, then run vdl generate locally or in CI.

    Configure a project

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 overview
  • Language

    Start Here

    Learn the VDL syntax in order, from files and comments to naming and validation.

    Learn syntax
  • Project setup

    Project Configuration

    Configure vdl.config.vdl, plugin sources, output directories, remotes, hooks, and lock files.

    Configure generation
  • Extension

    Creating Plugins

    Build custom JavaScript or TypeScript plugins that consume the resolved VDL IR.

    Write a plugin

Ready 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.

Install VDL Open the language guide

Generated files are regular files: inspect them, test them, commit them, or regenerate them in CI.