[Discussion] Make config tolerant of unknown keys for forward compatibility

[CasualDeveloper]

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.

[github-actions[bot]]

This issue might be a duplicate of existing issues. Please check:

• #1081: Cannot read newer opencode.json schema properties if opencode has not been updated (closed) - Exactly the same problem: users cannot use config files with newer options on older versions
• #5085: Unrecognized key: "limit" provider.llama.cpp (closed) - Similar validation issue with unrecognized keys causing config failures

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]

Thanks for flagging the duplicates. I checked #1081 and see that @thdxr intentionally chose strict validation:

"we're trying to be strict about config so people who mess it up get proper feedback"

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]

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]

Updated the branch with generated SDK types and a type fix for the keybind context (.passthrough() makes unknown keys typed as unknown, so added a guard before parsing).

[ariane-emory]

@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]

@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]

@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]

No worries lol. Just keep in mind: If another PR touching packages/sdk/openapi.json merges first, rebase and rerun bun ./script/generate.ts (chore: generate), then update packages/sdk/js/src/v2/gen/types.gen.ts.