Request/Response Schema Documentation Prompt Template

This prompt is designed for a specific, high-value task: converting a raw JSON Schema or OpenAPI schema object into polished, developer-facing reference documentation. The ideal user is an API designer, documentation engineer, or platform team member who already has a valid, machine-readable schema and needs to generate the human-readable field-level tables that form the core of an API reference. The prompt's job is not to interpret an API's behavior or to write endpoint descriptions; it is strictly to translate structural schema definitions—types, constraints, defaults, nullability, and nested object shapes—into clear, consistent prose and markdown tables that can be embedded directly into a developer portal or SDK documentation.

You should use this prompt when your primary goal is to keep your reference documentation synchronized with a live API contract. It excels in environments where the schema is the source of truth, such as a CI/CD pipeline that lints an OpenAPI spec and then automatically regenerates documentation. The prompt assumes you are providing a complete and valid schema object as input. It will produce the best results when you also supply context like a [STYLE_GUIDE] for tone and formatting, and an [OUTPUT_SCHEMA] to strictly control the structure of the generated markdown. Do not use this prompt to generate a schema from code, to document the behavior of specific HTTP endpoints (methods, headers, auth), or to write high-level conceptual guides. It is a precision tool for a single, repeatable documentation generation step.

Before using this prompt, ensure your input schema is valid and complete. A common failure mode is providing a partial schema, which will result in documentation with missing fields or constraints. Another is schema drift, where the schema object no longer matches the live API. To mitigate this, the prompt's output should always be validated against the original schema in your implementation harness. The next step after reading this section is to prepare your schema input and review the prompt template to understand its required placeholders. Avoid the temptation to use this prompt for generating example values or endpoint-level documentation; those are separate, specialized tasks covered by other playbooks in this pillar.

This prompt template transforms raw schema objects into structured, developer-facing documentation. It accepts a JSON Schema or OpenAPI schema fragment as input and produces field-level documentation including types, constraints, defaults, nullability, and nested object descriptions. The template is designed to be dropped directly into your AI harness—replace the square-bracket placeholders with your actual schema objects, output format requirements, and any domain-specific constraints before execution.

codeCopy
You are an API documentation specialist. Your task is to convert a JSON Schema or OpenAPI schema object into a human-readable field documentation table.

## INPUT SCHEMA
[SCHEMA_OBJECT]

## OUTPUT FORMAT
[OUTPUT_SCHEMA]

## CONSTRAINTS
- Document every field present in the schema, including nested properties.
- For each field, include: field name, data type, required/optional status, default value (if specified), nullability, format constraints (min/max, pattern, enum values), and a human-readable description.
- If the schema includes `oneOf`, `anyOf`, or `allOf`, document each variant clearly and note the discriminator field if present.
- Flag any fields where the description is missing, ambiguous, or appears to be a placeholder.
- If enum values are present, list every accepted value. Flag any enum without descriptions.
- Preserve any `deprecated` annotations and include a deprecation warning in the field description.
- For nested objects, produce a separate sub-table or indented section that maintains parent-child relationships.
- Do not invent field descriptions. If no description exists in the schema, mark the field as `[DESCRIPTION MISSING]`.
- Do not alter types, constraints, or enum values from the source schema.

## EXAMPLES
[EXAMPLES]

## ADDITIONAL CONTEXT
[CONTEXT]

## RISK LEVEL
[RISK_LEVEL]

Generate the field documentation table now.

To adapt this template, replace [SCHEMA_OBJECT] with the raw JSON Schema or OpenAPI schema fragment you need documented. Set [OUTPUT_SCHEMA] to your desired output structure—typically a markdown table with columns for field name, type, required, default, nullable, constraints, and description. Use [EXAMPLES] to provide one or two correctly documented fields that demonstrate your team's preferred style and level of detail. The [CONTEXT] placeholder accepts any additional domain knowledge, such as authentication requirements, pagination conventions, or error handling patterns that should inform the descriptions. Set [RISK_LEVEL] to low, medium, or high to control validation strictness—high-risk contexts should trigger mandatory human review of all [DESCRIPTION MISSING] flags and enum documentation gaps before publication. After generating the documentation, always validate the output against the source schema to catch type mismatches, missing fields, or invented descriptions before the content reaches your developer portal.

Integrating the Request/Response Schema Documentation prompt into a production workflow requires treating it as a deterministic documentation generator with strict validation gates, not a one-off chat interaction. The prompt expects a JSON Schema or OpenAPI schema object as its primary input and produces structured documentation including field tables, type constraints, nullability flags, and nested object descriptions. The harness must ensure that the input schema is valid before the prompt runs, that the output matches the expected documentation structure, and that any drift between the schema and the generated docs is caught before publication. This is a high-accuracy workflow where missing an enum value or misrepresenting a required field directly harms downstream API consumers.

Build the harness around a validate → generate → validate → repair loop. Before calling the model, validate the input schema against its specification (JSON Schema Draft 2020-12 or OpenAPI 3.x) using a standard parser. Feed the validated schema into the prompt along with any [OUTPUT_SCHEMA] that defines the expected documentation format. After generation, run structural validation on the output: confirm every field in the source schema appears in the documentation, every documented type matches the schema type, all required fields are marked as required, all enum values are listed, and nested objects are recursively documented. If validation fails, route the errors back into a repair prompt that includes the original schema, the failed output, and the specific validation failures. Limit repair attempts to 2 retries before flagging for human review. Log every generation attempt, validation result, and repair action for auditability.

For model selection, prefer models with strong JSON mode and structured output support (GPT-4o, Claude 3.5 Sonnet, or equivalent). Set response_format to json_object or use the model's native structured output feature with the documentation schema as the target. Implement a human approval gate for any schema that contains deprecated fields, breaking changes, or security-sensitive parameters (auth tokens, PII fields). The approval step should present a diff between the previous documentation version and the new generated version. Avoid wiring this prompt directly into a CI/CD pipeline without the validation and approval gates—schema documentation errors propagate to every API consumer and are expensive to correct after publication.