Derived Schemas
Write the type once and let llm4s-schema-derivation build the JSON schema for structured output, and typed tools, from it.
Experimental. The module is new and not part of the 1.0 frozen surface. It is published from
0.5.0on.
- Why
- Add the module
- A first call
- What is derived
- Tool parameters
- Typed tools
- Scoped tools
- Tools from methods
- An agent’s answer
- Sum types
- Named tuples
- Descriptions
- How it agrees with uPickle
- Strict mode
- Types the module does not know
- What cannot be derived
- Iron refinements
- Compile time
Why
completeStructured takes an ObjectSchema that you build by hand, so every field is written twice, once in the case class and once in the schema, and a mismatch only shows up when a model answers. llm4s-schema-derivation derives the schema from the case class with Scala 3’s derives, so the two cannot drift.
It layers on the public API: it builds the same ObjectSchema and calls the same completeStructured. Nothing in llm4s-core changes, and the module adds no dependency.
Add the module
libraryDependencies += "org.llm4s" %% "llm4s-schema-derivation" % "0.5.1"
A first call
1
2
3
4
5
6
7
8
9
import org.llm4s.schema.*
import upickle.default.ReadWriter
@description("An invoice extracted from text")
case class Invoice(
@description("Name of the vendor or supplier") vendor: String,
@description("Total invoice amount as a decimal number") amount: Double,
@description("ISO 4217 currency code, e.g. USD, EUR, GBP") currency: String
) derives SchemaOf, ReadWriter
derives SchemaOf gives the type its schema, and derives ReadWriter (uPickle) is what reads the model’s answer, as with completeStructured. With an LLMClient and a Conversation in scope, one call replaces the hand-built schema:
1
val invoice: Result[Invoice] = client.completeStructuredOf[Invoice](conversation)
Result is org.llm4s.types.Result. completeStructuredOf is an extension method on LLMClient, in org.llm4s.schema. It sets the same response format as completeStructured, so the provider enforces the schema where it can (OpenAI, Gemini) and falls back to an instruction in the prompt where it cannot (Anthropic).
To see the schema that is sent:
1
val json = SchemaOf[Invoice].toJsonSchema()
which is
1
2
3
4
5
6
7
8
9
10
11
{
"type": "object",
"description": "An invoice extracted from text",
"properties": {
"vendor": { "type": "string", "description": "Name of the vendor or supplier" },
"amount": { "type": "number", "description": "Total invoice amount as a decimal number" },
"currency": { "type": "string", "description": "ISO 4217 currency code, e.g. USD, EUR, GBP" }
},
"required": ["vendor", "amount", "currency"],
"additionalProperties": false
}
This is exactly the schema that Schema.object[Invoice](...) with three withRequiredField calls builds by hand; the module’s tests compare the two.
To show the value while the model writes it, client.streamStructuredOf[Invoice](conversation) { p => ... } streams
the same request and hands each partial value to your function, typed: see
Streaming structured output.
What is derived
| Scala type | JSON schema |
|---|---|
String |
string |
Int, Long |
integer |
Double, Float |
number |
Boolean |
boolean |
BigDecimal, BigInt |
string (uPickle writes and reads them as JSON strings) |
Option[A] |
the schema of A, also allowing null; the property is not required unless strict (below) |
List[A], Vector[A], Seq[A], Set[A] |
array of the schema of A |
| a case class | object with one property per field, in declaration order, additionalProperties: false |
an enum or sealed hierarchy of singletons |
string limited to the case names (a case’s @upickle.implicits.key, where it has one) |
an enum or sealed trait whose cases have fields |
anyOf with one schema per case: see Sum types |
Case classes nest, and they can be generic (Box[Int] is described for Int).
1
2
3
4
5
6
7
8
9
case class Contact(
name: String,
email: Option[String],
tags: List[String] = Nil
) derives SchemaOf, ReadWriter
enum Priority derives SchemaOf, ReadWriter {
case Low, Medium, High
}
Tool parameters
A tool’s parameters are a schema too. SchemaOf[A].definition is the derived schema as llm4s-core’s schema model, which ToolBuilder takes as it is, and the handler reads the arguments with the same ReadWriter:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
import org.llm4s.schema.*
import org.llm4s.toolapi.{ ToolBuilder, ToolFunction }
import org.llm4s.types.Result
import upickle.default.{ read, ReadWriter }
import scala.util.Try
@description("Where to look up the weather")
case class WeatherQuery(
@description("City name, for example Paris") city: String,
@description("Temperature unit; the default is Celsius") unit: Option[TemperatureUnit]
) derives SchemaOf, ReadWriter
enum TemperatureUnit derives SchemaOf, ReadWriter {
case Celsius, Fahrenheit
}
val weatherTool: Result[ToolFunction[WeatherQuery, String]] =
ToolBuilder[WeatherQuery, String]("get_weather", "Current weather in a city", SchemaOf[WeatherQuery].definition)
.withHandler { args =>
Try(read[WeatherQuery](args.params)).toEither.left.map(_.getMessage).map(query => s"Sunny in ${query.city}")
}
.buildSafe()
The tool is sent in strict mode, so every parameter is required and unit is a property that may be null. The module’s tests check that the parameters the tool sends are the derived schema, and that the handler reads a call.
The handler above still reads the arguments itself, and a call it cannot read reaches the model as uPickle’s message. Typed tools do the reading for you.
Typed tools
Tool.of builds the tool from a function over the arguments’ case class: the schema is derived from the type, the call’s arguments are decoded into it before your function runs, and the result is written with its uPickle ReadWriter. The name of a parameter is written once, in the case class, so the schema, the parsing and the function cannot drift apart.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
import org.llm4s.schema.*
import org.llm4s.toolapi.ToolFunction
import org.llm4s.types.Result
import upickle.default.ReadWriter
@description("A forecast request")
case class ForecastQuery(
@description("City name, for example Paris") city: String,
@description("How many days ahead, from 1 to 7") days: Int
) derives SchemaOf, ReadWriter
case class Forecast(city: String, days: Int, summary: String) derives ReadWriter
val forecastTool: Result[ToolFunction[ForecastQuery, Forecast]] =
Tool.of[ForecastQuery, Forecast]("get_forecast", "Weather forecast for a city") { query =>
if (query.days < 1 || query.days > 7) Left("days must be between 1 and 7")
else Right(Forecast(query.city, query.days, "Sunny"))
}
The result is the same ToolFunction that ToolBuilder builds, so it goes into a ToolRegistry, an agent or an MCP server like any other tool; nothing in llm4s-core changes. The function returns Either[String, R], as a ToolBuilder handler does: a Left is the error the model sees. Tool.of itself returns a Result, as buildSafe() does, because the arguments must be a JSON object: an enum or another type that is not a case class is refused with a Left, as is a schema that cannot be built (see Recursion). The result type needs a ReadWriter, not only a writer, because ToolFunction requires one.
A call whose arguments do not match the type never reaches your function. Each problem is reported as the ToolParameterError that SafeParameterExtractor reports for a hand-written tool, and the module’s tests compare the two:
| The call sends | The error |
|---|---|
no days |
MissingParameter("days", "integer", <the keys that were sent>) |
"days": null |
NullParameter("days", "integer") |
"days": "three", 2.5 or a number beyond the Int range |
TypeMismatch("days", "integer", <the JSON type sent>), as getInt refuses them |
| arguments that are not an object | InvalidNesting(<field>, "root", <the JSON type sent>) for each field |
a key ForecastQuery has no field for |
nothing: it is ignored, as a hand-written tool ignores it |
The problems are collected, every field at once, in declaration order: one is reported as its own message, as a hand-written handler’s Left would be, several as ToolParameterError.MultipleErrors’s. A nested field is named by its path (address.city, lines[0].quantity), as a dotted getString("address.city") names it; a nested object or an array that is not one is a TypeMismatch naming the object, as getObject reports it. A value outside an enum’s cases is a TypeMismatch that lists the cases, and a value of the right JSON type that the reader still refuses ("abc" for a BigDecimal) is a TypeMismatch with the reader’s reason. An Option field may be absent or null, and is None; every other field is required, including one with a default value, as the schema says.
The built-in calculator, re-expressed this way next to the hand-built original, is the TypedCalculatorExample sample (sbt "samples/runMain org.llm4s.samples.toolapi.TypedCalculatorExample").
Scoped tools
Tool.scoped builds the same tool from a function that returns its result directly and runs in a ToolScope: the call it serves, given to the function and nowhere else. Inside it, reject(message) ends the call with message as the error the model sees, ensure(condition, message) ends it unless the condition holds, and .? unwraps a Result or an Either[String, T], ending the call with the LLMError’s formatted message or the Left’s text. ToolScope.idempotencyKey is the key to pass to a system with a side effect, so that running the same call again does not repeat the effect:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
import org.llm4s.schema.*
import org.llm4s.toolapi.ToolFunction
import org.llm4s.types.Result
import upickle.default.ReadWriter
@description("A charge to a customer's saved card")
case class Charge(
@description("The customer to charge") customerId: String,
@description("Amount in cents, above zero") amountCents: Long,
@description("ISO 4217 code: EUR or USD") currency: String
) derives SchemaOf, ReadWriter
case class Receipt(chargeId: String) derives ReadWriter
case class Customer(id: String, blocked: Boolean)
trait Customers { def find(id: String): Result[Customer] }
trait Payments { def charge(customer: Customer, amountCents: Long, idempotencyKey: String): Result[String] }
def chargeTool(customers: Customers, payments: Payments): Result[ToolFunction[Charge, Receipt]] =
Tool.scoped[Charge, Receipt]("charge_card", "Charge a customer's saved card") { c =>
ensure(c.amountCents > 0, "amountCents must be positive")
ensure(Set("EUR", "USD")(c.currency), s"unsupported currency ${c.currency}")
val customer = customers.find(c.customerId).?
if (customer.blocked) reject("this customer cannot be charged")
Receipt(payments.charge(customer, c.amountCents, ToolScope.idempotencyKey).?)
}
The arguments are decoded, and refused, exactly as by Tool.of, and the result is the same ToolFunction. An agent runs every call with its ToolCallInfo, which the function reads as ToolScope.call; ToolScope.idempotencyKey is then that call’s key, the same in every run of the call (a retry, a recover, an approval). Without a ToolCallInfo, as with plain ToolRegistry calling, the key is derived from the tool’s name and the arguments, with their object keys sorted: equal arguments give equal keys, so two separate calls with equal arguments share one.
reject, ensure, .? and ToolScope need the scope, so using them outside a Tool.scoped function does not compile; the message says they are only available inside one. They end the call with scala.util.boundary’s break, which works from a lambda inside the function (in a map or a foreach) but is an exception underneath: a Try or a catch NonFatal around them catches it, so leave them outside one, and do not use the scope on another thread or after the function returns. An exception the function throws is not caught by the tool: a ToolRegistry turns it into the tool’s error, as for Tool.of.
The TypedCalculatorExample sample has a scoped calculator next to the others.
Tools from methods
Most tools already exist as methods on a service. Tools.derive[S](service) makes one tool per public method of the trait or class S, and Tool.fromMethod(service.method) makes the tool of one method, with no argument case class: the method’s parameters are the tool’s, and its Scaladoc describes it.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
import org.llm4s.schema.*
import org.llm4s.toolapi.{ ToolFunction, ToolRegistry }
import org.llm4s.types.Result
import upickle.default.ReadWriter
case class Order(id: String, totalCents: Long) derives ReadWriter
case class Cancellation(orderId: String, refunded: Boolean) derives ReadWriter
trait CustomerService {
/**
* Orders placed by a customer, newest first.
*
* @param customerId the customer's id, for example C-1001
* @param limit at most this many orders
*/
def findOrders(customerId: String, limit: Option[Int]): Result[List[Order]]
/** Cancel an order that has not shipped yet. */
@toolName("cancel")
def cancelOrder(
@description("The order's id, for example O-17") orderId: String,
reason: String
): Either[String, Cancellation]
@notATool
def poolSize: Int
}
def supportTools(service: CustomerService): Result[ToolRegistry] =
Tools.derive[CustomerService](service).map(tools => new ToolRegistry(tools))
def cancelTool(service: CustomerService): Result[ToolFunction[?, Cancellation]] =
Tool.fromMethod(service.cancelOrder)
supportTools has two tools, find_orders and cancel:
| Comes from | |
|---|---|
| Name | the method’s @toolName, else its name in snake_case |
| Description | the method’s @description, else its Scaladoc’s text before the first tag, else its name |
| A parameter’s description | its @description, else its Scaladoc @param, else its type’s @description, else its name |
| Parameters | the method’s parameters: the schema, the checks and the errors Tool.of gives a case class with those fields |
| The error the model sees | a Left(message); a Result’s LLMError, formatted; a Try’s failure, its message. Any other result is the answer. |
Methods inherited from Any, Object, Product, Equals and Serializable, synthetic, private, protected and extension methods, vals and methods marked @notATool are left out; the tools come in the order of their names. A parameter with a default value is still required, as a case class field with one is.
Everything is read at compile time, with no reflection at run time. A method no tool can take is refused when it compiles, with a message naming it: a parameter whose type has no SchemaOf (a Map, say), a result without a ReadWriter, an overloaded method (a model cannot tell two tools of one name apart), a polymorphic method, a by-name, repeated or context parameter, several parameter lists, two methods with one tool name, and a @toolName providers do not accept. Mark a method the model should not call @notATool.
Scaladoc is read from the source when the service is compiled in the same run as the call to Tools.derive, with no compiler flag. For a service compiled separately (another module of your build, or a library), the compiler reads Scaladoc from its TASTy only when asked: add scalacOptions += "-Xread-docs" to the project that calls Tools.derive. Without it such a service’s tools fall back to their names, unless @description describes them. A method that overrides another without Scaladoc or annotations of its own takes those of the method it overrides, so Tool.fromMethod(live.cancelOrder) on the implementing class describes the tool as the trait does.
The DerivedToolsExample sample derives a service’s tools and runs an agent on them with a scripted model, so it needs no API key.
An agent’s answer
An agent’s response format is a schema too: pass SchemaOf[A].definition to AgentBuilder.withOutput, and read the answer with decodeOutput[A] (see the agent guide). withOutput is in llm4s-agent, which this module does not depend on.
1
2
3
4
5
6
7
8
9
import org.llm4s.agent.Agent
import org.llm4s.schema.*
def extractWithAgent(client: LLMClient, email: String): Result[Invoice] =
for {
agent <- Agent.builder("extractor", client).withOutput(SchemaOf[Invoice].definition).build()
result <- agent.run(s"Extract the invoice from this email: $email")
invoice <- result.decodeOutput[Invoice]
} yield invoice
As with completeStructuredOf, A must be a case class: build refuses any other type with a Left.
Sum types
An enum or sealed trait whose cases have fields is a sum type: the reply is one of its cases. It derives like any other type.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
@description("What the support bot decides to do")
enum Action derives SchemaOf, ReadWriter {
@description("Refund the customer") case Refund(amount: BigDecimal, reason: String)
@description("Hand over to a human team") case Escalate(team: Team)
case Reply(text: String)
}
enum Team derives SchemaOf, ReadWriter {
case Billing, Shipping
}
def decide(client: LLMClient, conversation: Conversation): String =
client.completeStructuredOf[Action](conversation) match {
case Right(Action.Refund(amount, _)) => s"refund $amount"
case Right(Action.Escalate(team)) => s"escalate to $team"
case Right(Action.Reply(text)) => text
case Left(error) => error.message
}
The schema is an anyOf with one alternative per case, written as uPickle writes that case:
- A case with fields is an object whose first property is the discriminator, a required string that can only be the case’s tag (a single-value
enum), followed by the case’s fields. uPickle’s discriminator is"$type", or the key set with@upickle.implicits.key("kind")on the sealed trait or enum. The tag is the case’s name, or its own@upickle.implicits.key. A case class without fields (case class Blank()) is an object holding only the discriminator. - A case without fields (an enum case or a case object) is a string that can only be its tag, since uPickle writes it as a bare string.
- A case’s
@descriptiondescribes its alternative.
Sum types nest: a case class field, a List or an Option of a sum type is described in place (an Option adds {"type": "null"} to the anyOf), and a case may hold a case class or another sum type.
OpenAI’s strict mode refuses an anyOf at the root of a schema, so completeStructuredOf asks for a sum type wrapped in an object, {"value": <the case>}, sends that schema as a ResponseFormat.JsonSchema, and reads the reply’s value into the type: the caller never sees the wrapper. A case class that holds a sum type is an object already and is sent as it is. A case class without one goes through completeStructured as before. The wrapped schema is within the subset OpenAI’s strict mode accepts (anyOf below the root, additionalProperties: false and every property required on each object), and Gemini accepts it too; the module’s tests check both the subset and the round trip with uPickle for every case.
A sum type has no schema in llm4s-core’s model, which has no union node: SchemaOf[Action].toJsonSchema() is its schema, while SchemaOf[Action].definition throws an UnsupportedOperationException. So a tool’s parameters cannot hold a sum type yet, and Tool.of returns a Left for one.
Named tuples
For two or three fields wanted once, at one call site, a Scala 3.7 named tuple does without the case class. SchemaOf describes it as the case class with the same fields, and org.llm4s.schema.namedtuples provides the uPickle ReadWriter that uPickle itself lacks; import it explicitly.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
import org.llm4s.schema.*
import org.llm4s.schema.namedtuples.given
import org.llm4s.toolapi.ToolFunction
import upickle.default.ReadWriter
enum Sentiment derives SchemaOf, ReadWriter {
case Positive, Neutral, Negative
}
def review(client: LLMClient, conversation: Conversation): Result[String] =
client
.completeStructuredOf[(sentiment: Sentiment, confidence: Double, quote: Option[String])](conversation)
.map(r => s"${r.sentiment} (${r.confidence})")
val lookup: Result[ToolFunction[(city: String, days: Int), (high: Double, low: Double)]] =
Tool.of[(city: String, days: Int), (high: Double, low: Double)]("forecast", "Daily forecast") { query =>
Right((high = 20.0 + query.days, low = 12.5))
}
- The schema is an object with one property per element, in order, exactly as for a case class with those fields: an
Optionelement may benull(or absent in the relaxed form), elements may be case classes, enums, sum types, collections or other named tuples, and a named tuple may be a field of a case class. - Descriptions. A named tuple’s elements cannot carry annotations, so each property is described by its element type’s
@description, else by its name. When the model needs a description per field, use a case class. - The
ReadWriterwrites exactly what uPickle writes for the case class with the same fields (nullforNone), and reads it back; an absentOptionelement reads asNone, and keys the tuple has no element for are ignored. Each element type needs aReadWriterof its own. It is never found without the import, so it cannot compete with an instance uPickle may add later. - Everywhere a case class goes:
completeStructuredOf,Tool.of(arguments, with the same argument errors, and result) and an agent’swithOutput(SchemaOf[T].definition)withdecodeOutput[T]. - A tuple without names (
(Int, String)) is still refused: uPickle writes it as an array.
Descriptions
The model sees a description for every property and for the object. @description("...") sets it: on a case class parameter it describes the field, on a case class, enum or sealed trait it describes the type. The text must be a string literal, because the annotation is read at compile time. Without it a field is described by its type’s @description if it has one, and otherwise by its name, and a type by its name.
How it agrees with uPickle
The schema describes what uPickle’s derived ReadWriter reads and writes, so a reply that matches the schema reads back into your type. The module’s tests check this in both directions for every supported shape: what uPickle writes satisfies the schema, and a document that satisfies the schema is read into the right value. The points where it matters:
- Field names. A property is named as uPickle writes the field, so
@upickle.implicits.key("user_name")is honoured. Option. uPickle writesNoneasnullandSome(x)asx, and the schema allows exactly that.BigDecimal. uPickle writes it as a string and cannot read a JSON number, so the schema saysstring.- Sum types. uPickle writes a case with fields as an object with its tag under
"$type"(or the trait’s@upickle.implicits.key), and a case without fields as its tag alone; theanyOfdescribes exactly that (see Sum types). - Enums. uPickle writes a case as its name, or as its
@upickle.implicits.key("...")when the case (an enum case or a case object) has one, and theenumlist in the schema holds exactly those strings. Long. uPickle writes aLongbeyond 2^53 (9007199254740992) in either direction as a JSON string, because a JSON number that large loses precision in many readers; it reads both forms back. The schema saysinteger, so a value written that large does not match it. A model answering the schema writes a number, which reads back; if your values can be that large and you validate what uPickle writes, describe the field as a string yourself.BigDecimalandBigInttext. The schema saysstringand cannot say that only numeric text reads back (llm4s-core’s schema model has nopattern), so give such a field a@descriptionthat asks for a number.- Defaults. uPickle leaves out a field that equals its default when it writes, and reads a missing field as the default. The schema still lists the field:
completeStructuredsends the strict schema, in which every property is required (a model must answer every field), so a field with a default is asked for like any other.
Strict mode
completeStructured asks for strict mode, in which every property is required and an Option is a property that may be null instead of being absent. That is what providers with native structured output expect. SchemaOf[A].toJsonSchema(strict = false) returns the relaxed form, in which an Option property is not listed in required.
Types the module does not know
Another type needs a given SchemaOf of its own, written next to the ReadWriter that reads it. The derivation takes a hand-written given as it is and does not look inside the type, so this also works for a type it would otherwise refuse, such as a recursive type, as long as the given describes what its ReadWriter writes and does not itself derive a type that leads back to the one being derived (see Recursion). SchemaOf.string describes a type that is written as a JSON string, and SchemaOf.stringEnum one that is written as one of a fixed set of strings. The text you pass is what the model sees for a field of that type, unless the field has its own @description.
1
2
3
4
5
6
import java.time.Instant
given ReadWriter[Instant] = upickle.default.readwriter[String].bimap[Instant](_.toString, Instant.parse)
given SchemaOf[Instant] = SchemaOf.string("ISO-8601 instant, for example 2026-10-08T09:30:00Z")
case class Meeting(title: String, starts: Instant) derives SchemaOf, ReadWriter
What cannot be derived
These are refused at compile time, with a message that names the type:
Map.llm4s-core’sObjectSchemahas a fixed set of properties and no way to describe the values of a map.- Recursive types (a
Treewithchildren: List[Tree], or anExprsum type with anAdd(left: Expr, right: Expr)case). They need a JSON Schema$ref, which the derivation does not emit yet. One case is caught only at run time: see Recursion. - A sealed hierarchy nested in another (a sealed trait whose case is itself a sealed trait), and a sum type with a generic case (
case class Holds[A](a: A)). List the cases directly under one sealed trait or enum, without type parameters. Optiondirectly insideOption(Option[Option[Int]]). uPickle writes it as a JSON array ([],[null],[1]), not as the value ornull. AnOptioninside aListinside anOptionis fine.- Tuples (
(Int, String)). uPickle writes them as JSON arrays of mixed types. Use a case class or a named tuple. - A class that is not a case class, and a field of a type nothing describes (a function, for instance).
completeStructuredOf also needs the type to be a case class or a sum type whose cases have fields, since the model answers with a JSON object: for an enum of singletons or another type it returns a Left before calling the model.
Recursion
A recursive type is refused at compile time when the recursion runs through derived instances: a type that refers to itself, directly or through an Option, a collection or a generic case class; types that refer to each other and all derives SchemaOf; and a type whose own given is written as SchemaOf.derived of itself.
The compile-time check does not look inside any other hand-written given, so it cannot see a recursion that passes through one which itself calls SchemaOf.derived:
1
2
3
4
5
6
case class P(q: Option[Q])
case class Q(p: List[P])
object Schemas {
given ps: SchemaOf[P] = SchemaOf.derived[P] // compiles: Q's given is hand-written
given qs: SchemaOf[Q] = SchemaOf.derived[Q] // compiles: P's given is hand-written
}
This compiles, and making the instances still works: a derived instance does not look up its fields’ instances until its schema is built, so two such givens never wait on each other’s initialisation. Building the schema (SchemaOf[P].toJsonSchema() or .definition) throws an IllegalStateException on first use, and on every use after it, naming the type: recursive type P: llm4s-schema-derivation cannot describe recursive types; core's schema model has no $ref. .... completeStructuredOf[P] returns the same message as a Left(ValidationError) without calling the model. It never hangs and never overflows the stack. The same shape is fine when the given that closes the loop describes the type by hand rather than deriving it, for example given SchemaOf[Q] = SchemaOf.string("..."); that is why the check cannot refuse every hand-written given that reaches back.
A generic case class may be nested in itself at most 16 deep. W[W[...[Int]]] with 16 Ws is described; with 17 it is taken for a recursion. Spelled out in a field’s type, the deeper nesting is refused at compile time; summoned through W’s own derives SchemaOf instance (SchemaOf[W[...[Int]]]), it is refused at run time, when the schema is built, with the same IllegalStateException (recursive type W: ...).
Iron refinements
A plain Int or String has no bounds to describe. When a field must be “between 1 and 5” or “at most 80 characters”, give it an Iron refinement type and add llm4s-schema-iron: the derived schema then carries the bound, so the model is told it, and a reply that breaks it fails to decode instead of becoming a value the type should have rejected.
libraryDependencies += "org.llm4s" %% "llm4s-schema-iron" % "0.5.1"
It is a module of its own, so Iron is not a dependency of llm4s-schema-derivation or llm4s-core. It brings Iron 3.3.2 (Apache-2.0), the latest Iron whose TASTy the build’s Scala 3 compiler can read (Iron 3.4 is built with a newer Scala 3). Import its givens next to org.llm4s.schema.*:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
import io.github.iltotore.iron.*
import io.github.iltotore.iron.constraint.all.*
import org.llm4s.schema.*
import org.llm4s.schema.iron.given
import upickle.default.ReadWriter
@description("A product review")
case class Review(
@description("Short headline") title: String :| (Not[Blank] & MaxLength[80]),
@description("Stars") rating: Int :| Interval.Closed[1, 5],
@description("One to ten topics") tags: List[String] :| (MinLength[1] & MaxLength[10])
) derives SchemaOf, ReadWriter
def review(client: LLMClient, conversation: Conversation): Result[Review] =
client.completeStructuredOf[Review](conversation)
Put a conjunction in parentheses: :| binds more tightly than &, so List[String] :| MinLength[1] & MaxLength[10] would refine with MinLength[1] alone. The properties of the schema sent for Review:
1
2
3
4
5
6
7
8
9
10
11
{
"title": {"type": "string", "description": "Short headline", "minLength": 1, "maxLength": 80},
"rating": {"type": "integer", "description": "Stars", "minimum": 1, "maximum": 5},
"tags": {
"type": "array",
"description": "One to ten topics",
"items": {"type": "string", "description": "string"},
"minItems": 1,
"maxItems": 10
}
}
import org.llm4s.schema.iron.given also brings a uPickle ReadWriter for each refined type: it reads the base value and refines it, and a value that breaks the constraint fails with Iron’s message. So completeStructuredOf returns a Left(ValidationError) naming the field and the bound ($['rating']: Should be included in [1, 5]), and a typed tool reports a ToolParameterError.TypeMismatch for the field, which the model sees as the tool’s error and can correct:
1
2
3
4
5
6
7
case class Booking(
@description("Guest name") guest: String :| Not[Blank],
@description("Nights to stay") nights: Int :| Interval.Closed[1, 14]
) derives SchemaOf, ReadWriter
val book: Result[ToolFunction[Booking, String]] =
Tool.of[Booking, String]("book_stay", "Books a stay")(b => Right(s"Booked ${b.nights} nights for ${b.guest}"))
Iron’s own iron-upickle module defines the same ReadWriter; import one of the two, not both.
| Constraint | On | JSON Schema |
|---|---|---|
Greater, GreaterEqual, Less, LessEqual, StrictEqual, Positive, Positive0, Negative, Negative0, Interval.* |
Int, Long |
minimum, maximum; an exclusive bound as the inclusive one it equals (Positive is minimum: 1) |
| the same | Double, Float |
minimum, maximum, exclusiveMinimum, exclusiveMaximum |
MinLength, MaxLength, FixedLength, Not[Empty] |
String |
minLength, maxLength |
Not[Blank] |
String |
minLength: 1; that it is not only whitespace is checked when the reply is read |
MinLength, MaxLength, FixedLength, Not[Empty] |
List, Seq, Vector, Set |
minItems, maxItems |
C1 & C2 of the above |
both; of two bounds of one kind, the tighter |
Every other constraint is refused at compile time with a message naming it, rather than left out of the schema without a word: Match (llm4s-core’s StringSchema has no pattern yet), Multiple, StartWith, ForAll and the rest, a union other than the >= and <= Iron builds, Not of anything but Empty and Blank, and a constraint on any other type, such as BigDecimal, which is written as a JSON string. To use one of them, describe the type with a given SchemaOf of your own, which is taken as it is. A provider may or may not enforce these keywords while it generates; the ReadWriter enforces the constraint on every reply.
Compile time
The derivation is Scala 3 inline code plus a small macro that reads annotations and rejects the shapes above. The macro walks each type it reaches once, so a type reached along many paths does not multiply the work. For a case class with 30 fields, one measurement of an incremental compile of the single file took about 8 seconds with derives SchemaOf, ReadWriter against about 5 seconds with derives ReadWriter alone, so roughly 3 seconds more, on a busy machine. Measure your own project if compile time matters to you.