Skip to main content
The schema module provides comprehensive Zod schemas for type-safe validation of all configuration objects, service definitions, and API requests/responses.

​
Overview

All schemas are built using Zod for runtime validation and TypeScript type inference. Import schemas from @better-openclaw/core/schema. 
import { ServiceDefinitionSchema, GenerationInputSchema } from '@better-openclaw/core';

const input = GenerationInputSchema.parse(userInput);

​
Core Enums

​
ServiceCategorySchema

Defines available service categories. 
z.enum([
  "automation", "vector-db", "media", "storage", "database",
  "proxy", "monitoring", "browser", "search", "ai",
  "communication", "coding-agent", "social-media", "analytics",
  "ai-platform", "dev-tools", "knowledge", "desktop", "streaming", "security"
])

​
MaturitySchema

Service maturity level indicator. 
z.enum(["stable", "beta", "experimental"])

​
PlatformSchema

Supported deployment platforms. 
z.enum([
  "linux/amd64", "linux/arm64",
  "windows/amd64",
  "macos/amd64", "macos/arm64"
])

​
ProxyTypeSchema

Reverse proxy options. 
z.enum(["none", "caddy", "traefik"])

​
DeploymentTypeSchema

Deployment method for the stack. 
z.enum(["docker", "bare-metal", "local"])

​
DeploymentTargetSchema

Target environment for deployment. 
z.enum(["local", "vps", "homelab", "clawexa"])

​
Service Definition Schemas

​
ServiceDefinitionSchema

Complete schema for a service definition with Docker configuration, dependencies, and metadata.
​
id
string
required
Unique service identifier (lowercase alphanumeric with hyphens)
​
name
string
required
Human-readable service name
​
description
string
required
Service description
​
category
ServiceCategory
required
Service category
​
icon
string
required
Emoji or icon identifier
​
image
string
required
Docker image name
​
imageTag
string
required
Docker image tag
​
ports
PortMapping[]
default:"[]"
Port mappings for the service
​
volumes
VolumeMapping[]
default:"[]"
Volume mappings for the service
​
environment
EnvVariable[]
default:"[]"
Environment variable definitions
​
requires
string[]
default:"[]"
Required dependency service IDs
​
recommends
string[]
default:"[]"
Recommended companion service IDs
​
conflictsWith
string[]
default:"[]"
Service IDs that cannot coexist

​
PortMappingSchema

Defines a container port mapping.
​
host
number
required
Host port (1-65535)
​
container
number
required
Container port (1-65535)
​
description
string
required
Human-readable port description
​
exposed
boolean
default:"true"
Whether to expose on host network

​
VolumeMappingSchema

Defines a volume mount for a service.
​
name
string
required
Volume name or bind-mount path
​
containerPath
string
required
Mount path inside container
​
description
string
required
Volume purpose description
​
driver
string
Docker volume driver

​
EnvVariableSchema

Defines an environment variable for a service.
​
key
string
required
Environment variable name
​
defaultValue
string
required
Default value
​
secret
boolean
default:"false"
Whether this is a secret that should be auto-generated
​
description
string
required
Variable purpose description
​
required
boolean
default:"true"
Whether variable is required
​
validation
string
Regex pattern for value validation

​
Generation Input Schema

​
GenerationInputSchema

Input configuration for generating a complete OpenClaw stack.
​
projectName
string
required
Project name (lowercase alphanumeric with hyphens)
​
services
string[]
default:"[]"
Service IDs to include
​
skillPacks
string[]
default:"[]"
Skill pack IDs to include
​
aiProviders
AiProvider[]
default:"[]"
AI provider configurations
​
proxy
ProxyType
default:"none"
Reverse proxy to use
​
domain
string
Domain for proxy routing
​
platform
Platform
default:"linux/amd64"
Target platform
​
deployment
DeploymentTarget
default:"local"
Deployment target
​
deploymentType
DeploymentType
default:"docker"
Deployment method
​
generateSecrets
boolean
default:"true"
Auto-generate secret values
​
monitoring
boolean
default:"false"
Include monitoring stack
​
gpu
boolean
default:"false"
Enable GPU passthrough
​
openclawVersion
string
default:"latest"
OpenClaw version tag

​
Resolver Output Schema

​
ResolverOutputSchema

Output from the dependency resolver.
​
services
ResolvedService[]
required
All resolved services with dependency information
​
addedDependencies
AddedDependency[]
required
Dependencies automatically added
​
removedConflicts
object[]
required
Services removed due to conflicts
​
warnings
Warning[]
required
Non-blocking validation warnings
​
errors
Error[]
required
Blocking validation errors
​
isValid
boolean
required
Whether configuration is valid
​
estimatedMemoryMB
number
required
Estimated total memory requirement

​
Compose Options Schema

​
ComposeOptionsSchema

Options for Docker Compose file generation.
​
projectName
string
required
Docker Compose project name
​
proxy
ProxyType
default:"none"
Reverse proxy configuration
​
proxyHttpPort
number
Custom HTTP port for proxy
​
proxyHttpsPort
number
Custom HTTPS port for proxy
​
domain
string
Domain for routing
​
gpu
boolean
default:"false"
Enable GPU reservations
​
platform
Platform
default:"linux/amd64"
Target platform
​
hardened
boolean
default:"true"
Apply security hardening (cap_drop, no-new-privileges)
​
openclawInstallMethod
OpenclawInstallMethod
default:"docker"
How to install OpenClaw (docker or direct)

​
Usage Example

import {
  GenerationInputSchema,
  ServiceDefinitionSchema,
  type GenerationInput,
  type ServiceDefinition
} from '@better-openclaw/core';

// Validate user input
const input: GenerationInput = GenerationInputSchema.parse({
  projectName: 'my-stack',
  services: ['redis', 'postgresql'],
  proxy: 'caddy',
  domain: 'example.com',
  platform: 'linux/amd64',
  generateSecrets: true
});

// Define a custom service
const customService: ServiceDefinition = ServiceDefinitionSchema.parse({
  id: 'my-service',
  name: 'My Service',
  description: 'Custom service',
  category: 'automation',
  icon: '🚀',
  image: 'myorg/myservice',
  imageTag: 'latest',
  ports: [{
    host: 8080,
    container: 8080,
    description: 'HTTP API',
    exposed: true
  }],
  docsUrl: 'https://example.com/docs'
});

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us