[heft-json-schema-typings-plugin] Strip $schema from generated typings

Author: iclanton

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

@@ -0,0 +1,10 @@
+{
+  "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.",
+      "type": "patch"
+    }
+  ],
+  "packageName": "@rushstack/heft-json-schema-typings-plugin"
+}

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

@@ -43,8 +43,13 @@ export class JsonSchemaTypingsGenerator extends TypingsGenerator {
         relativePath: string
       ): Promise<string> => {
         const parsedFileContents: IExtendedJson4Schema = JSON.parse(fileContents);
-        const { [X_TSDOC_RELEASE_TAG_KEY]: tsdocReleaseTag, ...jsonSchemaWithoutReleaseTag } =
-          parsedFileContents;
+        const {
+          [X_TSDOC_RELEASE_TAG_KEY]: tsdocReleaseTag,
+          // Strip $schema so it doesn't appear as a property in the generated types
+          // eslint-disable-next-line @typescript-eslint/no-unused-vars
+          $schema: _schema,
+          ...jsonSchemaWithoutMetadata
+        } = parsedFileContents;
 
         // Use the absolute directory of the schema file so that cross-file $ref
         // (e.g. { "$ref": "./other.schema.json" }) resolves correctly.
@@ -53,7 +58,7 @@ export class JsonSchemaTypingsGenerator extends TypingsGenerator {
           dirname.length + 1,
           -SCHEMA_FILE_EXTENSION.length
         );
-        let typings: string = await compile(jsonSchemaWithoutReleaseTag, filenameWithoutExtension, {
+        let typings: string = await compile(jsonSchemaWithoutMetadata, filenameWithoutExtension, {
           // The typings generator adds its own banner comment
           bannerComment: '',
           cwd: dirname,

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

@@ -60,4 +60,16 @@ describe('JsonSchemaTypingsGenerator', () => {
     // The parent typings should reference the child type
     expect(parentTypings).toContain('ChildType');
   });
+
+  it('strips the $schema property from generated typings', async () => {
+    const generator = new JsonSchemaTypingsGenerator({
+      srcFolder: schemasFolder,
+      generatedTsFolder: outputFolder
+    });
+
+    await generator.generateTypingsAsync(['with-schema-field.schema.json']);
+    const typings: string = await readGeneratedTypings('with-schema-field.schema.json');
+    expect(typings).toMatchSnapshot();
+    expect(typings).not.toContain('$schema');
+  });
 });

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

@@ -83,3 +83,15 @@ childValue?: number
 }
 "
 `;
+
+exports[`JsonSchemaTypingsGenerator strips the $schema property from generated typings 1`] = `
+"// This file was generated by a tool. Modifying it will produce unexpected behavior
+
+export interface ConfigWithSchemaField {
+/**
+ * The name.
+ */
+name?: string
+}
+"
+`;

heft-plugins/heft-json-schema-typings-plugin/src/test/schemas/with-schema-field.schema.json

@@ -0,0 +1,12 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Config With Schema Field",
+  "type": "object",
+  "properties": {
+    "name": {
+      "description": "The name.",
+      "type": "string"
+    }
+  },
+  "additionalProperties": false
+}