Tiny spike to see how far we can get with generating JSON Schema from…

… our TS types

package.json

@@ -120,6 +120,7 @@
     "sloc": "^0.2.1",
     "storybook": "^7.6.17",
     "style-loader": "^3.3.3",
+    "ts-json-schema-generator": "^2.0.1",
     "typescript": "^5.4.2",
     "typescript-coverage-report": "^0.7.0",
     "vite-plugin-istanbul": "^5.0.0",
@@ -133,6 +134,7 @@
   },
   "scripts": {
     "gen:parsers": "yarn --cwd packages/kas gen:parsers",
+    "gen:schema": "utils/generate-schema.ts",
     "prebuild": "yarn gen:parsers",
     "build": "rollup -c config/build/rollup.config.js",
     "build:types": "yarn tsc --build tsconfig-build.json",

packages/perseus/src/perseus-types.ts

@@ -92,6 +92,12 @@ export type PerseusWidgetsMap = {
     [key in `video ${number}`]: VideoWidget;
 };
 
+/**
+ * The PerseusItem is the main Perseus data structure for an exercise.  It
+ * forms a question (with interactive widgets), a set of hints, and answer area
+ * configuration (such as whether to make a calculator or periodic table
+ * available to the learner).
+ */
 export type PerseusItem = {
     // The details of the question being asked to the user.
     question: PerseusRenderer;

utils/generate-schema.ts

@@ -0,0 +1,27 @@
+#!/usr/bin/env -S node -r @swc-node/register
+
+import fs from "fs";
+import path from "path";
+
+import {createGenerator} from "ts-json-schema-generator";
+
+import type {Config} from "ts-json-schema-generator";
+
+const config: Config = {
+    schemaId: "https://khanacademy.org/schema/perseus.json",
+    tsconfig: path.join(__dirname, "..", "tsconfig.json"),
+    jsDoc: "extended",
+
+    // type: "PerseusItem",
+};
+
+const outputPath = path.join(__dirname, "generated/schema.json");
+fs.mkdirSync(path.dirname(outputPath), {recursive: true});
+
+const schema = createGenerator(config).createSchema("PerseusItem"); // config.type);
+const schemaString = JSON.stringify(schema, null, 2);
+fs.writeFile(outputPath, schemaString, (err) => {
+    if (err) {
+        throw err;
+    }
+});