DSL reference

The .dvk file format is a domain-specific language for describing backend APIs. It is parsed by a hand-written recursive descent parser and compiled to TypeScript.

The syntax is intentionally constrained. This makes it suitable for AI-assisted generation — an LLM can produce valid .dvk files with very few tokens and no risk of hallucinating invalid imports or architecture.

Project declaration

Every .dvk file starts with top-level declarations that configure the project.

project "my-api"
database "supabase"
framework "express"
auth "jwt"
language "typescript"

Keyword	Values	Default
project	Any string — used as the npm package name	(required)
database	"supabase", "postgresql", "mysql", "sqlite"	"supabase"
framework	"express", "fastify", "hono"	"express"
auth	"jwt", "session", "apikey", "none"	"jwt"
language	"typescript", "javascript"	"typescript"

Models

Models define your data structures. Each model maps to a database table and generates a TypeScript interface plus a Zod validation schema.

model User {
  id        uuid       @primary
  email     string     @unique
  name      string
  role      enum       [admin, user, moderator]
  score     float
  active    boolean
  bio       text
  created   datetime   @default(now)
}

Field types

DSL type	TypeScript type	Zod validator
uuid	string	z.string().uuid()
string	string	z.string()
text	string	z.string()
email	string	z.string().email()
int / integer	number	z.number().int()
float / number / decimal	number	z.number()
bool / boolean	boolean	z.boolean()
datetime / date / timestamp	string	z.string().datetime()
enum	string	z.string()
json / object	Record<string, unknown>	z.record(z.unknown())

Field attributes

Attribute	Effect
@primary	Marks the field as the primary key
@unique	Adds a uniqueness constraint
@default(value)	Sets a default value. Use @default(now) for timestamps
[value1, value2]	Defines allowed enum values

Routes

Route groups define HTTP endpoints. Each group has a base path and contains individual routes that map HTTP methods to actions on models.

route "/users" {
  GET    "/"      -> list(User)     @auth
  POST   "/"      -> create(User)   @admin
  GET    "/:id"   -> get(User)      @auth
  PUT    "/:id"   -> update(User)   @auth
  DELETE "/:id"   -> delete(User)   @admin
}

HTTP methods

Supported methods: GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS.

Actions

Action	Generated behavior
list(Model)	Returns an array of all records
get(Model)	Returns a single record by ID from the URL parameter
create(Model)	Validates request body against the Zod schema, inserts a record
update(Model)	Validates a partial body, updates the record by ID
delete(Model)	Deletes a record by ID

Route attributes

Attribute	Effect
@auth	Requires a valid JWT token. Injects authenticate middleware
@admin	Requires authentication and an admin role
@public	No authentication required (this is the default)

Comments

Line comments start with // and are ignored by the parser.

// This is a comment
project "my-api"  // inline comment

Multiple files

FleetDVK reads all .dvk files in the current directory and concatenates them before parsing. You can split your spec across files:

config.dvk    # project, database, framework, auth
models.dvk    # all model definitions
routes.dvk    # all route groups

File order does not matter. The parser resolves all references after the full AST is built.