feat: generate json schema (#498)

Author: mathio

.changeset/silly-kangaroos-pay.md

@@ -0,0 +1,6 @@
+---
+"@lingo.dev/_spec": patch
+"lingo.dev": patch
+---
+
+build json schema for config

packages/cli/i18n.json

@@ -48,5 +48,6 @@
     "yaml-root-key": {
       "include": ["demo/yaml-root-key/[locale].yml"]
     }
-  }
+  },
+  "$schema": "https://lingo.dev/schema/i18n.json"
 }

packages/spec/package.json

@@ -17,17 +17,20 @@
   "scripts": {
     "dev": "tsup --watch",
     "build": "tsc --noEmit && tsup",
-    "test": "vitest run"
+    "test": "vitest run",
+    "test:watch": "vitest"
   },
   "keywords": [],
   "author": "",
   "license": "Apache-2.0",
   "dependencies": {
     "typescript": "^5.7.2",
     "vitest": "^2.1.8",
-    "zod": "^3.24.1"
+    "zod": "^3.24.1",
+    "zod-to-json-schema": "^3.24.3"
   },
   "devDependencies": {
+    "@types/node": "^22.13.5",
     "tsup": "^8.3.5"
   }
 }

packages/spec/src/config.spec.ts

@@ -42,6 +42,17 @@ const createV1_2Config = () => ({
   version: 1.2,
 });
 
+const createV1_3Config = () => ({
+  ...createV1_2Config(),
+  version: 1.3,
+});
+
+const createV1_4Config = () => ({
+  ...createV1_3Config(),
+  version: 1.4,
+  $schema: "https://lingo.dev/schema/i18n.json",
+});
+
 const createInvalidLocaleConfig = () => ({
   version: 1,
   locale: {
@@ -55,20 +66,22 @@ const createInvalidLocaleConfig = () => ({
 });
 
 describe("I18n Config Parser", () => {
-  it("should upgrade v0 config to v1.2", () => {
+  it("should upgrade v0 config to latest version", () => {
     const v0Config = createV0Config();
     const result = parseI18nConfig(v0Config);
 
-    expect(result.version).toBe(1.3);
+    expect(result["$schema"]).toBeDefined();
+    expect(result.version).toBe(1.4);
     expect(result.locale).toEqual(defaultConfig.locale);
     expect(result.buckets).toEqual({});
   });
 
-  it("should upgrade v1 config to v1.2", () => {
+  it("should upgrade v1 config to latest version", () => {
     const v1Config = createV1Config();
     const result = parseI18nConfig(v1Config);
 
-    expect(result.version).toBe(1.3);
+    expect(result["$schema"]).toBeDefined();
+    expect(result.version).toBe(1.4);
     expect(result.locale).toEqual(v1Config.locale);
     expect(result.buckets).toEqual({
       json: {
@@ -80,13 +93,6 @@ describe("I18n Config Parser", () => {
     });
   });
 
-  it("should not modify v1.1 config", () => {
-    const v1_1Config = createV1_1Config();
-    const result = parseI18nConfig(v1_1Config);
-
-    expect(result).toEqual(v1_1Config);
-  });
-
   it("should throw an error for invalid configurations", () => {
     const invalidConfig = { version: "invalid" };
     expect(() => parseI18nConfig(invalidConfig)).toThrow("Failed to parse config");
@@ -101,13 +107,13 @@ describe("I18n Config Parser", () => {
 
   it("should ignore extra fields in the config", () => {
     const configWithExtra = {
-      ...createV1_1Config(),
+      ...createV1_4Config(),
       extraField: "should be ignored",
     };
     const result = parseI18nConfig(configWithExtra);
 
     expect(result).not.toHaveProperty("extraField");
-    expect(result).toEqual(createV1_1Config());
+    expect(result).toEqual(createV1_4Config());
   });
 
   it("should throw an error for unsupported locales", () => {

packages/spec/src/config.ts

@@ -200,8 +200,29 @@ export const configV1_3Definition = extendConfigDefinition(configV1_2Definition,
   }),
 });
 
+const configSchema = "https://lingo.dev/schema/i18n.json";
+
+// v1.3 -> v1.4
+// Changes: Add $schema to the config
+export const configV1_4Definition = extendConfigDefinition(configV1_3Definition, {
+  createSchema: (baseSchema) =>
+    baseSchema.extend({
+      $schema: Z.string().default(configSchema),
+    }),
+  createDefaultValue: (baseDefaultValue) => ({
+    ...baseDefaultValue,
+    version: 1.4,
+    $schema: configSchema,
+  }),
+  createUpgrader: (oldConfig) => ({
+    ...oldConfig,
+    version: 1.4,
+    $schema: configSchema,
+  }),
+});
+
 // exports
-const LATEST_CONFIG_DEFINITION = configV1_3Definition;
+export const LATEST_CONFIG_DEFINITION = configV1_4Definition;
 
 export type I18nConfig = Z.infer<(typeof LATEST_CONFIG_DEFINITION)["schema"]>;
 

packages/spec/src/json-schema.ts

@@ -0,0 +1,11 @@
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+import { zodToJsonSchema } from "zod-to-json-schema";
+import { LATEST_CONFIG_DEFINITION } from "./config";
+
+export default function buildJsonSchema() {
+  const configSchema = zodToJsonSchema(LATEST_CONFIG_DEFINITION.schema);
+  const currentDir = path.dirname(fileURLToPath(import.meta.url));
+  fs.writeFileSync(`${currentDir}/../build/i18n.schema.json`, JSON.stringify(configSchema, null, 2));
+}

packages/spec/tsup.config.ts

@@ -1,4 +1,5 @@
 import { defineConfig } from "tsup";
+import buildJsonSchema from "./src/json-schema";
 
 export default defineConfig({
   clean: true,
@@ -12,4 +13,7 @@ export default defineConfig({
   outExtension: (ctx) => ({
     js: ctx.format === "cjs" ? ".cjs" : ".mjs",
   }),
+  onSuccess: async () => {
+    buildJsonSchema();
+  },
 });