OpenAI is a textbook example of Conway's Law

There's a principle in software design called Conway's Law: organizations design systems that mirror their own communication structures (AKA shipping their org charts).

OpenAI has two endpoints which do largely similar things: their older chat/completions API and the newer responses one. (Not to mention their even older completions endpoint that's now deprecated.)

Both let you generate text, call tools, and produce structured output. And at first glance, they look quite similar. But as you dig deeper, the differences quickly appear. Take structured outputs as an example. With chat/completions, you write:

{
  "response_format": {
    "type": "json_schema",
    "json_schema": {
      "name": "Response",
      "description": "A response to the user's question",
      "schema": {"type": "object", "properties": ...}
    }
  }
}

But for responses, it needs to look like this:

{
  "text": {
    "format": {
      "type": "json_schema",
      "name": "Response",
      "description": "A response to the user's question",
      "schema": {"type": "object", "properties": ...}
    }
  }
}

I see no reason why these need to be different. It makes me wonder if they're deliberately making it difficult to migrate from one endpoint to the other. And the docs don't explain this! They only have a couple of examples, at least one of which is incorrect. I had to read the source code in their Python package to figure it out.

Google suffers from this too. Their Gemini API rejects JSON Schema with {"type": "array", "items": {}} (a valid schema meaning "array of anything"). Their official Python package silently rewrites the schema to make it compliant before sending. I like to imagine that someone on the Python package team got fed up with backend team for not addressing this and decided to fix it themselves.

I admit that this isn't surprising for fast-moving orgs who are shipping features quickly. But it does put a lot of burden on developers to deal with loads of little quirks like this. And it makes me wonder what's going on inside these places.

And to be fair, our own API has its share of inconsistencies too. If any of them have slowed you down, let us know and we'll do our best to accommodate your request!