@twin.org/tools-core 0.0.3-next.25 → 0.0.3-next.26

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

@@ -1,5 +1,6 @@
 import type { IJsonSchema } from "@twin.org/tools-models";
 import type * as ts from "typescript";
+import type { EmbeddedSchemaMode } from "./embeddedSchemaMode.js";
 import type { ITypeScriptToSchemaOptions } from "./ITypeScriptToSchemaOptions.js";
 /**
  * Context for TypeScript to JSON schema generation.
@@ -57,6 +58,12 @@ export interface ITypeScriptToSchemaContext {
     typeParameterBindings?: {
         [id: string]: ts.TypeNode | null;
     };
+    /**
+     * Schema ids marked with @json-schema embedded and their embedding mode.
+     */
+    embeddedSchemaModes?: {
+        [id: string]: EmbeddedSchemaMode;
+    };
     /**
      * Optional schema generation options.
      */

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

@@ -0,0 +1,17 @@
+/**
+ * The available embedded schema modes.
+ */
+export declare const EmbeddedSchemaMode: {
+    /**
+     * Referenced schemas are added to the "defs" section of the root schema.
+     */
+    readonly Defs: "defs";
+    /**
+     * Referenced schemas are inlined into the referencing schema.
+     */
+    readonly Inline: "inline";
+};
+/**
+ * The embedded schema mode value type.
+ */
+export type EmbeddedSchemaMode = (typeof EmbeddedSchemaMode)[keyof typeof EmbeddedSchemaMode];

package/dist/types/utils/jsDoc.d.ts

@@ -37,7 +37,7 @@ export declare class JsDoc {
     static getNodeTagComment(node: ts.Node, tagName: string): string | undefined;
     /**
      * Parse a custom JSDoc tag value into JSON-compatible data.
-     * Values that begin with a JSON token character ({, [, ", true, false, null) or look like a
+     * Values that begin with a JSON token character (open brace, open bracket, double quote, true, false, null) or look like a
      * number are parsed with JSON.parse.  All other values are returned as plain strings.
      * @param value The raw value text.
      * @returns The parsed value.

package/dist/types/utils/typeScriptToSchema.d.ts

@@ -28,4 +28,65 @@ export declare class TypeScriptToSchema {
      * @returns True if the diagnostic originated from the package.
      */
     isDiagnosticFromPackage(path: string, fileName: string | undefined, packageName: string): boolean;
+    /**
+     * Rewrite refs to @json-schema embedded local types into the current schema's $defs.
+     * @param context The generation context.
+     * @param schema The root schema to rewrite.
+     * @param rootTitle The title of the root schema.
+     */
+    private inlineEmbeddedSchemas;
+    /**
+     * Traverse a schema tree and move embedded local refs into the root schema's $defs.
+     * @param context The generation context.
+     * @param rootSchema The root schema document being rewritten.
+     * @param currentNode The current schema node.
+     * @param rootTitle The title of the root schema.
+     * @param ancestry Titles currently being expanded to avoid recursion cycles.
+     * @returns True if inline embedding changed this node or a descendant.
+     */
+    private inlineEmbeddedSchemasInNode;
+    /**
+     * Flatten inline-expanded object allOf branches into the containing schema.
+     * @param schema The schema to flatten.
+     */
+    private flattenInlineAllOfBranches;
+    /**
+     * Determine whether an allOf branch can be flattened into its parent after inline embedding.
+     * @param branch The allOf branch.
+     * @returns True if the branch is a plain object schema.
+     */
+    private canFlattenInlineAllOfBranch;
+    /**
+     * Create a clone of an embedded schema suitable for defs or inline expansion.
+     * @param context The generation context.
+     * @param embeddedSchema The source schema.
+     * @param embeddedMode The embedding mode.
+     * @returns The cloned schema.
+     */
+    private createEmbeddedSchemaClone;
+    /**
+     * Replace the contents of a schema node while keeping the same object reference.
+     * @param target The schema node to mutate.
+     * @param replacement The replacement content.
+     */
+    private replaceSchemaNode;
+    /**
+     * Find a generated schema by its canonical id across all loaded packages.
+     * @param context The generation context.
+     * @param schemaId The schema id to locate.
+     * @returns The schema when found.
+     */
+    private findSchemaById;
+    /**
+     * Resolve the local $defs key to use for an embedded schema.
+     * @param schema The embedded schema.
+     * @param schemaId The canonical schema id.
+     * @returns The local definition key.
+     */
+    private getEmbeddedDefinitionKey;
+    /**
+     * Remove $comment fields from a schema tree.
+     * @param schema The schema tree to clean.
+     */
+    private removeSchemaComments;
 }

