Safe JSON Parsing in TypeScript: unknown Type, Type Guards, and Zod

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

Last updated: May 19, 2026

TypeScript's type system stops at runtime boundaries. JSON.parse() returns any — TypeScript trusts whatever you claim the value is. This guide covers the patterns that make JSON parsing genuinely type-safe: from the unknown type to custom type guards to Zod runtime validation.

The Problem: JSON.parse Returns any

// Dangerous: TypeScript trusts you but won't verify at runtime
const data = JSON.parse('{"name":"Ada"}') as User

// This compiles but crashes at runtime if shape is wrong:
console.log(data.email.toUpperCase())  // TypeError: Cannot read properties of undefined

// TypeScript 4.1+ with strict: true makes this slightly safer with
// return type widening, but JSON.parse() is still any

Approach 1: unknown + Type Guard

Assign the result to unknown, then narrow it with a type guard function before accessing properties.

interface User {
  id: string
  email: string
  name: string
  age?: number
}

function isUser(value: unknown): value is User {
  if (typeof value !== 'object' || value === null) return false
  const obj = value as Record<string, unknown>
  return (
    typeof obj.id === 'string' &&
    typeof obj.email === 'string' &&
    typeof obj.name === 'string' &&
    (obj.age === undefined || typeof obj.age === 'number')
  )
}

// Safe parsing
function parseUser(json: string): User | null {
  try {
    const parsed: unknown = JSON.parse(json)
    return isUser(parsed) ? parsed : null
  } catch {
    return null  // malformed JSON
  }
}

const user = parseUser('{"id":"1","email":"ada@example.com","name":"Ada"}')
if (user) {
  console.log(user.email.toUpperCase())  // TypeScript knows this is string
}

The value is User return type is the type predicate — TypeScript uses it to narrow the type inside an if (isUser(x)) block. The function must correctly verify all required fields; TypeScript cannot check whether the guard is accurate.

Approach 2: Zod (Recommended)

Zod generates TypeScript types from schemas and validates data at runtime. One source of truth for both the type and the validation logic.

import { z } from 'zod'

const UserSchema = z.object({
  id:    z.string(),
  email: z.string().email(),
  name:  z.string().min(1),
  age:   z.number().int().positive().optional(),
})

// Infer TypeScript type from schema — no duplicate definition
type User = z.infer<typeof UserSchema>

// parse() throws ZodError on invalid data
function parseUser(json: string): User {
  const parsed: unknown = JSON.parse(json)  // may throw SyntaxError
  return UserSchema.parse(parsed)            // may throw ZodError
}

// safeParse() never throws — returns { success, data } | { success, error }
function tryParseUser(json: string):
  | { success: true; data: User }
  | { success: false; error: string } {
  try {
    const parsed: unknown = JSON.parse(json)
    const result = UserSchema.safeParse(parsed)
    if (result.success) {
      return { success: true, data: result.data }
    }
    return { success: false, error: result.error.message }
  } catch (e) {
    return { success: false, error: 'Invalid JSON' }
  }
}

Zod Error Details

const result = UserSchema.safeParse({ id: 1, email: 'not-an-email' })
if (!result.success) {
  // flatten() gives { fieldErrors: {...}, formErrors: [...] }
  console.log(result.error.flatten())
  // {
  //   fieldErrors: {
  //     id: ['Expected string, received number'],
  //     email: ['Invalid email'],
  //     name: ['Required']
  //   },
  //   formErrors: []
  // }
}

Wrapping JSON.parse Errors

// TypeScript 4.0+: caught errors are unknown by default (with strict config)
// useUnknownInCatchVariables: true in tsconfig.json

function safeParse(text: string): unknown {
  try {
    return JSON.parse(text)
  } catch (e) {
    // e is unknown — must narrow before accessing .message
    const message = e instanceof Error ? e.message : String(e)
    throw new Error(`JSON parse failed: ${message}`)
  }
}

// Or return null on failure
function tryParse(text: string): unknown | null {
  try { return JSON.parse(text) }
  catch { return null }
}

// Or return a Result type
type ParseResult<T> =
  | { ok: true;  value: T }
  | { ok: false; error: Error }

function parseResult<T>(
  schema: z.ZodSchema<T>,
  text: string
): ParseResult<T> {
  try {
    const value = schema.parse(JSON.parse(text))
    return { ok: true, value }
  } catch (e) {
    return { ok: false, error: e instanceof Error ? e : new Error(String(e)) }
  }
}

Safe Fetch + JSON Validation

import { z } from 'zod'

const PostSchema = z.object({
  id:    z.number(),
  title: z.string(),
  body:  z.string(),
  userId: z.number(),
})

const PostListSchema = z.array(PostSchema)

async function fetchPosts(): Promise<z.infer<typeof PostListSchema>> {
  const res = await fetch('https://jsonplaceholder.typicode.com/posts')
  if (!res.ok) {
    throw new Error(`HTTP ${res.status}: ${res.statusText}`)
  }
  const raw: unknown = await res.json()
  return PostListSchema.parse(raw)  // throws if API shape changed
}

// Non-throwing version
async function tryFetchPosts() {
  const res = await fetch('/api/posts')
  if (!res.ok) return null
  const raw: unknown = await res.json()
  const result = PostListSchema.safeParse(raw)
  return result.success ? result.data : null
}

TypeScript tsconfig Best Practices

// tsconfig.json — enable all strict checks
{
  "compilerOptions": {
    "strict": true,                         // enables all strict family flags
    "useUnknownInCatchVariables": true,     // catch(e) → e: unknown
    "noImplicitAny": true,                  // disallow implicit any
    "strictNullChecks": true,               // null/undefined must be handled
    "exactOptionalPropertyTypes": true      // optional ≠ undefined-assignable
  }
}
// With strict: true, TypeScript catches more unsafe patterns at compile time
// but JSON.parse() still returns any — runtime validation is always needed

Comparison: Type Guard vs Zod vs ArkType

FAQ