Start with the maintained schema. Generated prose and plausible sample JSON should agree with it, rather than silently change what callers may send.
Inspect one object before writing the reference
This original fictional OpenAPI 3.1 schema fragment defines two properties. It is a teaching example, not a deployed endpoint or a full OpenAPI description:
{
"type": "object",
"required": ["nickname"],
"properties": {
"nickname": { "type": ["string", "null"] },
"timezone": { "type": "string" }
}
}
nickname must be present. Its value may be a string or null. timezone is not required, so it may be omitted. When supplied, its declared type is string. The fragment sets no rules about actual time-zone identifiers or empty strings; do not invent those rules in the explanation.
| JSON instance | Result under this fragment | Reason |
|---|---|---|
| {"nickname":null} | Valid | Required property is present; null is allowed |
| {} | Invalid | Required nickname is absent |
| {"nickname":"Ada","timezone":null} | Invalid | timezone is present with a non-string value |
| {"nickname":"Ada","timezone":"UTC"} | Valid | Both supplied values have allowed types |
The JSON Schema object reference, checked October 24, 2026, distinguishes property presence from a property's value. That distinction explains the table; it is not evidence that a server actually enforces the fragment.
Preserve the OpenAPI version
OpenAPI's official 3.0-to-3.1 guidance describes the change from the 3.0 nullable keyword to JSON Schema types that include null. Do not combine syntax from both versions just because two generated examples look similar.
If your source says OpenAPI 3.0, ask for an explanation of that source version. Treat migration as a separate approved change with validation in the project's tools. A documentation edit should not quietly become a contract migration.
Copy a schema-to-prose audit prompt
Audit these API documentation examples against the supplied schema.
OpenAPI version and authoritative schema location: [ENTER]
Relevant complete schema and referenced definitions: [PASTE]
Examples and explanatory text: [PASTE]
For each property distinguish required presence, permitted types,
null, omission and any explicitly declared default or constraint.
For every example, state valid/invalid only where the supplied schema
settles it, with the exact rule. Flag missing referenced definitions.
Do not infer a default, accepted identifier, server behavior, status
code or migration decision. Keep the schema version unchanged.
Suggest corrected explanatory wording and examples separately from
possible intentional contract changes. Do not call an endpoint.
OpenAI's prompting guidance supports this task-and-context structure. The useful result is a reason attached to each example, so another developer can check it without trusting a verdict alone.
Fix the maintained source before regenerating the page
If the intended contract allows a missing nickname, confirm that with the API owner before changing required. If the schema is already correct, fix the contradicting sample or prose. Validate complete examples with the team's schema tooling, then check actual behavior in an authorized test environment when that is part of the task.
Once the rules agree, the API reference template helps present requests and responses together. Keep the schema authoritative so a readable explanation does not become a competing definition of the API.