docs: Update README/serialization docs (#235)

## Update README/serialization docs with details on
`$ref`/`$defs`)deduplication, `kotlin.Any` mapping to `{}`, and sealed
class discriminator behavior

- Revised `JsonSchemaConfig` table in `serializable.md` to clarify
property defaults and add new polymorphism details.
- Explained subtype discriminator constant in generated schema examples.

Author: kpavlov

README.md

@@ -109,11 +109,13 @@ Quick Links:
 
 **Comprehensive Type Support:**
 
-- Enums, collections, maps, nested objects, nullability, generics (with star-projection)
-- Sealed class hierarchies with automatic `oneOf` generation
-- Proper union types for nullable parameters (`["string", "null"]`)
-- Type constraints (min/max, patterns, formats)
+- **Enums, collections, maps, nested objects, nullability, generics** (with star-projection)
+- **Sealed class hierarchies** with automatic `oneOf` generation and discriminator field
+- **Union types** for nullable parameters (`["string", "null"]`)
+- **Type constraints** (min/max, patterns, formats)
 - **Default values** (compile-time: tracked but not extracted; runtime: fully extracted)
+- **`$ref`/`$defs` deduplication**: named types appear once in `$defs` and are referenced everywhere via `$ref`
+- **`kotlin.Any`**: maps to the empty schema `{}` (accepts any JSON value)
 
 **Developer Experience:**
 
@@ -323,7 +325,8 @@ Schemas follow JSON Schema Draft 2020-12 format. Example (pretty-printed):
 - Nullable properties are emitted as a union including `null`.
 - Collections: `List<T>`/`Set<T>` → `{ "type":"array", "items": T }`; `Map<String, V>` →
   `{ "type":"object", "additionalProperties": V }`.
-- Unknown/generic type parameters resolve to `kotlin.Any` with a minimal definition in `$defs`.
+- `kotlin.Any` / unbound generic type parameters (e.g., `T`) map to the empty schema `{}`, which accepts any JSON value.
+- Named types (nested objects, enums, sealed classes) are deduplicated in a `$defs` section and referenced via `$ref` at every usage site.
 
 ## Examples
 
