Demonstrate JSON Schema as source of truth for web-features data #2990

ddbeck · 2025-05-21T16:18:47Z

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.

ddbeck · 2025-05-21T16:21:24Z

new.quicktype.ts

@@ -0,0 +1,208 @@
+/**


This file is generated by quicktype from the new, hand-authored JSON Schema. The generation is OK for now but if we add something like redirects as described in #91, it has a few inconveniences. We're going to insulate ourselves from quicktype with the next TS module.

ddbeck · 2025-05-21T16:29:41Z

newtypes.ts

+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"
+    >
+  >;


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.

Do the TypeScript error messages if you get types wrong end up looking completely bizarre with this layering?

They're not quite as nice as plain, from-scratch types but they're probably above-average in terms of informativeness in type error messages. I've seen some { … } & { … } & { … } & … monstrosities and this is nicer than that.

ddbeck · 2025-05-21T16:31:10Z

newtypes.ts

+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+const t1: FeatureData = {
+  name: "Test",
+  description: "Hi",
+  description_html: "Hi",
+  spec: "",
+  status: {
+    baseline: false,
+    support: {},
+  },
+};


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.

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.

We could do this, but I'd prefer to avoid it on the initial implementation. Quicktype can generate zod runtime type check code, but it'd be a new dependency that I don't feel especially ready to embrace just yet.

ddbeck · 2025-05-21T16:32:15Z

schemas/new.schema.json

@@ -0,0 +1,302 @@
+{


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.

I like it! By now I can almost read JSON Schema, and I find this quite readable.

foolip · 2025-05-22T15:17:41Z

I think we should do it! I'd rather have ugly TypeScript definitions than ugly JSON Schema.

schemas/data.schema.json

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

ddbeck · 2025-06-11T09:01:28Z

Thank you for the review, @jcscottiii. Thanks to your review I was able to find some other constraints that weren't in the new schema file. This also prompted me to discover some oddities in the rolled-up TypeScript types in npm package — I'm still working on fixing that part.

jcscottiii · 2025-06-16T20:48:04Z

I tried out the latest updates and it looks really good now! Thanks

ddbeck · 2025-06-30T17:39:44Z

packages/web-features/package.json

+    "types.d.ts",
+    "types.quicktype.d.ts",
    "index.js",
    "data.json",
    "data.schema.json"
  ],
  "scripts": {
-    "prepare": "tsc && rm types.js && tsup ./index.ts --dts-only --format=esm --out-dir=."
+    "prepare": "tsc && rm types.js && rm types.quicktype.js"
  },
  "devDependencies": {
    "@types/node": "^24.0.7",
-    "tsup": "^8.5.0",
    "typescript": "^5.8.3"


One thing I discovered in following up @foolip's #2990 (comment) question about type errors for consumers:

tsup adds another layer of name-mangling, on top of the layer given by converting JSON Schema to TypeScript (via quicktype). For example, as originally configured, FeatureData is shown as extending FeatureData$1. Ugly!

To fix this, I just let plain TypeScript generate the type declaration files. It's slightly less tidy — we have to include the types.d.ts and types.quicktype.d.ts files — but it's a very tiny hit for consumers (two additional small files and two development-time file reads for TypeScript consumers) and a nice boon for us (one fewer dependency and one less layer of indirection).

This also makes it a lot easier for us to do some other things in the future (e.g., adding util functions or making this a "normal" monorepo where we're doing less magic with the web-features package).

foolip · 2025-07-07T13:32:54Z

Commit 6e383ff LGTM, less code and still works!

foolip · 2025-09-04T18:40:54Z

types.quicktype.ts

+  /**
+   * caniuse.com identifier(s)
+   */
+  caniuse?: string[] | string;


I don't want to delay v3, but how quickly could we decide that the built output will always be an array instead of string-or-array? Here and for a bunch of things below.

In this PR, I tried my best to avoid changing anything material about the existing JSON schema, just flip around what we're generating (that is JSON schema → TypeScript, instead of the reverse—it's not exactly equivalent, which is why I haven't pushed to merge this sooner than v3). I expect we'll merge #3184 to fixup all the string-or-array types as part of v3. To the best of my knowledge, there's no opposition to landing that PR.

Alright, excellent!

foolip · 2025-09-04T18:42:10Z

types.quicktype.ts

+  /**
+   * Whether the feature is Baseline (low substatus), Baseline (high substatus), or not (false)
+   */
+  baseline: boolean | BaselineEnum;


Is it possible to put false here to rule out true as a possible value?

Suggested change

baseline: boolean | BaselineEnum;

