Schema Universal Converter

Convert between JSON Schema, TypeScript, Zod, OpenAPI, GraphQL, and more. Maintain schema consistency across your entire stack.

🎯 What It Does

Schema Universal Converter transforms schema definitions between popular formats used across modern development stacks. Stop manually rewriting types - convert once, use everywhere.

Perfect for:

• Full-Stack Developers: Keep frontend types in sync with backend schemas
• API Developers: Generate TypeScript clients from OpenAPI specs
• Data Engineers: Convert between data validation formats
• Platform Teams: Maintain schema consistency across microservices

✨ Key Features

🔄 Supported Formats

• JSON Schema (Draft 7) - Industry standard schema definition
• TypeScript - Generate type-safe interfaces and types
• Zod - Runtime validation with type inference
• OpenAPI 3.0 - REST API documentation standard
• GraphQL SDL - Schema Definition Language for GraphQL APIs

⚡ Powerful Conversions

• Bidirectional: Convert between any supported formats
• Type-Safe: Generated code includes full type information
• Customizable: Control output style, strictness, and formatting
• Validated: Optional schema validation before conversion
• Examples: Auto-generate example data matching your schema

🎨 Customization Options

• TypeScript: Banner comments, code style (semi, quotes), strictness
• Zod: Strict mode, error messages, custom descriptions
• OpenAPI: Version selection, example generation
• GraphQL: Description inclusion, nullable arrays

🚀 Use Cases

Use Case 1: API Client Generation

Problem: Your backend has an OpenAPI spec, need TypeScript types for frontend

{
  "sourceFormat": "openapi",
  "targetFormats": ["typescript", "zod"],
  "schemaSource": "url",
  "schemaInput": "https://api.example.com/openapi.json",
  "conversionOptions": {
    "typescript": {
      "bannerComment": "/* Auto-generated from OpenAPI - Do not edit */",
      "style": {
        "semi": false,
        "singleQuote": true
      }
    },
    "zod": {
      "strict": true,
      "errorMessages": true
    }
  }
}

Result: TypeScript interfaces + Zod validators ready to use in your React/Vue app

Use Case 2: Database Schema to API Types

Problem: Have JSON Schema for database validation, need GraphQL types

{
  "sourceFormat": "json-schema",
  "targetFormats": ["graphql", "typescript"],
  "schemaSource": "direct",
  "schemaInput": "{\"type\":\"object\",\"properties\":{\"id\":{\"type\":\"string\",\"format\":\"uuid\"},\"name\":{\"type\":\"string\"},\"email\":{\"type\":\"string\",\"format\":\"email\"},\"age\":{\"type\":\"integer\",\"minimum\":0}},\"required\":[\"id\",\"name\",\"email\"]}",
  "validateSchema": true
}

Result: GraphQL schema + TypeScript types with proper validation rules

Use Case 3: Runtime Validation Layer

Problem: Have TypeScript types, need runtime validation with Zod

Note: Currently best to start with JSON Schema as source

{
  "sourceFormat": "json-schema",
  "targetFormats": ["zod", "typescript"],
  "schemaSource": "url",
  "schemaInput": "https://raw.githubusercontent.com/your-repo/schemas/user.schema.json",
  "conversionOptions": {
    "zod": {
      "strict": false,
      "errorMessages": true
    }
  },
  "generateExamples": true
}

Result: Zod schema for API validation + TypeScript types + Example data

📥 Input Configuration

Required Fields

• sourceFormat (string): Format of input schema

  • Options: json-schema, typescript, zod, openapi, graphql, protobuf, avro
  • Note: Full support for json-schema and openapi as source. Others planned.

• targetFormats (array): Output formats to generate

  • Array of: json-schema, typescript, zod, openapi, graphql
  • Example: ["typescript", "zod", "graphql"]

• schemaSource (string): How to load the schema

  • direct - Paste schema directly
  • url - Fetch from URL
  • file - Load from file path (not supported in Actor environment)

• schemaInput (string): The actual schema content, URL, or file path

Optional Fields

• conversionOptions (object): Customize output

  {
    "typescript": {
      "bannerComment": "/* Generated types */",
      "style": {
        "semi": true,
        "singleQuote": true
      },
      "strictIndexSignatures": false
    },
    "zod": {
      "strict": true,
      "errorMessages": true
    },
    "openapi": {
      "version": "3.0.0",
      "includeExamples": true
    },
    "graphql": {
      "includeDescriptions": true,
      "nullableArrayItems": false
    }
  }
  

• validateSchema (boolean): Validate source schema before conversion (default: true)

• generateExamples (boolean): Generate example data conforming to schema (default: false)

📤 Output Data

Conversion Result Format

{
  "sourceFormat": "json-schema",
  "targetFormat": "typescript",
  "output": "export interface RootSchema {\n  name: string;\n  age: number;\n}\n",
  "valid": true,
  "metadata": {
    "typeCount": 1,
    "complexity": "simple",
    "size": 67
  }
}

Key-Value Store Outputs

• typescript_output - Generated TypeScript code
• zod_output - Generated Zod schema
• openapi_output - Generated OpenAPI document
• graphql_output - Generated GraphQL SDL
• conversion_summary - Summary of all conversions

Example Data Output (if generateExamples: true)

{
  "sourceFormat": "json-schema",
  "targetFormat": "json-schema",
  "output": "{\n  \"name\": \"example string\",\n  \"email\": \"user@example.com\",\n  \"age\": 42\n}",
  "valid": true
}

