$schema const locks to stale SchemaStore URL — local/updated schema not accepted

Open 💬 0 comments Opened Jun 10, 2026 by sundeepbhatia

Summary

The $schema field in settings.json has a const constraint that only accepts
"https://json.schemastore.org/claude-code-settings.json". Any other value
(including file:// paths pointing at a local copy) causes Claude Code to reject
the entire settings file with:

\$schema: Invalid value. Expected one of: "https://json.schemastore.org/claude-code-settings.json" Files with errors are skipped entirely, not just the invalid settings.

Problem

The SchemaStore copy lags the installed binary's schema by days or weeks. For
example, on 2.1.170 the SchemaStore schema is missing properties that are valid
and in active use:

  • defaultMode: "auto" (auto-approve mode)
  • disableBypassPermissionsMode
  • effortLevel
  • skipAutoPermissionPrompt
  • skipWorkflowUsageWarning
  • worktree
  • statusLine

The binary's own schema (extractable via claude --print + the built-in
update-config skill) has 134 top-level properties. The SchemaStore copy has
significantly fewer.

Impact

  • IDE tooling (VS Code, IntelliJ) flags valid settings as errors when using

SchemaStore for validation

  • Users cannot point $schema at a local, up-to-date copy to work around the lag
  • The const means the only "valid" schema reference is the one most likely to be

wrong after any release

Suggested fix

Either:

  1. Drop the const on $schema so users can supply a file:// URI to a local copy, or
  2. Ensure SchemaStore is updated as part of every Claude Code release pipeline

Claude version: 2.1.170
OS: macOS

View original on GitHub ↗