Contract design guide
Portable optional fields across OpenAI, Anthropic, Gemini, and MCP
Design optional tool parameters once, then compile correct provider-specific null and required semantics.
Optional, nullable, and omittable are different states. A portable canonical contract should preserve that business distinction before provider compilation changes its wire representation.
Read the schema and its provider wrapper as one contract. APITC distinguishes target requirements from portable JSON Schema, applies mechanical repairs only when intent is recoverable, and identifies transformations that can change meaning.
Diagnostic procedure
Repair the schema, then recompile.
- 01
Model business meaning
Decide whether missing, null, and an empty value mean different things.
- 02
Compile the wire form
OpenAI strict may need nullable-required; other targets can keep omission semantics.
- 03
Test round trips
If converting back cannot recover the original state distinction, mark the transform as lossy.
Canonical: limit may be omitted; null is not a valid business value.
OpenAI wire: limit is required and nullable; adapter removes null before invoking the business function.
$.inputSchemaClose this objectOpenAI strict requires additionalProperties: false on every object.
$.inputSchemaRequired array is incompleteStrict mode requires every property in required. APITC will make limit nullable.
No account · no upload · no endpoint calledOpen the full tool schema compiler and operating notes →
FAQ
Before you ship
Does APITC upload my schema?
No. Parsing, diagnostics, and compilation run in your browser tab.
Is the compiled result guaranteed to preserve meaning?
Safe repairs are deterministic. When the target provider cannot express a source constraint, APITC labels the transform as lossy instead of hiding it.
Protocol behavior checked against the OpenAI function calling guide. Recheck your pinned provider/API version before production deployment.