Schema

The npm run dev script runs vovk dev alongside next dev via concurrently . The Vovk process watches the modules folder for controller and validation changes. On the first run or after changes, it calls the Next.js dev server’s _schema_ endpoint for the relevant segment (available only when process.env.NODE_ENV is development). That endpoint returns the schema for the target segment, enabling isolated JSON emission per segment. This works in the Edge Runtime  because route.ts files do not import Node.js modules like fs.

Each segment emits its backend schema to an individual JSON file, which is then used to generate client-side RPC modules. If your application has multiple areas (e.g., root, admin, customer), each area has its own schema file.

For a segment structure like this:

• src/app/api
  • [[...vovk]]
    • route.ts (root segment /api/)
  • admin/[[...vovk]]
    • route.ts (admin segment /api/admin)
  • customer/[[...vovk]]
    • route.ts (customer segment /api/customer)
    • static/[[...vovk]]
      • route.ts (static segment /api/customer/static for OpenAPI)

The resulting schema files are written to .vovk-schema/:

• .vovk-schema
  • root.json
  • admin.json
  • customer.json
  • customer
    • static.json
  • _meta.json

Emitted files mirror the segment tree. For example, a foo/bar/baz segment emits .vovk-schema/foo/bar/baz.json. The root segment is the only exception and uses root.json for clarity.

_meta.json contains additional metadata, including selected fields from vovk.config under the config key, plus other information.

When the Vovk CLI reads these files, it builds a single object with segments and meta. segments is flat, keyed by segment name, and meta contains the _meta.json content. This object powers client-side RPC generation and OpenAPI output, and is also available on both the client and server as the schema export.

{
  "segments": {
    "": { ... }, // root segment schema from root.json
    "admin": { ... }, // admin segment schema from admin.json
    "customer": { ... }, // customer segment schema from customer.json
    "customer/static": { ... } // static segment schema from customer/static.json
  },
  "meta": { ... } // content of _meta.json file
}

import { schema } from 'vovk-client';
// or
import { schema } from 'vovk-client/schema'; // exports only the schema object (no RPC modules)
 
import type { VovkSchema, VovkSegmentSchema } from 'vovk';
 
console.log(schema satisfies VovkSchema); // full schema
console.log(schema.segments.admin satisfies VovkSegmentSchema); // admin segment schema

The schema is also available in the segmented client, containing exactly one segment:

{
  "segments": {
    "": { ... } // root segment schema from root.json
  },
  "meta": { ... } // content of _meta.json file
}

import { schema } from '@client/root';
// or
import { schema } from '@client/root/schema';

Example of a segment schema file:

{
  // Segment schema version
  "$schema": "https://vovk.dev/api/spec/v3/segment.json",
  // initSegment option controlling whether this segment emits a schema
  "emitSchema": true,
  // Segment name; the root segment uses an empty string
  "segmentName": "foo",
  // Controllers as key-value pairs for fast access:
  // Key: exported RPC module name from "vovk-client"
  // Value: controller information
  "controllers": {
    "HelloRPC": {
      // RPC module name used on the client
      "rpcModuleName": "HelloRPC",
      // Original controller class name (used to resolve segment