@twin.org/ts-to-schema 0.0.1-next.24 → 0.0.1-next.26

package/dist/cjs/index.cjs

@@ -10,6 +10,7 @@ var tsJsonSchemaGenerator = require('ts-json-schema-generator');
 var _documentCurrentScript = typeof document !== 'undefined' ? document.currentScript : null;
 // Copyright 2024 IOTA Stiftung.
 // SPDX-License-Identifier: Apache-2.0.
+const SCHEMA_VERSION = "https://json-schema.org/draft/2020-12/schema";
 /**
  * Build the root command to be consumed by the CLI.
  * @param program The command to build on.
@@ -79,14 +80,23 @@ async function tsToSchema(config, outputFolder, workingDirectory) {
     cliCore.CLIDisplay.break();
     cliCore.CLIDisplay.task(core.I18n.formatMessage("commands.ts-to-schema.progress.writingSchemas"));
     for (const typeSource of config.types) {
-        cliCore.CLIDisplay.task(core.I18n.formatMessage("commands.ts-to-schema.progress.generatingSchema"));
         const typeSourceParts = typeSource.split("/");
         const type = core.StringHelper.pascalCase(typeSourceParts[typeSourceParts.length - 1].replace(/(\.d)?\.ts$/, ""), false);
-        const schemas = await generateSchemas(typeSource, type, workingDirectory);
-        if (core.Is.empty(schemas[type])) {
-            throw new core.GeneralError("commands", "commands.ts-to-schema.schemaNotFound", { type });
+        let schemaObject;
+        if (core.Is.object(config.overrides?.[type])) {
+            cliCore.CLIDisplay.task(core.I18n.formatMessage("commands.ts-to-schema.progress.overridingSchema"));
+            schemaObject = config.overrides?.[type];
         }
-        let content = JSON.stringify(schemas[type], undefined, "\t");
+        else {
+            cliCore.CLIDisplay.task(core.I18n.formatMessage("commands.ts-to-schema.progress.generatingSchema"));
+            const schemas = await generateSchemas(typeSource, type, workingDirectory);
+            if (core.Is.empty(schemas[type])) {
+                throw new core.GeneralError("commands", "commands.ts-to-schema.schemaNotFound", { type });
+            }
+            schemaObject = schemas[type];
+        }
+        schemaObject = finaliseSchema(schemaObject, config.baseUrl, type);
+        let content = JSON.stringify(schemaObject, undefined, "\t");
         if (core.Is.objectValue(config.externalReferences)) {
             for (const external in config.externalReferences) {
                 content = content.replace(new RegExp(`#/definitions/${external}`, "g"), config.externalReferences[external]);
@@ -201,6 +211,76 @@ function extractTypesFromSchema(allTypes, schema, output) {
         extractTypes(allTypes, additionalTypes, output);
     }
 }
+/**
+ * Process the schema object to ensure it has the correct properties.
+ * @param schemaObject The schema object to process.
+ * @param baseUrl The base URL for the schema references.
+ * @param type The type of the schema object.
+ * @returns The finalised schema object.
+ */
+function finaliseSchema(schemaObject, baseUrl, type) {
+    processArrays(schemaObject);
+    const { description, ...rest } = schemaObject;
+    return {
+        $schema: SCHEMA_VERSION,
+        $id: `${baseUrl}${core.StringHelper.stripPrefix(type)}`,
+        description,
+        ...rest
+    };
+}
+/**
+ * Process arrays in the schema object.
+ * @param schemaObject The schema object to process.
+ */
+function processArrays(schemaObject) {
+    if (core.Is.object(schemaObject)) {
+        // latest specs have singular items in `items` property
+        // and multiple items in prefixItems, so update the schema accordingly
+        // https://www.learnjsonschema.com/2020-12/applicator/items/
+        // https://www.learnjsonschema.com/2020-12/applicator/prefixitems/
+        const schemaItems = schemaObject.items;
+        if (core.Is.array(schemaItems) || core.Is.object(schemaItems)) {
+            schemaObject.prefixItems = core.ArrayHelper.fromObjectOrArray(schemaItems);
+            schemaObject.items = false;
+        }
+        const additionalItems = schemaObject.additionalItems;
+        if (core.Is.array(additionalItems) || core.Is.object(additionalItems)) {
+            schemaObject.items = core.ArrayHelper.fromObjectOrArray(additionalItems)[0];
+            delete schemaObject.additionalItems;
+        }
+        processSchemaDictionary(schemaObject.properties);
+        processArrays(schemaObject.additionalProperties);
+        processSchemaArray(schemaObject.allOf);
+        processSchemaArray(schemaObject.anyOf);
+        processSchemaArray(schemaObject.oneOf);
+    }
+}
+/**
+ * Process arrays in the schema object.
+ * @param schemaDictionary The schema object to process.
+ */
+function processSchemaDictionary(schemaDictionary) {
+    if (core.Is.object(schemaDictionary)) {
+        for (const item of Object.values(schemaDictionary)) {
+            if (core.Is.object(item)) {
+                processArrays(item);
+            }
+        }
+    }
+}
+/**
+ * Process arrays in the schema object.
+ * @param schemaArray The schema object to process.
+ */
+function processSchemaArray(schemaArray) {
+    if (core.Is.arrayValue(schemaArray)) {
+        for (const item of schemaArray) {
+            if (core.Is.object(item)) {
+                processArrays(item);
+            }
+        }
+    }
+}
 
 // Copyright 2024 IOTA Stiftung.
 // SPDX-License-Identifier: Apache-2.0.
