Schemas & Validation
Relevant source files
The following files were used as context for generating this wiki page:
Schemas and validation in OCX serve as the structural backbone for maintaining consistency across the monorepo, its CLI tool, and the various AI components (skills, plugins, and agents) it manages. By leveraging Zod for schema definition, OCX enforces a "Parse, Don't Validate" philosophy, ensuring that data crossing boundaries—such as configuration files, registry manifests, or implementation plans—is immediately transformed into trusted, typed structures.
The validation system is distributed across the CLI for registry building and configuration management, and within specific plugins (like the Workspace Plugin) for real-time validation of human-AI collaboration artifacts like implementation plans. This ensures technical accuracy and project-wide adherence to defined standards.
Sources: AGENTS.md:144-154, examples/registry-starter/AGENTS.md:23-38, workers/kdco-registry/files/plugin/workspace-plugin.ts:161-177
Core Validation Philosophy: The 5 Laws
OCX validation logic adheres to a specific architectural framework known as the "5 Laws of Elegant Defense." This approach prioritizes early failure and strict data boundaries to reduce runtime complexity.
| Law | Principle | Implementation Detail |
|---|---|---|
| Early Exit | Guard clauses at function tops | Functions return early on invalid input to avoid deep nesting. |
| Parse, Don't Validate | Transform at boundaries | Use Zod schemas to convert unknown data into typed data once at the entry point. |
| Atomic Predictability | Pure functions | Functions are designed to produce the same output for the same input without hidden state. |
| Fail Fast, Fail Loud | Clear errors | Systems throw descriptive exceptions or return detailed errors immediately upon failure. |
| Intentional Naming | Self-documenting code | Variable and function names are chosen to reveal logic and intent clearly. |
Sources: examples/registry-starter/AGENTS.md:17-64, workers/kdco-registry/files/plugin/workspace-plugin.ts:161-177
Implementation Plan Validation
The Workspace Plugin implements a sophisticated validation pipeline for AI-generated implementation plans. This system uses a hierarchical Zod schema to enforce specific formatting for tasks, phases, and frontmatter.
Plan Schema Structure
The diagram above illustrates the nested relationship of the implementation plan components, where a plan is composed of metadata (frontmatter) and a sequence of phases containing individual tasks.
Sources: workers/kdco-registry/files/plugin/workspace-plugin.ts:11-47
Data Flow: Markdown to Typed Plan
Validation follows a two-step process: raw extraction from Markdown followed by structured Zod parsing.
This flowchart describes the "Parse, Don't Validate" implementation in workspace-plugin.ts, where raw text is first extracted into an intermediate object before being validated against the strict Zod schema.
Sources: workers/kdco-registry/files/plugin/workspace-plugin.ts:98-158, workers/kdco-registry/files/plugin/workspace-plugin.ts:161-177
CLI & Registry Schemas
OCX utilizes a set of common schemas within packages/cli to validate component names, namespaces, and target paths. These schemas use strict regex patterns to prevent invalid naming conventions across registries.
Naming Conventions & Regex Constraints
| Schema | Pattern / Constraint | Example |
|---|---|---|
openCodeNameSchema | Lowercase, hyphens allowed, no special chars, max 64 chars | researcher, my-component |
namespaceSchema | Same as openCodeNameSchema | kdco, my-namespace |
qualifiedComponent | namespace/component | kdco/researcher |
targetPathSchema | Must start with .opencode/ and use valid directories | .opencode/plugin/foo.ts |
Sources: packages/cli/tests/schemas.test.ts:14-118
Configuration Schemas
The CLI also manages schemas for agent configurations and permissions, allowing for fine-grained control over what tools an AI agent can access.
// Example of permission configuration validation
const permissionConfig = {
bash: { "*": "deny", "git *": "allow" },
edit: { "*.md": "allow", "*.ts": "ask" },
mcp: { "dangerous-mcp": "deny" }
}
// Sources: [packages/cli/tests/schemas.test.ts:311-330]
Error Handling & Reporting
Validation systems in OCX are designed to be "loud." The formatZodErrors function in the Workspace Plugin ensures that instead of a generic "Invalid" message, the system provides the specific path to the error and a helpful context message.
- Missing Fields: Reported as "Required field missing."
- Invalid Enums: Lists the received value versus the expected valid options.
- Regex Failures: Provides specific format requirements (e.g., "Date must be YYYY-MM-DD").
Sources: workers/kdco-registry/files/plugin/workspace-plugin.ts:129-155
Conclusion
Schemas & Validation in OCX are not merely data checks but an architectural enforcement layer. By combining strict Zod schemas with a clear "5 Laws" philosophy, the project ensures that data remains predictable and safe as it moves between developers, CLI tools, and AI agents. This structure allows for complex features like implementation plan tracking and cross-registry dependency management to function reliably.