package/dist/types/utils/utilityTypeSchemaMapper.d.ts

@@ -6,65 +6,65 @@ import type { ITypeScriptToSchemaContext } from "../models/ITypeScriptToSchemaCo
  */
 export declare class UtilityTypeSchemaMapper {
     /**
-     * Map Partial<T> to an object schema with no required properties.
+     * Map `Partial<T>` to an object schema with no required properties.
      * @param context The generation context.
-     * @param typeNode The Partial type reference.
+     * @param typeNode The `Partial` type reference.
      * @returns The mapped schema.
      */
     static mapPartialUtilityType(context: ITypeScriptToSchemaContext, typeNode: ts.TypeReferenceNode): IJsonSchema | undefined;
     /**
-     * Map Required<T> to an object schema with all properties required.
+     * Map `Required<T>` to an object schema with all properties required.
      * @param context The generation context.
-     * @param typeNode The Required type reference.
+     * @param typeNode The `Required` type reference.
      * @returns The mapped schema.
      */
     static mapRequiredUtilityType(context: ITypeScriptToSchemaContext, typeNode: ts.TypeReferenceNode): IJsonSchema | undefined;
     /**
-     * Map Pick<T, K> to an object schema with selected keys preserved.
+     * Map `Pick<T, K>` to an object schema with selected keys preserved.
      * @param context The generation context.
      * @param typeNode The Pick type reference.
      * @returns The mapped schema.
      */
     static mapPickUtilityType(context: ITypeScriptToSchemaContext, typeNode: ts.TypeReferenceNode): IJsonSchema | undefined;
     /**
-     * Map Omit<T, K> to an object schema with selected keys removed.
+     * Map `Omit<T, K>` to an object schema with selected keys removed.
      * @param context The generation context.
-     * @param typeNode The Omit type reference.
+     * @param typeNode The `Omit` type reference.
      * @returns The mapped schema.
      */
     static mapOmitUtilityType(context: ITypeScriptToSchemaContext, typeNode: ts.TypeReferenceNode): IJsonSchema | undefined;
     /**
-     * Map Exclude<T, U> to a schema that removes U members from T.
+     * Map `Exclude<T, U>` to a schema that removes `U` members from `T`.
      * @param context The generation context.
-     * @param typeNode The Exclude type reference.
+     * @param typeNode The `Exclude` type reference.
      * @returns The mapped schema.
      */
     static mapExcludeUtilityType(context: ITypeScriptToSchemaContext, typeNode: ts.TypeReferenceNode): IJsonSchema | undefined;
     /**
-     * Map Extract<T, U> to a schema that keeps U members from T.
+     * Map `Extract<T, U>` to a schema that keeps `U` members from `T`.
      * @param context The generation context.
-     * @param typeNode The Extract type reference.
+     * @param typeNode The `Extract` type reference.
      * @returns The mapped schema.
      */
     static mapExtractUtilityType(context: ITypeScriptToSchemaContext, typeNode: ts.TypeReferenceNode): IJsonSchema | undefined;
     /**
-     * Map NonNullable<T> by removing null and undefined branches from T.
+     * Map `NonNullable<T>` by removing `null` and `undefined` branches from `T`.
      * @param context The generation context.
-     * @param typeNode The NonNullable type reference.
+     * @param typeNode The `NonNullable` type reference.
      * @returns The mapped schema.
      */
     static mapNonNullableUtilityType(context: ITypeScriptToSchemaContext, typeNode: ts.TypeReferenceNode): IJsonSchema | undefined;
     /**
-     * Map Record<K, V> to an object schema with key constraints where possible.
+     * Map `Record<K, V>` to an object schema with key constraints where possible.
      * @param context The generation context.
-     * @param typeNode The Record type reference.
+     * @param typeNode The `Record` type reference.
      * @returns The mapped schema.
      */
     static mapRecordUtilityType(context: ITypeScriptToSchemaContext, typeNode: ts.TypeReferenceNode): IJsonSchema | undefined;
     /**
-     * Map JsonLdObject utility types using key-removal and optional key-addition rules.
+     * Map `JsonLdObject` utility types using key-removal and optional key-addition rules.
      * @param context The generation context.
-     * @param typeNode The JsonLdObject utility type reference.
+     * @param typeNode The `JsonLdObject` utility type reference.
      * @param options The mapping options for key removal and optional key addition.
      * @param options.keysToRemove The property keys to remove from the base schema.
      * @param options.keyToAdd The optional key to add after removal.
@@ -77,16 +77,16 @@ export declare class UtilityTypeSchemaMapper {
         isAddedKeyRequired?: boolean;
     }): IJsonSchema | undefined;
     /**
-     * Map ObjectOrArray<T> to a schema accepting T or T[].
+     * Map `ObjectOrArray<T>` to a schema accepting `T` or `T[]`.
      * @param context The generation context.
-     * @param typeNode The ObjectOrArray type reference.
+     * @param typeNode The `ObjectOrArray` type reference.
      * @returns The mapped schema.
      */
     static mapObjectOrArrayUtilityType(context: ITypeScriptToSchemaContext, typeNode: ts.TypeReferenceNode): IJsonSchema | undefined;
     /**
-     * Map SingleOccurrenceArray<T, U> to a non-empty array containing exactly one U.
+     * Map `SingleOccurrenceArray<T, U>` to a non-empty array containing exactly one `U`.
      * @param context The generation context.
-     * @param typeNode The SingleOccurrenceArray type reference.
+     * @param typeNode The `SingleOccurrenceArray` type reference.
      * @returns The mapped schema.
      */
     static mapSingleOccurrenceArrayUtilityType(context: ITypeScriptToSchemaContext, typeNode: ts.TypeReferenceNode): IJsonSchema | undefined;

package/docs/changelog.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [0.0.3-next.26](https://github.com/twinfoundation/tools/compare/tools-core-v0.0.3-next.25...tools-core-v0.0.3-next.26) (2026-03-27)
+
+
+### Features
+
+* add json-schema embedded mode ([#102](https://github.com/twinfoundation/tools/issues/102)) ([f070967](https://github.com/twinfoundation/tools/commit/f070967f8f3308e0b5320eab278a319c9d229e3e))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/tools-models bumped from 0.0.3-next.25 to 0.0.3-next.26
+
 ## [0.0.3-next.25](https://github.com/twinfoundation/tools/compare/tools-core-v0.0.3-next.24...tools-core-v0.0.3-next.25) (2026-03-23)
 
 

package/docs/reference/classes/JsDoc.md

@@ -123,7 +123,7 @@ The trimmed comment text, or undefined when absent.
 > `static` **parseTagValue**(`value`): `unknown`
 
 Parse a custom JSDoc tag value into JSON-compatible data.
-Values that begin with a JSON token character ({, [, ", true, false, null) or look like a
+Values that begin with a JSON token character (open brace, open bracket, double quote, true, false, null) or look like a
 number are parsed with JSON.parse.  All other values are returned as plain strings.
 
 #### Parameters

package/docs/reference/classes/UtilityTypeSchemaMapper.md

@@ -18,7 +18,7 @@ Static utility-type schema mapping helpers.
 
 > `static` **mapPartialUtilityType**(`context`, `typeNode`): `IJsonSchema` \| `undefined`
 
-Map Partial<T> to an object schema with no required properties.
+Map `Partial<T>` to an object schema with no required properties.
 
 #### Parameters
 
@@ -32,7 +32,7 @@ The generation context.
 
 `TypeReferenceNode`
 
-The Partial type reference.
+The `Partial` type reference.
 
 #### Returns
 
@@ -46,7 +46,7 @@ The mapped schema.
 
 > `static` **mapRequiredUtilityType**(`context`, `typeNode`): `IJsonSchema` \| `undefined`
 
-Map Required<T> to an object schema with all properties required.
+Map `Required<T>` to an object schema with all properties required.
 
 #### Parameters
 
@@ -60,7 +60,7 @@ The generation context.
 
 `TypeReferenceNode`
 
-The Required type reference.
+The `Required` type reference.
 
 #### Returns
 
@@ -74,7 +74,7 @@ The mapped schema.
 
 > `static` **mapPickUtilityType**(`context`, `typeNode`): `IJsonSchema` \| `undefined`
 
-Map Pick<T, K> to an object schema with selected keys preserved.
+Map `Pick<T, K>` to an object schema with selected keys preserved.
 
 #### Parameters
 
@@ -102,7 +102,7 @@ The mapped schema.
 
 > `static` **mapOmitUtilityType**(`context`, `typeNode`): `IJsonSchema` \| `undefined`
 
-Map Omit<T, K> to an object schema with selected keys removed.
+Map `Omit<T, K>` to an object schema with selected keys removed.
 
 #### Parameters
 
@@ -116,7 +116,7 @@ The generation context.
 
 `TypeReferenceNode`
 
-The Omit type reference.
+The `Omit` type reference.
 
 #### Returns
 
@@ -130,7 +130,7 @@ The mapped schema.
 
 > `static` **mapExcludeUtilityType**(`context`, `typeNode`): `IJsonSchema` \| `undefined`
 
-Map Exclude<T, U> to a schema that removes U members from T.
+Map `Exclude<T, U>` to a schema that removes `U` members from `T`.
 
 #### Parameters
 
@@ -144,7 +144,7 @@ The generation context.
 
 `TypeReferenceNode`
 
-The Exclude type reference.
+The `Exclude` type reference.
 
 #### Returns
 
@@ -158,7 +158,7 @@ The mapped schema.
 
 > `static` **mapExtractUtilityType**(`context`, `typeNode`): `IJsonSchema` \| `undefined`
 
-Map Extract<T, U> to a schema that keeps U members from T.
+Map `Extract<T, U>` to a schema that keeps `U` members from `T`.
 
 #### Parameters
 
@@ -172,7 +172,7 @@ The generation context.
 
 `TypeReferenceNode`
 
-The Extract type reference.
+The `Extract` type reference.
 
 #### Returns
 
@@ -186,7 +186,7 @@ The mapped schema.
 
 > `static` **mapNonNullableUtilityType**(`context`, `typeNode`): `IJsonSchema` \| `undefined`
 
-Map NonNullable<T> by removing null and undefined branches from T.
+Map `NonNullable<T>` by removing `null` and `undefined` branches from `T`.
 
 #### Parameters
 
@@ -200,7 +200,7 @@ The generation context.
 
 `TypeReferenceNode`
 
-The NonNullable type reference.
+The `NonNullable` type reference.
 
 #### Returns
 
@@ -214,7 +214,7 @@ The mapped schema.
 
 > `static` **mapRecordUtilityType**(`context`, `typeNode`): `IJsonSchema` \| `undefined`
 
-Map Record<K, V> to an object schema with key constraints where possible.
+Map `Record<K, V>` to an object schema with key constraints where possible.
 
 #### Parameters
 
@@ -228,7 +228,7 @@ The generation context.
 
 `TypeReferenceNode`
 
-The Record type reference.
+The `Record` type reference.
 
 #### Returns
 
@@ -242,7 +242,7 @@ The mapped schema.
 
 > `static` **mapJsonLdObjectUtilityType**(`context`, `typeNode`, `options`): `IJsonSchema` \| `undefined`
 
-Map JsonLdObject utility types using key-removal and optional key-addition rules.
+Map `JsonLdObject` utility types using key-removal and optional key-addition rules.
 
 #### Parameters
 
@@ -256,7 +256,7 @@ The generation context.
 
 `TypeReferenceNode`
 
-The JsonLdObject utility type reference.
+The `JsonLdObject` utility type reference.
 
 ##### options
 
@@ -292,7 +292,7 @@ The mapped schema.
 
 > `static` **mapObjectOrArrayUtilityType**(`context`, `typeNode`): `IJsonSchema` \| `undefined`
 
-Map ObjectOrArray<T> to a schema accepting T or T[].
+Map `ObjectOrArray<T>` to a schema accepting `T` or `T[]`.
 
 #### Parameters
 
@@ -306,7 +306,7 @@ The generation context.
 
 `TypeReferenceNode`
 
-The ObjectOrArray type reference.
+The `ObjectOrArray` type reference.
 
 #### Returns
 
@@ -320,7 +320,7 @@ The mapped schema.
 
 > `static` **mapSingleOccurrenceArrayUtilityType**(`context`, `typeNode`): `IJsonSchema` \| `undefined`
 
-Map SingleOccurrenceArray<T, U> to a non-empty array containing exactly one U.
+Map `SingleOccurrenceArray<T, U>` to a non-empty array containing exactly one `U`.
 
 #### Parameters
 
@@ -334,7 +334,7 @@ The generation context.
 
 `TypeReferenceNode`
 
-The SingleOccurrenceArray type reference.
+The `SingleOccurrenceArray` type reference.
 
 #### Returns
 

package/docs/reference/index.md

@@ -25,3 +25,11 @@
 - [ITypeScriptToSchemaContext](interfaces/ITypeScriptToSchemaContext.md)
 - [ITypeScriptToSchemaDiagnostics](interfaces/ITypeScriptToSchemaDiagnostics.md)
 - [ITypeScriptToSchemaOptions](interfaces/ITypeScriptToSchemaOptions.md)
+
+## Type Aliases
+
+- [EmbeddedSchemaMode](type-aliases/EmbeddedSchemaMode.md)
+
+## Variables
+
+- [EmbeddedSchemaMode](variables/EmbeddedSchemaMode.md)

package/docs/reference/interfaces/ITypeScriptToSchemaContext.md

@@ -106,6 +106,18 @@ Generic type parameter bindings active for the current mapping scope.
 
 ***
 
+### embeddedSchemaModes? {#embeddedschemamodes}
+
+> `optional` **embeddedSchemaModes?**: `object`
+
+Schema ids marked with
+
+#### Index Signature
+
+\[`id`: `string`\]: [`EmbeddedSchemaMode`](../type-aliases/EmbeddedSchemaMode.md)
+
+***
+
 ### options? {#options}
 
 > `optional` **options?**: [`ITypeScriptToSchemaOptions`](ITypeScriptToSchemaOptions.md)

package/docs/reference/type-aliases/EmbeddedSchemaMode.md

@@ -0,0 +1,5 @@
+# Type Alias: EmbeddedSchemaMode
+
+> **EmbeddedSchemaMode** = *typeof* [`EmbeddedSchemaMode`](../variables/EmbeddedSchemaMode.md)\[keyof *typeof* [`EmbeddedSchemaMode`](../variables/EmbeddedSchemaMode.md)\]
+
+The embedded schema mode value type.

package/docs/reference/variables/EmbeddedSchemaMode.md

@@ -0,0 +1,19 @@
+# Variable: EmbeddedSchemaMode
+
+> `const` **EmbeddedSchemaMode**: `object`
+
+The available embedded schema modes.
+
+## Type Declaration
+
+### Defs {#defs}
+
+> `readonly` **Defs**: `"defs"` = `"defs"`
+
+Referenced schemas are added to the "defs" section of the root schema.
+
+### Inline {#inline}
+
+> `readonly` **Inline**: `"inline"` = `"inline"`
+
+Referenced schemas are inlined into the referencing schema.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@twin.org/tools-core",
-	"version": "0.0.3-next.25",
+	"version": "0.0.3-next.26",
 	"description": "Shared utilities and models for tooling packages",
 	"repository": {
 		"type": "git",
@@ -16,7 +16,7 @@
 	"dependencies": {
 		"@twin.org/core": "next",
 		"@twin.org/nameof": "next",
-		"@twin.org/tools-models": "0.0.3-next.25",
+		"@twin.org/tools-models": "0.0.3-next.26",
 		"glob": "13.0.6"
 	},
 	"main": "./dist/es/index.js",