diff --git a/docs/StardustDocs/d.tree b/docs/StardustDocs/d.tree
index b5188a5693..f2ef4fd112 100644
--- a/docs/StardustDocs/d.tree
+++ b/docs/StardustDocs/d.tree
@@ -32,20 +32,19 @@
-
+
+
+
+
+
+
+
+
-
-
-
-
-
-
-
-
@@ -194,4 +193,5 @@
+
diff --git a/docs/StardustDocs/topics/FAQ.md b/docs/StardustDocs/topics/FAQ.md
index e805f7813a..99ed9ec049 100644
--- a/docs/StardustDocs/topics/FAQ.md
+++ b/docs/StardustDocs/topics/FAQ.md
@@ -174,15 +174,18 @@ and examples with beautiful [Kandy](https://kotlin.github.io/kandy) geo visualiz
> The current Gradle plugin is **under consideration for deprecation** and may be officially marked as deprecated
> in future releases.
-> The KSP plugin doesn't work for now.
+>
+> The KSP plugin is **not compatible with [KSP2](https://github.com/google/ksp?tab=readme-ov-file#ksp2-is-here)**
+> and may **not work properly with Kotlin 2.1 or newer**.
>
> At the moment, **[data schema generation is handled via dedicated methods](DataSchemaGenerationMethods.md)** instead
-> of relying on the plugins.
+> of relying on the plugins.
+> See [](Migration-From-Plugins.md).
{style="warning"}
All these plugins relate to working with [dataframe schemas](schemas.md), but they serve different purposes:
-- **[Gradle Plugin](DataSchemaGenerationGradle.md)** and **[KSP Plugin](https://github.com/Kotlin/dataframe/tree/master/plugins/symbol-processor)**
+- **[Gradle Plugin](Gradle-Plugin.md)** and **[KSP Plugin](https://github.com/Kotlin/dataframe/tree/master/plugins/symbol-processor)**
are used to **generate data schemas** from external sources as part of the Gradle build process.
- **Gradle Plugin**: You declare the data source in your `build.gradle.kts` file
@@ -193,12 +196,13 @@ All these plugins relate to working with [dataframe schemas](schemas.md), but th
See [Data Schemas in Gradle Projects](https://kotlin.github.io/dataframe/schemasgradle.html) for more.
-- **[Compiler Plugin](Compiler-Plugin.md)**
- provides **on-the-fly generation** of [extension properties](extensionPropertiesApi.md)
- based on an existing schema **during compilation**.
- However, when reading data from files or external sources (like SQL),
- the schema cannot be inferred automatically — you need to
- specify it manually or use the Gradle or KSP plugin to generate it.
+- **[Compiler Plugin](Compiler-Plugin.md)** provides **on-the-fly generation** of
+[extension properties](extensionPropertiesApi.md)
+based on an existing schema **during compilation**, and updates the [`DataFrame`](DataFrame.md)
+schema seamlessly after operations.
+However, when reading data from files or external sources (like SQL),
+the initial `DataFrame` schema cannot be inferred automatically —
+you need to specify it manually or generate it using the [`generate..()` methods](DataSchemaGenerationMethods.md).
## How do I contribute or report an issue?
diff --git a/docs/StardustDocs/topics/concepts/schemas.md b/docs/StardustDocs/topics/concepts/schemas.md
deleted file mode 100644
index 7a921bd08f..0000000000
--- a/docs/StardustDocs/topics/concepts/schemas.md
+++ /dev/null
@@ -1,46 +0,0 @@
-[//]: # (title: Working with Data Schemas)
-
-
-
-The Kotlin DataFrame library provides typed data access via [generation of extension properties](extensionPropertiesApi.md) for
-type `DataFrame`, where
-`T` is a marker class that represents `DataSchema` of [`DataFrame`](DataFrame.md).
-
-Schema of [`DataFrame`](DataFrame.md) is a mapping from column names to column types of [`DataFrame`](DataFrame.md).
-It ignores order of columns in [`DataFrame`](DataFrame.md), but tracks column hierarchy.
-
-In Jupyter environment compile-time [`DataFrame`](DataFrame.md) schema is synchronized with real-time data after every cell execution.
-
-In IDEA projects, you can use the [Gradle plugin](schemasGradle.md#configuration) to extract schema from the dataset
-and generate extension properties.
-
-
-## Popular use cases with Data Schemas
-
-Here's a list of the most popular use cases with Data Schemas.
-
-* [**Data Schemas in Gradle projects**](schemasGradle.md)
- If you are developing a server application and building it with Gradle.
-
-* [**DataSchema workflow in Jupyter**](schemasJupyter.md)
- If you prefer Notebooks.
-
-* [**Schema inheritance**](schemasInheritance.md)
- It's worth knowing how to reuse Data Schemas generated earlier.
-
-* [**Custom Data Schemas**](schemasCustom.md)
- Sometimes it is necessary to create your own scheme.
-
-* [**Use external Data Schemas in Jupyter**](schemasExternalJupyter.md)
- Sometimes it is convenient to extract reusable code from Jupyter Notebook into the Kotlin JVM library.
- Schema interfaces should also be extracted if this code uses Custom Data Schemas.
-
-* [**Schema Definitions from SQL Databases in Gradle Project**](schemasImportSqlGradle.md)
- When you need to take data from the SQL database.
-
-* [**Import OpenAPI 3.0.0 Schemas (Experimental) in Gradle Project**](schemasImportOpenApiGradle.md)
- When you need to take data from the endpoint with OpenAPI Schema.
-
-* [**Import Data Schemas, e.g. from OpenAPI 3.0.0 (Experimental), in Jupyter**](schemasImportOpenApiJupyter.md)
- Similar to [importing OpenAPI Data Schemas in Gradle projects](schemasImportOpenApiGradle.md),
- you can also do this in Jupyter Notebooks.
diff --git a/docs/StardustDocs/topics/concepts/schemasCustom.md b/docs/StardustDocs/topics/concepts/schemasCustom.md
deleted file mode 100644
index 0f7f876b4a..0000000000
--- a/docs/StardustDocs/topics/concepts/schemasCustom.md
+++ /dev/null
@@ -1,80 +0,0 @@
-[//]: # (title: Custom Data Schemas)
-
-
-
-You can define your own [`DataSchema`](schema.md) interfaces and use them in functions and classes to represent [`DataFrame`](DataFrame.md) with
-specific set of columns:
-
-```kotlin
-@DataSchema
-interface Person {
- val name: String
- val age: Int
-}
-```
-
-After execution of this cell in Jupyter or annotation processing in IDEA, extension properties for data access will be
-generated. Now we can use these properties to create functions for typed [`DataFrame`](DataFrame.md):
-
-```kotlin
-fun DataFrame.splitName() = split { name }.by(",").into("firstName", "lastName")
-fun DataFrame.adults() = filter { age > 18 }
-```
-
-In Jupyter these functions will work automatically for any [`DataFrame`](DataFrame.md) that matches `Person` schema:
-
-
-
-```kotlin
-val df = dataFrameOf("name", "age", "weight")(
- "Merton, Alice", 15, 60.0,
- "Marley, Bob", 20, 73.5,
-)
-```
-
-
-
-Schema of `df` is compatible with `Person`, so auto-generated schema interface will inherit from it:
-
-```kotlin
-@DataSchema(isOpen = false)
-interface DataFrameType : Person
-
-val ColumnsContainer.weight: DataColumn get() = this["weight"] as DataColumn
-val DataRow.weight: Double get() = this["weight"] as Double
-```
-
-Despite `df` has additional column `weight`, previously defined functions for `DataFrame` will work for it:
-
-
-
-```kotlin
-df.splitName()
-```
-
-
-
-```text
-firstName lastName age weight
- Merton Alice 15 60.000
- Marley Bob 20 73.125
-```
-
-
-
-```kotlin
-df.adults()
-```
-
-
-
-```text
-name age weight
-Marley, Bob 20 73.5
-```
-
-In JVM project you will have to [cast](cast.md) [`DataFrame`](DataFrame.md) explicitly to the target interface:
-
-```kotlin
-df.cast().splitName()
-```
diff --git a/docs/StardustDocs/topics/concepts/schemasExternalJupyter.md b/docs/StardustDocs/topics/concepts/schemasExternalJupyter.md
deleted file mode 100644
index 2b587b640e..0000000000
--- a/docs/StardustDocs/topics/concepts/schemasExternalJupyter.md
+++ /dev/null
@@ -1,50 +0,0 @@
-[//]: # (title: Use external Data Schemas in Jupyter)
-
-
-
-Sometimes it is convenient to extract reusable code from Jupyter Notebook into the Kotlin JVM library.
-Schema interfaces should also be extracted if this code uses [Custom Data Schemas](schemasCustom.md).
-
-In order to enable support them in Jupyter, you should register them in
-library [integration class](https://github.com/Kotlin/kotlin-jupyter/blob/master/docs/libraries.md) with `useSchema`
-function:
-
-```kotlin
-@DataSchema
-interface Person {
- val name: String
- val age: Int
-}
-
-fun DataFrame.countAdults() = count { it[Person::age] > 18 }
-
-@JupyterLibrary
-internal class Integration : JupyterIntegration() {
-
- override fun Builder.onLoaded() {
- onLoaded {
- useSchema()
- }
- }
-}
-```
-
-After loading this library into Jupyter notebook, schema interfaces for all [`DataFrame`](DataFrame.md) variables that match `Person`
-schema will derive from `Person`
-
-
-
-```kotlin
-val df = dataFrameOf("name", "age")(
- "Alice", 15,
- "Bob", 20,
-)
-```
-
-
-
-Now `df` is assignable to `DataFrame` and `countAdults` is available:
-
-```kotlin
-df.countAdults()
-```
diff --git a/docs/StardustDocs/topics/concepts/schemasJupyter.md b/docs/StardustDocs/topics/concepts/schemasJupyter.md
deleted file mode 100644
index 4e4c817e80..0000000000
--- a/docs/StardustDocs/topics/concepts/schemasJupyter.md
+++ /dev/null
@@ -1,58 +0,0 @@
-[//]: # (title: DataSchema workflow in Jupyter)
-
-
-
-After execution of cell
-
-
-
-```kotlin
-val df = dataFrameOf("name", "age")(
- "Alice", 15,
- "Bob", null,
-)
-```
-
-
-
-the following actions take place:
-
-1. Columns in `df` are analyzed to extract data schema
-2. Empty interface with [`DataSchema`](schema.md) annotation is generated:
-
-```kotlin
-@DataSchema
-interface DataFrameType
-```
-
-3. Extension properties for this [`DataSchema`](schema.md) are generated:
-
-```kotlin
-val ColumnsContainer.age: DataColumn @JvmName("DataFrameType_age") get() = this["age"] as DataColumn
-val DataRow.age: Int? @JvmName("DataFrameType_age") get() = this["age"] as Int?
-val ColumnsContainer.name: DataColumn @JvmName("DataFrameType_name") get() = this["name"] as DataColumn
-val DataRow.name: String @JvmName("DataFrameType_name") get() = this["name"] as String
-```
-
-Every column produces two extension properties:
-
-* Property for `ColumnsContainer` returns column
-* Property for `DataRow` returns cell value
-
-4. `df` variable is typed by schema interface:
-
-```kotlin
-val temp = df
-```
-
-```kotlin
-val df = temp.cast()
-```
-
-> _Note, that object instance after casting remains the same. See [cast](cast.md).
-
-To log all these additional code executions, use cell magic
-
-```
-%trackExecution -all
-```
diff --git a/docs/StardustDocs/topics/gettingStarted/Modules.md b/docs/StardustDocs/topics/gettingStarted/Modules.md
index 257f2dbc37..be8a087ea7 100644
--- a/docs/StardustDocs/topics/gettingStarted/Modules.md
+++ b/docs/StardustDocs/topics/gettingStarted/Modules.md
@@ -517,7 +517,7 @@ The Gradle plugin allows generating [data schemas](schemas.md) from samples of d
(of supported formats) like JSON, CSV, Excel files, or URLs, as well as from data fetched from SQL databases
using Gradle.
-See the [Gradle Plugin Reference](DataSchemaGenerationGradle.md) for installation
+See the [Gradle Plugin Reference](Gradle-Plugin.md) for installation
and usage instructions in Gradle projects.
> By default, the Gradle plugin also applies the [KSP plugin](#ksp-plugin).
diff --git a/docs/StardustDocs/topics/readSqlFromCustomDatabase.md b/docs/StardustDocs/topics/readSqlFromCustomDatabase.md
index 57e1931630..f3e2660493 100644
--- a/docs/StardustDocs/topics/readSqlFromCustomDatabase.md
+++ b/docs/StardustDocs/topics/readSqlFromCustomDatabase.md
@@ -129,7 +129,7 @@ fun createAndPopulateTable(con: Connection) {
**Define the Table Schema**
-Use the `@DataSchema` annotation to define a [**custom data schema**](schemasCustom.md) for the `orders` table.
+Use the `@DataSchema` annotation to define a [**custom data schema**](schemas.md) for the `orders` table.
```kotlin
@DataSchema
diff --git a/docs/StardustDocs/topics/schemas/Data-Schemas-In-Kotlin-Notebook.md b/docs/StardustDocs/topics/schemas/Data-Schemas-In-Kotlin-Notebook.md
new file mode 100644
index 0000000000..873480cc40
--- /dev/null
+++ b/docs/StardustDocs/topics/schemas/Data-Schemas-In-Kotlin-Notebook.md
@@ -0,0 +1,180 @@
+[//]: # (title: Data Schemas in Kotlin Notebook)
+
+
+
+After execution of a cell
+
+
+
+```kotlin
+val df = dataFrameOf("name", "age")(
+ "Alice", 15,
+ "Bob", null,
+)
+```
+
+
+
+the following actions take place:
+
+1. Columns in `df` are analyzed to extract data schema
+2. Empty interface with [`DataSchema`](schema.md) annotation is generated:
+
+```kotlin
+@DataSchema
+interface DataFrameType
+```
+
+3. Extension properties for this [`DataSchema`](schema.md) are generated:
+
+```kotlin
+val ColumnsContainer.age: DataColumn @JvmName("DataFrameType_age") get() = this["age"] as DataColumn
+val DataRow.age: Int? @JvmName("DataFrameType_age") get() = this["age"] as Int?
+val ColumnsContainer.name: DataColumn @JvmName("DataFrameType_name") get() = this["name"] as DataColumn
+val DataRow.name: String @JvmName("DataFrameType_name") get() = this["name"] as String
+```
+
+Every column produces two extension properties:
+
+* Property for `ColumnsContainer` returns column
+* Property for `DataRow` returns cell value
+
+4. `df` variable is typed by schema interface:
+
+```kotlin
+val temp = df
+```
+
+```kotlin
+val df = temp.cast()
+```
+
+> _Note, that object instance after casting remains the same. See [cast](cast.md).
+
+To log all these additional code executions, use cell magic
+
+```
+%trackExecution -all
+```
+
+## Custom Data Schemas
+
+You can define your own [`DataSchema`](schema.md) interfaces and use them in functions and classes to represent [`DataFrame`](DataFrame.md) with
+a specific set of columns:
+
+```kotlin
+@DataSchema
+interface Person {
+ val name: String
+ val age: Int
+}
+```
+
+After execution of this cell in notebook or annotation processing in IDEA, extension properties for data access will be
+generated. Now we can use these properties to create functions for typed [`DataFrame`](DataFrame.md):
+
+```kotlin
+fun DataFrame.splitName() = split { name }.by(",").into("firstName", "lastName")
+fun DataFrame.adults() = filter { age > 18 }
+```
+
+In Kotlin Notebook these functions will work automatically for any [`DataFrame`](DataFrame.md) that matches `Person` schema:
+
+
+
+```kotlin
+val df = dataFrameOf("name", "age", "weight")(
+ "Merton, Alice", 15, 60.0,
+ "Marley, Bob", 20, 73.5,
+)
+```
+
+
+
+Schema of `df` is compatible with `Person`, so auto-generated schema interface will inherit from it:
+
+```kotlin
+@DataSchema(isOpen = false)
+interface DataFrameType : Person
+
+val ColumnsContainer.weight: DataColumn get() = this["weight"] as DataColumn
+val DataRow.weight: Double get() = this["weight"] as Double
+```
+
+Despite `df` has additional column `weight`, previously defined functions for `DataFrame` will work for it:
+
+
+
+```kotlin
+df.splitName()
+```
+
+
+
+```text
+firstName lastName age weight
+ Merton Alice 15 60.000
+ Marley Bob 20 73.125
+```
+
+
+
+```kotlin
+df.adults()
+```
+
+
+
+```text
+name age weight
+Marley, Bob 20 73.5
+```
+
+## Use external Data Schemas
+
+Sometimes it is convenient to extract reusable code from Kotlin Notebook into the Kotlin JVM library.
+Schema interfaces should also be extracted if this code uses [Custom Data Schemas](#custom-data-schemas).
+
+In order to enable support them in Kotlin, you should register them in
+library [integration class](https://github.com/Kotlin/kotlin-jupyter/blob/master/docs/libraries.md) with `useSchema`
+function:
+
+```kotlin
+@DataSchema
+interface Person {
+ val name: String
+ val age: Int
+}
+
+fun DataFrame.countAdults() = count { it[Person::age] > 18 }
+
+@JupyterLibrary
+internal class Integration : JupyterIntegration() {
+
+ override fun Builder.onLoaded() {
+ onLoaded {
+ useSchema()
+ }
+ }
+}
+```
+
+After loading this library into the notebook, schema interfaces for all [`DataFrame`](DataFrame.md) variables that match `Person`
+schema will derive from `Person`
+
+
+
+```kotlin
+val df = dataFrameOf("name", "age")(
+ "Alice", 15,
+ "Bob", 20,
+)
+```
+
+
+
+Now `df` is assignable to `DataFrame` and `countAdults` is available:
+
+```kotlin
+df.countAdults()
+```
diff --git a/docs/StardustDocs/topics/concepts/DataSchemaGenerationMethods.md b/docs/StardustDocs/topics/schemas/DataSchemaGenerationMethods.md
similarity index 97%
rename from docs/StardustDocs/topics/concepts/DataSchemaGenerationMethods.md
rename to docs/StardustDocs/topics/schemas/DataSchemaGenerationMethods.md
index e36f233b7d..7c3755954b 100644
--- a/docs/StardustDocs/topics/concepts/DataSchemaGenerationMethods.md
+++ b/docs/StardustDocs/topics/schemas/DataSchemaGenerationMethods.md
@@ -47,7 +47,7 @@ Useful when you want to:
* `extensionProperties`: `Boolean` – Whether to generate [extension properties](extensionPropertiesApi.md)
in addition to `interface` declarations.
Useful if you don't use the [compiler plugin](Compiler-Plugin.md), otherwise they are not needed;
- the [compiler plugin](Compiler-Plugin.md), [notebooks](schemasJupyter.md),
+ the [compiler plugin](Compiler-Plugin.md), [notebooks](gettingStartedKotlinNotebook.md),
and older [Gradle/KSP plugin](schemasGradle.md) generate them automatically.
Default: `false`.
* `visibility`: `MarkerVisibility` – Visibility modifier for the generated declarations.
@@ -122,7 +122,7 @@ in cases where the schema cannot be inferred automatically from the source.
* `extensionProperties`: `Boolean` – Whether to generate [extension properties](extensionPropertiesApi.md)
in addition to `interface` declarations.
Useful if you don't use the [compiler plugin](Compiler-Plugin.md), otherwise they are not needed;
- the [compiler plugin](Compiler-Plugin.md), [notebooks](schemasJupyter.md),
+ the [compiler plugin](Compiler-Plugin.md), [notebooks](gettingStartedKotlinNotebook.md),
and older [Gradle/KSP plugin](schemasGradle.md) generate them automatically.
Default: `false`.
* `visibility`: `MarkerVisibility` – Visibility modifier for the generated declarations.
diff --git a/docs/StardustDocs/topics/schemas/Migration-From-Plugins.md b/docs/StardustDocs/topics/schemas/Migration-From-Plugins.md
new file mode 100644
index 0000000000..3349b204cd
--- /dev/null
+++ b/docs/StardustDocs/topics/schemas/Migration-From-Plugins.md
@@ -0,0 +1,53 @@
+# Migration from Gradle/KSP Plugin
+
+Gradle and KSP plugins were useful tools in earlier versions of Kotlin DataFrame.
+However, they are now being phased out. This section provides an overview of their current state and migration guidance.
+
+## Gradle Plugin
+
+> Do not confuse this with the [](Compiler-Plugin.md), which is a Kotlin compiler plugin
+> and has a different plugin ID.
+> {style="note"}
+
+1. **Generation of [data schemas](schemas.md)** from data sources
+ (files, databases, or external URLs).
+ - You could copy already generated schemas from `build/generate` into your project sources.
+ - To generate a `DataSchema` for a [`DataFrame`](DataFrame.md) now, use
+ the [`generate..()` methods](DataSchemaGenerationMethods.md).
+
+2. **Generation of [extension properties](extensionPropertiesApi.md)** from data schemas
+ This is now handled by the [](Compiler-Plugin.md), which:
+ - Generates extension properties for declared data schemas.
+ - Automatically updates the schema and regenerates properties after structural DataFrame operations.
+
+> The Gradle plugin still works and may be helpful for generating schemas from data sources.
+> However, it is planned for deprecation, and **we do not recommend using it going forward**.
+> {style="warning"}
+
+If you still choose to use Gradle plugin, make sure to disable the automatic KSP plugin dependency
+to avoid compatibility issues with Kotlin 2.1+ by adding this line to `gradle.properties`:
+
+```properties
+kotlin.dataframe.add.ksp=false
+```
+
+## KSP Plugin
+
+- **Generation of [data schemas](schemas.md)** from data sources
+ (files, databases, or external URLs).
+ - You could copy already generated schemas from `build/generate/ksp` into your project sources.
+ - To generate a `DataSchema` for a [`DataFrame`](DataFrame.md) now, use the
+ [`generate..()` methods](DataSchemaGenerationMethods.md) instead.
+
+> The KSP plugin is **not compatible with [KSP2](https://github.com/google/ksp?tab=readme-ov-file#ksp2-is-here)**
+> and may **not work properly with Kotlin 2.1 or newer**.
+> It is planned for deprecation or major changes, and **we do not recommend using it at this time**.
+> {style="warning"}
+
+If you still choose to use the KSP plugin with Kotlin 2.1+,
+disable [KSP2](https://github.com/google/ksp?tab=readme-ov-file#ksp2-is-here)
+by adding this line to `gradle.properties`:
+
+```properties
+ksp.useKSP2=false
+```
diff --git a/docs/StardustDocs/topics/concepts/DataSchemaGenerationGradle.md b/docs/StardustDocs/topics/schemas/gradle/Gradle-Plugin.md
similarity index 99%
rename from docs/StardustDocs/topics/concepts/DataSchemaGenerationGradle.md
rename to docs/StardustDocs/topics/schemas/gradle/Gradle-Plugin.md
index 1ff1a81c53..e3e9b25651 100644
--- a/docs/StardustDocs/topics/concepts/DataSchemaGenerationGradle.md
+++ b/docs/StardustDocs/topics/schemas/gradle/Gradle-Plugin.md
@@ -1,4 +1,4 @@
-[//]: # (title: Data Shemas Generation in Gradle)
+[//]: # (title: Gradle Plugin (deprecated))
> The current Gradle plugin is **under consideration for deprecation** and may be officially marked as deprecated in future releases.
>
diff --git a/docs/StardustDocs/topics/concepts/schemasGradle.md b/docs/StardustDocs/topics/schemas/gradle/schemasGradle.md
similarity index 97%
rename from docs/StardustDocs/topics/concepts/schemasGradle.md
rename to docs/StardustDocs/topics/schemas/gradle/schemasGradle.md
index ead7311457..44e75cf569 100644
--- a/docs/StardustDocs/topics/concepts/schemasGradle.md
+++ b/docs/StardustDocs/topics/schemas/gradle/schemasGradle.md
@@ -136,7 +136,7 @@ dataframes {
}
```
-See [reference](DataSchemaGenerationGradle.md) and [examples](DataSchemaGenerationGradle.md#examples) for more details.
+See [reference](Gradle-Plugin.md) and [examples](Gradle-Plugin.md#examples) for more details.
diff --git a/docs/StardustDocs/topics/concepts/schemasImportOpenApiGradle.md b/docs/StardustDocs/topics/schemas/gradle/schemasImportOpenApiGradle.md
similarity index 100%
rename from docs/StardustDocs/topics/concepts/schemasImportOpenApiGradle.md
rename to docs/StardustDocs/topics/schemas/gradle/schemasImportOpenApiGradle.md
diff --git a/docs/StardustDocs/topics/concepts/schemasImportSqlGradle.md b/docs/StardustDocs/topics/schemas/gradle/schemasImportSqlGradle.md
similarity index 100%
rename from docs/StardustDocs/topics/concepts/schemasImportSqlGradle.md
rename to docs/StardustDocs/topics/schemas/gradle/schemasImportSqlGradle.md
diff --git a/docs/StardustDocs/topics/schemas/schemas.md b/docs/StardustDocs/topics/schemas/schemas.md
new file mode 100644
index 0000000000..09981123f5
--- /dev/null
+++ b/docs/StardustDocs/topics/schemas/schemas.md
@@ -0,0 +1,147 @@
+[//]: # (title: Data Schemas)
+
+The Kotlin DataFrame library provides typed data access via
+[generation of extension properties](extensionPropertiesApi.md) for the type
+[`DataFrame`](DataFrame.md) (as well as for [`DataRow`](DataRow.md)), where
+`T` is a marker class representing the `DataSchema` of the [`DataFrame`](DataFrame.md).
+
+A *schema* of a [`DataFrame`](DataFrame.md) is a mapping from column names to column types.
+This data schema can be expressed as a Kotlin class or interface.
+If the DataFrame is hierarchical — contains a [column group](DataColumn.md#columngroup) or a
+[column of dataframes](DataColumn.md#framecolumn) — the data schema reflects this structure,
+with a separate class representing the schema of each column group or nested `DataFrame`.
+
+For example, consider a simple hierarchical DataFrame from
+.
+
+This DataFrame consists of two columns:
+- `name`, which is a `String` column
+- `info`, which is a [column group](DataColumn.md#columngroup) containing two nested [value columns](DataColumn.md#valuecolumn):
+ - `age` of type `Int`
+ - `height` of type `Double`
+
+
+
+
+ | name |
+ info |
+
+
+ |
+ age |
+ height |
+
+
+
+
+ | Alice |
+ 23 |
+ 175.5 |
+
+
+ | Bob |
+ 27 |
+ 160.2 |
+
+
+
+
+The data schema corresponding to this DataFrame can be represented as:
+
+```kotlin
+// Data schema of the "info" column group
+@DataSchema
+data class Info(
+ val age: Int,
+ val height: Float
+)
+
+// Data schema of the entire DataFrame
+@DataSchema
+data class Person(
+ val info: Info,
+ val name: String
+)
+```
+
+[Extension properties](extensionPropertiesApi.md) for `DataFrame`
+are generated based on this schema and allow accessing columns
+or using them in operations:
+
+```kotlin
+// Assuming `df` has type `DataFrame`
+
+// Get "age" column from "info" group
+df.info.age
+
+// Select "name" and "height" columns
+df.select { name and info.height }
+
+// Filter rows by "age"
+df.filter { age >= 18 }
+```
+
+See [](extensionPropertiesApi.md) for more information.
+
+
+## Schema Retrieving
+
+Defining a data schema manually can be difficult, especially for dataframes with many columns or deeply nested
+structures, and may lead to mistakes in column names or types.
+Kotlin DataFrame provides several methods for generating data schemas.
+
+* [**`generate..()` methods**](DataSchemaGenerationMethods.md) are extensions for [`DataFrame`](DataFrame.md)
+(or for its [`schema`](schema.md)) that generate a code string representing its `DataSchema`.
+
+* [**Kotlin DataFrame Compiler Plugin**](Compiler-Plugin.md) **cannot automatically infer** a
+data schema from external sources such as files or URLs.
+However, it **can** infer the schema if you construct the [`DataFrame`](DataFrame.md)
+manually — that is, by explicitly declaring the columns using the API.
+It will also **automatically update** the schema during operations that modify the structure of the DataFrame.
+
+> For best results when working with the Compiler Plugin, it's recommended to
+> generate the initial schema using one of
+> the [`generate..()` methods](DataSchemaGenerationMethods.md).
+> Once generated, the Compiler Plugin will automatically keep the schema up to date
+> after any operations that change the structure of the DataFrame.
+
+### Plugins
+
+> The current Gradle plugin is **under consideration for deprecation** and
+> may be officially marked as deprecated in future releases.
+>
+> The KSP plugin is **not compatible with [KSP2](https://github.com/google/ksp?tab=readme-ov-file#ksp2-is-here)**
+> and may **not work properly with Kotlin 2.1 or newer**.
+>
+> At the moment, **[data schema generation is handled via dedicated methods](DataSchemaGenerationMethods.md)** instead of relying on the plugins.
+{style="warning"}
+
+* The [Gradle plugin](Gradle-Plugin.md) allows generating a data schema automatically by specifying a source file path in the Gradle build script.
+
+* The KSP plugin allows generating a data schema automatically using
+[Kotlin Symbol Processing](https://kotlinlang.org/docs/ksp-overview.html) by specifying
+a source file path in your code file.
+
+## Extension Properties Generation
+
+Once you have a data schema, you can generate [extension properties](extensionPropertiesApi.md).
+
+The easiest and most convenient way is to use the [**Kotlin DataFrame Compiler Plugin**](Compiler-Plugin.md),
+which generates extension properties on the fly for declared data schemas
+and automatically keeps them up to date after operations
+that modify the structure of the [`DataFrame`](DataFrame.md).
+
+> Extension properties generation was deprecated from the Gradle plugin in favor of the Compiler Plugin.
+> {style="warning"}
+
+* When using Kotlin DataFrame inside [Kotlin Notebook](gettingStartedKotlinNotebook.md),
+the schema and extension properties
+are generated automatically after each cell execution for all `DataFrame` variables declared in that cell.
+See [extension properties example in Kotlin Notebook](extensionPropertiesApi.md#example).
+
+> Compiler Plugin is coming to Kotlin Notebook soon.
+
+* If you're not using the Compiler Plugin, you can still generate
+[extension properties](extensionPropertiesApi.md) for a [`DataFrame`](DataFrame.md)
+manually by calling one of the [`generate..()` methods](DataSchemaGenerationMethods.md)
+with the `extensionProperties = true` argument.
diff --git a/docs/StardustDocs/topics/concepts/schemasImportOpenApiJupyter.md b/docs/StardustDocs/topics/schemas/schemasImportOpenApiJupyter.md
similarity index 89%
rename from docs/StardustDocs/topics/concepts/schemasImportOpenApiJupyter.md
rename to docs/StardustDocs/topics/schemas/schemasImportOpenApiJupyter.md
index 118106afd8..2e41208a61 100644
--- a/docs/StardustDocs/topics/concepts/schemasImportOpenApiJupyter.md
+++ b/docs/StardustDocs/topics/schemas/schemasImportOpenApiJupyter.md
@@ -1,4 +1,4 @@
-[//]: # (title: Import Data Schemas, e.g. from OpenAPI, in Jupyter)
+[//]: # (title: Import Data Schemas, e.g. from OpenAPI, in Kotlin Notebook)
@@ -7,7 +7,7 @@ OpenAPI 3.0.0 schema support is marked as experimental. It might change or be re
Similar to [importing OpenAPI Data Schemas in Gradle projects](schemasImportOpenApiGradle.md),
-you can also do this in Jupyter Notebooks.
+you can also do this in Kotlin Notebook.
This requires enabling the `enableExperimentalOpenApi` setting, like:
```
%use dataframe(..., enableExperimentalOpenApi=true)
diff --git a/docs/StardustDocs/topics/concepts/schemasInheritance.md b/docs/StardustDocs/topics/schemas/schemasInheritance.md
similarity index 100%
rename from docs/StardustDocs/topics/concepts/schemasInheritance.md
rename to docs/StardustDocs/topics/schemas/schemasInheritance.md