SDK Type Definition and Model Documentation Prompt

Use this prompt when you need to produce a complete, structured reference for a data model, interface, or type definition in an SDK. The primary job-to-be-done is converting a raw source of truth—such as a JSON Schema, a protobuf definition, or a set of annotated source files—into a developer-facing document that describes every field, its type, nullability, default value, and relationship to other objects. The ideal user is an SDK engineer, a technical writer embedded in a platform team, or a developer relations engineer who must ensure that the public documentation surface is an exact and faithful representation of the serialization contract. This prompt is designed for a workflow where accuracy and completeness are non-negotiable because a missing field or incorrect type in the docs will cause integration bugs downstream.

This prompt is not a general-purpose documentation writer. Do not use it for conceptual overviews, getting-started narratives, or architectural decision records. It is strictly for structured, reference-style type documentation. You should have the canonical schema or source code available as input; the prompt works best when it can reference a concrete artifact rather than generating a type definition from memory. The required context includes the raw type definition, the target language or serialization format, and any specific documentation conventions your team follows, such as how to mark deprecated fields or experimental features. The output is a predictable, machine-readable structure that can be rendered into HTML, MDX, or a PDF without manual reformatting.

Before using this prompt, confirm that you have a stable source of truth for the type. If the schema is still in flux, the generated documentation will drift immediately, creating a maintenance burden. Pair this prompt with a validation step that diffs the generated output against the source schema to catch omissions. For high-stakes APIs where a documentation error could cause data loss or a security incident, always require human review of the final output before publication. The next step after generating the reference is to integrate it into your CI pipeline so that every schema change triggers a documentation refresh and a review request.

This prompt template generates structured documentation for SDK data models, interfaces, and type definitions. It expects source annotations, type definitions, or implementation code as input and produces field-level reference documentation with descriptions, nullability, enum values, nested object relationships, and serialization notes. The template is designed to be wired into a documentation pipeline where consistency with actual serialization behavior matters.

textCopy
You are an SDK documentation engineer. Generate structured type reference documentation from the provided source annotations and type definitions.

## INPUT
[SOURCE_ANNOTATIONS]

## OUTPUT SCHEMA
Return a JSON object with this exact structure:
{
  "type_name": "string",
  "package_path": "string",
  "description": "string",
  "fields": [
    {
      "name": "string",
      "type": "string",
      "required": boolean,
      "nullable": boolean,
      "description": "string",
      "default_value": "string or null",
      "enum_values": ["string"] or null,
      "deprecated": boolean,
      "deprecation_message": "string or null",
      "serialization_name": "string or null",
      "validation_constraints": "string or null"
    }
  ],
  "nested_types": [
    {
      "name": "string",
      "fields": [/* same field structure */]
    }
  ] or null,
  "serialization_format": "json" | "form" | "multipart" | "custom",
  "deserialization_notes": "string or null",
  "example_json": "string or null"
}

## CONSTRAINTS
- Extract every public field from the source annotations, including inherited fields.
- Mark fields as nullable only when the annotation explicitly allows null.
- Include enum_values when the type is an enum or string union with known values.
- Set serialization_name when the wire format name differs from the field name (e.g., snake_case vs camelCase).
- Flag deprecated fields with deprecation_message from the annotation.
- For nested object types, include them in nested_types with full field definitions.
- Generate example_json that matches the serialization_format and includes all required fields.
- If the source annotations are incomplete, note missing information in the relevant field description rather than omitting the field.
- Do not invent types, fields, or constraints not present in the source.

## EXAMPLES
[EXAMPLES]

## RISK LEVEL
[RISK_LEVEL]

Adapt this template by replacing each square-bracket placeholder. [SOURCE_ANNOTATIONS] should contain the raw type definitions, JSDoc comments, docstrings, or annotation tags from source code. [EXAMPLES] should include one or two well-formed output examples showing the expected structure for your SDK's specific type patterns. Set [RISK_LEVEL] to low for internal documentation, medium for customer-facing docs where errors cause confusion, or high for types involved in billing, auth, or data integrity where mistakes have operational consequences. For high-risk types, add a human review step before publication and validate the generated output against actual serialization test fixtures.

This prompt is designed to be called programmatically as part of a documentation generation pipeline, not as a one-off chat interaction. The typical integration point is a CI/CD workflow or a docs-platform backend that receives source code annotations, OpenAPI schemas, or protobuf definitions and produces structured type reference pages. The prompt expects a well-formed [INPUT] containing the raw type definition (interface, class, struct, or schema) and any available docstrings or annotations. The [OUTPUT_SCHEMA] placeholder should be replaced with a strict JSON schema that defines the exact structure you want: field name, type, description, required/optional, nullable, default value, enum members, and nested object relationships. Do not rely on the model to invent a consistent schema on its own—provide the target schema explicitly to ensure downstream consumers (static site generators, API reference renderers, IDE integrations) receive predictable output.

Wire the prompt into an application using a three-stage pipeline: generation, validation, and repair-or-escalate. In the generation stage, call the model with the prompt template and capture the raw output. In the validation stage, parse the output against your [OUTPUT_SCHEMA] using a JSON Schema validator. Common failures include missing required fields, incorrect enum value casing, and nested object flattening errors. If validation fails, invoke a repair prompt (from the Output Repair and Validation Prompts pillar) that provides the original input, the failed output, and the specific validation errors. Retry once. If the repair also fails, escalate to a human reviewer queue with the source type definition, both failed outputs, and the validation error log. For high-risk SDK surfaces (authentication, payments, data deletion), always require human approval before publishing, regardless of validation success.

Model choice matters here. Use a model with strong structured output capabilities and a large context window if your type definitions include deeply nested generics or extensive docstrings. For cost-sensitive pipelines processing hundreds of types, consider batching multiple type definitions into a single prompt call with clear delimiters, but be aware that larger batches increase the risk of field confusion between types. Log every generation attempt with the prompt version, model identifier, input hash, output hash, validation result, and reviewer decision. This audit trail is essential for debugging type reference drift when source code changes. Avoid wiring this prompt directly to a publish action—always insert a staging step where generated docs can be diffed against the previous version before going live.