Demonstrate JSON Schema as source of truth for web-features data #2990
Conversation
github-actions
bot
added
the
tools and infrastructure
| @@ -0,0 +1,208 @@ | |||
| /** | |||
There was a problem hiding this comment.
| export interface WebFeaturesData | ||
| extends Pick<QuicktypeWebFeaturesData, "browsers" | "groups" | "snapshots"> { | ||
| features: { [key: string]: FeatureData }; | ||
| } | ||
|
|
||
| export type FeatureData = Required< | ||
| Pick< | ||
| QuicktypeMonolithicFeatureData, | ||
| "description_html" | "description" | "name" | "spec" | "status" | ||
| > | ||
| > & | ||
| Partial< | ||
| Pick< | ||
| QuicktypeMonolithicFeatureData, | ||
| "caniuse" | "compat_features" | "discouraged" | ||
| > | ||
| >; |
There was a problem hiding this comment.
This is a preview of what's coming when we add redirects. TypeScript and JSON Schema's type systems aren't strictly equivalent, so quicktype will generate correct but overbroad types. In this module, I'll pluck out some nuances (and badly generated names) that quicktype doesn't handle very well and clean them up by extending the generated types. While it's a bit weird looking, the benefit is that we can't completely diverge from the underlying JSON Schema.
There was a problem hiding this comment.
Do the TypeScript error messages if you get types wrong end up looking completely bizarre with this layering?
| // eslint-disable-next-line @typescript-eslint/no-unused-vars | ||
| const t1: FeatureData = { | ||
| name: "Test", | ||
| description: "Hi", | ||
| description_html: "Hi", | ||
| spec: "", | ||
| status: { | ||
| baseline: false, | ||
| support: {}, | ||
| }, | ||
| }; |
There was a problem hiding this comment.
If we like, we can even "test" some properties of our types—like I do here demonstrating a FeatureData object without any of the optional fields—by instantiating some objects and letting the typechecker complain if we get it wrong.
There was a problem hiding this comment.
That seems like a useful smoke test. I guess that when we load the JSON and interpret it as a TypeScript type, there's no checking going on that we could rely on? That would be helpful, but I suspect it's not a thing.
| @@ -0,0 +1,302 @@ | |||
| { | |||
There was a problem hiding this comment.
And here is the JSON Schema, intended for a human (me) to work with, instead of the generated JSON Schema. Mostly, things are ordered in a more readable way.
There was a problem hiding this comment.
I like it! By now I can almost read JSON Schema, and I find this quite readable.
ddbeck
force-pushed
the
91-jsonschema-source-of-truth
branch
from
7c9c780 to
9846b90
Compare
|
I think we should do it! I'd rather have ugly TypeScript definitions than ugly JSON Schema. |
This PR demonstrates switching from generating JSON Schema to authoring a JSON Schema. This is a prerequisite for #91 and fixes #2722. I'll self-review to point out some interesting things.
This NOT ready to merge. Don't merge it! If we want to go down this route, then there are a few tasks remaining to get this into a mergeable state: