opencode icon indicating copy to clipboard operation
opencode copied to clipboard

feat: add JSON Schema as source of truth for type definitions

Open TonyMarkham opened this issue 1 week ago • 1 comments

Summary

This PR implements JSON Schema as the canonical source of truth for OpenCode's type definitions, addressing #6879.

72+ JSON Schema files now define all major type domains, with Zod validators auto-generated from them.

What's Included

Domain Schemas Key Types
Model 8 files ModelInfo, ModelCost, ModelCapabilities, ModelLimits
Provider 6 files ProviderInfo, ProviderOptions, ProviderSource
Auth 4 files Auth, ApiAuth, OAuth, WellKnownAuth
Session 10 files SessionInfo, SessionTime, SessionSummary, FileDiff
Message 20 files Message, UserMessage, AssistantMessage, all Part types, Error types
Tool 9 files ToolState, ToolPart, PermissionRequest, PermissionReply
Agent 2 files AgentInfo, AgentModel
Event 13 files Event, GlobalEvent, SessionStatus, all event types

Implementation

  1. Custom code generator (script/generate-from-schemas.ts)

    • Validates schemas with AJV
    • Generates Zod validators + TypeScript types
    • Handles cross-file $ref correctly (existing tools don't)
    • Integrated with bun run generate workflow
  2. Refactored source files to use generated validators:

    • provider.ts, message-v2.ts, permission/next.ts
    • agent/agent.ts, session/status.ts, server/server.ts
  3. Documentation in schema/README.md

Results

  • ✅ All 87 schemas validate
  • ✅ All 544 tests pass
  • ✅ TypeScript compilation passes
  • ✅ Build succeeds (11 platforms)
  • ✅ Runtime behavior unchanged

Benefits for External Clients

# Rust
typify schema/modelInfo.schema.json

# Python
datamodel-codegen --input schema/ --output opencode_types/

# C#
NJsonSchema.CodeGeneration schema/modelInfo.schema.json

Technical Notes

  • Generated files are gitignored (build artifacts)
  • Zod 4.x compatible
  • z.union()z.discriminatedUnion() where schema has discriminator (behavioral equivalence)

Closes #6879

TonyMarkham avatar Jan 05 '26 20:01 TonyMarkham