[heft-json-schema-typings-plugin] Make $schema stripping configurable via includeSchemaMetadata option

Author: iclanton

common/changes/@rushstack/heft-json-schema-typings-plugin/strip-schema-property_2026-02-18-13-17.json

@@ -2,7 +2,7 @@
   "changes": [
     {
       "packageName": "@rushstack/heft-json-schema-typings-plugin",
-      "comment": "Strip the `$schema` metadata property from JSON schema files before generating TypeScript typings, so it does not appear as a property in the generated `.d.ts` declarations.",
+      "comment": "Strip the `$schema` metadata property from JSON schema files before generating TypeScript typings, so it does not appear as a property in the generated `.d.ts` declarations. This behavior can be disabled by setting the new `includeSchemaMetadata` option to `true`.",
       "type": "patch"
     }
   ],

heft-plugins/heft-json-schema-typings-plugin/README.md

@@ -48,6 +48,7 @@ to produce type declarations that can be imported alongside the schema at build
 | `srcFolder`          | `string`   | `"src"`              | Source directory to scan for `*.schema.json` files.                              |
 | `generatedTsFolders` | `string[]` | `["temp/schemas-ts"]`| Output directories for the generated `.d.ts` files.                             |
 | `formatWithPrettier` | `boolean`  | `false`              | When `true`, format generated typings with [prettier](https://prettier.io/). Requires `prettier` as an installed dependency. |
+| `includeSchemaMetadata` | `boolean` | `false`           | When `true`, keep the `$schema` property in the generated typings. By default it is stripped so it does not appear as a field in the emitted types. |
 
 ## Vendor extension: `x-tsdoc-release-tag`
 

heft-plugins/heft-json-schema-typings-plugin/src/JsonSchemaTypingsGenerator.ts

@@ -21,6 +21,17 @@ interface IJsonSchemaTypingsGeneratorBaseOptions extends ITypingsGeneratorBaseOp
    * Enabling this requires the `prettier` package to be installed as a dependency.
    */
   formatWithPrettier?: boolean;
+
+  /**
+   * If true, include the `$schema` property in the generated typings.  Defaults to false.
+   *
+   * @remarks
+   * By default, the `$schema` metadata property is stripped from the JSON schema before
+   * generating TypeScript declarations so that it does not appear as a field in the
+   * emitted types.  Set this to `true` if you need the `$schema` property to be
+   * part of the generated interface.
+   */
+  includeSchemaMetadata?: boolean;
 }
 
 const SCHEMA_FILE_EXTENSION: '.schema.json' = '.schema.json';
