Advanced TypeScript JSON Types: Inference, Generics, and Type Guards

Written and reviewed by the Jsonic editorial team — every guide is verified against the official spec or runtime before publication.

Last updated: May 19, 2025

Advanced TypeScript JSON typing goes beyond JSON.parse() returning any — satisfies, const assertions, template literal types, and recursive mapped types give you full compile-time safety for JSON structures. JSON.parse(text) as unknown followed by a Zod parse or manual type guard narrows unknown to your specific type without unsafe casting. const schema = { name: "string", age: 0 } as const with typeof schema derives the shape type from the literal value itself.

This guide covers the satisfies operator for JSON literals, recursive JSON value types, discriminated union parsing, template literal type paths, infer for JSON schema derivation, and ReturnType + Awaited for JSON API responses. Each pattern is shown with complete, runnable code and explained from the bottom up. Internal links connect to TypeScript JSON types for foundational concepts and safe JSON parsing TypeScript for parse-time safety patterns.

The satisfies Operator for JSON Literals

Introduced in TypeScript 4.9, satisfies validates that a value matches a type without widening the inferred type. This is exactly what JSON config objects need: you want TypeScript to check the shape, but you also want to keep the precise literal types for autocomplete and exhaustiveness checking.

Without satisfies, annotating const config: AppConfig = { theme: "dark" } widens theme to string. With satisfies, const config = { theme: "dark" } satisfies AppConfig keeps the type as the literal "dark" while still catching missing or extra fields at compile time. This matters for switch exhaustiveness on JSON enum fields.

type Theme = 'light' | 'dark' | 'system'
type AppConfig = { theme: Theme; locale: string; maxRetries: number }

// Without satisfies — theme is widened to string
const configA: AppConfig = { theme: 'dark', locale: 'en', maxRetries: 3 }
type ThemeA = typeof configA.theme  // string (widened)

// With satisfies — theme keeps its literal type
const configB = { theme: 'dark', locale: 'en', maxRetries: 3 } satisfies AppConfig
type ThemeB = typeof configB.theme  // 'dark' (preserved!)

// Enum-like JSON map — satisfies validates every key is covered
const LABELS = {
  light: 'Light mode',
  dark: 'Dark mode',
  system: 'System default',
} satisfies Record<Theme, string>
// TypeScript errors if you add a new Theme variant and forget a label

Recursive JSON Value Types

TypeScript has no built-in JSON type. Define a recursive JSONValue type that covers all valid JSON values: primitives, arrays, and objects. TypeScript has supported recursive type aliases since version 3.7.

The base definition handles all cases. From it you can derive JSONObject and JSONArray for narrower variables. DeepPartial<T> is a mapped type variant useful for partial JSON patches — every field becomes optional recursively. One limitation: the type allows circular object references at the type level, but JSON.stringify will throw at runtime if you pass one.

// Recursive JSON value type — covers all valid JSON
type JSONValue =
  | string
  | number
  | boolean
  | null
  | JSONValue[]
  | { [key: string]: JSONValue }

type JSONObject = { [key: string]: JSONValue }
type JSONArray = JSONValue[]

// DeepPartial — recursively optional fields (useful for PATCH payloads)
type DeepPartial<T> = T extends object
  ? { [K in keyof T]?: DeepPartial<T[K]> }
  : T

interface User { id: number; name: string; address: { city: string; zip: string } }
type UserPatch = DeepPartial<User>
// { id?: number; name?: string; address?: { city?: string; zip?: string } }

// Usage — any valid JSON value fits JSONValue
function logJson(value: JSONValue) {
  console.log(JSON.stringify(value, null, 2))
}
logJson({ users: [{ id: 1, active: true }], count: 1, cursor: null })

Type Guards and Narrowing for JSON

A type guard is a function whose return type is a type predicate (value is T). When called in an if condition, TypeScript narrows the variable to T inside the block. This is the safe alternative to as T casts for JSON parsed from unknown.

Write guards that check every field you rely on. Use Array.isArray for arrays and structural checks for objects. Prefer structural checks over instanceof for JSON objects — instanceof checks prototype chains, which plain JSON objects do not use. For discriminated unions, check the discriminant field first to select the right branch.

interface User { id: number; name: string; role: 'admin' | 'viewer' }