baseline: false | BaselineEnum;

Same change below if so.

This file is generated, so no. But I can fix this with the types.ts file that fixes up some of this. I've pushed 707c6f5 and 64de65d to do this.

foolip · 2025-09-04T18:43:32Z

types.quicktype.ts

+   * Browser versions that most-recently introduced the feature
+   */
+  support: Support;
+  [property: string]: any;


What does this line do?

This whole file is generated by Quicktype. This line is a bug (or limitation, not sure) of Quicktype: it doesn't seem to be able to determine whether the Status object might have additional properties (or what their types might be). The types.ts file corrects this with the Pick<…> types, so that these arbitrary keys are stripped from the exported types.

types.ts

foolip · 2025-09-04T18:46:24Z

types.ts

-    /** Whether developers are formally discouraged from using this feature */
-    discouraged?: Discouraged;
+export interface WebFeaturesData
+  extends Pick<QuicktypeWebFeaturesData, "browsers" | "groups" | "snapshots"> {


Just about here is where I no longer understand what I'm reading and will just trust that this is all great. It sure looks like TypeScript. If you're really unsure about anything I can try harder to understand.

In the interest of completeness and posterity, I'll explain this a bit better:

Here, I'm making the types nicer than what Quicktype generates by "picking" good stuff out of the schema, but partly modifying the generated type for the features["…"] objects (FeatureData, below). This isn't strictly required now, but will be when we add redirects (in a follow up PR).

Anyway, by doing it this way instead of writing wholly custom types, we preserve the link between JSON Schema and TypeScript.

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

…| false`

…| false` (continued)

* 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]>

Demonstrate JSON Schema as source of truth

9846b90

github-actions bot added the tools and infrastructure Project internal tooling, such as linters, GitHub Actions, or repo settings label May 21, 2025

ddbeck commented May 21, 2025

View reviewed changes

ddbeck requested a review from foolip May 21, 2025 16:34

ddbeck force-pushed the 91-jsonschema-source-of-truth branch from 7c9c780 to 9846b90 Compare May 22, 2025 07:09

ddbeck added 2 commits May 26, 2025 19:18

Replace types with newly generated types

1012068

Add new types to web-features package build

77bf8f9

ddbeck added major version required This PR requires a minor version semver release (vX+1.0.0) package:web-features labels May 26, 2025

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

Format types.ts

7742c64

ddbeck mentioned this pull request May 27, 2025

Add move and split redirects to the schema #3000

Merged

jcscottiii reviewed Jun 9, 2025

View reviewed changes

schemas/data.schema.json Show resolved Hide resolved

jcscottiii reviewed Jun 9, 2025

View reviewed changes

schemas/data.schema.json Show resolved Hide resolved

jcscottiii reviewed Jun 9, 2025

View reviewed changes

schemas/data.schema.json Outdated Show resolved Hide resolved

jcscottiii mentioned this pull request Jun 9, 2025

WIP: try updated web features data.schema.json GoogleChrome/webstatus.dev#1552

Closed

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

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 commented Jun 30, 2025

View reviewed changes

ddbeck added 2 commits July 16, 2025 19:55

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

cf6fad8

Fix bad Quicktype command parsing

0d54e06

ddbeck mentioned this pull request Jul 25, 2025

Change schema string | string[] properties to string[] #3184

Merged

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

0c20225

ddbeck added 2 commits August 18, 2025 13:36

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

16a5cb6

Fix out of date package-lock.json

f88369b

captainbrosset changed the base branch from main to v3.0 August 29, 2025 14:15

ddbeck added 3 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

ddbeck marked this pull request as ready for review September 3, 2025 16:33

foolip approved these changes Sep 4, 2025

View reviewed changes

ddbeck and others added 4 commits September 5, 2025 17:39

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)

foolip approved these changes Sep 6, 2025

View reviewed changes

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

ddbeck deleted the 91-jsonschema-source-of-truth branch September 8, 2025 12:36

ddbeck mentioned this pull request Sep 8, 2025

Prepare v3.0.0 #3333

Merged

	baseline: boolean \| BaselineEnum;
	baseline: false \| BaselineEnum;

Demonstrate JSON Schema as source of truth for web-features data #2990

Demonstrate JSON Schema as source of truth for web-features data #2990

Uh oh!

Conversation

ddbeck commented May 21, 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!

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!

foolip commented May 22, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ddbeck commented Jun 11, 2025

Uh oh!

jcscottiii commented Jun 16, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

foolip commented Jul 7, 2025

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!

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

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 21, 2025 •

edited

Loading

ddbeck Sep 5, 2025 •

edited

Loading