@@ -160,6 +160,16 @@ apply plugin: 'org.openapi.generator'
 |None
 |Local root folder with spec file(s)
 
+|schemaLocation
+|String / Provider<Directory>
+|None
+|Optional directory containing additional schema files referenced via `$ref` in the input specification. By default, Gradle only tracks `inputSpec` for up-to-date checks, so changes to `$ref`-referenced schema files elsewhere would not trigger re-generation. Declaring this directory makes Gradle track all files inside it too. This only affects up-to-date/cache tracking; it does not change how `$ref`s are resolved at generation time. For schemas that aren't all under one directory, use `schemaLocations` instead.
+
+|schemaLocations
+|ConfigurableFileCollection
+|empty
+|Like `schemaLocation`, but accepts any combination of individual files, multiple directories, or filtered file trees instead of a single whole directory, e.g. `schemaLocations.from("schemas/user.yaml", "schemas/order.yaml")` or `schemaLocations.from(fileTree("schemas") { include("*.yaml") })`. Since it isn't a `Provider`-based property, it does not support Groovy `=` assignment — use `.from(...)`, or the `setSchemaLocationsAsStrings(vararg paths)` convenience method.
+
 |mergedFileName
 |String / Provider<String>
 |`merged`
@@ -559,6 +569,47 @@ models: "User:Pet"
 ----
 ====
 
+==== Tracking additional schema files ($ref)
+
+By default, Gradle only watches `inputSpec` for up-to-date checks, so changes to `$ref`-referenced
+schema files elsewhere are not picked up automatically. Use `schemaLocation` (a single directory)
+or `schemaLocations` (any combination of files, directories, or filtered file trees) to have Gradle
+track them too. Neither property changes how `$ref`s are resolved at generation time — they only
+affect Gradle's up-to-date/cache tracking.
+
+[source,kotlin]
+----
+openApiGenerate {
+    inputSpec.set("$rootDir/specs/petstore.yaml")
+    // Track a single directory of referenced schemas
+    schemaLocation.set(file("$rootDir/specs/schemas"))
+    // Or track specific files / multiple locations / filtered trees
+    schemaLocations.from("specs/schemas/user.yaml", "specs/schemas/order.yaml")
+}
+----
+
+[source,groovy]
+----
+openApiGenerate {
+    inputSpec = "$rootDir/specs/petstore.yaml"
+    schemaLocation = "specs/schemas"
+    schemaLocations.from("specs/schemas/user.yaml", "specs/schemas/order.yaml")
+}
+----
+
+Alternatively, the Groovy-friendly `setSchemaLocationsAsStrings(...)` helper can be used instead of
+`schemaLocations.from(...)` — note that it *replaces* any previously configured `schemaLocations`
+entries rather than adding to them, so do not combine the two on the same property:
+
+[source,groovy]
+----
+openApiGenerate {
+    inputSpec = "$rootDir/specs/petstore.yaml"
+    schemaLocation = "specs/schemas"
+    setSchemaLocationsAsStrings("specs/schemas/user.yaml", "specs/schemas/order.yaml")
+}
+----
+
 === openApiValidate
 
 .Options
