YAML & Project Structure

YAML & Project Structure

Project layout, YAML definition files, and naming conventions.

Directory Layout

myapp/
├── .wippy.yaml          # Runtime configuration
├── wippy.lock           # Source directories config
├── .wippy/              # Installed modules
└── src/                 # Application source
    ├── _index.yaml      # Entry definitions
    ├── api/
    │   ├── _index.yaml
    │   └── *.lua
    └── workers/
        ├── _index.yaml
        └── *.lua

YAML Definition Files

YAML definitions are loaded into the registry at startup. The registry is the source of truth - YAML files are one way to populate it. Entries can also come from other sources or be created programmatically.

File Structure

Any YAML file with a namespace plus either an entries array or a top-level name+kind is a valid definition file. version is optional:

version: "1.0"
namespace: app.api

entries:
  - name: get_user
    kind: function.lua
    meta:
      comment: Fetches user by ID
    source: file://get_user.lua
    method: handler
    modules:
      - sql
      - json

  - name: get_user.endpoint
    kind: http.endpoint
    meta:
      comment: User API endpoint
    method: GET
    path: /users/{id}
    func: get_user

Field	Required	Description
version	no	Schema version (currently "1.0")
namespace	yes	Entry namespace for this file
entries	yes	Array of entry definitions

Naming Convention

Use dots (.) for semantic separation and underscores (_) for words:

# Function and its endpoint
- name: get_user              # The function
- name: get_user.endpoint     # Its HTTP endpoint

# Multiple endpoints for same function
- name: list_orders
- name: list_orders.endpoint.get
- name: list_orders.endpoint.post

# Routers
- name: api.public            # Public API router
- name: api.admin             # Admin API router

Pattern: base_name.variant - dots separate semantic parts, underscores separate words within a part.

Namespaces

Namespaces are dot-separated identifiers:

app
app.api
app.api.v2
app.workers

Entry full ID combines namespace and name: app.api:get_user

Source Directories

The wippy.lock file defines where Wippy loads definitions from:

directories:
  modules: .wippy
  src: ./src

Wippy recursively scans these directories for YAML files.

Entry Definitions

Each entry in the entries array. Properties are at root level (no data: wrapper):

entries:
  - name: hello
    kind: function.lua
    meta:
      comment: Returns hello world
    source: file://hello.lua
    method: handler
    modules:
      - http
      - json

  - name: hello.endpoint
    kind: http.endpoint
    meta:
      comment: Hello endpoint
    method: GET
    path: /hello
    func: hello

Metadata

Use meta for UI-friendly information:

- name: payment_handler
  kind: function.lua
  meta:
    title: Payment Processor
    comment: Handles Stripe payments
  source: file://payment.lua

Convention: meta.title and meta.comment render nicely in management UIs.

Application Entries

Use registry.entry kind for application-level configuration:

- name: config
  kind: registry.entry
  meta:
    title: Application Settings
    type: application
  environment: production
  features:
    dark_mode: true
    beta_access: false

Common Entry Kinds

Kind	Purpose
registry.entry	General-purpose data
function.lua	Callable Lua function
process.lua	Long-running process
http.service	HTTP server
http.router	Route group
http.endpoint	HTTP handler
process.host	Process supervisor

See Entry Kinds Guide for complete reference.

Configuration Files

.wippy.yaml

Runtime configuration at project root:

version: "1.0"

logger:
  encoding: json

logmanager:
  min_level: 0

supervisor:
  host:
    worker_count: 16

See Configuration Guide for all options.

wippy.lock

Defines source directories:

directories:
  modules: .wippy
  src: ./src

Referencing Entries

Reference entries by full ID or relative name. Children attach to their parent through meta, not via parent-side lists:

# Router declares itself against a server
- name: api
  kind: http.router
  meta:
    server: app:gateway
  prefix: /api

# Endpoint references router by registry ID (cross-namespace works the same way)
- name: get_user.endpoint
  kind: http.endpoint
  meta:
    router: app.api:api
  method: GET
  path: /users/{id}
  func: app.api:get_user

Example Project

myapp/
├── .wippy.yaml
├── wippy.lock
└── src/
    ├── _index.yaml           # namespace: app
    ├── api/
    │   ├── _index.yaml       # namespace: app.api
    │   ├── users.lua
    │   └── orders.lua
    ├── lib/
    │   ├── _index.yaml       # namespace: app.lib
    │   └── database.lua
    └── workers/
        ├── _index.yaml       # namespace: app.workers
        └── email_sender.lua

See Also

• Entry Kinds Guide - Available entry kinds
• Configuration Guide - Runtime options
• Custom Entry Kinds - Implementing handlers (advanced)