|
2 | 2 |
|
3 | 3 | Runtime JSON Schema generation from Kotlin classes and functions. |
4 | 4 |
|
5 | | -Concrete implementations of schema generators for JVM runtime analysis via Kotlin reflection and kotlinx-serialization. |
| 5 | +Concrete implementations of schema generators using Kotlin reflection (JVM) and kotlinx-serialization (Multiplatform). |
6 | 6 |
|
7 | | -**Platform Support:** JVM only (requires Kotlin reflection) • Kotlin 2.2+ |
| 7 | +**Platform Support:** |
| 8 | +- **Multiplatform**: Transformers and serialization-based generators (Common) |
| 9 | +- **JVM only**: Reflection-based generators (require kotlin-reflect) |
8 | 10 |
|
9 | 11 | ## Generators |
10 | 12 |
|
| 13 | +### Reflection-Based (JVM Only) |
| 14 | + |
11 | 15 | - [ReflectionClassJsonSchemaGenerator] - generates schemas from any KClass via reflection |
12 | 16 | - [ReflectionFunctionCallingSchemaGenerator] - generates function calling schemas from KCallable |
13 | | -- [SerializationClassJsonSchemaGenerator] - generates schemas from @Serializable classes |
14 | 17 |
|
15 | | -## Example |
| 18 | +### Serialization-Based (Multiplatform) |
| 19 | + |
| 20 | +- [SerializationClassJsonSchemaGenerator] - generates schemas from @Serializable classes (works on JVM, Native, JS, Wasm) |
| 21 | + |
| 22 | +## Examples |
| 23 | + |
| 24 | +### Reflection Generator (JVM) |
16 | 25 |
|
17 | 26 | ```kotlin |
18 | 27 | // Class schema generation |
19 | 28 | val generator = ReflectionClassJsonSchemaGenerator.Default |
20 | 29 | val schema: JsonObject = generator.generateSchema(User::class) |
21 | 30 |
|
22 | | -// Function schema generation |
| 31 | +// Function calling schema generation |
23 | 32 | val funcGenerator = ReflectionFunctionCallingSchemaGenerator.Default |
24 | 33 | val funcSchema = funcGenerator.generateSchema(::myFunction) |
25 | 34 | ``` |
26 | 35 |
|
| 36 | +### Serialization Generator (Multiplatform) |
| 37 | + |
| 38 | +```kotlin |
| 39 | +import kotlinx.serialization.Serializable |
| 40 | +import kotlinx.schema.generator.json.serialization.SerializationClassJsonSchemaGenerator |
| 41 | + |
| 42 | +@Serializable |
| 43 | +data class User(val name: String, val email: String? = null) |
| 44 | + |
| 45 | +val generator = SerializationClassJsonSchemaGenerator.Default |
| 46 | +val schema = generator.generateSchema(User.serializer().descriptor) |
| 47 | +``` |
| 48 | + |
27 | 49 | ## Features |
28 | 50 |
|
| 51 | +**Reflection Generators (JVM only):** |
29 | 52 | - Analyze third-party classes without source modification |
30 | 53 | - Extract default values from data class properties |
31 | | -- Recognize foreign annotations (Jackson, LangChain4j, Koog) |
| 54 | +- Recognize foreign annotations (Jackson, Koog, LangChain4j) |
32 | 55 | - OpenAI/Anthropic function calling format |
33 | 56 | - Sealed class hierarchies with `oneOf` |
34 | 57 |
|
| 58 | +**Serialization Generators (Multiplatform):** |
| 59 | +- Works on all kotlinx-serialization targets (JVM, Native, JS, Wasm) |
| 60 | +- Consistent with kotlinx-serialization behavior |
| 61 | + |
35 | 62 | ## Limitations |
36 | 63 |
|
37 | | -- KDoc annotations not available at runtime |
| 64 | +**Reflection Generators:** |
38 | 65 | - Function parameter defaults cannot be extracted (data class property defaults work) |
| 66 | +- JVM only |
| 67 | + |
| 68 | +**Serialization Generators:** |
| 69 | +- Requires `@Serializable` annotation |
| 70 | +- Cannot extract actual default values (only detects presence) |
| 71 | +- Cannot extract descriptions, because of the `SerialDescriptor` limitation |
39 | 72 |
|
40 | 73 | # Package kotlinx.schema.generator.json |
41 | 74 |
|
|
0 commit comments