Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

next
mdx 66 lines 2.27 KB
Raw
1 ---
2 title: "Simplified Schemas for Optional Fields"
3 description: "Tool schemas are now cleaner for optional fields by removing redundant anyOf null constructs"
4 date: "2026-01-30"
5 ---
6
7 Tool schemas are now cleaner for optional fields by removing redundant `anyOf: [{type}, {type: "null"}]` constructs.
8
9 ## Background: How JSON Schema Handles Optional Fields
10
11 In JSON Schema, there are two distinct concepts:
12
13 | Concept | Meaning | How it's expressed |
14 |---------|---------|-------------------|
15 | **Optional** | Field can be omitted entirely | Field is NOT in the `required` array |
16 | **Nullable** | Field accepts `null` as a value | `anyOf: [{type}, {type: "null"}]` |
17
18 Previously, our schemas used `anyOf` with null type for all optional fields—even when the field wasn't in `required`. This was redundant: if a field can be omitted, explicitly marking it as "accepts null" adds no value.
19
20 ## What Changed
21
22 For fields that are **not in the `required` array**, the schema processing now:
23 - Removes the redundant `{type: "null"}` from `anyOf` arrays
24 - Removes `default: null` since it's implied by being optional
25 - Flattens single-type `anyOf` to direct `type` declarations
26
27 ## Before vs After
28
29 For example, the `page_token` field in `GOOGLECALENDAR_LIST_CALENDARS` (which is optional/not required):
30
31 **Previous (verbose):**
32 ```json
33 {
34 "page_token": {
35 "anyOf": [
36 { "type": "string" },
37 { "type": "null" }
38 ],
39 "default": null,
40 "description": "Token for the page of results to return...",
41 "title": "Page Token"
42 }
43 }
44 ```
45
46 **Now (simplified):**
47 ```json
48 {
49 "page_token": {
50 "type": "string",
51 "description": "Token for the page of results to return...",
52 "title": "Page Token"
53 }
54 }
55 ```
56
57 ## What's Preserved
58
59 - **Required nullable fields**: Fields in the `required` array that accept null still use `anyOf` with null type
60 - **Union types**: Fields accepting multiple value types (e.g., `string | number`) retain their full `anyOf` array
61
62 ## Why This Matters
63
64 - **Fewer tokens**: Simpler schemas reduce token usage when tools are passed to LLMs
65 - **Better compatibility**: Some code generators and validators handle direct types better than `anyOf` constructs
66 - **Clearer semantics**: Non-required fields don't need explicit null type—being optional already implies they can be omitted