Add move and split redirects to the schema

[ddbeck]

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 webcodecs (Split webcodecs into audio-codecs and video-codecs #2918) and moving numeric-seperators to numeric-separators (Fix typo in file name #2484)

This PR mostly follows the mock documentation discussed from #91 (see #91 (comment)). Some changes I made based on the discussion there:

• The reason for changing an ID is moved, instead of renamed, to avoid implying that the ID will change any time the human-readable name field changes.
• The to string/array of strings is now two distinct fields, target and targets, depending on the reason. This is to avoid some weirdness in using a preposition as a noun (i.e., to avoid saying silly things like "this feature has two tos") and to ensure the name of the field implies its type.

[foolip]

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?

[ddbeck]

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.

[ddbeck]

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

[foolip]

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?

[ddbeck]

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.

[foolip]

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).

[ddbeck]

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

[ddbeck]

@jcscottiii I've added the kind the discriminator field, but the actual discriminator annotation appears to be an OpenAPI Spec extension rather than JSON Schema. I added a $comment field to document it (hopefully).

But, once I added the discriminator field, I found that the existing structure was duplicative. Using the discriminator meant I could flatten the feature data—this greatly simplifies distinguishing the types (even if Quicktype ignores this fact). We now have things like this:

{ "kind": "feature", "name": "<abbr>", "description": "…" }
{ "kind": "moved", "redirect_target": "…" }
{ "kind": "split", "redirect_targets": ["feat1", "feat2"] }

I'm curious to know your thoughts on this variation.

[ddbeck]

The actual schema validation is failing right now (but strangely, only for the split feature). Trying to figure out why exactly.

Edit: it was a bug in the script that assembles the data.json, not the schema. Whew!

[jcscottiii]

@jcscottiii I've added the kind the discriminator field, but the actual discriminator annotation appears to be an OpenAPI Spec extension rather than JSON Schema. I added a $comment field to document it (hopefully).

But, once I added the discriminator field, I found that the existing structure was duplicative. Using the discriminator meant I could flatten the feature data—this greatly simplifies distinguishing the types (even if Quicktype ignores this fact). We now have things like this:

{ "kind": "feature", "name": "<abbr>", "description": "…" }
{ "kind": "moved", "redirect_target": "…" }
{ "kind": "split", "redirect_targets": ["feat1", "feat2"] }

I'm curious to know your thoughts on this variation.

Ahh. Thanks for pointing out that the discriminator is an OpenAPI-only feature.

I like the use of kind. It really helps out on my side. And I'm glad to hear things are simplified on your side too.

I will pull in those changes tomorrow in my PR and give an update.

[jcscottiii]

I updated my PR and it looks to me. The kind variable really helped. I can easily peek at the kind variable and determine how I want to read the rest of the object.

https://github.com/GoogleChrome/webstatus.dev/pull/1635/files#diff-4a334edc4e5f4d5f3f1c1c6688d33271a80ab0d5cfbdbc7a007e27a3242a0f30R107-R140

[jcscottiii]

I have not reviewed everything else. But from the data.schema.json POV, it looks good to me! I only have one nit/question.

[jcscottiii]

Nit: Currently this is the same as StringOrStrings. I think you meant to add the format of the string? Otherwise, could you simplify to use StringOrStrings.

[ddbeck]

Good catch. I'll fix this more comprehensively with #3184.

[jcscottiii]

Hey @ddbeck @atopal @foolip

Question 1

I have a question about the cases when a feature is split up partially (i.e. the scope of feature is narrowed).

For a feature that is partially split (meaning its scope is narrowed, and new features are spun off while the original Feature X still exists), I have two questions:

1. Can Feature X be partially split up multiple times? For example, if Feature X is first split, resulting in Feature X (narrowed scope) and Feature Y. Could Feature X then be partially split again at a later date, resulting in Feature X (even narrower scope), Feature Y, and now a new Feature Z?
2. If a feature can be partially split multiple times, do we want to track or expose the specific dates when each of those subsequent partial splits occurred? This would help understand the historical evolution of the feature's scope over time.

---

Question 2

Talking about timestamps, do we want to include a date for the move in the schema too?

---

For both questions, I'm okay keeping it as-is. I just started to think of different possibilities when I was working on GoogleChrome/webstatus.dev#1677

[jcscottiii]

@ddbeck

One more question about split features:

For those features that are partially split out, how will the YAML look with this 3.0.0 schema?

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"

[captainbrosset]

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]

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]

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.