Documentation Feedback: Missing indentation in Python/JS code examples for Structured Outputs

Documentation
1

Hi everyone,

Background

I noticed a formatting issue in the Structured Outputs documentation.

In several code examples, the Python and JavaScript sample code lacks proper indentation, making it hard to read.

Browsers

I have tested the following browsers and can confirm that the issues occur in all of them.

  • Chrome (version: 148.0.7778.179 64 bit)

  • Firefox (version: 143.0 64 bit)

  • edge (version: 148.0.3967.83 64 bit)

Issues

Here are the specific sections where the indentation is broken:

  • Refusals with Structured Outputs (URL fragment exits but not work well)

  • Streaming

  • Root objects must not be anyOf and must be an object (No URL fragment)

My Questions & Requests:

  1. Is there a public repository for the documentation? For Google Gemini, the documentation examples are hosted in a public GitHub repository, allowing users to submit Pull Requests directly. Does OpenAI have a similar public repo where community members can contribute documentation fixes?

  2. Request to the Documentation Team: If there isn’t a public repo for this, could someone from the OpenAI documentation team please review and fix the indentation in the sections mentioned above?

Thank you!

2

OpenAI doesn’t accept pulls against the specification that precipitates out the API reference. Nor does a PR against one of their libraries even really matter, as the code is auto-generated.

The rate they close issues is somewhere between “occasionally, internally” and “never and no more” depending on the Github repo.

You can see the two megabyte yaml reference used to generate libraries and generally used to automate the API reference (sometimes out-of sync or held back) referenced in an OpenAI SDK repo.

So you are free to protest the issue here, and occasionally it might have been noted by a staff lurker in the past.

3

Hi @_j !

Thank you for your prompt reply.

I understand that the reference and SDK are automatically generated based on the two-megabyte YAML references.

I didn’t know that, and I find it really intriguing.

It seems that all I can do is hope that an internal engineer will find this post by chance and fix the document.

Thank you again for your detailed reply!

4

Hi @_j!

Just one quick thing to clarify—I realized my previous wording might have been a bit ambiguous.

I’m not actually contesting or protesting the API specification itself. I just wanted to report a pure frontend/UI bug where the Python/JS code examples are losing their indentation on the webpage, making them look a bit cluttered.

Since it’s an automated pipeline like you said, it’s probably a rendering glitch on their docs site. Thanks again for the great context!

5

The examples in the API reference are quite literal in the reference.

The documentation, however, is OpenAI’s own “source”, so indeed, they’ll need to get into the code and the content, and discover the solution themselves.

Thanks!

6

Welcome to the community and thanks for reporting this @Tetsuto-HARA, and also appreciate the extra context from @_j.

This definitely sounds more like a docs rendering/frontend issue than a problem with the underlying spec itself. I can see why the broken indentation would make those Structured Outputs examples much harder to follow, especially in the streaming sections.

Right now there isn’t really a public contribution flow for the docs in the same way some other API platforms handle GitHub PRs, so forum reports like this are often the best way to surface issues like these.

I’m passing this along internally as feedback so the docs team can take a look at the formatting problems you called out.

-Mark G.