Create a spec for a Baseline config file

[tonypconway]

Hi all, as discussed yesterday, here's a summary of the discussion we've had internally around producing some kind of Baseline config file spec or data provider so that developers can configure once and be consumed by all tools that consume it.

Motivation

Currently, the most popular tools for determining feature compatibility (like Browserslist and esbuild's targets) rely on minimum browser versions for all feature decision making. This approach is often too coarse for modern development because developers want to make exceptions:

• Exceptions for specific audiences: A feature might not have a formal "Widely Available" Baseline status globally, but could be supported by >99% of a specific site's user base.
• Acceptable partial support: A feature might be marked as "Newly available" or "Limited availability" due to lacking a sub-feature or a minor bug on an older browser, but the developer might accept this degradation.
• Progressive enhancements: Features like cross-document view transitions can be implemented with zero negative impact on older browsers, even though they are not fully globally supported yet.
• Webview limitations: Webviews account for roughly 10% of global HTTP requests (and up to 15-20% in some regions, see Cloudflare Radar for ongoing trends). They don't support the full subset of Baseline features, as some behaviors specific to browsers cannot be used in webviews, so WebView developers might want to have warnings or errors appear on all Webview incompatible features.
• Tooling fragmentation: It is time-consuming to configure exceptions across multiple bundlers, linters, framework configs, and packagers—especially since these tools often use different identifiers for the exact same web features.

Use cases

Developers need a single, unified configuration file that acts as a central source of truth for their tooling ecosystem. The use cases include:

• Setting a default feature ceiling: Establish a base Baseline target (e.g., "widely-available" or "2020") against which tools will default to warning or polyfilling.
• Explicit feature allowance: Definitively allow specific "unsupported" features to pass linters and bypass polyfills without warnings (e.g., when adding progressive enhancements).
• Explicit feature disallowance: Explicitly forbid certain widely-supported features—potentially due to accessibility concerns or webview incompatibilities—to trigger linter errors or require replacement/polyfilling.
• Warning-only lists: Highlight features that shouldn't break the build but should alert developers.
• Explicit polyfill-only lists: Define features that should be polyfilled but not warned intentionally, allowing early adoption of upcoming features.
• Extending shared feature lists: Allow developers to augment their configs by importing curated lists of feature IDs (e.g., subscribing to a "safe progressive enhancements" list published by front-end experts, large organisations centres of excellence sharing common policies across teams, FOSS CMSes like Wordpress).
• Excluding webview-unsupported features: Implementing a global exclusion of features features known to break in webviews, based on MDN compatibility data.
• Excluding or including based on 'aspects': Make it easy for developers to warn on features that are within their default ceiling but have a particular aspect applied, e.g. accessibility-degradation.

Possible design choices

Configuration Format

• Static (JSON / YAML): Minimal maintenance and familiar to developers, but statically defined constraints might push the burden of interpretation onto tool developers.
• Dynamic (JS Module): A .js file exporting an API. This allows for programmatic filtering and a robust plugin ecosystem, but requires more maintenance and carries a higher risk of integration breakages. Familiar style of config from the likes of ESLint, Vite, etc.
• Hybrid: A YAML/JSON file for straightforward lists, interpreted by a JS module that permits plugins.

Identifier Ecosystem

• Which feature keys should be accepted? Should it just stick to web-features IDs (e.g., cross-document-view-transitions), or concurrently accept MDN BCD keys (potentially supporting wildcards like mdn:api.HTMLElement.*Popover) and caniuse.com keys? I would say we should certainly support BCD keys, as they are the underlying currency of web-features and therefore Baseline data.

Configuration Syntax

Two possible approaches to the hierarchy of rules:

• Rule-based syntax: Focusing the top-level keys on rule sets (e.g., allowFeatures, disallowFeatures). It could optionally support human-readable inline justifications (e.g., "reason": "unintrusive progressive enhancement").
• Tool-based syntax: Grouping options by the tooling pipeline steps (e.g., linters: { ignore: [], warn: [], error: [] } vs polyfill: { do: [], dont: [] }).

Decisions/open questions

• What file format should standard configuration take? (JSON vs. YAML vs. JS module vs. Hybrid)
• How should we support uniform matching for tools? We may need an extension of the web-features package that maps feature/compat keys directly to AST or syntactic tokens so that performance is predictable across different parsers.
• Which ID sources should be officially supported? Do we support all three keys natively (web-features, MDN, caniuse), or standardize primarily on web-features and map the others? Are wildcards permitted?
• How should the configuration schema be structured? Is a Rule-based syntax or Tool-based syntax preferable?
• How do we surface secondary data like aspects, webview compat, a11y flags?

[captainbrosset]

I don't know a whole lot about the tooling ecosystem and the patterns, but I can try to give a point of view on the open questions:

• What file format should standard configuration take? (JSON vs. YAML vs. JS module vs. Hybrid)

I would start with static, making the entry bar very low, and probably enough for 80% of the use cases, but also leaving the door open for an hybrid format if there's a need for it.

• How should we support uniform matching for tools? We may need an extension of the web-features package that maps feature/compat keys directly to AST or syntactic tokens so that performance is predictable across different parsers.

Not 100% sure I understand the question here. I'm guessing this has to do with giving tools a way to detect features in code.
I think that, so far, this only exists for CSS and HTML (VS Code has Baseline hover cards), but not in JS, which is far more complicated to do.
Are you suggesting that the WebDX CG should own this parsing logic/the ability to map code to features?

• Which ID sources should be officially supported? Do we support all three keys natively (web-features, MDN, caniuse), or standardize primarily on web-features and map the others? Are wildcards permitted?

I would personally keep it simple and only support WebDX feature IDs. They're starting to get used all over the place, from WPT, to State-of surveys, to bug trackers, and more. Even caniuse displays features based on the web-features package.
Supporting both caniuse and WebDX IDs feels like that could introduce confusion at some point.
As for support BCD keys, I'm not sure that's the level of granularity which developers need, and I see a risk for confusion there too, where they ignore/allow a very specific key without realizing it has 10 other sister keys that should have been considered too.
Part of our work on web-features is to create features that make sense to developers. So I would stick to that level of granularity.

• How should the configuration schema be structured? Is a Rule-based syntax or Tool-based syntax preferable?

Rule-based feels more natural to me, letting each tool do what it needs to do based on these higher-level directives.

• How do we surface secondary data like aspects, webview compat, a11y flags?

Where would these aspects even come from? Like accessibility-degradation, is this something you imagine would be coming from web-features?