🔄 Conversion Matrix

From ↓ / To →	JSON Schema	TypeScript	Zod	OpenAPI	GraphQL
JSON Schema	✅	✅	✅	✅	✅
OpenAPI	✅	✅	✅	✅	✅
TypeScript	🚧	✅	🚧	🚧	🚧
Zod	🚧	🚧	✅	🚧	🚧
GraphQL	🚧	🚧	🚧	🚧	✅

✅ = Fully supported | 🚧 = Planned

Current Recommendation: Use JSON Schema or OpenAPI as source format for maximum compatibility.

💡 Best Practices

Schema Organization

• Single Source of Truth: Choose one format as your source (recommend JSON Schema)
• Version Control: Store schemas in git alongside code
• Documentation: Use descriptions in schemas - they carry over to outputs

Conversion Strategy

• Development Workflow: JSON Schema → TypeScript + Zod
• API Documentation: OpenAPI → TypeScript + GraphQL
• Data Validation: JSON Schema → Zod + Examples

Code Generation

• CI/CD Integration: Run converter in build pipeline
• Git Ignore Generated Files: Or commit with clear banner comments
• Type Safety: Always generate both types and validators together

🛠 Technical Details

Type Mapping

JSON Schema	TypeScript	Zod	GraphQL
string	string	z.string()	String
number	number	z.number()	Float
integer	number	z.number().int()	Int
boolean	boolean	z.boolean()	Boolean
array	T[]	z.array(T)	[T]
object	interface {}	z.object({})	type {}
enum	enum / union	z.enum([])	enum
null	null	z.null()	n/a

Format Support

JSON Schema format values:

• email → TypeScript: string / Zod: .email() / GraphQL: String
• url → TypeScript: string / Zod: .url() / GraphQL: String
• uuid → TypeScript: string / Zod: .uuid() / GraphQL: String
• date-time → TypeScript: string / Zod: .coerce.date() / GraphQL: DateTime

Validation

Uses Ajv for JSON Schema validation:

• Draft 7 support
• Custom formats
• Detailed error messages

📊 Example Outputs

Input JSON Schema

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "User's full name"
    },
    "email": {
      "type": "string",
      "format": "email"
    },
    "age": {
      "type": "integer",
      "minimum": 0,
      "maximum": 120
    },
    "roles": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": ["admin", "user", "guest"]
      }
    }
  },
  "required": ["name", "email"]
}

Generated TypeScript

/* Auto-generated types */

export interface RootSchema {
  /**
   * User's full name
   */
  name: string;
  email: string;
  age?: number;
  roles?: ("admin" | "user" | "guest")[];
}

Generated Zod

import { z } from "zod";

export const schema = z.object({
  name: z.string().describe("User's full name"),
  email: z.string().email(),
  age: z.number().int().min(0).max(120).optional(),
  roles: z.array(z.enum(["admin", "user", "guest"])).optional()
}).strict();

export type Schema = z.infer<typeof schema>;

Generated GraphQL

# Auto-generated GraphQL schema

scalar DateTime
scalar JSON

"""User's full name"""
type RootType {
  """User's full name"""
  name: String!
  email: String!
  age: Int
  roles: [String]
}

🔄 Integration Workflows

GitHub Actions CI/CD

name: Generate Types
on: [push]
jobs:
  generate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Run Schema Converter
        uses: apify/apify-actor-action@v1
        with:
          actor-id: YOUR_ACTOR_ID
          input: |
            {
              "sourceFormat": "json-schema",
              "targetFormats": ["typescript", "zod"],
              "schemaSource": "url",
              "schemaInput": "https://raw.githubusercontent.com/${{ github.repository }}/main/schema.json"
            }
      - name: Download generated types
        run: |
          # Download from Apify dataset/key-value store
          # Commit to repo if needed

Pre-commit Hook

#!/bin/bash
# .git/hooks/pre-commit

# Run converter on schema changes
if git diff --cached --name-only | grep -q "schema.json"; then
  echo "Schema changed, regenerating types..."
  # Call Apify API to run converter
  # Update generated files
fi

🚨 Troubleshooting

Invalid Schema Error

• Check JSON syntax (use JSONLint)
• Ensure schema follows JSON Schema Draft 7
• Enable validateSchema option to see detailed errors

Conversion Failed

• Some complex schemas may not convert perfectly
• Review error messages in output
• Simplify schema or split into multiple conversions

Missing Types

• Ensure all referenced schemas are included
• Use $ref carefully - may need resolution first
• Check that source format is fully supported

📈 Roadmap

Planned Features

• Bidirectional TS/Zod: Parse TypeScript and Zod as source formats
• Protobuf Support: Convert to/from Protocol Buffers
• Avro Support: Apache Avro schema conversion
• Schema Merging: Combine multiple schemas
• Diff Generation: Compare schema versions
• Migration Scripts: Generate upgrade paths between versions

Community Requests

• JSON Schema Draft 2020-12 support
• Custom template engines
• Plugin system for custom converters

🤝 Contributing

Love schema conversions? Help us improve:

• Test with your real-world schemas
• Report edge cases or bugs
• Suggest new format conversions
• Contribute converter implementations

📄 License

MIT License - use freely in your projects!

🏆 Apify $1M Challenge

Built for developers tired of manually maintaining types across formats. Help us reach more developers:

• Star the repository
• Share with your team
• Provide feedback on conversions
• Suggest new formats to support

---

One schema, infinite formats 🔄