Add move and split redirects to the schema #3000

ddbeck · 2025-05-27T16:26:13Z

Towards #91 and the sequel to #2990.

~~Because this PR follows #2990, looking at the diff between them might be easier to look at. See: ddbeck/web-features@91-jsonschema-source-of-truth...ddbeck:web-features:91-redirects~~

This PR does the following:

Adds redirects to the JSON Schema
Generates (and embellishes) types for the new schema
Modifies our scripts to use the new types and support redirects
Demonstrates both types of redirects, by splitting single-color-gradients and moving numeric-seperators to numeric-separators (Fix typo in file name #2484)

index.ts

foolip · 2025-05-27T18:00:53Z

features/webcodecs.yml

-name: WebCodecs
-description: The WebCodecs API provides low-level access to individual video frames and chunks of audio samples, for full control over the way media is processed.
-spec: https://w3c.github.io/webcodecs/
-caniuse: webcodecs


I think we should split it, but the fact that this is in caniuse makes me think we should somehow keep webcodecs as well? With composite features or similar we could.

Do we have any other candidates for splitting where the existing entry is just wrong and has no value to preserve?

This is a good point. One thing I haven't done is to write guidelines that say when to move or split a feature—I just put these in to demonstrate the fact that one could do it. I think it would actually be best to back out the YAML files from this PR before merging and land those changes separately, especially to make the release notes more informative.

Which is to say, once I've written the guidelines, webcodecs might not get a split at all.

Alright, making the actual changes separately sounds good!

We do need to make sure we have a real case for splitting however. If we can only come up with "composite" features that we might later want to merge back together, then I'm not sure we should remove the original feature. Do have features that were combined by mistake and should never be considered one?

Hmm, I'm not currently seeing a compulsory split, if we're assuming some future composite feature schema.

It's somewhat easier to find historic cases. #1089 is a case where, without a splitting schema, would produce either a) a breaking release (which is basically what we did, in the pre-1.0 era) or b) a useless composite feature that combines something interoperable and something that never will be. In the latter case, caniuse has a corresponding feature, but I don't think we should follow caniuse's lead there.

There are also cases we've already merged that look a little suspect, where we split something by moving keys, tweaking a description, and just kinda pretending we got it right in the first place (e.g., #2491, #2652). I don't wish to bank on always being on the right side of that line.

Which brings me to my last concern: split ought to be the reverse of merged. If we wish to be able to merge freely, then we'll need a safe undo. Otherwise, merges will have the feeling of a semver-major event for maintainers here, even if it doesn't bump the version number.

Let's use #2776 as the feature to demonstrating split. We'd split that into gradients (2 BCD keys) and conic-gradients (1 BCD key).

I switched to the single color stop feature as our demonstrator in 9b276f0

Co-authored-by: James C Scott III <[email protected]>

captainbrosset · 2025-08-29T14:16:48Z

Now targeting the v3.0 branch (which was created from main a minute ago, so the conflicts here are the same as they were before).

ddbeck · 2025-08-29T14:50:22Z

When I say partially split out, I mean Feature A still exists but it has been scoped down and now feature B and C are split out of Feature A.

I was writing some e2e tests for webstatus.dev and currently I don't see a way for Feature A to use both "#/definitions/FeatureData" and "#/definitions/FeatureSplitData"

@jcscottiii Good question! The main answer is: partial splits can't happen.

In some cases, we'll error correct a feature silently (e.g., if a few compat keys were assigned erroneously—that wouldn't impact the meaning of the name, description, mapping to caniuse, etc.—then we'll just move those keys to another feature)—we do this already. Otherwise, the feature will have to be fully split (i.e., the original ID is just a pointer to two or more others).

I've given some thoughts to more sophistication around partial splits, but it's something we'd have to consider in a v4.0.0 (along with a notion of aspects of a larger feature and/or composite features).

jcscottiii · 2025-08-29T15:20:58Z

Sounds good to me!

Background: I was just thinking about adding a banner to the feature detail page on webstatus.dev to let users know that they could reference other features in the event the original feature's scope was downsized. But I couldn't see a way for the current schema to tell me that information directly.

In the meantime, if we really wanted this, we could potentially track the BCD keys for each feature. But that introduces its own challenges, such as determining whether a key's removal was an editorial correction or a true feature split.

Anyway, I'm completely okay leaving this for v4 once we have more usage of this.

Currently, v3 cannot let us know if a feature has been partially split out. This commit removes the split out info from the Regular Feature model. See comment: web-platform-dx/web-features#3000 (comment) This allows us to simplify this. We can revisit in v4.

* fix: Return correct feature evolution data for moved and split features The primary changes are: - The `GetMovedWebFeatureDetailsByOriginalFeatureKey` function has been fixed. It was previously returning the internal database ID of the new feature; it now correctly returns the human-readable feature key, as intended. - The main feature query has been updated to join against a new `SplitWebFeatures` table. The `GET /v1/features` and `GET /v1/features/{feature_id}` endpoints now include an `evolution` object in the response. This object contains `split_off_info` which lists any features that have been split off from the primary feature. To support this, the following changes were also made: - The `openapi.yaml` specification has been updated to include the new `evolution` fields in the `Feature` schema. - The fake data generation process in `util/cmd/load_fake_data` has been significantly enhanced to create more realistic test data for feature evolution, including scenarios for moved, fully split, and partially split features. - End-to-end tests and snapshots have been updated to reflect the new data structures and the changes in the underlying test data.start There needs to be some frontend changes. But that will come in a future PR. * fix snapshots * Remove split out info from Regular Feature model Currently, v3 cannot let us know if a feature has been partially split out. This commit removes the split out info from the Regular Feature model. See comment: web-platform-dx/web-features#3000 (comment) This allows us to simplify this. We can revisit in v4. * update snapshots

Co-authored-by: Philip Jägenstedt <[email protected]>

…| false`

…| false` (continued)

ddbeck · 2025-09-08T14:21:57Z

types.quicktype.ts

 /**
 * A feature data entry
+ *
+ * A feature has permanently moved to exactly one other ID
+ *
+ * A feature has split into two or more other features
 */
 export interface FeatureData {
  /**


Note for other reviewers: Quicktype combines the schema for ordinary features, moved features, and split features into one all-optional mega object type. This is a little useless, so types.ts cleans this up. See that file for further commentary.

ddbeck · 2025-09-08T14:25:04Z

schemas/data.schema.json

      "required": ["name"],
      "additionalProperties": false
    },
+    "Release": {


Note to other reviewers: I alphabetized these sort of on accident. This not real change for Release or SnapshotData. Please tell me if you'd rather that I revert this.

ddbeck · 2025-09-08T14:30:15Z

types.ts

+type FeatureRedirectData = { kind: Exclude<Kind, "feature"> } & Required<
+  Pick<QuicktypeMonolithicFeatureData, "redirect_target" | "redirect_targets">
+>;


Note to other reviewers: Here I define a helper type for any redirect feature (i.e., kind is not "feature" and it has redirect_target and redirect_targets). Then I use this to construct the more specific FeatureMovedData and FeatureSplitData types.

index.ts

ddbeck · 2025-09-11T16:51:26Z

assertions.test.ts

+describe("assertValidReference()", function () {
+  it("throws if target ID is a move", function () {
+    assert.throws(() => {
+      assertValidFeatureReference("a", "some-moving-feature", {
+        "some-moving-feature": { kind: "moved" },
+      });
+    });
+  });
+
+  it("throws if target ID is a split", function () {
+    assert.throws(() => {
+      assertValidFeatureReference("a", "some-split-feature", {
+        "some-split-feature": { kind: "split" },
+      });
+    });
+  });
+
+  it("throws if target ID is not defined", function () {
+    assert.throws(() => {
+      assertValidFeatureReference(
+        "a",
+        "this-is-a-completely-invalid-feature",
+        {},
+      );
+    });
+  });
+
+  it("does not throw if target ID is a feature", function () {
+    assert.doesNotThrow(() => {
+      assertValidFeatureReference("a", "dom", { dom: { kind: "feature" } });
+    });
+  });
+});


@foolip there are now tests for asserting feature references (and a little refactoring to make this easier to do for other things, like snapshots, later), for your consideration.

I consider this excellent!

* Demonstrate JSON Schema as source of truth for web-features data (#2990) * Add move and split redirects to the schema (#3000) * Add guidelines for moving and splitting features (#3180) * Add consumer docs for moved and split features (#3181) * Change schema `string | string[]` properties to `string[]` (#3184) * Fix missing `group` and `snapshot` keys from convenience types Co-authored-by: James C Scott III <[email protected]> Co-authored-by: Philip Jägenstedt <[email protected]> Co-authored-by: Patrick Brosset <[email protected]> Co-authored-by: szepeviktor <[email protected]> Co-authored-by: LeoMcA <[email protected]> Co-authored-by: foolip <[email protected]>

ddbeck added 7 commits May 21, 2025 18:15

Demonstrate JSON Schema as source of truth

9846b90

Replace types with newly generated types

1012068

Add new types to web-features package build

77bf8f9

Format types.ts

7742c64

Fix schema key sort order

7f7aa98

Add redirect feature schema types

459ac43

Update scripts to use redirects

758e77a

ddbeck added schema Schema changes, proposals, and bugs major version required This PR requires a minor version semver release (vX+1.0.0) package:web-features feature evolution Issues/PRs for describing changing feature definitions over time (as opposed to support) labels May 27, 2025

github-actions bot added feature definition Creating or defining new features or groups of features. tools and infrastructure Project internal tooling, such as linters, GitHub Actions, or repo settings labels May 27, 2025

ddbeck added 2 commits May 27, 2025 18:30

Split webcodecs

2294698

Rename numeric-seperators

eaf208d

ddbeck force-pushed the 91-redirects branch from 8341941 to eaf208d Compare May 27, 2025 16:30

ddbeck requested a review from foolip May 27, 2025 16:31

ddbeck commented May 27, 2025

View reviewed changes

index.ts Outdated Show resolved Hide resolved

Prevent double and circular redirects

dc4974b

foolip reviewed May 27, 2025

View reviewed changes

ddbeck added this to the web-features v3.0 milestone May 29, 2025

ddbeck and others added 3 commits June 10, 2025 15:35

Merge branch 'main' into 91-jsonschema-source-of-truth

95bf898

Add unintentionally missing required fields

b2b6762

Co-authored-by: James C Scott III <[email protected]>

Add more property constraints to reduce any in TS

dd23730

foolip mentioned this pull request Jun 11, 2025

New single color stop gradients feature #2776

Merged

ddbeck added 2 commits June 30, 2025 18:55

Merge branch 'main' into 91-jsonschema-source-of-truth

a8b6ba1

Drop tsup and export our types directly

6e383ff

ddbeck force-pushed the 91-redirects branch from 4dfad0a to 51687f6 Compare June 30, 2025 17:48

Merge branch '91-jsonschema-source-of-truth' into 91-redirects

036bdaf

ddbeck force-pushed the 91-redirects branch from 51687f6 to 036bdaf Compare June 30, 2025 17:48

jcscottiii mentioned this pull request Aug 29, 2025

fix: Resolve moved features and refactor evolution handling GoogleChrome/webstatus.dev#1772

Merged

ddbeck and others added 12 commits September 3, 2025 18:21

Merge branch 'v3.0' into 91-jsonschema-source-of-truth

0074415

Fix bad package.json merge

9de2f6c

Upgrade quicktype

5ae8ec4

Fix typo

2bcab6c

Co-authored-by: Philip Jägenstedt <[email protected]>

Fix Quicktype's overly permissive type for `baseline: "high" | "low" …

707c6f5

…| false`

Fix top-level snapshots as optional in the JSON Schema

4990926

Fix Quicktype's overly permissive type for `baseline: "high" | "low" …

64de65d

…| false` (continued)

Merge branch '91-jsonschema-source-of-truth' into 91-redirects

710f949

Merge branch 'v3.0' into 91-redirects

1717294

Remove redirect dating

ea6a67d

Undo unintended change to snapshot schema

320ca18

Don't expose intermediate cleanup type

27b90eb

ddbeck commented Sep 8, 2025

View reviewed changes

ddbeck requested a review from foolip September 8, 2025 14:31

ddbeck marked this pull request as ready for review September 8, 2025 14:31

foolip approved these changes Sep 10, 2025

View reviewed changes

index.ts Outdated Show resolved Hide resolved

Add tests for assertValidFeatureReference

0de21c7

ddbeck force-pushed the 91-redirects branch from bf8cbb2 to 0de21c7 Compare September 11, 2025 16:50

ddbeck commented Sep 11, 2025

View reviewed changes

foolip approved these changes Sep 11, 2025

View reviewed changes

ddbeck merged commit 0d40182 into web-platform-dx:v3.0 Sep 12, 2025
3 checks passed

ddbeck deleted the 91-redirects branch September 12, 2025 10:48

ddbeck mentioned this pull request Sep 12, 2025

Prepare v3.0.0 #3333

Merged

Add move and split redirects to the schema #3000

Add move and split redirects to the schema #3000

Uh oh!

Conversation

ddbeck commented May 27, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

captainbrosset commented Aug 29, 2025

Uh oh!

ddbeck commented Aug 29, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jcscottiii commented Aug 29, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

ddbeck commented May 27, 2025 •

edited

Loading

ddbeck commented Aug 29, 2025 •

edited

Loading

jcscottiii commented Aug 29, 2025 •

edited

Loading