Seeking Clarity and Enhancements in JSON Schema Documentation for Assistants API

API Feedback
, , , ,
1

Dear OpenAI team,

I’m reaching out to express my frustration and suggest some improvements in the documentation and guides related to defining custom functions/tools using JSON Schema in the Assistants API.

Working with the API frequently feels like navigating a black box. This is not in reference to the stochastic nature of LLMs, but specifically to the available documentation on JSON Schemas.

Here’s some of my feedback:

  1. Explicitly communicate in your docs which JSON Schema draft or specification is supported in the Assistants API.
  2. Include a section in the Guide about JSON Schemas and how it relates to defining custom tools.
  3. Explain how JSON Schemas are converted into TypeScript and passed to the Assistants API.
  4. Mention any deviations from the official JSON Schema specifications. For instance, the API previously ignored deeply nested "description" annotations – source. Highlighting these instances in the Guides or Docs would be highly beneficial for developers.

Suggestion:

  • Consider the opportunity of defining a unique JSON Schema vocabulary tailored for custom functions in the Assistants API. This could streamline the development process and clarify usage for developers.

Thanks for taking my feedback and considering my suggestion.

2 Likes
2

+1

I’ve seen a fair amount of confusion on the discord about this. I’m also currently working on a problem that may actually be a bug in the API:

You could save everyone including yourselves a lot of time by simply providing one example in the docs of each data type that is supported.

2 Likes
3

Thank you to the OpenAI team for the much improved docs for Structured Outputs!
https://platform.openai.com/docs/guides/structured-outputs/supported-schemas