feat: support external JSON schema file references in type generation (#14749)

## Description

Enables the use of external JSON schema file references in type
generation by adding the `cwd` parameter to
`json-schema-to-typescript`'s `compile()` function.

## Changes

- Added `cwd: process.cwd()` parameter to `generateTypes()` compile call
- Enables `$ref` pointers to external `.json` schema files in
`typescriptSchema` field config
- Added test case with external schema file reference
- Documented external schema reference usage in generating-types.mdx

## Test Coverage

✅ New test: `resolves external schema file references`
- Created `test/types/schemas/custom-type.json` as external schema
- Added field with `typescriptSchema` referencing the external file
- Verified generated types include the external type correctly

## Example Usage

```typescript
// payload.config.ts
{
  typescript: {
    schema: [
      ({ jsonSchema }) => {
        jsonSchema.definitions.MyType = {
          $ref: './schemas/my-type.json'
        }
        return jsonSchema
      },
    ]
  }
}
```

External references are resolved relative to `process.cwd()`.

## Related Issue

This was identified during investigation of JSON Schema parser
capabilities. The `cwd` parameter is a standard
`json-schema-to-typescript` option that was not being passed.

Author: tak-amboss

docs/typescript/generating-types.mdx

@@ -98,6 +98,28 @@ export interface Test {
 
 This function takes the existing JSON schema as an argument and returns the modified JSON schema. It can be useful for plugins that wish to generate their own types.
 
+### External schema references
+
+You can use `$ref` to reference external JSON schema files in your custom schemas:
+
+```ts
+// payload.config.ts
+{
+  typescript: {
+    schema: [
+      ({ jsonSchema }) => {
+        jsonSchema.definitions.MyType = {
+          $ref: './schemas/my-type.json',
+        }
+        return jsonSchema
+      },
+    ]
+  }
+}
+```
+
+External references are resolved relative to your project's working directory (`process.cwd()`).
+
 ## Example Usage
 
 For example, let's look at the following simple Payload Config:

packages/payload/src/bin/generateTypes.ts

@@ -44,6 +44,8 @@ export async function generateTypes(
     // If a field defines an interfaceName, it should be included in the generated types
     // even if it's not used by another type. Reason: the user might want to use it in their own code.
     unreachableDefinitions: true,
+    // Allow resolving external file references in $ref pointers
+    cwd: process.cwd(),
   })
 
   compiled = addSelectGenericsToGeneratedTypes({ compiledGeneratedTypes: compiled })

test/types/config.ts

@@ -79,6 +79,15 @@ export default buildConfigWithDefaults({
             },
           ],
         },
+        {
+          name: 'externalType',
+          type: 'text',
+          typescriptSchema: [
+            () => ({
+              $ref: './test/types/schemas/custom-type.json',
+            }),
+          ],
+        },
       ],
     },
     {

test/types/payload-types.ts

@@ -164,9 +164,14 @@ export interface Post {
     insideNamedGroup?: string | null;
   };
   radioField: MyRadioOptions;
+  externalType?: CustomType;
   updatedAt: string;
   createdAt: string;
 }
+export interface CustomType {
+  externalField: string;
+  externalNumber?: number;
+}
 /**
  * This interface was referenced by `Config`'s JSON-Schema
  * via the `definition` "pages".
@@ -298,6 +303,7 @@ export interface PostsSelect<T extends boolean = true> {
         insideNamedGroup?: T;
       };
   radioField?: T;
+  externalType?: T;
   updatedAt?: T;
   createdAt?: T;
 }

test/types/schemas/custom-type.json

@@ -0,0 +1,14 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "properties": {
+    "externalField": {
+      "type": "string"
+    },
+    "externalNumber": {
+      "type": "number"
+    }
+  },
+  "required": ["externalField"],
+  "additionalProperties": false
+}

test/types/types.spec.ts

@@ -156,6 +156,13 @@ describe('Types testing', () => {
     test('has global generated options interface based on radio field', () => {
       expect(asType<Post['radioField']>()).type.toBe<MyRadioOptions>()
     })
+
+    test('resolves external schema file references', () => {
+      // The externalType field uses a $ref to ./test/types/schemas/custom-type.json
+      expect<Post>().type.toHaveProperty('externalType')
+      expect<NonNullable<Post['externalType']>>().type.toHaveProperty('externalField')
+      expect<NonNullable<Post['externalType']>>().type.toHaveProperty('externalNumber')
+    })
   })
 
   describe('fields', () => {