Repository navigation
[DISCUSSION] Make config tolerant of unknown keys for forward compatibility #6145
Description
Problem
Currently, opencode.json uses Zod .strict() validation which rejects unknown config keys. This breaks when using a config file with newer options on an older OpenCode version.
Example scenario: A user has session_delete keybind configured (a newer option). When they run an older OpenCode version that doesn't recognize this key, config validation fails entirely instead of just ignoring the unknown key.
Proposed Solution
Change .strict() to .passthrough() on user-facing config schemas:
Keybinds(line 575)Provider(line 636)Info/ main config (line 831)
Internal schemas like McpLocal, McpRemote, McpOAuth remain .strict() since they're programmatic, not user-facing.
Additionally, add warning logs for unknown keys so users still get feedback about potential typos while configs from newer versions still work. This addresses the concern from #1081 about catching typos.
Tradeoffs
Pros:
- Forward compatibility - newer configs work on older versions
- Better UX when sharing configs across different OpenCode versions
- Users still get warning feedback about potential typos
Cons:
- Typos don't cause hard failures (but warnings are logged)
Implementation
Working implementation on branch feat/config-forward-compat at https://github.com/CasualDeveloper/opencode/tree/feat/config-forward-compat
Looking for feedback on whether this approach is acceptable before opening a PR.
Activity
github-actions commentedon Dec 25, 2025
This issue might be a duplicate of existing issues. Please check:
These issues describe the same core problem: strict config validation that breaks forward/backward compatibility. Your proposed solution addresses all of them.
Feel free to ignore if there are additional nuances specific to your case.
CasualDeveloper commentedon Dec 25, 2025
Thanks for flagging the duplicates. I checked #1081 and see that @thdxr intentionally chose strict validation:
Fair. But I was thinking more towards forward compatibility. That and it's kinda troublesome to manage the config files if I want to switch between stable and my dev fork of opencode lol
Meet in the middle? I added a way for opencode to warn on unknown keys but don't fail - that way users still get feedback on potential typos while configs from newer versions still work
rekram1-node commentedon Dec 25, 2025
This is up to @thdxr I know he made this decision pretty intentionally but I suppose if we had a good warning system... then maybe it'd be fine
CasualDeveloper commentedon Dec 25, 2025
Updated the branch with generated SDK types and a type fix for the keybind context (
.passthrough()makes unknown keys typed asunknown, so added a guard before parsing).ariane-emory commentedon Dec 26, 2025
@CasualDeveloper Psst... you talked about updating 'the branch', but there is no PR associated with this Issue. Did you mean to link to/create a PR?
I think I found the branch that you meant on your fork and I'm going to try out merging it into my own fork's next integration branch when I next toss one into the blender, but finding 'the branch' it did take some digging.
CasualDeveloper commentedon Dec 26, 2025
@ariane-emory yeah I haven't opened a PR yet since this is still in the proposal / discussion stages for now. I've linked my fork of opencode with the branch I was talking about in my original post
ariane-emory commentedon Dec 26, 2025
@CasualDeveloper Fair enough, no rush at all - especially not today, of all days, people ought enjoy the holidays. The mention of 'the branch' just had me confused and searching for a few moments. ;)
CasualDeveloper commentedon Dec 26, 2025
No worries lol. Just keep in mind: If another PR touching
packages/sdk/openapi.jsonmerges first, rebase and rerunbun ./script/generate.ts(chore: generate), then updatepackages/sdk/js/src/v2/gen/types.gen.ts.[-]Proposal: Make config tolerant of unknown keys for forward compatibility[/-][+][Proposal] Make config tolerant of unknown keys for forward compatibility[/+][-][Proposal] Make config tolerant of unknown keys for forward compatibility[/-][+][Discussion] Make config tolerant of unknown keys for forward compatibility[/+]29 remaining items