VPP-0: Core

VPP-0: Core defines the expectations for foundational plugins that generate the most primitive VDL artifacts for a target language.

A Core plugin is responsible for turning plain VDL declarations into idiomatic source code. It should generate the basic model layer that the rest of the ecosystem can trust: types, enums, and constants.

Core plugins are intentionally narrow. They do not implement other plugn behavior like RPC, event routing, authorization policy, etc. Their job is to produce a stable, high-quality foundation that other plugins can build on.

Scope

A VPP-0 Core plugin handles exactly these VDL declaration families.

1. Types: structured object declarations and their fields.
2. Enums: named sets of allowed values.
3. Constants: named literal values declared with const.

Everything outside those primitives belongs to another protocol or to an extension plugin.

For example, a Core plugin may generate a Go struct, a TypeScript interface, a Rust struct, an enum type, or exported constants. It should not generate HTTP handlers, event publishers, policy evaluators, or application-specific code.

Purpose

Core plugins exist for two reasons.

First, they are useful on their own. Many projects only need strongly typed models, enums, and constants generated from a shared schema. A good Core plugin should make that workflow simple, predictable, and idiomatic.

Second, they provide the base layer for higher-level plugins. Other protocols often need to refer to the generated representation of a VDL type, enum, or constant. A stable Core output gives those plugins something concrete to import, reference, extend, or wrap.

This makes Core plugins the foundation of the VDL plugin ecosystem.

Language Idioms

Core output must be idiomatic for the target language.

The protocol defines semantic expectations, not one universal code shape. A TypeScript Core plugin should feel natural to TypeScript users. A Go Core plugin should feel natural to Go users. A Rust Core plugin should feel natural to Rust users.

Idiomatic output includes language-appropriate naming, file organization, visibility rules, literal representation, enum modeling, documentation comments, and serialization tags when the target ecosystem conventionally expects them.

The generated code should look like code a skilled developer in that language would be comfortable maintaining, even though it is generated.

Plugin Naming

Core plugins should use the name vdl-plugin-<language>, where <language> is the target language generated by the plugin (or a commonly recognized abbreviation).

Examples include vdl-plugin-go and vdl-plugin-ts.

This naming convention should be respected as much as possible so users can quickly identify the foundational plugin for a target language and other plugins can refer to it consistently.

Stability Requirements

Core plugins must prioritize stable, deterministic output.

Given the same input schema and configuration, a Core plugin should produce the same files, names, and exported symbols every time. This allows downstream plugins, application code, tests, and generated documentation to reference Core artifacts safely.

A compliant Core plugin should avoid unnecessary renames, unstable file splitting, random ordering, environment-dependent output, or hidden behavior that makes generated artifacts difficult to depend on.

Extension Points

Core plugins should be easy for other plugins to build on.

Higher-level plugins need a reliable way to know where Core artifacts were generated and how to reference them. A Core plugin should therefore expose clear configuration for its output location and use predictable import paths, package names, module names, or file names according to the target language.

Other plugins should be able to say, in effect: "the Core model layer was generated here; import or reference it from there."

This does not require every Core plugin to share the same directory layout. It does require each Core plugin to make its layout deterministic, documented, and configurable enough for composition.

Relationship With Other Protocols

VPP-0 Core is the base layer. Other protocols may depend on it, but Core must not depend on them.

A Core plugin may preserve protocol metadata in comments, annotations, generated metadata files, or language-specific attributes when doing so is useful and non-invasive. However, it must not implement the behavior of other protocols as part of Core generation.

For example, if a declaration is marked as deprecated under VPP-1, a Core plugin may emit the appropriate language-level deprecation comment, attribute, or feature to preserve the semantics defined by that protocol. That is still compatible with Core because it affects the generated representation of a primitive declaration. By contrast, generating an RPC server from @rpc belongs to the RPC protocol, not to VPP-0 Core.

Expected Behavior

A compliant Core plugin should follow these rules.

1. Generate declarations for VDL types, enums, and constants only.
2. Preserve the semantic meaning of VDL primitives in the target language.
3. Produce idiomatic code for the target ecosystem.
4. Keep output deterministic and stable across runs.
5. Provide clear, documented output locations for downstream plugins.
6. Avoid implementing higher-level protocol behavior directly.
7. Respect cross-cutting standards, such as deprecation metadata, when they apply to generated primitive artifacts.

VPP-0 Core is deliberately simple. Its strength comes from being small, predictable, and dependable enough to serve as the foundation for everything else.