Add move and split redirects to the schema #3000
Conversation
ddbeck
added
schema
github-actions
bot
added
feature definition
| 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 |
There was a problem hiding this comment.
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?
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
Which is to say, once I've written the guidelines, webcodecs might not get a split at all.
There was a problem hiding this comment.
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?
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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).
|
@jcscottiii Would you mind taking this PR for a test drive, pointing your schema tooling at the JSON Schema file like you did in GoogleChrome/webstatus.dev#1552 and #2990 (comment)? I'm hoping to get a move on with this schema change (and other requests, such as #1981). This PR is stacked on top of #2990 and adds feature redirects (renames and splits). I'm wondering what the experience of consuming that version of the schema would be like. spoilersI found that, at least for TypeScript, Quicktype's generated types weren't as nice, so I wrote some convenience wrapper types in |
|
Trying it out now! I will make a WIP PR and report back |
| "additionalProperties": { | ||
| "oneOf": [ | ||
| { | ||
| "$ref": "#/definitions/FeatureData" | ||
| }, | ||
| { | ||
| "$ref": "#/definitions/FeatureMovedData" | ||
| }, | ||
| { | ||
| "$ref": "#/definitions/FeatureSplitData" | ||
| } | ||
| ] |
There was a problem hiding this comment.
I ran into the spoiler you mentioned lol.
Raw notes:
By doing this: My feature structure looks like this
// A feature has split into two or more other features
type FeatureValue struct {
// caniuse.com identifier(s)
Caniuse *StringOrStrings `json:"caniuse"`
// Sources of support data for this feature
CompatFeatures []string `json:"compat_features,omitempty"`
// Short description of the feature, as a plain text string
Description *string `json:"description,omitempty"`
// Short description of the feature, as an HTML string
DescriptionHTML *string `json:"description_html,omitempty"`
// Whether developers are formally discouraged from using this feature
Discouraged *Discouraged `json:"discouraged,omitempty"`
// Group identifier(s)
Group *StringOrStrings `json:"group"`
// Short name
Name *string `json:"name,omitempty"`
// Snapshot identifier(s)
Snapshot *StringOrStrings `json:"snapshot"`
// Specification URL(s)
Spec *StringOrStrings `json:"spec"`
// Whether a feature is considered a "Baseline" web platform feature and when it achieved
// that status
Status *StatusHeadline `json:"status,omitempty"`
Redirect *Redirect `json:"redirect,omitempty"`
}
Required fields like description can now be nil. And I see that you have the same thing in your types.quicktype.ts
Question: Would you be open to using the discriminator feature alongside the oneOf?
"features": {
"description": "Feature identifiers and data",
"type": "object",
"oneOf": [
{
"$ref": "#/definitions/FeatureData"
},
{
"$ref": "#/definitions/FeatureMovedData"
},
{
"$ref": "#/definitions/FeatureSplitData"
}
],
"discriminator": {
"propertyName": "kind"
}
},
...
"FeatureData": {
"description": "A feature data entry",
"type": "object",
"properties": {
"kind": { "const": "data" },
"name": {
"description": "Short name",
"type": "string"
},
"description": {
"description": "Short description of the feature, as a plain text string",
"type": "string"
},
"description_html": {
"description": "Short description of the feature, as an HTML string",
"type": "string"
},
"spec": {
"description": "Specification URL(s)",
"$ref": "#/definitions/URLOrURLs"
},
"group": {
"description": "Group identifier(s)",
"$ref": "#/definitions/StringOrStrings"
},
"snapshot": {
"description": "Snapshot identifier(s)",
"$ref": "#/definitions/StringOrStrings"
},
"caniuse": {
"description": "caniuse.com identifier(s)",
"$ref": "#/definitions/StringOrStrings"
},
"compat_features": {
"description": "Sources of support data for this feature",
"$ref": "#/definitions/Strings"
},
"status": {
"description": "Whether a feature is considered a \"Baseline\" web platform feature and when it achieved that status",
"$ref": "#/definitions/StatusHeadline"
},
"discouraged": {
"description": "Whether developers are formally discouraged from using this feature",
"$ref": "#/definitions/Discouraged"
}
},
"required": ["name", "description", "description_html", "kind", "spec", "status"],
"additionalProperties": false
},
"FeatureMovedData": {
"description": "A feature has permanently moved to exactly one other ID",
"type": "object",
"properties": {
"kind": { "const": "moved" },
"redirect": {
"type": "object",
"properties": {
"reason": {
"const": "moved"
},
"target": {
"description": "The new ID for this feature",
"type": "string"
}
},
"required": ["reason", "target"],
"additionalProperties": false
}
},
"required": ["redirect", "kind"],
"additionalProperties": false
},
"FeatureSplitData": {
"description": "A feature has split into two or more other features",
"type": "object",
"properties": {
"kind": { "const": "split" },
"redirect": {
"type": "object",
"properties": {
"reason": {
"const": "split"
},
"targets": {
"description": "The new IDs for this feature",
"$ref": "#/definitions/Strings"
}
},
"required": ["reason", "targets"],
"additionalProperties": false
}
},
"required": ["kind", "redirect"],
"additionalProperties": false
},
This is something that allows consumers to clearly know which data type it should be trying to use.
It will add an extra line but I think it's worth it for clarity.
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:
webcodecs(Splitwebcodecsintoaudio-codecsandvideo-codecs#2918) and movingnumeric-seperatorstonumeric-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:
reasonfor changing an ID ismoved, instead ofrenamed, to avoid implying that the ID will change any time the human-readablenamefield changes.tostring/array of strings is now two distinct fields,targetandtargets, depending on thereason. 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.