@@ -395,16 +398,14 @@ val schemaObject = Product::class.jsonSchema
         },
         "inStock": {
             "type": "boolean",
-            "description": "Whether the product is currently in stock",
-            "default": true
+            "description": "Whether the product is currently in stock"
         },
         "tags": {
             "type": "array",
             "items": {
                 "type": "string"
             },
-            "description": "List of tags for categorization and search",
-            "default": []
+            "description": "List of tags for categorization and search"
         }
     },
     "required": [
@@ -542,9 +543,9 @@ data class Container<T>(
 
 <!--- KNIT example-knit-readme-06.kt -->
 
-Generic type parameters are resolved at the usage site. When generating a schema for a generic class, unbound type
-parameters (like `T`) are treated as `kotlin.Any` with a minimal definition in the `$defs` section. For more specific
-typing, instantiate the generic class with concrete types when you need them.
+Generic type parameters are resolved at the usage site. Unbound type parameters (like `T`) and `kotlin.Any`-typed
+properties map to `{}` — the empty JSON Schema that accepts any JSON value. For more specific typing, instantiate the
+generic class with concrete types when you need them.
 
 ### Sealed class polymorphism
 
@@ -611,19 +612,19 @@ println(schema.encodeToString(Json { prettyPrint = true }))
     "additionalProperties": false,
     "oneOf": [
         {
-            "$ref": "#/$defs/Animal.Cat"
+            "$ref": "#/$defs/kotlinx.schema.integration.type.Animal.Cat"
         },
         {
-            "$ref": "#/$defs/Animal.Dog"
+            "$ref": "#/$defs/kotlinx.schema.integration.type.Animal.Dog"
         }
     ],
     "$defs": {
-        "Animal.Cat": {
+        "kotlinx.schema.integration.type.Animal.Cat": {
             "type": "object",
             "properties": {
                 "type": {
                     "type": "string",
-                    "const": "Animal.Cat"
+                    "const": "kotlinx.schema.integration.type.Animal.Cat"
                 },
                 "name": {
                     "type": "string",
@@ -636,12 +637,12 @@ println(schema.encodeToString(Json { prettyPrint = true }))
             ],
             "additionalProperties": false
         },
-        "Animal.Dog": {
+        "kotlinx.schema.integration.type.Animal.Dog": {
             "type": "object",
             "properties": {
                 "type": {
                     "type": "string",
-                    "const": "Animal.Dog"
+                    "const": "kotlinx.schema.integration.type.Animal.Dog"
                 },
                 "name": {
                     "type": "string",
@@ -662,10 +663,11 @@ println(schema.encodeToString(Json { prettyPrint = true }))
 
 **Key features:**
 
-- **`oneOf` with `$ref`**: Each sealed subclass is referenced from a `$defs` section
-- **Property inheritance**: Base class properties included in each subtype
+- **`oneOf` with `$ref`**: Each sealed subclass is stored in `$defs` and referenced via `$ref`
+- **Fully qualified names**: `$defs` keys and discriminator `const` values use fully qualified class names (e.g., `com.example.Animal.Cat`) to avoid collisions across packages
+- **Discriminator property**: A `type` field with a `const` value is automatically added to each subtype for runtime dispatch
+- **Property inheritance**: Base class properties are included in each subtype
 - **Type safety**: Each subtype gets its own schema definition
-- **Default values**: Subtype properties with defaults (like `lives: Int = 9`) are included
 
 ## Using @Schema and @Description annotations
 

docs/serializable.md

@@ -281,13 +281,14 @@ This code generates:
 
 ### JsonSchemaConfig reference
 
-| Property                 | Type      | Default | Description                                                                    |
-|:-------------------------|:----------|:--------|:-------------------------------------------------------------------------------|
-| `respectDefaultPresence` | `Boolean` | `false` | Mark fields with default values as optional (requires reflection).             |
-| `requireNullableFields`  | `Boolean` | `true`  | Whether nullable fields appear in the `required` array.                        |
-| `useUnionTypes`          | `Boolean` | `true`  | Represent nullable types as `["string", "null"]` (Draft 2020-12).              |
-| `useNullableField`       | `Boolean` | `false` | Emit `"nullable": true` instead of union types (legacy OpenAPI compatibility). |
-| `includeDiscriminator`   | `Boolean` | `false` | Include a `discriminator` object in polymorphic schemas (OpenAPI 3.x).         |
+| Property                                 | Type      | Default | Description                                                                                                            |
+|:-----------------------------------------|:----------|:--------|:-----------------------------------------------------------------------------------------------------------------------|
+| `respectDefaultPresence`                 | `Boolean` | `true`  | Mark fields with default values as optional (requires reflection; KSP tracks presence but not values).                 |
+| `requireNullableFields`                  | `Boolean` | `false` | Include nullable fields in the `required` array.                                                                       |
+| `useUnionTypes`                          | `Boolean` | `true`  | Represent nullable types as `["string", "null"]` (Draft 2020-12).                                                      |
+| `useNullableField`                       | `Boolean` | `false` | Emit `"nullable": true` instead of union types (legacy OpenAPI compatibility).                                         |
+| `includePolymorphicDiscriminator`        | `Boolean` | `true`  | Add a `"type"` property with a constant discriminator value to each polymorphic subtype schema.                        |
+| `includeOpenAPIPolymorphicDiscriminator` | `Boolean` | `false` | Include a `discriminator` mapping object in `oneOf` schemas (OpenAPI 3.x). Requires `includePolymorphicDiscriminator`. |
 
 > [!NOTE]
 > `useUnionTypes` and `useNullableField` are mutually exclusive — exactly one must be `true`.
@@ -337,7 +338,9 @@ println(schemaString)
 -->
 <!--- KNIT example-knit-serializable-04.kt -->
 
-The generated schema uses `oneOf` with a `$defs` section for each subtype, with a required `type` discriminator field on each subtype object.
+The generated schema uses `oneOf` with a `$defs` section for each subtype. 
+Each subtype gets a required `type` property containing the subtype's serial name as a constant (from `@SerialName`), 
+enabling runtime dispatch.
 
 ```json
 {
@@ -357,18 +360,27 @@ The generated schema uses `oneOf` with a `$defs` section for each subtype, with
         "com.example.Shape.Circle": {
             "type": "object",
             "properties": {
+                "type": {
+                    "type": "string",
+                    "const": "com.example.Shape.Circle"
+                },
                 "radius": {
                     "type": "number"
                 }
             },
             "required": [
+                "type",
                 "radius"
             ],
             "additionalProperties": false
         },
         "com.example.Shape.Rectangle": {
             "type": "object",
             "properties": {
+                "type": {
+                    "type": "string",
+                    "const": "com.example.Shape.Rectangle"
+                },
                 "width": {
                     "type": "number"
                 },
@@ -377,6 +389,7 @@ The generated schema uses `oneOf` with a `$defs` section for each subtype, with
                 }
             },
             "required": [
+                "type",
                 "width",
                 "height"
             ],