Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
Mirrored from https://github.com/Camo67/composio.git
Synced Nov 22, 12:00 UTC
docs: add changelog for simplified optional field schemas (#2538)
Shrey Singla committed
Jan 30, 2026 at 19:21 UTC
4ea04319ff10360f2deea867129bc1ef71a1bec4
1 file changed
+66
docs/content/changelog/01-30-26-simplified-optional-schemas.mdx
new
+66
@@ -0,0 +1,66 @@
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