@devries-cameron20 / composio-1 / commits / 4ea04319f
Fork 0

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

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