Add JSON schema generation.

packages/spec/package.json

@@ -23,15 +23,21 @@
   },
   "scripts": {
     "prebuild": "rimraf dist && mkdir dist",
-    "build": "tsc && node ../../esbuild.js mosaic-spec",
+    "build": "npm run types && node ../../esbuild.js mosaic-spec",
     "lint": "eslint src test",
-    "pretest": "tsc",
+    "types": "tsc -p tsconfig.json && npm run schema",
+    "schema": "ts-json-schema-generator -f tsconfig.json -p src/spec/Spec.ts -t Spec --no-type-check --no-ref-encode --functions hide > dist/mosaic-schema.json",
+    "pretest": "npm run prebuild && npm run types",
     "test": "mocha 'test/**/*-test.js' && tsc -p jsconfig.json",
     "prepublishOnly": "npm run test && npm run lint && npm run build"
   },
   "dependencies": {
     "@uwdata/mosaic-core": "^0.7.1",
     "@uwdata/mosaic-sql": "^0.7.0",
-    "@uwdata/vgplot": "^0.7.1"
+    "@uwdata/vgplot": "^0.7.1",
+    "ts-json-schema-generator": "^2.0.0"
+  },
+  "devDependencies": {
+    "ajv": "^8.12.0"
   }
 }

packages/spec/src/spec/CSSStyles.ts

@@ -0,0 +1,9 @@
+type OmittedProperties =
+  | 'parentRule'
+  | 'getPropertyPriority'
+  | 'getPropertyValue'
+  | 'item'
+  | 'removeProperty'
+  | 'setProperty';
+
+export type CSSStyles = Partial<Omit<CSSStyleDeclaration, OmittedProperties>>;

packages/spec/src/spec/Data.ts

@@ -37,7 +37,7 @@ export type DataArray = object[];
 /**
  * A data definition that loads an external data file.
  */
-export interface DataFile {
+export interface DataFile extends DataBaseOptions {
   /**
    * The data file to load. If no type option is provided,
    * the file suffix must be one of `.csv`, `.json`, or `.parquet`.

packages/spec/src/spec/PlotAttribute.ts

@@ -1,3 +1,4 @@
+import { CSSStyles } from './CSSStyles.js';
 import { ParamRef } from './Param.js';
 import {
   ColorScaleType, ColorScheme, ContinuousScaleType, DiscreteScaleType,
@@ -124,7 +125,7 @@ export interface PlotAttributes {
    * [3]: https://www.w3.org/TR/css-values-4/#deprecated-quirky-length
    * [4]: https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#currentcolor_keyword
    */
-  style?: string | Partial<CSSStyleDeclaration> | null | ParamRef;
+  style?: string | CSSStyles | null | ParamRef;
 
   /**
    * How to distribute unused space in the **range** for *point* and *band*

packages/spec/src/spec/marks/Marks.ts

@@ -4,10 +4,7 @@ import { PlotMarkData } from '../PlotFrom.js';
 import { CurveName, FrameAnchor, Interval, Reducer, ScaleName } from '../PlotTypes.js';
 import { Transform } from '../Transform.js';
 
-/**
- * The set of known channel names. Channels in custom marks may use other names;
- * these known names are enumerated for convenient autocomplete.
- */
+/** The set of known channel names. */
 export type ChannelName =
   | 'ariaLabel'
   | 'fill'
@@ -38,8 +35,7 @@ export type ChannelName =
   | 'y'
   | 'y1'
   | 'y2'
-  | 'z'
-  | (string & Record<never, never>); // custom channel; see also https://github.com/microsoft/TypeScript/issues/29729
+  | 'z';
 
 type ChannelScale = ScaleName | 'auto' | boolean | null;
 
@@ -49,13 +45,12 @@ type ChannelScale = ScaleName | 'auto' | boolean | null;
  * - a field name, to extract the corresponding value for each datum
  * - an iterable of values, typically of the same length as the data
  * - a channel transform or SQL expression
- * - a constant date, number, or boolean
+ * - a constant number or boolean
  * - null to represent no value
  */
 export type ChannelValue =
   | any[] // column of values
   | (string & Record<never, never>) // field or literal color; see also https://github.com/microsoft/TypeScript/issues/29729
-  | Date // constant
   | number // constant
   | boolean // constant
   | null // constant
@@ -912,9 +907,7 @@ export interface CurveAutoOptions {
 export type StackOffsetName =
   | 'center'
   | 'normalize'
-  | 'wiggle'
-  | ('expand' & Record<never, never>) // deprecated; use normalize
-  | ('silhouette' & Record<never, never>); // deprecated; use center
+  | 'wiggle';
 
 /**
  * A stack offset method; one of:
@@ -955,8 +948,6 @@ export type StackOrderName = 'value' | 'x' | 'y' | 'z' | 'sum' | 'appearance' |
  *
  * - a named stack order method such as *inside-out* or *sum*
  * - a field name, for natural order of the corresponding values
- * - an accessor function, for natural order of the corresponding values
- * - a comparator function for ordering data
  * - an array of explicit **z** values in the desired order
  */
 export type StackOrder =

packages/spec/test/load-specs.js

@@ -29,3 +29,9 @@ export function loadJSON(name) {
 export function loadESM(name) {
   return readFile(join(ESM, `${name}.js`), 'utf8');
 }
+
+export async function loadJSONSchema() {
+  const path = join(__dirname, '../dist/mosaic-schema.json');
+  const text = await readFile(path, 'utf8');
+  return parse(text);
+}

packages/spec/test/parse-test.js → packages/spec/test/spec-test.js

@@ -1,7 +1,25 @@
 import assert from 'node:assert';
-import { specs, loadJSON, loadESM } from './load-specs.js';
+import ajv from 'ajv';
+import { specs, loadJSON, loadJSONSchema, loadESM } from './load-specs.js';
 import { astToESM, parseSpec } from '../src/index.js';
 
+// initialize JSON schema validator
+const validator = new ajv({
+  allErrors: true,
+  allowUnionTypes: true,
+  verbose: true
+});
+const schema = await loadJSONSchema();
+const validate = validator.compile(schema);
+
+// validate JSON schema
+describe('JSON schema', () => {
+  it('is a valid JSON schema', () => {
+    assert.ok(validator.validateSchema(schema));
+  });
+});
+
+// validate specs, parsing, and generation
 for (const [name, spec] of specs) {
   describe(`Test specification: ${name}`, () => {
     it(`produces esm output`, async () => {
@@ -23,5 +41,13 @@ for (const [name, spec] of specs) {
         `${name} did not round trip unchanged`
       );
     });
+    it(`passes JSON schema validation`, () => {
+      const valid = validate(spec);
+      if (!valid) {
+        console.error(validate.errors);
+      }
+      assert.ok(valid);
+      assert.ok(parseSpec(spec).toJSON());
+    });
   });
 }