@@ -68,44 +68,77 @@ public final class Schema: Sendable {
68
68
/// The format of the data.
69
69
public let format : String ?
70
70
71
- /// A brief description of the parameter.
71
+ /// A human-readable explanation of the purpose of the schema or property. While not strictly
72
+ /// enforced on the value itself, good descriptions significantly help the model understand the
73
+ /// context and generate more relevant and accurate output.
72
74
public let description : String ?
73
75
76
+ /// A human-readable name/summary for the schema or a specific property. This helps document the
77
+ /// schema's purpose but doesn't typically constrain the generated value. It can subtly guide the
78
+ /// model by clarifying the intent of a field.
79
+ public let title : String ?
80
+
74
81
/// Indicates if the value may be null.
75
82
public let nullable : Bool ?
76
83
77
84
/// Possible values of the element of type "STRING" with "enum" format.
78
85
public let enumValues : [ String ] ?
79
86
80
- /// Schema of the elements of type `"ARRAY"`.
87
+ /// Defines the schema for the elements within the `"ARRAY"`. All items in the generated array
88
+ /// must conform to this schema definition. This can be a simple type (like .string) or a complex
89
+ /// nested object schema.
81
90
public let items : Schema ?
82
91
83
- /// The minimum number of items (elements) in a schema of type `"ARRAY"`.
92
+ /// An integer specifying the minimum number of items the generated `"ARRAY"` must contain .
84
93
public let minItems : Int ?
85
94
86
- /// The maximum number of items (elements) in a schema of type `"ARRAY"`.
95
+ /// An integer specifying the maximum number of items the generated `"ARRAY"` must contain .
87
96
public let maxItems : Int ?
88
97
89
- /// Properties of type `"OBJECT"`.
98
+ /// The minimum value of a numeric type.
99
+ public let minimum : Double ?
100
+
101
+ /// The maximum value of a numeric type.
102
+ public let maximum : Double ?
103
+
104
+ /// Defines the members (key-value pairs) expected within an object. It's a dictionary where keys
105
+ /// are the property names (strings) and values are nested `Schema` definitions describing each
106
+ /// property's type and constraints.
90
107
public let properties : [ String : Schema ] ?
91
108
92
- /// Required properties of type `"OBJECT"`.
109
+ /// An array of strings, where each string is the name of a property defined in the `properties`
110
+ /// dictionary that must be present in the generated object. If a property is listed here, the
111
+ /// model must include it in the output.
93
112
public let requiredProperties : [ String ] ?
94
113
114
+ /// A specific hint provided to the Gemini model, suggesting the order in which the keys should
115
+ /// appear in the generated JSON string. Important: Standard JSON objects are inherently unordered
116
+ /// collections of key-value pairs. While the model will try to respect propertyOrdering in its
117
+ /// textual JSON output, subsequent parsing into native Swift objects (like Dictionaries or
118
+ /// Structs) might not preserve this order. This parameter primarily affects the raw JSON string
119
+ /// serialization.
120
+ public let propertyOrdering : [ String ] ?
121
+
95
122
required init ( type: DataType , format: String ? = nil , description: String ? = nil ,
123
+ title: String ? = nil ,
96
124
nullable: Bool = false , enumValues: [ String ] ? = nil , items: Schema ? = nil ,
97
- minItems: Int ? = nil , maxItems: Int ? = nil ,
98
- properties: [ String : Schema ] ? = nil , requiredProperties: [ String ] ? = nil ) {
125
+ minItems: Int ? = nil , maxItems: Int ? = nil , minimum: Double ? = nil ,
126
+ maximum: Double ? = nil , properties: [ String : Schema ] ? = nil ,
127
+ requiredProperties: [ String ] ? = nil , propertyOrdering: [ String ] ? = nil ) {
99
128
dataType = type
100
129
self . format = format
101
130
self . description = description
131
+ self . title = title
102
132
self . nullable = nullable
103
133
self . enumValues = enumValues
104
134
self . items = items
105
135
self . minItems = minItems
106
136
self . maxItems = maxItems
137
+ self . minimum = minimum
138
+ self . maximum = maximum
107
139
self . properties = properties
108
140
self . requiredProperties = requiredProperties
141
+ self . propertyOrdering = propertyOrdering
109
142
}
110
143
111
144
/// Returns a `Schema` representing a string value.
@@ -184,12 +217,19 @@ public final class Schema: Sendable {
184
217
/// use Markdown format.
185
218
/// - nullable: If `true`, instructs the model that it may generate `null` instead of a number;
186
219
/// defaults to `false`, enforcing that a number is generated.
187
- public static func float( description: String ? = nil , nullable: Bool = false ) -> Schema {
220
+ /// - minimum: If specified, instructs the model that the value should be greater than or
221
+ /// equal to the specified minimum.
222
+ /// - maximum: If specified, instructs the model that the value should be less than or equal
223
+ /// to the specified maximum.
224
+ public static func float( description: String ? = nil , nullable: Bool = false ,
225
+ minimum: Float ? = nil , maximum: Float ? = nil ) -> Schema {
188
226
return self . init (
189
227
type: . number,
190
228
format: " float " ,
191
229
description: description,
192
- nullable: nullable
230
+ nullable: nullable,
231
+ minimum: minimum. map { Double ( $0) } ,
232
+ maximum: maximum. map { Double ( $0) }
193
233
)
194
234
}
195
235
@@ -203,11 +243,18 @@ public final class Schema: Sendable {
203
243
/// use Markdown format.
204
244
/// - nullable: If `true`, instructs the model that it may return `null` instead of a number;
205
245
/// defaults to `false`, enforcing that a number is returned.
206
- public static func double( description: String ? = nil , nullable: Bool = false ) -> Schema {
246
+ /// - minimum: If specified, instructs the model that the value should be greater than or
247
+ /// equal to the specified minimum.
248
+ /// - maximum: If specified, instructs the model that the value should be less than or equal
249
+ /// to the specified maximum.
250
+ public static func double( description: String ? = nil , nullable: Bool = false ,
251
+ minimum: Double ? = nil , maximum: Double ? = nil ) -> Schema {
207
252
return self . init (
208
253
type: . number,
209
254
description: description,
210
- nullable: nullable
255
+ nullable: nullable,
256
+ minimum: minimum,
257
+ maximum: maximum
211
258
)
212
259
}
213
260
@@ -232,12 +279,15 @@ public final class Schema: Sendable {
232
279
/// formats ``IntegerFormat/int32`` and ``IntegerFormat/int64`` are supported; custom values
233
280
/// may be specified using ``IntegerFormat/custom(_:)`` but may be ignored by the model.
234
281
public static func integer( description: String ? = nil , nullable: Bool = false ,
235
- format: IntegerFormat ? = nil ) -> Schema {
282
+ format: IntegerFormat ? = nil ,
283
+ minimum: Int ? = nil , maximum: Int ? = nil ) -> Schema {
236
284
return self . init (
237
285
type: . integer,
238
286
format: format? . rawValue,
239
287
description: description,
240
- nullable: nullable
288
+ nullable: nullable. self,
289
+ minimum: minimum. map { Double ( $0) } ,
290
+ maximum: maximum. map { Double ( $0) }
241
291
)
242
292
}
243
293
@@ -317,7 +367,9 @@ public final class Schema: Sendable {
317
367
/// - nullable: If `true`, instructs the model that it may return `null` instead of an object;
318
368
/// defaults to `false`, enforcing that an object is returned.
319
369
public static func object( properties: [ String : Schema ] , optionalProperties: [ String ] = [ ] ,
320
- description: String ? = nil , nullable: Bool = false ) -> Schema {
370
+ propertyOrdering: [ String ] ? = nil ,
371
+ description: String ? = nil , title: String ? = nil ,
372
+ nullable: Bool = false ) -> Schema {
321
373
var requiredProperties = Set ( properties. keys)
322
374
for optionalProperty in optionalProperties {
323
375
guard properties. keys. contains ( optionalProperty) else {
@@ -329,9 +381,11 @@ public final class Schema: Sendable {
329
381
return self . init (
330
382
type: . object,
331
383
description: description,
384
+ title: title,
332
385
nullable: nullable,
333
386
properties: properties,
334
- requiredProperties: requiredProperties. sorted ( )
387
+ requiredProperties: requiredProperties. sorted ( ) ,
388
+ propertyOrdering: propertyOrdering
335
389
)
336
390
}
337
391
}
@@ -344,12 +398,16 @@ extension Schema: Encodable {
344
398
case dataType = " type "
345
399
case format
346
400
case description
401
+ case title
347
402
case nullable
348
403
case enumValues = " enum "
349
404
case items
350
405
case minItems
351
406
case maxItems
407
+ case minimum
408
+ case maximum
352
409
case properties
353
410
case requiredProperties = " required "
411
+ case propertyOrdering
354
412
}
355
413
}
0 commit comments