@@ -777,7 +828,7 @@ When configuring project extensions like `openApiGenerate { }`, `openApiValidate
 |Extension |Available Methods
 
 |`openApiGenerate`
-|`setInputSpec(path)`, `setOutputDir(path)`, `setTemplateDir(path)`, `setConfigFile(path)`, `setIgnoreFileOverride(path)`, `setInputSpecRootDirectory(path)`
+|`setInputSpec(path)`, `setOutputDir(path)`, `setTemplateDir(path)`, `setConfigFile(path)`, `setIgnoreFileOverride(path)`, `setInputSpecRootDirectory(path)`, `setSchemaLocation(path)`, `setSchemaLocationsAsStrings(vararg paths)`
 
 |`openApiValidate`
 |`setInputSpec(path)`
@@ -881,7 +932,7 @@ Both patterns work identically for String-based property configuration in Groovy
 |Task Type |Available Methods
 
 |`GenerateTask`
-|`setInputSpecAsString(path)`, `setOutputDirAsString(path)`, `setTemplateDirAsString(path)`, `setConfigFileAsString(path)`, `setIgnoreFileOverrideAsString(path)`, `setInputSpecRootDirectoryAsString(path)`, `setSchemaLocationAsString(path)`
+|`setInputSpecAsString(path)`, `setOutputDirAsString(path)`, `setTemplateDirAsString(path)`, `setConfigFileAsString(path)`, `setIgnoreFileOverrideAsString(path)`, `setInputSpecRootDirectoryAsString(path)`, `setSchemaLocationAsString(path)`, `setSchemaLocationsAsStrings(vararg paths)`
 
 |`ValidateTask`
 |`setInputSpecAsString(path)`
 
@@ -115,6 +115,8 @@ class OpenApiGeneratorPlugin : Plugin<Project> {
                     inputSpecRootDirectory.set(generate.inputSpecRootDirectory)
                     inputSpecRootDirectorySkipMerge.set(generate.inputSpecRootDirectorySkipMerge)
                     inputSpecFiles.from(generate.inputSpecFiles)
+                    schemaLocation.set(generate.schemaLocation)
+                    schemaLocations.from(generate.schemaLocations)
                     mergedFileOutputDir.set(generate.mergedFileOutputDir)
                     mergedFileName.set(generate.mergedFileName)
                     mergedFileInfoName.set(generate.mergedFileInfoName)
 
@@ -85,6 +85,30 @@ open class OpenApiGeneratorGenerateExtension(private val project: Project) {
      */
     val inputSpecFiles: ConfigurableFileCollection = project.objects.fileCollection()
 
+    /**
+     * Optional directory containing additional schema files referenced via `$ref` in the input
+     * specification, tracked for up-to-date checks.
+     *
+     * Declaring this directory tells Gradle to track all files inside it for up-to-date checks.
+     * Without it, changes to `$ref`-referenced schemas will not trigger re-generation because
+     * Gradle only watches [inputSpec] by default.
+     *
+     * For schemas that aren't all under one directory, use [schemaLocations] instead.
+     */
+    val schemaLocation: DirectoryProperty = project.objects.directoryProperty()
+
+    /**
+     * Optional collection of additional schema files/directories referenced via `$ref` in the input
+     * specification, tracked for up-to-date checks.
+     *
+     * Unlike [schemaLocation], which only accepts a single whole directory, this accepts any
+     * combination of individual files, multiple directories, or filtered file trees, e.g.:
+     * ```kotlin
+     * schemaLocations.from("schemas/user.yaml", "schemas/order.yaml")
+     * ```
+     */
+    val schemaLocations: ConfigurableFileCollection = project.objects.fileCollection()
+
     /**
      * Directory where the merged spec file is written when [inputSpecFiles] is used.
      * Must be set when [inputSpecFiles] is non-empty.
@@ -641,6 +665,24 @@ open class OpenApiGeneratorGenerateExtension(private val project: Project) {
         ignoreFileOverride.set(project.layout.projectDirectory.file(path))
     }
 
+    /** Backwards-compatibility bridge for schemaLocation */
+    fun setSchemaLocation(path: String) {
+        schemaLocation.set(project.layout.projectDirectory.dir(path))
+    }
+
+    /**
+     * Groovy-compatible helper for schemaLocations.
+     *
+     * [schemaLocations] is a [ConfigurableFileCollection], which does not support Groovy `=`
+     * assignment (it isn't a [org.gradle.api.provider.Property]). Use this method instead:
+     * ```groovy
+     * setSchemaLocationsAsStrings("schemas/user.yaml", "schemas/order.yaml")
+     * ```
+     */
+    fun setSchemaLocationsAsStrings(vararg paths: String) {
+        schemaLocations.setFrom(paths.map { project.layout.projectDirectory.asFile.resolve(it) })
+    }
+
     // ========================================================================
     // Kotlin DSL extension functions for property setters
     // These allow Kotlin DSL users to call .set(String) on file/directory properties
@@ -674,6 +716,8 @@ open class OpenApiGeneratorGenerateExtension(private val project: Project) {
             setInputSpecRootDirectory(path)
         } else if (this === templateDir) {
             setTemplateDir(path)
+        } else if (this === schemaLocation) {
+            setSchemaLocation(path)
         } else {
             // Fallback for any other DirectoryProperty
             this.set(project.layout.projectDirectory.dir(path))
 
@@ -367,12 +367,36 @@ abstract class GenerateTask : DefaultTask() {
      * Declaring this directory tells Gradle to track all files inside it for up-to-date checks.
      * Without it, changes to `$ref`-referenced schemas will not trigger re-generation because
      * Gradle only watches [inputSpec] by default.
+     *
+     * For schemas that aren't all under one directory (individual files, multiple directories, or a
+     * filtered subset of a directory), use [schemaLocations] instead, which accepts any combination of
+     * files, directories, and file trees.
      */
     @get:Optional
     @get:InputDirectory
-    @get:PathSensitive(PathSensitivity.ABSOLUTE)
+    @get:PathSensitive(PathSensitivity.RELATIVE)
     abstract val schemaLocation: DirectoryProperty
 
+    /**
+     * Optional collection of additional schema files/directories referenced via `$ref` in the input
+     * specification, tracked for up-to-date checks.
+     *
+     * Unlike [schemaLocation], which only accepts a single whole directory, this property is a
+     * [ConfigurableFileCollection] and can be populated with any combination of individual files,
+     * multiple directories, or filtered file trees, e.g.:
+     * ```kotlin
+     * schemaLocations.from("schemas/user.yaml", "schemas/order.yaml")
+     * schemaLocations.from(fileTree("schemas") { include("*.yaml") })
+     * ```
+     *
+     * As with [schemaLocation], this only affects Gradle's up-to-date/cache tracking; it does not
+     * change how `$ref`s are resolved at generation time.
+     */
+    @get:InputFiles
+    @get:Optional
+    @get:PathSensitive(PathSensitivity.RELATIVE)
+    val schemaLocations: ConfigurableFileCollection = project.objects.fileCollection()
+
     /**
      * The output target directory into which code will be generated.
      */
@@ -1357,4 +1381,17 @@ abstract class GenerateTask : DefaultTask() {
     fun setSchemaLocationAsString(path: String) {
         schemaLocation.set(layout.projectDirectory.dir(path))
     }
+
+    /**
+     * Groovy-compatible helper for schemaLocations property.
+     *
+     * [schemaLocations] is a [ConfigurableFileCollection], which does not support Groovy `=`
+     * assignment (it isn't a [org.gradle.api.provider.Property]). Use this method instead:
+     * ```groovy
+     * setSchemaLocationsAsStrings("schemas/user.yaml", "schemas/order.yaml")
+     * ```
+     */
+    fun setSchemaLocationsAsStrings(vararg paths: String) {
+        schemaLocations.setFrom(paths.map { layout.projectDirectory.asFile.resolve(it) })
+    }
 }
@@ -104,6 +104,90 @@ class GenerateTaskConfigurationCacheTest : TestBase() {
         assertTrue(result3.output.contains("Configuration cache entry reused."))
     }
 
+    // schemaLocation / schemaLocations tests
+
+    private fun schemaLocationsExtensionContents(format: PropertyFormat) = """
+        generatorName = "kotlin"
+        inputSpec = ${"spec.yaml".toPropertyReference(format)}
+        schemaLocation = ${"schemaDir".toPropertyReference(format)}
+        schemaLocations.from(${"schemaLocationsDir/schema.yaml".toPropertyReference(format)})
+        cleanupOutput.set(true)
+        """.trimIndent()
+
+    @Test(dataProvider = "gradle_version_provider")
+    fun `openApiGenerate with schemaLocation and schemaLocations should reuse configuration cache`(gradleVersion: String, format: String) {
+        val propertyFormat = PropertyFormat.valueOf(format)
+        // Arrange
+        withProject(schemaLocationsExtensionContents(propertyFormat))
+        projectDirCC.resolve("schemaDir").mkdir().also {
+            projectDirCC.resolve("schemaDir/schema.yaml").writeText("type: object")
+        }
+        projectDirCC.resolve("schemaLocationsDir").mkdir().also {
+            projectDirCC.resolve("schemaLocationsDir/schema.yaml").writeText("type: object")
+        }
+
+        // Act
+        val result1 = build {
+            withProjectDir(projectDirCC)
+            withArguments("--configuration-cache", "clean", "openApiGenerate")
+            withGradleVersion(gradleVersion)
+        }
+
+        val result2 = build {
+            withProjectDir(projectDirCC)
+            withArguments("--configuration-cache", "clean", "openApiGenerate")
+            withGradleVersion(gradleVersion)
+        }
+
+        // Assert
+        assertEquals(TaskOutcome.SUCCESS, result1.task(":openApiGenerate")?.outcome)
+        assertTrue(result1.output.contains("Configuration cache entry stored."))
+        assertEquals(TaskOutcome.SUCCESS, result2.task(":openApiGenerate")?.outcome)
+        assertTrue(result2.output.contains("Configuration cache entry reused."))
+    }
+
+    @Test(dataProvider = "gradle_version_provider")
+    fun `openApiGenerate with schemaLocation and schemaLocations should re-execute but reuse configuration cache on schema file change`(gradleVersion: String, format: String) {
+        val propertyFormat = PropertyFormat.valueOf(format)
+        // Arrange
+        withProject(schemaLocationsExtensionContents(propertyFormat))
+        projectDirCC.resolve("schemaDir").mkdir().also {
+            projectDirCC.resolve("schemaDir/schema.yaml").writeText("type: object")
+        }
+        projectDirCC.resolve("schemaLocationsDir").mkdir().also {
+            projectDirCC.resolve("schemaLocationsDir/schema.yaml").writeText("type: object")
+        }
+
+        // Act - First run: store the configuration cache
+        val result1 = build {
+            withProjectDir(projectDirCC)
+            withArguments("--configuration-cache", "openApiGenerate")
+            withGradleVersion(gradleVersion)
+        }
+        assertEquals(TaskOutcome.SUCCESS, result1.task(":openApiGenerate")?.outcome)
+        assertTrue(result1.output.contains("Configuration cache entry stored."))
+
+        // Act - Second run: change a file tracked via schemaLocation and re-run
+        projectDirCC.resolve("schemaDir/schema.yaml").writeText("type: object\nadditionalProperties: false")
+        val result2 = build {
+            withProjectDir(projectDirCC)
+            withArguments("--configuration-cache", "openApiGenerate")
+            withGradleVersion(gradleVersion)
+        }
+        assertEquals(TaskOutcome.SUCCESS, result2.task(":openApiGenerate")?.outcome)
+        assertTrue(result2.output.contains("Configuration cache entry reused."))
+
+        // Act - Third run: change a file tracked via schemaLocations and re-run
+        projectDirCC.resolve("schemaLocationsDir/schema.yaml").writeText("type: object\nadditionalProperties: false")
+        val result3 = build {
+            withProjectDir(projectDirCC)
+            withArguments("--configuration-cache", "openApiGenerate")
+            withGradleVersion(gradleVersion)
+        }
+        assertEquals(TaskOutcome.SUCCESS, result3.task(":openApiGenerate")?.outcome)
+        assertTrue(result3.output.contains("Configuration cache entry reused."))
+    }
+
     private fun getJavaVersion(): Int {
         val version = System.getProperty("java.version")
         val parts = version.split('.')
 
@@ -67,6 +67,66 @@ class GenerateTaskUpToDateTest : TestBase() {
         }
     }
 
+    // schemaLocation tests
+
+    private fun schemaLocationExtensionContents(format: PropertyFormat) = """
+        generatorName = "kotlin"
+        inputSpec = ${"spec.yaml".toPropertyReference(format)}
+        schemaLocation = ${"schemaDir".toPropertyReference(format)}
+        """.trimIndent()
+
+    private fun initializeSchemaLocationTest(): File {
+        val schemaDir = temp.resolve("schemaDir")
+        schemaDir.mkdir()
+        return schemaDir.resolve("schema.yaml").apply { writeText("type: object") }
+    }
+
+    @Test(dataProvider = "gradle_version_provider")
+    fun `schemaLocation - no file changes - should be up-to-date`(gradleVersion: String, format: String) {
+        val propertyFormat = PropertyFormat.valueOf(format)
+        initializeSchemaLocationTest()
+        runShouldBeUpToDateTest(gradleVersion, schemaLocationExtensionContents(propertyFormat))
+    }
+
+    @Test(dataProvider = "gradle_version_provider")
+    fun `schemaLocation - has file changes - should execute`(gradleVersion: String, format: String) {
+        val propertyFormat = PropertyFormat.valueOf(format)
+        val schemaFile = initializeSchemaLocationTest()
+        runShouldExecuteTest(gradleVersion, schemaLocationExtensionContents(propertyFormat)) {
+            schemaFile.writeText("type: object\nadditionalProperties: false")
+        }
+    }
+
+    // schemaLocations tests
+
+    private fun schemaLocationsExtensionContents(format: PropertyFormat) = """
+        generatorName = "kotlin"
+        inputSpec = ${"spec.yaml".toPropertyReference(format)}
+        schemaLocations.from(${"schemaLocationsDir/schema.yaml".toPropertyReference(format)})
+        """.trimIndent()
+
+    private fun initializeSchemaLocationsTest(): File {
+        val schemaDir = temp.resolve("schemaLocationsDir")
+        schemaDir.mkdir()
+        return schemaDir.resolve("schema.yaml").apply { writeText("type: object") }
+    }
+
+    @Test(dataProvider = "gradle_version_provider")
+    fun `schemaLocations - no file changes - should be up-to-date`(gradleVersion: String, format: String) {
+        val propertyFormat = PropertyFormat.valueOf(format)
+        initializeSchemaLocationsTest()
+        runShouldBeUpToDateTest(gradleVersion, schemaLocationsExtensionContents(propertyFormat))
+    }
+
+    @Test(dataProvider = "gradle_version_provider")
+    fun `schemaLocations - has file changes - should execute`(gradleVersion: String, format: String) {
+        val propertyFormat = PropertyFormat.valueOf(format)
+        val schemaFile = initializeSchemaLocationsTest()
+        runShouldExecuteTest(gradleVersion, schemaLocationsExtensionContents(propertyFormat)) {
+            schemaFile.writeText("type: object\nadditionalProperties: false")
+        }
+    }
+
     // configFile tests
 
     private fun configFileExtensionContents(format: PropertyFormat) = """