Output Formats

sparktype can generate type definitions in multiple languages and schema libraries from the same OpenAPI specification.

Supported Formats

Format	Language	Description
typescript	TypeScript	Native interfaces and type aliases
zod	TypeScript	Zod schema definitions for runtime validation
python	Python	TypedDict classes with type hints
go	Go	Struct definitions with JSON tags

Choosing a Format

TypeScript

Best for:

• Frontend applications using TypeScript
• Type-only imports (no runtime overhead)
• Maximum IDE support

{
  "format": "typescript",
  "options": {
    "exportType": "interface"
  }
}

Zod

Best for:

• Runtime validation of API responses
• Form validation
• Data parsing with transformations

{
  "format": "zod",
  "options": {
    "inferTypes": true
  }
}

Python

Best for:

• FastAPI or Flask backends
• Type checking with mypy/pyright
• Python 3.10+ projects

{
  "format": "python"
}

Go

Best for:

• Go microservices
• API clients in Go
• Backend services

{
  "format": "go",
  "options": {
    "package": "types"
  }
}

Multiple Formats

Generate multiple formats from the same spec:

{
  "specs": {
    "api": { "path": "./openapi.yaml" }
  },
  "outputs": [
    {
      "path": "./frontend/src/types/api.ts",
      "format": "typescript",
      "contents": ["api:*"]
    },
    {
      "path": "./frontend/src/schemas/api.ts",
      "format": "zod",
      "contents": ["api:*"],
      "options": { "inferTypes": true }
    },
    {
      "path": "./backend/types/api.py",
      "format": "python",
      "contents": ["api:*"]
    },
    {
      "path": "./services/types/api.go",
      "format": "go",
      "contents": ["api:*"],
      "options": { "package": "types" }
    }
  ]
}

Global Options

These options affect all formats:

Option	Effect
generateEnums	Use native enums vs union types
nullableHandling	How nullable fields are represented
dereferenceRefs	Inline references vs named types

See Options for details.

Generated File Header

All generated files include a header comment:

// Generated by an automated build step. Do not edit.

Or in Python:

# Generated by an automated build step. Do not edit.

This helps identify generated files and prevents accidental manual edits.

Next Steps

• TypeScript - Interface and type generation
• Zod - Schema generation with runtime validation
• Python - TypedDict generation
• Go - Struct generation