diff --git a/.swiftlint-baseline.json b/.swiftlint-baseline.json
index 42d2f64..7657a86 100644
--- a/.swiftlint-baseline.json
+++ b/.swiftlint-baseline.json
@@ -267,7 +267,6 @@
{"violation":{"ruleDescription":"Properties should have a type interface","ruleIdentifier":"explicit_type_interface","location":{"file":"Sources/ModelRelay/Models/Generation/DecisionByLanguageModel.swift","line":29,"character":21},"reason":"Properties should have a type interface","severity":"warning","ruleName":"Explicit Type Interface"},"text":" let text = field.textValue.trimmingCharacters(in: .whitespacesAndNewlines.union(CharacterSet(charactersIn: \"\\\"'\")))"},
{"violation":{"ruleDescription":"Properties should have a type interface","ruleIdentifier":"explicit_type_interface","location":{"file":"Sources/ModelRelay/Models/Generation/DecisionByLanguageModel.swift","line":35,"character":21},"reason":"Properties should have a type interface","severity":"warning","ruleName":"Explicit Type Interface"},"text":" let text = field.textValue.trimmingCharacters(in: .whitespacesAndNewlines.union(CharacterSet(charactersIn: \"\\\"'\")))"},
{"violation":{"ruleDescription":"Use `Self` to refer to the surrounding type name","ruleIdentifier":"prefer_self_in_static_references","location":{"file":"Sources/ModelRelay/Models/Generation/Field.swift","line":8,"character":28},"reason":"Use `Self` to refer to the surrounding type name","severity":"warning","ruleName":"Prefer Self in Static References"},"text":" indirect case list(Kind)"},
-{"violation":{"ruleDescription":"Properties should have a type interface","ruleIdentifier":"explicit_type_interface","location":{"file":"Sources/ModelRelay/Models/Generation/SchemaBuilder.swift","line":18,"character":13},"reason":"Properties should have a type interface","severity":"warning","ruleName":"Explicit Type Interface"},"text":" let root = DynamicGenerationSchema(name: name, properties: fields.map { field in"},
{"violation":{"ruleDescription":"Enums should be explicitly assigned their raw values","ruleIdentifier":"explicit_enum_raw_value","location":{"file":"Sources/ModelRelay/Models/ModelCatalog.swift","line":7,"character":10},"reason":"Enums should be explicitly assigned their raw values","severity":"warning","ruleName":"Explicit Enum Raw Value"},"text":" case local, remote, unspecified"},
{"violation":{"ruleDescription":"Enums should be explicitly assigned their raw values","ruleIdentifier":"explicit_enum_raw_value","location":{"file":"Sources/ModelRelay/Models/ModelCatalog.swift","line":7,"character":17},"reason":"Enums should be explicitly assigned their raw values","severity":"warning","ruleName":"Explicit Enum Raw Value"},"text":" case local, remote, unspecified"},
{"violation":{"ruleDescription":"Enums should be explicitly assigned their raw values","ruleIdentifier":"explicit_enum_raw_value","location":{"file":"Sources/ModelRelay/Models/ModelCatalog.swift","line":7,"character":25},"reason":"Enums should be explicitly assigned their raw values","severity":"warning","ruleName":"Explicit Enum Raw Value"},"text":" case local, remote, unspecified"},
@@ -453,7 +452,7 @@
{"violation":{"ruleDescription":"Enums should be explicitly assigned their raw values","ruleIdentifier":"explicit_enum_raw_value","location":{"file":"Sources/ModelRelay/Workflow/Validation/Workflow+Validation.swift","line":6,"character":48},"reason":"Enums should be explicitly assigned their raw values","severity":"warning","ruleName":"Explicit Enum Raw Value"},"text":" case incompatibleModel, invalidSchema, unavailableTool, invalidContext, invalidVersion"},
{"violation":{"ruleDescription":"Enums should be explicitly assigned their raw values","ruleIdentifier":"explicit_enum_raw_value","location":{"file":"Sources/ModelRelay/Workflow/Validation/Workflow+Validation.swift","line":6,"character":65},"reason":"Enums should be explicitly assigned their raw values","severity":"warning","ruleName":"Explicit Enum Raw Value"},"text":" case incompatibleModel, invalidSchema, unavailableTool, invalidContext, invalidVersion"},
{"violation":{"ruleDescription":"Enums should be explicitly assigned their raw values","ruleIdentifier":"explicit_enum_raw_value","location":{"file":"Sources/ModelRelay/Workflow/Validation/Workflow+Validation.swift","line":6,"character":81},"reason":"Enums should be explicitly assigned their raw values","severity":"warning","ruleName":"Explicit Enum Raw Value"},"text":" case incompatibleModel, invalidSchema, unavailableTool, invalidContext, invalidVersion"},
-{"violation":{"ruleDescription":"Function bodies should not span too many lines","ruleIdentifier":"function_body_length","location":{"file":"Sources/ModelRelay/Workflow/Validation/Workflow+Validation.swift","line":21,"character":5},"reason":"Function body should span 80 lines or less excluding comments and whitespace: currently spans 107 lines","severity":"error","ruleName":"Function Body Length"},"text":" func validationIssues(catalog: ModelCatalog, kits: [String: ToolKit]) -> [WorkflowValidationIssue] {"},
+{"violation":{"ruleDescription":"Function bodies should not span too many lines","ruleIdentifier":"function_body_length","location":{"file":"Sources/ModelRelay/Workflow/Validation/Workflow+Validation.swift","line":21,"character":5},"reason":"Function body should span 80 lines or less excluding comments and whitespace: currently spans 94 lines","severity":"error","ruleName":"Function Body Length"},"text":" func validationIssues(catalog: ModelCatalog, kits: [String: ToolKit]) -> [WorkflowValidationIssue] {"},
{"violation":{"ruleDescription":"Properties should have a type interface","ruleIdentifier":"explicit_type_interface","location":{"file":"Sources/ModelRelay/Workflow/Validation/Workflow+Validation.swift","line":31,"character":13},"reason":"Properties should have a type interface","severity":"warning","ruleName":"Explicit Type Interface"},"text":" let knownModels = Set(catalog.ids)"},
{"violation":{"ruleDescription":"Complexity of function bodies should be limited.","ruleIdentifier":"cyclomatic_complexity","location":{"file":"Sources/ModelRelay/Workflow/Validation/Workflow+Validation.swift","line":50,"character":9},"reason":"Function should have complexity 8 or less; currently complexity is 33","severity":"error","ruleName":"Cyclomatic Complexity"},"text":" func visit(_ steps: [Step]) {"},
{"violation":{"ruleDescription":"Function bodies should not span too many lines","ruleIdentifier":"function_body_length","location":{"file":"Sources/ModelRelay/Workflow/Validation/Workflow+Validation.swift","line":50,"character":9},"reason":"Function body should span 40 lines or less excluding comments and whitespace: currently spans 72 lines","severity":"warning","ruleName":"Function Body Length"},"text":" func visit(_ steps: [Step]) {"},
diff --git a/CHANGELOG.md b/CHANGELOG.md
index d28729f..c36b733 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -9,6 +9,14 @@
- A `modelrelay` agent skill and Claude Code plugin marketplace, so coding agents in host apps
add the package, use the docs of their resolved version and follow the SDK's safety contracts.
`make check-skill` keeps its guide links and API names in sync with the package.
+- `Field.Kind.object` groups fields, so `extract` steps and tool parameters can ask for
+ lists of records such as `.list(.object([...]))`. Each object reads as a dictionary.
+ Exhaustive `switch`es over `Field.Kind` need a case for it.
+
+### Fixed
+
+- Named schema nodes no longer share a definition when their names repeat (a tool and one of its
+ choice parameters, or fields in different objects), which let one replace the other's shape.
## [0.1.0] - 2026-10-18
diff --git a/Documentation/Usage.md b/Documentation/Usage.md
index c65fc56..877bc13 100644
--- a/Documentation/Usage.md
+++ b/Documentation/Usage.md
@@ -6,8 +6,8 @@ Pick a recipe and add the integrations it needs. Models used by a step must
be available in your executor's catalog.
[🎯 Steps](#step-types) · [🔀 Branches](#composition) · [📦 Values](#values-and-input) ·
-[🌐 HTTP](#http-requests-and-agent-tools) · [☁️ Cloud](#cloud-models) · [📷 Images](#images) ·
-[👨💻 Swift](#custom-swift) · [🧰 MCP](#mcp-tools-and-oauth) · [🗳 Decisions](#decision-models)
+[🧾 Nested fields](#nested-fields) · [🌐 HTTP](#http-requests-and-agent-tools) · [☁️ Cloud](#cloud-models) ·
+[📷 Images](#images) · [👨💻 Swift](#custom-swift) · [🧰 MCP](#mcp-tools-and-oauth) · [🗳 Decisions](#decision-models)
@@ -87,6 +87,30 @@ Executions are independent. Opt into [conversation/handoff](ContextAndPolicies.m
for shared history or selected context. `stepTimeout` defaults to 30 seconds
per bounded operation, not per workflow; cancellation remains cooperative.
+
+
+## 🧾 Extract lists of objects
+
+Group fields with `.object`. A list of objects reads records such as the lines of an order:
+
+```swift
+let workflow = Workflow(
+ name: "Order from text"
+) {
+ Step.extract("order", instruction: "Turn the order into lines.", model: .appleOnDevice) {
+ Field("lines", .list(.object([
+ Field("product", .choice(["Beer", "Cola", "Fries"])),
+ Field("quantity", .number),
+ Field("note", .text),
+ ])))
+ }
+}
+```
+
+Each object becomes a dictionary (`{{order.lines}}` inserts the list as JSON).
+Objects work wherever fields do, including tool parameters. Nested field names
+only need to be unique within their object.
+
## 🌐 Call an HTTP API
diff --git a/Sources/ModelRelay/Execution/Steps/WorkflowExecutor+Tools.swift b/Sources/ModelRelay/Execution/Steps/WorkflowExecutor+Tools.swift
index 8bd3ba9..d42eb15 100644
--- a/Sources/ModelRelay/Execution/Steps/WorkflowExecutor+Tools.swift
+++ b/Sources/ModelRelay/Execution/Steps/WorkflowExecutor+Tools.swift
@@ -119,7 +119,7 @@ private enum ServerArguments {
case let .list(item):
if let data = text.data(using: .utf8), let parsed = Value(json: data), case .list = parsed { return parsed }
return .list(text.split(whereSeparator: \.isNewline).map { value(String($0).trimmingCharacters(in: .whitespaces), as: item) })
- case .text, .choice:
+ case .text, .choice, .object:
// A JSON object or list written into a text field is sent as one.
if text.hasPrefix("{") || text.hasPrefix("["), let data = text.data(using: .utf8), let parsed = Value(json: data) {
return parsed
diff --git a/Sources/ModelRelay/Models/Generation/Field.swift b/Sources/ModelRelay/Models/Generation/Field.swift
index e2f8504..b04df8a 100644
--- a/Sources/ModelRelay/Models/Generation/Field.swift
+++ b/Sources/ModelRelay/Models/Generation/Field.swift
@@ -6,6 +6,9 @@ public struct Field: Codable, Sendable, Hashable {
case text, number, bool
case choice([String])
indirect case list(Kind)
+ /// Named fields of their own, such as each line of an order in a
+ /// `.list(.object([...]))`. The result is a dictionary.
+ case object([Field])
}
public var name: String
diff --git a/Sources/ModelRelay/Models/Generation/SchemaBuilder.swift b/Sources/ModelRelay/Models/Generation/SchemaBuilder.swift
index d984aee..d44b40b 100644
--- a/Sources/ModelRelay/Models/Generation/SchemaBuilder.swift
+++ b/Sources/ModelRelay/Models/Generation/SchemaBuilder.swift
@@ -1,32 +1,53 @@
import AnyLanguageModel
-extension Field.Kind {
- func schema(named name: String) -> DynamicGenerationSchema {
- switch self {
- case .text: DynamicGenerationSchema(type: String.self)
- case .number: DynamicGenerationSchema(type: Double.self)
- case .bool: DynamicGenerationSchema(type: Bool.self)
- case let .choice(options): DynamicGenerationSchema(name: name, anyOf: options)
- case let .list(item): DynamicGenerationSchema(arrayOf: item.schema(named: name + "Item"))
- }
- }
-}
-
enum SchemaBuilder {
/// A guided-generation schema for an object with `fields`.
static func object(named name: String, fields: [Field]) throws -> GenerationSchema {
- let root = DynamicGenerationSchema(name: name, properties: fields.map { field in
+ var names: SchemaNames = .init()
+ return try GenerationSchema(root: names.object(named: name, fields: fields), dependencies: [])
+ }
+
+ /// A schema whose only valid output is one of `labels`.
+ static func label(from labels: [String]) throws -> GenerationSchema {
+ try GenerationSchema(root: DynamicGenerationSchema(name: "Label", anyOf: labels), dependencies: [])
+ }
+}
+
+/// Named nodes (objects and choices) become shared definitions keyed by name,
+/// and a later node with the same name replaces an earlier one. Nested fields
+/// often repeat names (`name`, `kind`), so each node gets its own.
+private struct SchemaNames {
+ private var used: Set = []
+
+ mutating func object(named name: String, fields: [Field]) -> DynamicGenerationSchema {
+ let name: String = unique(name)
+ return DynamicGenerationSchema(name: name, properties: fields.map { field in
DynamicGenerationSchema.Property(
name: field.name,
description: field.description,
- schema: field.kind.schema(named: field.name)
+ schema: schema(field.kind, named: field.name)
)
})
- return try GenerationSchema(root: root, dependencies: [])
}
- /// A schema whose only valid output is one of `labels`.
- static func label(from labels: [String]) throws -> GenerationSchema {
- try GenerationSchema(root: DynamicGenerationSchema(name: "Label", anyOf: labels), dependencies: [])
+ private mutating func schema(_ kind: Field.Kind, named name: String) -> DynamicGenerationSchema {
+ switch kind {
+ case .text: DynamicGenerationSchema(type: String.self)
+ case .number: DynamicGenerationSchema(type: Double.self)
+ case .bool: DynamicGenerationSchema(type: Bool.self)
+ case let .choice(options): DynamicGenerationSchema(name: unique(name), anyOf: options)
+ case let .list(item): DynamicGenerationSchema(arrayOf: schema(item, named: name + "Item"))
+ case let .object(fields): object(named: name, fields: fields)
+ }
+ }
+
+ private mutating func unique(_ base: String) -> String {
+ var name: String = base
+ var suffix: Int = 2
+ while !used.insert(name).inserted {
+ name = "\(base)\(suffix)"
+ suffix += 1
+ }
+ return name
}
}
diff --git a/Sources/ModelRelay/Workflow/Validation/Field+Validation.swift b/Sources/ModelRelay/Workflow/Validation/Field+Validation.swift
new file mode 100644
index 0000000..5e06d5e
--- /dev/null
+++ b/Sources/ModelRelay/Workflow/Validation/Field+Validation.swift
@@ -0,0 +1,31 @@
+import Foundation
+
+extension [Field] {
+ /// Why these fields can't become a guided-generation schema, nested objects included.
+ var schemaProblems: [String] {
+ var problems: [String] = []
+ if Set(map(\.name)).count != count || contains(where: { $0.name.isEmpty }) {
+ problems.append("fields need unique nonempty names")
+ }
+ for field in self {
+ problems += field.kind.schemaProblems
+ }
+ return problems
+ }
+}
+
+extension Field.Kind {
+ var schemaProblems: [String] {
+ switch self {
+ case let .choice(options):
+ let blank: Bool = options.contains { $0.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty }
+ return options.isEmpty || blank || Set(options).count != options.count ? ["choices must be nonempty and unique"] : []
+ case let .list(item):
+ return item.schemaProblems
+ case let .object(fields):
+ return (fields.isEmpty ? ["objects need at least one field"] : []) + fields.schemaProblems
+ case .text, .number, .bool:
+ return []
+ }
+ }
+}
diff --git a/Sources/ModelRelay/Workflow/Validation/Workflow+Validation.swift b/Sources/ModelRelay/Workflow/Validation/Workflow+Validation.swift
index 63b7620..434fb12 100644
--- a/Sources/ModelRelay/Workflow/Validation/Workflow+Validation.swift
+++ b/Sources/ModelRelay/Workflow/Validation/Workflow+Validation.swift
@@ -29,22 +29,9 @@ extension Workflow {
}
var names: Set = []
let knownModels = Set(catalog.ids)
- func fields(_ fields: [Field], step: String) {
- if Set(fields.map(\.name)).count != fields.count || fields.contains(where: { $0.name.isEmpty }) {
- issue(step, .invalidSchema, "fields need unique nonempty names")
- }
- func kind(_ value: Field.Kind) {
- switch value {
- case let .choice(options):
- if options.isEmpty || options.contains(where: { $0.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty }) || Set(options).count != options.count {
- issue(step, .invalidSchema, "choices must be nonempty and unique")
- }
- case let .list(item): kind(item)
- default: break
- }
- }
- for field in fields {
- kind(field.kind)
+ func fields(_ list: [Field], step: String) {
+ for problem in list.schemaProblems {
+ issue(step, .invalidSchema, problem)
}
}
func visit(_ steps: [Step]) {
diff --git a/Tests/ModelRelayTests/Models/LiveAppleTests.swift b/Tests/ModelRelayTests/Models/LiveAppleTests.swift
index 036507f..366bcd7 100644
--- a/Tests/ModelRelayTests/Models/LiveAppleTests.swift
+++ b/Tests/ModelRelayTests/Models/LiveAppleTests.swift
@@ -45,6 +45,20 @@ struct LiveAppleTests {
#expect(report.output["queue"] == .text("shipping"))
}
+ @Test func onDeviceModelExtractsListsOfObjects() async throws {
+ let workflow: Workflow = .init(name: "Order", steps: [Step("order", .extract(instruction: "Turn the order into lines.", fields: [
+ Field("lines", .list(.object([
+ Field("product", .choice(["Beer", "Cola", "Fries"])),
+ Field("quantity", .number),
+ ]))),
+ ]), model: .appleOnDevice)])
+ let report: WorkflowExecutionReport = try await WorkflowExecutor().run(workflow, input: .text("Two beers and one portion of fries, please."))
+ print("LIVE order:", report.output["lines"]?.modelText ?? "", "|", report.duration)
+ let lines: [Value] = try #require(report.output["lines"].flatMap { if case let .list(items) = $0 { items } else { nil } })
+ #expect(lines.contains(.dictionary(["product": .text("Beer"), "quantity": .number(2)])))
+ #expect(lines.contains(.dictionary(["product": .text("Fries"), "quantity": .number(1)])))
+ }
+
/// Its first use in a process prepares the model, which can take a
/// minute on a Mac; later runs take a fraction of a second.
@Test func appleTextRecognitionReadsTheImageOnDevice() async throws {
diff --git a/Tests/ModelRelayTests/Models/NestedFieldTests.swift b/Tests/ModelRelayTests/Models/NestedFieldTests.swift
new file mode 100644
index 0000000..5ae34dc
--- /dev/null
+++ b/Tests/ModelRelayTests/Models/NestedFieldTests.swift
@@ -0,0 +1,93 @@
+import AnyLanguageModel
+import Foundation
+import Testing
+@testable import ModelRelay
+
+@Suite struct NestedFieldTests {
+ private let order: [Field] = [
+ Field("table", .text),
+ Field("lines", .list(.object([
+ Field("kind", .choice(["add", "remove"])),
+ Field("product", .text),
+ Field("quantity", .number),
+ ]))),
+ ]
+
+ @Test func extractReturnsListsOfObjects() async throws {
+ let model: ScriptedModel = .init("small", replies: [#"""
+ {"table": "4", "lines": [
+ {"kind": "add", "product": "Beer", "quantity": 2},
+ {"kind": "remove", "product": "Cola", "quantity": 1}
+ ]}
+ """#])
+ let workflow: Workflow = .init(name: "Order", steps: [
+ Step("order", .extract(instruction: "Read the order.", fields: order), model: "small"),
+ ])
+
+ let report: WorkflowExecutionReport = try await WorkflowExecutor(catalog: .scripted(["small": model]))
+ .run(workflow, input: .text("Two beers, no cola"))
+
+ #expect(report.output["table"] == .text("4"))
+ #expect(report.output["lines"] == .list([
+ .dictionary(["kind": .text("add"), "product": .text("Beer"), "quantity": .number(2)]),
+ .dictionary(["kind": .text("remove"), "product": .text("Cola"), "quantity": .number(1)]),
+ ]))
+ }
+
+ @Test func repeatedNamesKeepTheirOwnDefinitions() throws {
+ let fields: [Field] = [
+ Field("kind", .choice(["dine-in", "takeaway"])),
+ Field("lines", .list(.object([Field("kind", .choice(["add", "remove"]))]))),
+ Field("total", .object([Field("amount", .number)])),
+ ]
+
+ let schema: GenerationSchemaJSON = try .init(SchemaBuilder.object(named: "Result", fields: fields))
+
+ #expect(Set(schema.definitions.keys) == ["Result", "kind", "linesItem", "kind2", "total"])
+ #expect(schema.choices("kind") == ["dine-in", "takeaway"])
+ #expect(schema.choices("kind2") == ["add", "remove"])
+ let item: [String: Any]? = schema.definitions["linesItem"] as? [String: Any]
+ #expect((item?["properties"] as? [String: Any])?["kind"] as? [String: String] == ["$ref": "#/$defs/kind2"])
+ }
+
+ @Test func emptyAndDuplicateNestedFieldsArePreflightIssues() async {
+ let model: ScriptedModel = .init("small", replies: [])
+ let executor: WorkflowExecutor = .init(catalog: .scripted(["small": model]))
+ let workflow: Workflow = .init("Order") {
+ Step.extract("order", instruction: "Read.", model: "small") {
+ Field("empty", .object([]))
+ Field("lines", .list(.object([Field("product", .text), Field("product", .number)])))
+ }
+ }
+
+ let issues: [WorkflowValidationIssue] = await executor.validate(workflow)
+
+ #expect(issues.count == 2)
+ #expect(Set(issues.map(\.detail)) == ["objects need at least one field", "fields need unique nonempty names"])
+ #expect(model.callCount == 0)
+ }
+
+ @Test func workflowsWithObjectsRoundTripAsJSON() throws {
+ let workflow: Workflow = .init(name: "Order", steps: [
+ Step("order", .extract(instruction: "Read.", fields: order), model: .appleOnDevice),
+ ])
+
+ let data: Data = try JSONEncoder().encode(workflow)
+
+ #expect(try JSONDecoder().decode(Workflow.self, from: data) == workflow)
+ }
+}
+
+/// A generation schema as the JSON providers receive, to read its shared definitions.
+private struct GenerationSchemaJSON {
+ let definitions: [String: Any]
+
+ init(_ schema: GenerationSchema) throws {
+ let json: Any = try JSONSerialization.jsonObject(with: JSONEncoder().encode(schema))
+ definitions = (json as? [String: Any])?["$defs"] as? [String: Any] ?? [:]
+ }
+
+ func choices(_ name: String) -> [String]? {
+ (definitions[name] as? [String: Any])?["enum"] as? [String]
+ }
+}
diff --git a/skills/modelrelay/references/api-map.md b/skills/modelrelay/references/api-map.md
index 9ee729b..45cdf9d 100644
--- a/skills/modelrelay/references/api-map.md
+++ b/skills/modelrelay/references/api-map.md
@@ -10,6 +10,7 @@ Read signatures in `Sources/` before calling anything not shown in a guide.
| --- | --- | --- |
| Generated text | `Step.prompt("summary", "Summarize.", model: .appleOnDevice)` | `Documentation/Usage.md#step-types` |
| Typed fields | `Step.extract("expense", instruction: "…", model:) { Field(…) }` | `README.md#usage` |
+| Lists of records | `Field("lines", .list(.object([Field(…)])))` | `Documentation/Usage.md#nested-fields` |
| One label | `Step.classify("kind", "…", labels: […], model:)` | `Documentation/Usage.md#composition` |
| Yes/no, choices, scores | `Step.decide("ticket", questions: [Question(…)], model:)` | `Documentation/Usage.md#decision-models` |
| An answer that may call tools | `Step.agent("answer", "…", tools: [AgentTool(…)], model:)` | `Documentation/Usage.md#http-requests-and-agent-tools` |