// Type predicate guard
function isUser(v: unknown): v is User {
  if (typeof v !== 'object' || v === null) return false
  const obj = v as Record<string, unknown>
  return (
    typeof obj.id === 'number' &&
    typeof obj.name === 'string' &&
    (obj.role === 'admin' || obj.role === 'viewer')
  )
}

// Usage with JSON.parse
const raw: unknown = JSON.parse(text)
if (isUser(raw)) {
  console.log(raw.name)  // TypeScript: raw is User here
  console.log(raw.role)  // 'admin' | 'viewer'
}

// Discriminated union guard — check the tag field first
type Shape =
  | { kind: 'circle'; radius: number }
  | { kind: 'rect'; width: number; height: number }

function isShape(v: unknown): v is Shape {
  if (typeof v !== 'object' || v === null) return false
  const obj = v as Record<string, unknown>
  if (obj.kind === 'circle') return typeof obj.radius === 'number'
  if (obj.kind === 'rect') return typeof obj.width === 'number' && typeof obj.height === 'number'
  return false
}

Discriminated Unions for JSON APIs

Discriminated unions model JSON API responses where a shared type or status field distinguishes between variants. TypeScript narrows each branch in a switch automatically. This pattern replaces fragile if (response.error) checks with exhaustive, compile-time-verified handling.

Add a default: never branch to make exhaustiveness checking explicit — if a new variant is added to the union but not handled, the never assignment becomes a type error. Use the Exclude utility to compute partial sets of variants. For APIs that mix success and error shapes at the top level, wrap the discriminated union in a JSON data validation layer at the API boundary.

// Discriminated union — 'type' field is the discriminant
type ApiResponse<T> =
  | { type: 'success'; data: T; requestId: string }
  | { type: 'error'; message: string; code: number }
  | { type: 'loading' }

function handleResponse<T>(res: ApiResponse<T>): T | null {
  switch (res.type) {
    case 'success':
      return res.data         // TypeScript: res is { type: 'success'; data: T; requestId: string }
    case 'error':
      console.error(res.message, res.code)
      return null
    case 'loading':
      return null
    default:
      // Exhaustiveness check — compile error if a new variant is not handled
      const _exhaustive: never = res
      return _exhaustive
  }
}

// Exclude utility — partial union subsets
type NonLoadingResponse<T> = Exclude<ApiResponse<T>, { type: 'loading' }>
// { type: 'success'; data: T; requestId: string } | { type: 'error'; message: string; code: number }

Template Literal Types for JSON Paths

Template literal types build string literal types by concatenating other string literal types. For JSON objects, this means you can derive all valid dotted-path strings at the type level, giving you autocomplete and type safety for generic get(obj, path) utilities.

The Path<T> utility recurses over object keys, building "key" and "key.subkey" strings. Pair it with PathValue<T, P> to get the value type at a given path — editors use both to autocomplete path arguments and infer return types. This is the same technique used by libraries like Lodash typings and React Hook Form.

// Template literal path type — recurse over object keys
type Path<T> = T extends object
  ? {
      [K in keyof T]: K extends string
        ? K | `${K}.${Path<T[K]>}`
        : never
    }[keyof T]
  : never

// Value type at a given path
type PathValue<T, P extends string> =
  P extends `${infer K}.${infer Rest}`
    ? K extends keyof T
      ? PathValue<T[K], Rest>
      : never
    : P extends keyof T
    ? T[P]
    : never

interface User {
  id: number
  name: string
  address: { city: string; country: string }
}

type UserPath = Path<User>
// 'id' | 'name' | 'address' | 'address.city' | 'address.country'

type CityType = PathValue<User, 'address.city'>  // string

// Generic get utility using both
function get<T, P extends Path<T>>(obj: T, path: P): PathValue<T, P> {
  return path.split('.').reduce((acc: unknown, key) => (acc as Record<string, unknown>)[key], obj) as PathValue<T, P>
}

const user: User = { id: 1, name: 'Alice', address: { city: 'NYC', country: 'US' } }
const city = get(user, 'address.city')  // typed as string, autocomplete shows all valid paths

Inferring Types from Zod Schemas

z.infer<typeof schema> extracts the TypeScript type that a Zod schema validates. Define the schema once — you get both runtime validation and a compile-time type with no duplication. This schema-first approach ensures the two never drift apart.

z.output gives the type after transformations (e.g., after .transform() converts a string to a Date), while z.input gives the type before — useful when the raw JSON shape differs from the processed shape. See JSON Schema patterns for schema-first design patterns.

