Includes

Why Includes Exist

As schemas grow, it is useful to split them into focused files.

For example:

schema.vdl
shared.vdl
events.vdl

Use include to bring definitions from another .vdl file into the same compilation context.

include "./shared.vdl"

type UserSession {
  token string
  account Account
}

The included file can define types, enums, constants, or documentation used by the current file.

Example shared.vdl:

type Account {
  id string
  email string
}

Example schema.vdl:

include "./shared.vdl"

type Session {
  account Account
  token string
}

Session.account can use Account because schema.vdl includes shared.vdl.

Include paths are resolved relative to the file that contains the include statement.

include "../shared/types.vdl"
include "./events/user_events.vdl"

This makes each file self-contained: moving the entry point does not change how nested includes are resolved.

Includes are recursive. If schema.vdl includes orders.vdl, and orders.vdl includes money.vdl, all three files are analyzed together.

include "./orders.vdl"

type Checkout {
  order Order
}

Each file is processed once. Circular includes are reported as diagnostics.

Regular included schema files should have names matching this pattern:

[a-z0-9_]+.vdl

Good names:

shared.vdl
order_events.vdl
api_v1.vdl

Avoid names like:

Shared.vdl
order-events.vdl
schema.backup.vdl

vdl.config.vdl is the project generation configuration file. It cannot be included as a normal schema file.

Keep language schemas and generation configuration separate:

schema.vdl        # Your contracts
vdl.config.vdl    # Plugin generation configuration