@@ -32,7 +43,7 @@ interface IExtendedJson4Schema extends Json4Schema {
 
 export class JsonSchemaTypingsGenerator extends TypingsGenerator {
   public constructor(options: IJsonSchemaTypingsGeneratorBaseOptions) {
-    const { formatWithPrettier = false, ...otherOptions } = options;
+    const { formatWithPrettier = false, includeSchemaMetadata = false, ...otherOptions } = options;
     super({
       ...otherOptions,
       fileExtensions: [SCHEMA_FILE_EXTENSION],
@@ -43,13 +54,19 @@ export class JsonSchemaTypingsGenerator extends TypingsGenerator {
         relativePath: string
       ): Promise<string> => {
         const parsedFileContents: IExtendedJson4Schema = JSON.parse(fileContents);
-        const {
-          [X_TSDOC_RELEASE_TAG_KEY]: tsdocReleaseTag,
-          // Strip $schema so it doesn't appear as a property in the generated types
+        const { [X_TSDOC_RELEASE_TAG_KEY]: tsdocReleaseTag, ...jsonSchemaWithoutReleaseTag } =
+          parsedFileContents;
+
+        // Unless includeSchemaMetadata is true, strip $schema so it doesn't appear
+        // as a property in the generated types.
+        let schemaForCompilation: Json4Schema;
+        if (includeSchemaMetadata) {
+          schemaForCompilation = jsonSchemaWithoutReleaseTag;
+        } else {
           // eslint-disable-next-line @typescript-eslint/no-unused-vars
-          $schema: _schema,
-          ...jsonSchemaWithoutMetadata
-        } = parsedFileContents;
+          const { $schema: _schema, ...rest } = jsonSchemaWithoutReleaseTag;
+          schemaForCompilation = rest;
+        }
 
         // Use the absolute directory of the schema file so that cross-file $ref
         // (e.g. { "$ref": "./other.schema.json" }) resolves correctly.
@@ -58,7 +75,7 @@ export class JsonSchemaTypingsGenerator extends TypingsGenerator {
           dirname.length + 1,
           -SCHEMA_FILE_EXTENSION.length
         );
-        let typings: string = await compile(jsonSchemaWithoutMetadata, filenameWithoutExtension, {
+        let typings: string = await compile(schemaForCompilation, filenameWithoutExtension, {
           // The typings generator adds its own banner comment
           bannerComment: '',
           cwd: dirname,

heft-plugins/heft-json-schema-typings-plugin/src/JsonSchemaTypingsPlugin.ts

@@ -19,6 +19,7 @@ export interface IJsonSchemaTypingsPluginOptions {
   srcFolder?: string;
   generatedTsFolders?: string[];
   formatWithPrettier?: boolean;
+  includeSchemaMetadata?: boolean;
 }
 
 export default class JsonSchemaTypingsPlugin implements IHeftTaskPlugin<IJsonSchemaTypingsPluginOptions> {
@@ -35,7 +36,12 @@ export default class JsonSchemaTypingsPlugin implements IHeftTaskPlugin<IJsonSch
       hooks: { run, runIncremental }
     } = taskSession;
     const { buildFolderPath } = heftConfiguration;
-    const { srcFolder = 'src', generatedTsFolders = ['temp/schemas-ts'], formatWithPrettier } = options;
+    const {
+      srcFolder = 'src',
+      generatedTsFolders = ['temp/schemas-ts'],
+      formatWithPrettier,
+      includeSchemaMetadata
+    } = options;
 
     const resolvedTsFolders: string[] = [];
     for (const generatedTsFolder of generatedTsFolders) {
@@ -49,7 +55,8 @@ export default class JsonSchemaTypingsPlugin implements IHeftTaskPlugin<IJsonSch
       generatedTsFolder,
       secondaryGeneratedTsFolders,
       terminal,
-      formatWithPrettier
+      formatWithPrettier,
+      includeSchemaMetadata
     });
 
     run.tapPromise(PLUGIN_NAME, async () => {

heft-plugins/heft-json-schema-typings-plugin/src/schemas/heft-json-schema-typings-plugin.schema.json

@@ -23,6 +23,11 @@
     "formatWithPrettier": {
       "type": "boolean",
       "description": "If true, format generated typings with prettier. Defaults to false."
+    },
+
+    "includeSchemaMetadata": {
+      "type": "boolean",
+      "description": "If true, include the $schema property in the generated typings. Defaults to false."
     }
   }
 }

heft-plugins/heft-json-schema-typings-plugin/src/test/JsonSchemaTypingsGenerator.test.ts

@@ -72,4 +72,16 @@ describe('JsonSchemaTypingsGenerator', () => {
     expect(typings).toMatchSnapshot();
     expect(typings).not.toContain('$schema');
   });
+
+  it('succeeds with includeSchemaMetadata enabled', async () => {
+    const generator = new JsonSchemaTypingsGenerator({
+      srcFolder: schemasFolder,
+      generatedTsFolder: outputFolder,
+      includeSchemaMetadata: true
+    });
+
+    await generator.generateTypingsAsync(['with-schema-field.schema.json']);
+    const typings: string = await readGeneratedTypings('with-schema-field.schema.json');
+    expect(typings).toMatchSnapshot();
+  });
 });

heft-plugins/heft-json-schema-typings-plugin/src/test/__snapshots__/JsonSchemaTypingsGenerator.test.ts.snap

@@ -95,3 +95,15 @@ name?: string
 }
 "
 `;
+
+exports[`JsonSchemaTypingsGenerator succeeds with includeSchemaMetadata enabled 1`] = `
+"// This file was generated by a tool. Modifying it will produce unexpected behavior
+
+export interface ConfigWithSchemaField {
+/**
+ * The name.
+ */
+name?: string
+}
+"
+`;