YAML to TypeScript Generator

YAML to TypeScript: Typing Configuration Files and API Specs

YAML is everywhere in modern development — Kubernetes manifests, GitHub Actions workflows, Docker Compose files, OpenAPI specs, and application config. Most projects read these files at runtime with no type safety at all. Generating TypeScript interfaces from your YAML gives you autocomplete, refactoring support, and compile-time checks on the values your app depends on.

When YAML-to-TypeScript Actually Helps

Not every YAML file needs TypeScript types. The cases where it pays off most:

• App configuration loaded at startup (feature flags, database URLs, service endpoints) — validate the shape before the app runs
• GitHub Actions / CI configs that you generate or template programmatically
• OpenAPI specs where you want typed request/response objects without a full codegen pipeline
• Kubernetes manifests when writing a deployment tool or operator in TypeScript

Application Config Example

# config.yaml
server:
  port: 8080
  host: "0.0.0.0"
  tls: false

database:
  url: "postgres://localhost/myapp"
  pool_size: 10
  ssl: true

features:
  new_dashboard: false
  beta_api: true

allowed_origins:
  - "https://app.example.com"
  - "https://staging.example.com"

// Generated TypeScript
export interface AppConfig {
  server: {
    port:   number;
    host:   string;
    tls:    boolean;
  };
  database: {
    url:       string;
    pool_size: number;
    ssl:       boolean;
  };
  features: {
    new_dashboard: boolean;
    beta_api:      boolean;
  };
  allowed_origins: string[];
}

Validating Config at Startup with Zod

A TypeScript interface alone won't catch a missing environment variable or a misconfigured YAML at startup. Pair the generated type with a Zod schema to validate before the app serves any requests:

import { z } from 'zod';
import { readFileSync } from 'fs';
import { parse } from 'js-yaml';

const AppConfigSchema = z.object({
  server: z.object({
    port: z.number().int().min(1).max(65535),
    host: z.string(),
    tls:  z.boolean(),
  }),
  database: z.object({
    url:       z.string().url(),
    pool_size: z.number().int().positive(),
    ssl:       z.boolean(),
  }),
  features: z.object({
    new_dashboard: z.boolean(),
    beta_api:      z.boolean(),
  }),
  allowed_origins: z.array(z.string().url()),
});

export type AppConfig = z.infer<typeof AppConfigSchema>;

export function loadConfig(path: string): AppConfig {
  const raw = parse(readFileSync(path, 'utf8'));
  // Throws a detailed ZodError if any field is missing or wrong type
  return AppConfigSchema.parse(raw);
}

GitHub Actions Workflow Types

When generating or validating GitHub Actions configs programmatically, having the shape typed prevents silent mistakes:

# .github/workflows/deploy.yml  (partial)
name: Deploy
on:
  push:
    branches: [main]
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Build
        run: npm ci && npm run build

// Generated types for programmatic workflow generation
export interface WorkflowTrigger {
  push?: { branches: string[] };
  pull_request?: { branches: string[] };
  workflow_dispatch?: Record<string, unknown>;
}

export interface WorkflowJob {
  'runs-on': string;
  steps: Array<{
    uses?: string;
    name?: string;
    run?: string;
    with?: Record<string, string | number | boolean>;
    env?: Record<string, string>;
  }>;
}

export interface GitHubWorkflow {
  name: string;
  on: WorkflowTrigger;
  jobs: Record<string, WorkflowJob>;
}

Kubernetes Manifest Types

// Partial typing for a Kubernetes Deployment manifest
export interface K8sDeployment {
  apiVersion: 'apps/v1';
  kind: 'Deployment';
  metadata: {
    name:      string;
    namespace?: string;
    labels?:   Record<string, string>;
  };
  spec: {
    replicas: number;
    selector: {
      matchLabels: Record<string, string>;
    };
    template: {
      metadata: { labels: Record<string, string> };
      spec: {
        containers: Array<{
          name:  string;
          image: string;
          ports?: Array<{ containerPort: number }>;
          env?:   Array<{ name: string; value?: string; valueFrom?: unknown }>;
          resources?: {
            requests?: { cpu?: string; memory?: string };
            limits?:   { cpu?: string; memory?: string };
          };
        }>;
      };
    };
  };
}

Handling Optional vs Required Fields

YAML fields that are sometimes absent need careful handling. Don't mark everything optional — that forces null checks everywhere. Be deliberate:

// If a field is always present → required
// If a field may be absent but has a sensible default → optional with default in Zod
// If a field is genuinely optional with no default → optional union

const ServiceConfigSchema = z.object({
  name:     z.string(),
  port:     z.number().int().default(3000),           // default if absent
  timeout:  z.number().optional(),                     // truly optional
  replicas: z.number().int().min(1).max(10).default(1),
});

Common Pitfalls

• YAML type coercion: YAML auto-converts unquoted true, false, yes, no, on, off to booleans, and bare numbers to number. This can surprise you with values like port numbers typed as strings.
• Multiline strings: YAML block scalars (| and >) produce strings with different whitespace handling. Always type them as string but test that the value after parsing matches what you expect.
• Anchors and aliases: YAML &anchor / *alias let you reuse values. Most parsers resolve these before you see the data, so they don't affect the TypeScript type — but the type reflects the merged shape, not the anchor definition.
• Number precision: Large integers in YAML (like Kubernetes resource quantities) may be parsed as floats. Use z.coerce.string() for values like memory: 512Mi that look numeric but should stay as strings.

FAQ

Q: Should I type the YAML file itself, or the parsed JavaScript object?
A: Type the parsed JavaScript object — that's what your code actually works with. The YAML file is just a serialization format. Validate the parsed object with Zod at the boundary (file load time) and trust the types everywhere else.

Q: How do I handle YAML with dynamic keys (like environment variables maps)?
A: Use Record<string, string> for maps with arbitrary string keys, or z.record(z.string(), z.string()) in Zod. If the keys are a known set, use an explicit interface instead for stronger safety.

Q: My OpenAPI YAML is huge — should I type the whole spec?
A: Don't type the raw spec object; type the request/response bodies instead. Tools like openapi-typescript generate types from OpenAPI specs automatically and produce clean per-endpoint types without manual YAML-to-TypeScript conversion.

Q: Can I use these types at runtime, or are they only for development?
A: TypeScript types are erased at runtime. For runtime safety, generate a Zod schema from the same source and use it to parse the YAML. The TypeScript type you derive from Zod keeps compile-time and runtime validation in sync with a single definition.