import { z } from 'zod'

// Schema-first: define once, get type for free
const UserSchema = z.object({
  id: z.number().int().positive(),
  name: z.string().min(1).max(200),
  email: z.string().email(),
  role: z.enum(['admin', 'editor', 'viewer']),
  // Transform ISO string to Date — z.input is string, z.output is Date
  createdAt: z.string().datetime().transform(s => new Date(s)),
})

// Infer types
type User = z.infer<typeof UserSchema>       // output type (Date for createdAt)
type UserInput = z.input<typeof UserSchema>  // input type (string for createdAt)

// safeParse — no try/catch needed
const result = UserSchema.safeParse(JSON.parse(text))
if (result.success) {
  const user = result.data            // typed as User
  console.log(user.createdAt)         // Date object — transformed!
} else {
  result.error.issues.forEach(issue =>
    console.error(issue.path.join('.'), issue.message)
  )
}

// Compose schemas — reuse across routes
const CreateUserSchema = UserSchema.omit({ id: true, createdAt: true })
const UpdateUserSchema = UserSchema.partial().required({ id: true })
type CreateUserInput = z.infer<typeof CreateUserSchema>

ReturnType and Awaited for API Responses

ReturnType<typeof fn> extracts the return type of a function. Awaited<T> unwraps Promise<T> to T. Combined, Awaited<ReturnType<typeof fetchUser>> gives you the resolved JSON type of any async fetch function — without duplicating the type annotation.

Build a generic fetch wrapper that accepts a Zod schema and returns validated, typed JSON. The wrapper handles HTTP errors, JSON parsing, and Zod validation in one place. Every call site gets full type inference. An error union at the return type level makes both success and failure cases first-class, eliminating thrown exceptions in favor of return values.

import { z } from 'zod'

// Generic fetch wrapper with Zod validation
async function fetchValidated<T>(
  schema: z.ZodType<T>,
  url: string,
  init?: RequestInit
): Promise<{ ok: true; data: T } | { ok: false; error: string }> {
  try {
    const res = await fetch(url, {
      headers: { Accept: 'application/json', ...init?.headers },
      ...init,
    })
    if (!res.ok) return { ok: false, error: `HTTP ${res.status}: ${res.statusText}` }
    const raw = await res.json()
    const parsed = schema.safeParse(raw)
    if (!parsed.success) return { ok: false, error: parsed.error.issues[0].message }
    return { ok: true, data: parsed.data }
  } catch (e) {
    return { ok: false, error: e instanceof Error ? e.message : 'Unknown error' }
  }
}

// ReturnType + Awaited to extract the type without annotation
async function fetchUser(id: number) {
  return fetchValidated(UserSchema, `/api/users/${id}`)
}

type FetchUserResult = Awaited<ReturnType<typeof fetchUser>>
// { ok: true; data: User } | { ok: false; error: string }

// Usage — discriminated union handles both cases
const result = await fetchUser(1)
if (result.ok) {
  console.log(result.data.name)   // typed as User
} else {
  console.error(result.error)     // typed as string
}

Definitions

Type guard

A function with return type value is T that narrows the type of a variable inside an if block. Enables safe use of unknown values from JSON without unsafe casts.

Discriminated union

A union type where each member has a shared literal field (the discriminant). TypeScript narrows each branch in a switch or if automatically, enabling exhaustive, type-safe handling of JSON API response variants.

Satisfies operator

TypeScript 4.9+ syntax (expr satisfies Type) that checks an expression against a type without widening the inferred type. Use for JSON config literals and enum maps to keep precise literal types while still catching shape errors.

Template literal type

A type that builds a new string literal type by embedding other string literal types inside a template expression: {"`${Prefix}.${Suffix}`"}. Used to derive all valid dotted JSON paths from an object type.

Recursive type

A type alias that references itself, enabling types for tree-structured or arbitrarily nested data. type JSONValue = ... | JSONValue[] | { [key: string]: JSONValue } is the canonical recursive JSON type.

Type predicate

The return type annotation of a type guard function: value is T. Tells TypeScript to narrow the variable to T in the truthy branch of the calling if statement.

Const assertion

The as const suffix on a literal value that makes all properties readonly and narrows all values to their exact literal types. Combined with typeof, it lets you derive a type from a JSON literal value.

FAQ