Package Format

Structure

An .oikapp package is a compressed tar.gz archive containing:

app-name-1.0.0.oikapp
├── oikapi.json              # App metadata (required)
├── operations.json          # Schema + demo data operations (required)
├── checksums.sha256         # SHA256 checksums (required)
├── signature.json           # Ed25519 signature (optional)
├── rules/                   # Externalized business rule scripts (optional)
├── templates/               # Externalized document template content (optional)
├── webapp/                  # Web application source files (optional)
│   └── <name>/App.tsx
├── emails/                  # Compiled email templates (optional)
├── generated/               # TypeScript type definitions (optional)
└── demo-data/               # Demo data records (optional)

Content like business rule scripts and document templates are externalized from operations.json into separate files for readability and version control.

Auto-prefixing

When building a package, the builder automatically prefixes all resource names with the app name:

Source	Package
tables/projects.json	myapp_projects
tables/tasks.json	myapp_tasks
"target_table": "tasks"	"target_table": "myapp_tasks"
"system.users"	"system.users" (preserved)

This prevents naming conflicts when multiple apps are installed on the same instance.

Building

# Validate first
oi validate my-app

# Build the package
oi build my-app

# Output: my-app-1.0.0.oikapp

Installing

# Install from the marketplace
oi app install @oikapi/my-app

# Install a specific version
oi app install @oikapi/my-app@1.2.0

# Install from a local file
oi app install ./my-app-1.0.0.oikapp

Any demo data shipped in the package is managed separately once installed — see oi app demo.

Signing

Packages can be cryptographically signed with Ed25519 keys for supply-chain security. The signature is stored as signature.json and covers the package’s checksums.sha256, so any tampering with a packaged file invalidates it. The marketplace verifies signatures and surfaces verification status to users.