@@ -220,7 +300,7 @@ class CLI extends cliCore.CLIBase {
         return this.execute({
             title: "TWIN TypeScript To Schema",
             appName: "ts-to-schema",
-            version: "0.0.1-next.24", // x-release-please-version
+            version: "0.0.1-next.26", // x-release-please-version
             icon: "⚙️ ",
             supportsEnvFiles: false,
             overrideOutputWidth: options?.overrideOutputWidth

package/dist/esm/index.mjs

@@ -2,11 +2,12 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { CLIDisplay, CLIUtils, CLIBase } from '@twin.org/cli-core';
 import { mkdir, rm, writeFile } from 'node:fs/promises';
-import { I18n, GeneralError, Is, StringHelper } from '@twin.org/core';
+import { I18n, GeneralError, Is, StringHelper, ArrayHelper } from '@twin.org/core';
 import { createGenerator } from 'ts-json-schema-generator';
 
 // Copyright 2024 IOTA Stiftung.
 // SPDX-License-Identifier: Apache-2.0.
+const SCHEMA_VERSION = "https://json-schema.org/draft/2020-12/schema";
 /**
  * Build the root command to be consumed by the CLI.
  * @param program The command to build on.
@@ -76,14 +77,23 @@ async function tsToSchema(config, outputFolder, workingDirectory) {
     CLIDisplay.break();
     CLIDisplay.task(I18n.formatMessage("commands.ts-to-schema.progress.writingSchemas"));
     for (const typeSource of config.types) {
-        CLIDisplay.task(I18n.formatMessage("commands.ts-to-schema.progress.generatingSchema"));
         const typeSourceParts = typeSource.split("/");
         const type = StringHelper.pascalCase(typeSourceParts[typeSourceParts.length - 1].replace(/(\.d)?\.ts$/, ""), false);
-        const schemas = await generateSchemas(typeSource, type, workingDirectory);
-        if (Is.empty(schemas[type])) {
-            throw new GeneralError("commands", "commands.ts-to-schema.schemaNotFound", { type });
+        let schemaObject;
+        if (Is.object(config.overrides?.[type])) {
+            CLIDisplay.task(I18n.formatMessage("commands.ts-to-schema.progress.overridingSchema"));
+            schemaObject = config.overrides?.[type];
         }
-        let content = JSON.stringify(schemas[type], undefined, "\t");
+        else {
+            CLIDisplay.task(I18n.formatMessage("commands.ts-to-schema.progress.generatingSchema"));
+            const schemas = await generateSchemas(typeSource, type, workingDirectory);
+            if (Is.empty(schemas[type])) {
+                throw new GeneralError("commands", "commands.ts-to-schema.schemaNotFound", { type });
+            }
+            schemaObject = schemas[type];
+        }
+        schemaObject = finaliseSchema(schemaObject, config.baseUrl, type);
+        let content = JSON.stringify(schemaObject, undefined, "\t");
         if (Is.objectValue(config.externalReferences)) {
             for (const external in config.externalReferences) {
                 content = content.replace(new RegExp(`#/definitions/${external}`, "g"), config.externalReferences[external]);
@@ -198,6 +208,76 @@ function extractTypesFromSchema(allTypes, schema, output) {
         extractTypes(allTypes, additionalTypes, output);
     }
 }
+/**
+ * Process the schema object to ensure it has the correct properties.
+ * @param schemaObject The schema object to process.
+ * @param baseUrl The base URL for the schema references.
+ * @param type The type of the schema object.
+ * @returns The finalised schema object.
+ */
+function finaliseSchema(schemaObject, baseUrl, type) {
+    processArrays(schemaObject);
+    const { description, ...rest } = schemaObject;
+    return {
+        $schema: SCHEMA_VERSION,
+        $id: `${baseUrl}${StringHelper.stripPrefix(type)}`,
+        description,
+        ...rest
+    };
+}
+/**
+ * Process arrays in the schema object.
+ * @param schemaObject The schema object to process.
+ */
+function processArrays(schemaObject) {
+    if (Is.object(schemaObject)) {
+        // latest specs have singular items in `items` property
+        // and multiple items in prefixItems, so update the schema accordingly
+        // https://www.learnjsonschema.com/2020-12/applicator/items/
+        // https://www.learnjsonschema.com/2020-12/applicator/prefixitems/
+        const schemaItems = schemaObject.items;
+        if (Is.array(schemaItems) || Is.object(schemaItems)) {
+            schemaObject.prefixItems = ArrayHelper.fromObjectOrArray(schemaItems);
+            schemaObject.items = false;
+        }
+        const additionalItems = schemaObject.additionalItems;
+        if (Is.array(additionalItems) || Is.object(additionalItems)) {
+            schemaObject.items = ArrayHelper.fromObjectOrArray(additionalItems)[0];
+            delete schemaObject.additionalItems;
+        }
+        processSchemaDictionary(schemaObject.properties);
+        processArrays(schemaObject.additionalProperties);
+        processSchemaArray(schemaObject.allOf);
+        processSchemaArray(schemaObject.anyOf);
+        processSchemaArray(schemaObject.oneOf);
+    }
+}
+/**
+ * Process arrays in the schema object.
+ * @param schemaDictionary The schema object to process.
+ */
+function processSchemaDictionary(schemaDictionary) {
+    if (Is.object(schemaDictionary)) {
+        for (const item of Object.values(schemaDictionary)) {
+            if (Is.object(item)) {
+                processArrays(item);
+            }
+        }
+    }
+}
+/**
+ * Process arrays in the schema object.
+ * @param schemaArray The schema object to process.
+ */
+function processSchemaArray(schemaArray) {
+    if (Is.arrayValue(schemaArray)) {
+        for (const item of schemaArray) {
+            if (Is.object(item)) {
+                processArrays(item);
+            }
+        }
+    }
+}
 
 // Copyright 2024 IOTA Stiftung.
 // SPDX-License-Identifier: Apache-2.0.
@@ -217,7 +297,7 @@ class CLI extends CLIBase {
         return this.execute({
             title: "TWIN TypeScript To Schema",
             appName: "ts-to-schema",
-            version: "0.0.1-next.24", // x-release-please-version
+            version: "0.0.1-next.26", // x-release-please-version
             icon: "⚙️ ",
             supportsEnvFiles: false,
             overrideOutputWidth: options?.overrideOutputWidth

package/dist/locales/en.json

@@ -80,6 +80,8 @@
 			"array": "Property \"{property}\" must be an array, it is \"{value}\"",
 			"arrayValue": "Property \"{property}\" must be an array with at least one item",
 			"arrayOneOf": "Property \"{property}\" must be one of [{options}], it is \"{value}\"",
+			"arrayStartsWith": "Property \"{property}\" must be an array starting with [{startValues}], it is \"{value}\"",
+			"arrayEndsWith": "Property \"{property}\" must be an array ending with [{endValues}], it is \"{value}\"",
 			"uint8Array": "Property \"{property}\" must be a Uint8Array, it is \"{value}\"",
 			"function": "Property \"{property}\" must be a function, it is \"{value}\"",
 			"urn": "Property \"{property}\" must be a Urn formatted string, it is \"{value}\"",
@@ -250,6 +252,7 @@
 				"loadingConfigJson": "Loading Config JSON",
 				"creatingWorkingDir": "Creating Working Directory",
 				"generatingSchema": "Generating Schema",
+				"overridingSchema": "Overriding Schema",
 				"writingSchemas": "Writing Schemas",
 				"writingSchema": "Writing Schema",
 				"models": "Models"

package/dist/types/models/IJsonSchema.d.ts

@@ -0,0 +1,5 @@
+import type { AnySchemaObject } from "ajv/dist/2020.js";
+/**
+ * Default schema type.
+ */
+export type IJsonSchema = AnySchemaObject;

package/dist/types/models/ITsToSchemaConfig.d.ts

@@ -1,3 +1,4 @@
+import type { IJsonSchema } from "./IJsonSchema";
 /**
  * Configuration for the tool.
  */
@@ -16,4 +17,10 @@ export interface ITsToSchemaConfig {
     externalReferences?: {
         [id: string]: string;
     };
+    /**
+     * Override for specific types, to be used when the type cannot be generated automatically, or is generated incorrectly.
+     */
+    overrides?: {
+        [id: string]: IJsonSchema;
+    };
 }

package/docs/changelog.md

@@ -1,5 +1,41 @@
 # @twin.org/ts-to-schema - Changelog
 
+## [0.0.1-next.26](https://github.com/twinfoundation/tools/compare/ts-to-schema-v0.0.1-next.25...ts-to-schema-v0.0.1-next.26) (2025-06-11)
+
+
+### Features
+
+* use most recent JSON schema specs ([4598cbf](https://github.com/twinfoundation/tools/commit/4598cbf29f7b82dba4a9f3b19f81dfe66f5a6060))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/nameof bumped from 0.0.1-next.25 to 0.0.1-next.26
+  * devDependencies
+    * @twin.org/merge-locales bumped from 0.0.1-next.25 to 0.0.1-next.26
+    * @twin.org/nameof-transformer bumped from 0.0.1-next.25 to 0.0.1-next.26
+    * @twin.org/nameof-vitest-plugin bumped from 0.0.1-next.25 to 0.0.1-next.26
+
+## [0.0.1-next.25](https://github.com/twinfoundation/tools/compare/ts-to-schema-v0.0.1-next.24...ts-to-schema-v0.0.1-next.25) (2025-06-10)
+
+
+### Features
+
+* add ts-to-schema overrides ([3c54504](https://github.com/twinfoundation/tools/commit/3c5450468eb998204a75576b7791a7ca4027da62))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/nameof bumped from 0.0.1-next.24 to 0.0.1-next.25
+  * devDependencies
+    * @twin.org/merge-locales bumped from 0.0.1-next.24 to 0.0.1-next.25
+    * @twin.org/nameof-transformer bumped from 0.0.1-next.24 to 0.0.1-next.25
+    * @twin.org/nameof-vitest-plugin bumped from 0.0.1-next.24 to 0.0.1-next.25
+
 ## [0.0.1-next.24](https://github.com/twinfoundation/tools/compare/ts-to-schema-v0.0.1-next.23...ts-to-schema-v0.0.1-next.24) (2025-06-05)
 
 

package/docs/reference/interfaces/ITsToSchemaConfig.md

@@ -29,3 +29,15 @@ External type references
 #### Index Signature
 
 \[`id`: `string`\]: `string`
+
+***
+
+### overrides?
+
+> `optional` **overrides**: `object`
+
+Override for specific types, to be used when the type cannot be generated automatically, or is generated incorrectly.
+
+#### Index Signature
+
+\[`id`: `string`\]: `AnySchemaObject`

package/locales/en.json

@@ -23,6 +23,7 @@
 				"loadingConfigJson": "Loading Config JSON",
 				"creatingWorkingDir": "Creating Working Directory",
 				"generatingSchema": "Generating Schema",
+				"overridingSchema": "Overriding Schema",
 				"writingSchemas": "Writing Schemas",
 				"writingSchema": "Writing Schema",
 				"models": "Models"

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@twin.org/ts-to-schema",
-	"version": "0.0.1-next.24",
+	"version": "0.0.1-next.26",
 	"description": "Tool to convert TypeScript definitions to JSON schemas",
 	"repository": {
 		"type": "git",
@@ -16,10 +16,10 @@
 	"dependencies": {
 		"@twin.org/cli-core": "next",
 		"@twin.org/core": "next",
-		"@twin.org/nameof": "0.0.1-next.24",
-		"commander": "13.1.0",
-		"glob": "11.0.1",
-		"jsonschema": "1.5.0",
+		"@twin.org/nameof": "0.0.1-next.26",
+		"ajv": "8.17.1",
+		"commander": "14.0.0",
+		"glob": "11.0.2",
 		"ts-json-schema-generator": "2.4.0"
 	},
 	"main": "./dist/cjs/index.cjs",