Schema migration compatibility during major version upgrades

Question

Biome utilizes a strict schema for its biome.json file to manage linting rules and formatting configurations. When upgrading between major versions, the configuration structure often undergoes breaking changes to accommodate new toolchain capabilities.
Currently, there is no native, automated rollback mechanism to programmatically revert the configuration to a previous schema state if a manual migration results in unexpected behavior. The CLI may fail to execute or ignore specific settings if the JSON structure does not align with the binary's expectations.
The uncertainty lies in how the engine handles deprecated keys versus entirely removed properties during the transition period between two major releases.

How does Biome treat configuration keys that have been renamed in the latest version?
  Is there a recommended strategy for verifying schema compatibility before applying a major upgrade to a shared configuration?

Siddharth · Answer

Configuration Key Handling
Biome treats renamed or unknown configuration keys as invalid. When a key is renamed in a major version, the binary typically does not map the old key to the new one automatically. Instead, the tool will either trigger a schema validation warning or ignore the deprecated key entirely, depending on the specific version's strictness. This means settings associated with renamed keys may silently revert to their default values, potentially altering linting or formatting behavior without failing the build.

Verification Strategy for Shared Configurations
Since Biome lacks a native programmatic rollback for biome.json, the following strategy is recommended to verify compatibility before merging a major upgrade into a shared environment:

Version Control Branching: Perform the upgrade on a dedicated feature branch. This ensures that Git remains the primary mechanism for reverting the configuration state.
  Automated Migration: Attempt to run the migration command if available for your version:
    biome migrate
  
  Schema Validation Check: Execute a check across the project to surface validation errors or warnings in the console output:
    biome check .
  
  IDE Integration: Ensure your editor is pointed to the latest Biome JSON schema. Most modern IDEs will highlight invalid or deprecated keys in biome.json with a squiggly underline if the schema is correctly linked.

Assumptions and Uncertainty
This guidance assumes the use of a standard biome.json setup. There is inherent uncertainty regarding the exact lifecycle of a deprecated key (i.e., exactly how many versions a key remains as a "warning" before becoming "ignored"), as this varies by release. Users should treat any console warning regarding "unknown keys" as a critical action item.

Diagnostic Detail Needed: Are you utilizing a shared configuration package (e.g., a published npm package) or a local biome.json file? This changes whether you need to manage semantic versioning for the config package itself.

Schema migration compatibility during major version upgrades

1 answer

Configuration Key Handling

Verification Strategy for Shared Configurations

Assumptions and Uncertainty

Your perspective belongs here.

0 question comments