OpenAPI Spec to TypeScript Type Definition Prompt Template

This prompt is designed for frontend engineers who need to generate TypeScript type definitions—interfaces, type aliases, and type guard functions—directly from OpenAPI 3.0 or 3.1 component schemas. The core job-to-be-done is eliminating manual, error-prone translation of API contracts into TypeScript types. Instead of reading a spec and typing out interfaces by hand, you provide a valid OpenAPI schema fragment, and the prompt produces compilable TypeScript that accurately reflects the source spec's nullability, enum literals, optionality, and polymorphic structures like oneOf/anyOf with discriminator fields. The ideal user is a product engineer consuming internal or external APIs who needs type safety at compile time without introducing a heavy code generation pipeline. Required context includes the raw OpenAPI component schemas (typically the #/components/schemas block) and any project-specific conventions, such as a prefix for generated type names or a preference for interface over type.

This prompt is scoped strictly to type-level constructs. It produces TypeScript that can be checked by tsc and used for autocompletion, parameter validation in IDEs, and compile-time safety. It does not generate runtime validation logic (e.g., Zod schemas, class-validator decorators), full API client classes with fetch wrappers, or human-readable documentation. If you need runtime request/response validation that executes in the browser or Node.js, pair this prompt's output with a schema-to-validator tool or a separate prompt designed for runtime code generation. The prompt assumes the input spec is structurally valid; it will not fix malformed $ref targets, missing type fields, or circular references that would produce nonsensical TypeScript. Pre-process your spec fragment with an OpenAPI validator before feeding it to this prompt to avoid garbage-in, garbage-out failures.

Before using this prompt, confirm that you have the exact component schemas you need—not the full spec with paths and servers unless you intend to filter them out first. If your goal is to generate types for request bodies, response objects, and parameters across all endpoints, you may need a broader code generation tool or a multi-step workflow. This prompt excels at focused schema-to-type conversion where you control exactly which schemas enter the context window. After generating the types, always run the output through tsc --noEmit and spot-check discriminated unions and enum fields against the source spec. If the output fails compilation or misrepresents a nullable field, adjust the prompt's [CONSTRAINTS] block to add explicit rules before regenerating.

This prompt template converts OpenAPI component schemas into production-ready TypeScript type definitions. It is designed for frontend engineers who need accurate interfaces, type guards, and discriminated unions that mirror the source spec exactly. The template handles nullability, enum literals, optional properties, and polymorphic structures. Before using it, ensure you have extracted the relevant schema object from your OpenAPI spec—this prompt works best with a single component schema or a focused set of related schemas, not an entire multi-thousand-line spec file dumped in at once.

codeCopy
You are a TypeScript type definition generator. Your task is to convert an OpenAPI component schema into accurate, production-ready TypeScript type definitions.

## INPUT

OpenAPI Schema:
```json
[OPENAPI_SCHEMA_JSON]

Additional context about how these types will be used: [USAGE_CONTEXT]

CONSTRAINTS

• Generate only TypeScript type and interface definitions. Do not include runtime code, API clients, or fetch logic.
• Preserve exact nullability from the schema: nullable: true becomes | null, absent nullable means required unless in a required array context.
• Convert enum arrays into TypeScript string literal unions or const assertions.
• For oneOf, anyOf, and allOf with a discriminator, generate discriminated unions with a shared discriminant property.
• Mark properties as optional (?) when the property is not listed in the parent schema's required array.
• Use readonly for properties marked readOnly: true in the schema.
• For additionalProperties, generate an index signature [key: string]: ValueType.
• Include JSDoc comments for each type and property using the description field from the schema.
• If the schema contains $ref references to other component schemas, generate placeholder type references with a comment indicating the expected import path.
• Do not use the any type unless the schema explicitly has no type constraint.
• Prefer unknown over any for untyped schema nodes.

OUTPUT FORMAT

Return only the TypeScript code inside a single fenced code block labeled typescript. Do not include explanations, summaries, or markdown outside the code block.

EXAMPLES

Input Schema:

jsonCopy
{
  "type": "object",
  "required": ["id", "status"],
  "properties": {
    "id": { "type": "string", "description": "Unique identifier" },
    "status": { "type": "string", "enum": ["active", "inactive", "pending"] },
    "label": { "type": "string", "nullable": true }
  }
}

Expected Output:

typescriptCopy
/** Represents the resource. */
export interface Resource {
  /** Unique identifier */
  id: string;
  status: "active" | "inactive" | "pending";
  label: string | null;
}

RISK_LEVEL

[RISK_LEVEL: low | medium | high]

If RISK_LEVEL is high, add a comment at the top of the output: // WARNING: Generated types for high-risk schema. Manual review required before production use.

After pasting this template, replace the square-bracket placeholders with your actual values. [OPENAPI_SCHEMA_JSON] should contain the raw JSON of a single component schema or a small set of related schemas—avoid pasting an entire spec file, as this degrades accuracy on large documents. [USAGE_CONTEXT] is optional but recommended: describe whether these types will be used in a React component, a data-fetching layer, or a shared package, as this helps the model choose appropriate export patterns and naming conventions. [RISK_LEVEL] should be set to high if the schema governs authentication, payments, PII, or compliance-sensitive data; otherwise use medium or low. For high-risk schemas, always run the generated types through a TypeScript compiler check and a manual review against the source spec before merging.

The output is a single TypeScript code block. Copy it into a .ts file and run tsc --noEmit to verify compilation. For schemas with $ref references, the model will generate placeholder imports—replace these with your actual import paths. If the schema uses oneOf with a discriminator, verify that the generated discriminated union correctly narrows on the discriminant property by writing a quick type-narrowing test. Do not ship these types without at least one round-trip check: deserialize a sample JSON response into the generated type and confirm no properties are lost or mistyped.

This prompt is designed to be called programmatically, not used in a one-off chat. The typical harness reads an OpenAPI spec file, extracts the components.schemas block, injects it into the prompt's [OPENAPI_COMPONENT_SCHEMAS] placeholder, and sends the request to a capable code-generation model. The output is raw TypeScript that must pass through a compilation check before it ever reaches a developer's IDE. Treat the generated types as a build artifact: they should be written to a file, compiled with tsc --noEmit, and only merged into the codebase if the compilation succeeds and the type surface matches the source spec's structure.

The harness should enforce a strict validation pipeline. After the model returns, strip any markdown fences from the response and write the result to a temporary .ts file. Run tsc --noEmit --strict against it. If compilation fails, capture the error messages and feed them back into a retry prompt that includes the original schema, the failed output, and the compiler errors. Limit retries to two attempts before flagging the generation for human review. For high-stakes API surfaces, add a structural conformance check: parse the generated TypeScript AST and verify that every $ref target in the source spec has a corresponding exported type or interface, that enum values match exactly, and that nullable: true fields produce | null unions rather than optional properties.

Model choice matters here. Use a model with strong code generation performance and long-context handling if your spec is large. For specs exceeding the model's context window, split components.schemas into batches of related schemas, generate types per batch, and then run a merge pass that resolves cross-references. Log every generation attempt—input hash, model version, compilation result, and diff against the previous generated file—so you can trace regressions when the prompt or model changes. Never ship generated types without compilation and a diff review against the prior version.