# Type-Safe JSON in TypeScript: Parsing, Typing, and Runtime Validation
JSON serves as TypeScript's primary data exchange format, bridging the gap between JavaScript's dynamic runtime and TypeScript's static type system. Working with JSON in TypeScript means parsing external data, validating structure, and maintaining type safety throughout your application. This combination lets you consume API responses, read configuration files, and handle user input while catching type errors before they reach production. **TypeScript's type system transforms JSON from loosely-typed data into strongly-typed objects**, ensuring you catch mismatches between expected and actual data structures during development rather than at runtime.
Rather than relying on runtime checks to verify JSON structure, you **define TypeScript interfaces that describe your expected data shape and use type guards to validate incoming JSON**. This strategy catches errors immediately when data doesn't match expectations, provides autocomplete and refactoring support throughout your codebase, and creates self-documenting code where types explain data structure without separate documentation.
In this guide, you'll learn how TypeScript handles JSON parsing and serialization differently from plain JavaScript, techniques for typing JSON data with interfaces and type assertions, and strategies for validating JSON structure at runtime while maintaining compile-time type safety.
## Prerequisites
You'll need Node.js 18 or higher installed:
```command
node --version
```
```text
[output]
v22.19.0
```
## Setting up the project
Create a new TypeScript project for exploring JSON handling:
```command
mkdir ts-json-guide && cd ts-json-guide
```
Initialize with package.json configured for ES modules:
```command
npm init -y
```
```command
npm pkg set type="module"
```
Install TypeScript and development tools:
```command
npm install -D typescript @types/node tsx
```
Generate a TypeScript configuration:
```command
npx tsc --init
```
This configuration enforces strict null checks, proper function type checking, and catches common type errors. You now have an environment ready for exploring type-safe JSON operations.
## Understanding JSON parsing in TypeScript
TypeScript compiles to JavaScript, which means `JSON.parse()` behaves identically at runtime whether you're using TypeScript or plain JavaScript. The difference lies entirely in compile-time type checking. When you parse JSON in JavaScript, the result has type `any`, meaning the compiler offers no guarantees about the data's structure. TypeScript lets you add type annotations that describe what you expect from parsed JSON, but these annotations don't perform runtime validation.
Create a file demonstrating basic JSON parsing:
```typescript
[label src/basic-parsing.ts]
const jsonString = '{"name": "Alice", "age": 30, "active": true}';
const data = JSON.parse(jsonString);
console.log(data.name);
console.log(data.age);
console.log(data.active);
```
TypeScript assigns `data` the type `any`, which means you get no autocomplete, no type checking, and no compile-time safety. You can access any property without errors, even properties that don't exist:
```typescript
[label src/basic-parsing.ts]
const jsonString = '{"name": "Alice", "age": 30, "active": true}';
const data = JSON.parse(jsonString);
console.log(data.name);
[highlight]
console.log(data.nonExistent); // No error at compile time
console.log(data.age.toUpperCase()); // No error at compile time
[/highlight]
```
Compile and run this code:
```command
npx tsx src/basic-parsing.ts
```
```text
[output]
Alice
undefined
TypeError: data.age.toUpperCase is not a function
```
The code compiles successfully but crashes at runtime. This happens because `JSON.parse()` returns `any`, bypassing TypeScript's type system completely. You need explicit type annotations to get compile-time safety.
## Adding type annotations to parsed JSON
You improve type safety by defining an interface describing your expected JSON structure, then using a type assertion to tell TypeScript what shape the parsed data should have. Type assertions don't perform runtime validation, but they enable compile-time checking against your interface, catching errors where you misuse the parsed data.
Define an interface and parse JSON with a type assertion:
```typescript
[label src/typed-parsing.ts]
interface User {
name: string;
age: number;
active: boolean;
}
const jsonString = '{"name": "Alice", "age": 30, "active": true}';
const user = JSON.parse(jsonString) as User;
console.log(user.name.toUpperCase());
console.log(user.age + 5);
console.log(user.active ? "Active user" : "Inactive user");
```
Now try accessing a non-existent property:
```typescript
[label src/typed-parsing.ts]
interface User {
name: string;
age: number;
active: boolean;
}
const jsonString = '{"name": "Alice", "age": 30, "active": true}';
const user = JSON.parse(jsonString) as User;
...
[highlight]
console.log(user.email); // Error!
[/highlight]
```
Compile the code:
```command
npx tsc --noEmit src/typed-parsing.ts
```
```text
[output]
src/typed-parsing.ts:11:19 - error TS2339: Property 'email' does not exist on type 'User'.
11 console.log(user.email);
~~~~~
Found 1 error in src/typed-parsing.ts:11
```
TypeScript catches the error at compile time because `email` doesn't exist in the `User` interface. This protection applies throughout your codebase wherever you use the `user` variable, giving you autocomplete and preventing typos in property access.
Remove the invalid line and run the working code:
```typescript
[label src/typed-parsing.ts]
interface User {
name: string;
age: number;
active: boolean;
}
const jsonString = '{"name": "Alice", "age": 30, "active": true}';
const user = JSON.parse(jsonString) as User;
console.log(user.name.toUpperCase());
console.log(user.age + 5);
console.log(user.active ? "Active user" : "Inactive user");
```
```command
npx tsx src/typed-parsing.ts
```
```text
[output]
ALICE
35
Active user
```
The type assertion gives you compile-time safety, but it's crucial to understand its limitation: **it doesn't validate that the actual JSON matches your interface**. If the JSON contains different properties or wrong types, TypeScript won't catch it.
## The gap between type assertions and runtime reality
Type assertions tell the TypeScript compiler to trust you about a value's type, but they don't change how the code executes. When you parse JSON with `as User`, you're making a promise that the data matches the `User` interface, but TypeScript doesn't verify this promise at runtime. If the actual JSON differs from your interface, you get a type mismatch that only appears when the code runs.
Create JSON that doesn't match your interface:
```typescript
[label src/mismatched-json.ts]
interface User {
name: string;
age: number;
active: boolean;
}
// JSON has wrong types
const jsonString = '{"name": "Alice", "age": "thirty", "active": "yes"}';
const user = JSON.parse(jsonString) as User;
console.log(`Age next year: ${user.age + 1}`);
console.log(user.active ? "Active" : "Inactive");
```
Compile the code:
```command
npx tsc --noEmit src/mismatched-json.ts
```
TypeScript reports no errors. The type assertion tells the compiler that `user` matches the `User` interface, so it allows the code. Run it:
```command
npx tsx src/mismatched-json.ts
```
```text
[output]
Age next year: thirty1
true
```
The output reveals the mismatch. Adding 1 to the string "thirty" produces "thirty1" through string concatenation instead of arithmetic. The `active` property is the string "yes" rather than a boolean, but JavaScript's truthiness rules mean it evaluates to `true` in the conditional. These bugs slip through because the type assertion bypasses runtime validation entirely.
This example demonstrates why type assertions alone aren't sufficient for external data. You need runtime validation to ensure JSON actually matches your expected structure before treating it as a typed object.
## Implementing runtime type guards
Type guards bridge the gap between compile-time types and runtime values by performing actual checks on data structure. You write functions that inspect properties and types at runtime, then narrow TypeScript's understanding of a value based on those checks. When a type guard confirms data matches your interface, TypeScript allows you to use that data with full type safety.
Create a type guard function for validating users:
```typescript
[label src/type-guards.ts]
interface User {
name: string;
age: number;
active: boolean;
}
function isUser(value: unknown): value is User {
if (typeof value !== "object" || value === null) {
return false;
}
const obj = value as Record;
return (
typeof obj.name === "string" &&
typeof obj.age === "number" &&
typeof obj.active === "boolean"
);
}
const jsonString = '{"name": "Alice", "age": 30, "active": true}';
const parsed = JSON.parse(jsonString);
if (isUser(parsed)) {
console.log(`User: ${parsed.name}, Age: ${parsed.age}`);
console.log(`Status: ${parsed.active ? "Active" : "Inactive"}`);
} else {
console.error("Invalid user data");
}
```
The `isUser` function checks each property's type explicitly. The return type `value is User` tells TypeScript that when this function returns true, the value definitely matches the `User` interface. Run it with valid data:
```command
npx tsx src/type-guards.ts
```
```text
[output]
User: Alice, Age: 30
Status: Active
```
Now test it with invalid JSON:
```typescript
[label src/type-guards.ts]
interface User {
name: string;
age: number;
active: boolean;
}
function isUser(value: unknown): value is User {
if (typeof value !== "object" || value === null) {
return false;
}
const obj = value as Record;
return (
typeof obj.name === "string" &&
typeof obj.age === "number" &&
typeof obj.active === "boolean"
);
}
const jsonString = '{"name": "Alice", "age": "thirty", "active": "yes"}';
const parsed = JSON.parse(jsonString);
if (isUser(parsed)) {
console.log(`User: ${parsed.name}, Age: ${parsed.age}`);
console.log(`Status: ${parsed.active ? "Active" : "Inactive"}`);
} else {
console.error("Invalid user data");
}
```
```command
npx tsx src/type-guards.ts
```
```text
[output]
Invalid user data
```
The type guard catches the mismatch at runtime and prevents you from treating invalid data as a valid `User`. This approach combines compile-time type safety with runtime validation, giving you confidence that when TypeScript sees a `User` type, the data actually matches that structure.
## Final thoughts
Working with JSON in TypeScript means thinking about two separate but connected problems: telling the compiler what types you expect, and verifying at runtime that the data actually matches those expectations. **Type assertions handle the first part by giving you compile-time safety throughout your code, while type guards or validation libraries handle the second by checking actual data structure before you use it**.
When you combine these techniques, you get the benefits of TypeScript's type system—autocomplete, refactoring support, early error detection—while also catching malformed data from external sources before it causes runtime crashes. The approach you choose depends on your project's complexity, but the core principle remains the same: define your data's shape precisely, validate it when it enters your system, and let TypeScript's type checker protect you everywhere else.