JSON in TypeScript-Typen umwandeln

Um JSON in TypeScript zu konvertieren, ordnen Sie jeden JSON-Wert seinem Typ zu: Zeichenketten werden zu string, Zahlen zu number, Objekte zu verschachtelten interface-Definitionen und Arrays zu T[]. Die schwierigen Teile sind das Ableiten optionaler versus erforderlicher Felder, das Zusammenführen gemischter Arrays in Union-Typen und die Entscheidung, wann Sie auch eine Laufzeitvalidierung mit Zod benötigen.

Die automatische Generierung erledigt die langweiligen 90%. Die restlichen 10%, der Teil, den ein naiver Konverter falsch macht, sind die Stellen, an denen Fehler lauern. Ein einzelnes API-Beispiel kann Ihnen nicht sagen, welche Felder nullbar sind, welche manchmal fehlen oder ob ein leeres Array string[] oder never[] ist. Diese Anleitung führt durch die Mechanik und die Fallstricke und zeigt dann, wie Sie aus einem einzigen Einfügen die Schnittstelle, ein Zod-Schema und eine Go-Struktur generieren.

Die grundlegende Zuordnung: JSON-Werte zu TypeScript-Typen#

Beginnen wir mit einer konkreten API-Antwort. Angenommen, Sie integrieren einen Benutzerendpunkt:

{
  "id": 4821,
  "username": "ada",
  "email": "[email protected]",
  "isActive": true,
  "roles": ["admin", "editor"],
  "profile": {
    "displayName": "Ada Lovelace",
    "avatarUrl": null
  },
  "lastLoginAt": "2026-05-30T11:04:00Z"
}

Eine direkte, korrekte Übersetzung sieht so aus:

interface User {
  id: number;
  username: string;
  email: string;
  isActive: boolean;
  roles: string[];
  profile: Profile;
  lastLoginAt: string;
}

interface Profile {
  displayName: string;
  avatarUrl: string | null;
}

Hier sind bereits einige Entscheidungen getroffen, die ein unachtsamer Generator übersehen würde. Beachten Sie, dass avatarUrl als string | null deklariert ist, nicht als string, weil der Beispielwert null ist. Beachten Sie, dass lastLoginAt als string deklariert ist, nicht als Date, weil JSON keinen Datumstyp hat, es ist nur ein ISO-String, bis Sie ihn parsen. Und profile wurde in ein eigenes benanntes Interface Profile extrahiert, anstatt inline zu bleiben, was die Typen wiederverwendbar macht.

Die grundlegende Zuordnungstabelle ist kurz:

JSON	TypeScript	Achtung
"text"	string	ISO-Daten sind immer noch string
42, 3.14	number	Keine Unterscheidung zwischen int und float
true / false	boolean
null	null	Meist Teil einer Union, z.B. string | null
{ ... }	interface / verschachteltes Objekt	Wiederverwendbare Formen in benannte Interfaces extrahieren
[ ... ]	T[]	Arrays mit gemischten Typen werden zu einer Union; leere Arrays sind mehrdeutig

Interface vs Type Alias: Welches soll generiert werden#

Sowohl interface als auch type können eine Objektstruktur beschreiben, und für einfache API-Antworten sind sie nahezu austauschbar. Die praktische Anleitung:

• Verwenden Sie interface für Objektstrukturen, die Sie möglicherweise erweitern oder die einen API-Vertrag darstellen. Interfaces unterstützen Deklarationszusammenführung und liefern klarere Fehlermeldungen.
• Verwenden Sie type, wenn Sie Unions, Schnittmengen, gemappte Typen oder Tupel benötigen, die ein Interface nicht ausdrücken kann.

Für aus JSON abgeleitete Modelle verwenden Sie standardmäßig interface. Greifen Sie nur dann zu type, wenn die Daten selbst eine Union sind, z.B. ein Feld, das "pending" | "complete" ist. Die meisten Generatoren ermöglichen die Wahl des Ausgabestils, und interface ist der sicherere Standard für eine externe API-Struktur.

Die drei Fallstricke, die Single-Sample-Generatoren falsch machen#

Hier scheitern die meisten Online-Konverter. Sie übersetzen genau das, was Sie einfügen, und nichts weiter, sodass die Typen nur so korrekt sind wie Ihre eine Stichprobe.

Fallstrick 1: Optionale vs. erforderliche Felder#

Eine einzelne Antwort kann Ihnen nicht sagen, ob ein Feld optional ist. Wenn avatarUrl in Ihrer Stichprobe vorhanden ist, die API es aber für Benutzer weglässt, die nie eines festgelegt haben, markiert ein Generator es als erforderlich und Ihr Code bricht zur Laufzeit ab, wenn es fehlt.

Sie haben zwei ehrliche Optionen. Entweder füttern Sie den Generator mit mehreren Stichproben, damit er sehen kann, welche Schlüssel verschwinden, oder Sie markieren Felder basierend auf der API-Dokumentation von Hand als optional:

interface User {
  id: number;
  username: string;
  email: string;
  isActive: boolean;
  roles: string[];
  profile: Profile;
  lastLoginAt?: string; // optional: fehlt bei Benutzern, die nie eingeloggt waren
}

Das ? macht die Eigenschaft zu string | undefined. Das unterscheidet sich von string | null. null bedeutet, dass der Schlüssel mit einem Nullwert vorhanden ist; undefined bedeutet, dass der Schlüssel ganz fehlen kann. Beides zu verwechseln ist eine klassische Quelle für cannot read property of undefined-Fehler.

Fallstrick 2: Union-Typen aus gemischten Arrays#

Echte Arrays sind nicht immer homogen. Betrachten Sie einen Feed von Ereignissen:

{
  "events": [
    { "type": "click", "x": 120, "y": 44 },
    { "type": "scroll", "delta": -300 }
  ]
}

Ein schwacher Generator wählt entweder die Form des ersten Elements und ignoriert den Rest oder führt jedes Feld zu einem aufgeblähten Objekt mit allem optional zusammen. Die korrekte Ausgabe ist eine diskriminierte Union:

type AppEvent =
  | { type: "click"; x: number; y: number }
  | { type: "scroll"; delta: number };

interface EventPayload {
  events: AppEvent[];
}

Das gemeinsame Feld type ist der Diskriminator. TypeScript kann die Union nun in einem switch (event.type) eingrenzen, was ein einzelnes zusammengeführtes Interface niemals erlauben würde.

Fallstrick 3: Leere Arrays und Nur-Null-Felder#

Welchen Typ hat "tags": []? Es gibt kein Element zur Ableitung, also ist die ehrliche Antwort "unbekannt". Naive Tools geben any[] oder never[] aus, beides in der Praxis falsch. Dasselbe Problem betrifft ein Feld, dessen einziger Stichprobenwert null ist: Sie können den Nicht-Null-Typ nicht allein aus null ableiten. Wenn Sie darauf stoßen, liefern Sie eine Stichprobe mit Daten oder annotieren Sie den Typ selbst (tags: string[]) basierend auf dem, was Sie über die API-Rückgabe wissen.

Wann Sie auch Zod benötigen (Laufzeitvalidierung)#

TypeScript-Typen verschwinden zur Kompilierzeit. Sie bieten keinerlei Schutz dagegen, dass eine API tatsächlich etwas anderes zurückgibt, als Sie typisiert haben. Wenn der Server einen String sendet, wo Sie eine Zahl erwartet haben, vertraut TypeScript bereits der falschen Form und Ihre App scheitert mit einem verwirrenden Fehler.

Zod schließt diese Lücke. Sie definieren ein Schema einmal, validieren die Antwort an der Grenze und leiten den statischen Typ aus demselben Schema ab, sodass Sie ihn nie zweimal schreiben:

import { z } from "zod";

const ProfileSchema = z.object({
  displayName: z.string(),
  avatarUrl: z.string().url().nullable(),
});

const UserSchema = z.object({
  id: z.number().int(),
  username: z.string(),
  email: z.string().email(),
  isActive: z.boolean(),
  roles: z.array(z.string()),
  profile: ProfileSchema,
  lastLoginAt: z.string().datetime().optional(),
});

// Der statische Typ wird aus dem Schema abgeleitet, nicht von Hand geschrieben:
type User = z.infer<typeof UserSchema>;

// An der Netzwerkgrenze:
const user = UserSchema.parse(await response.json());

Jetzt wirft UserSchema.parse() einen präzisen, lesbaren Fehler, sobald die Daten den Vertrag verletzen, und z.infer hält den TypeScript-Typ perfekt synchron. Verwenden Sie Zod (oder ein ähnliches Tool wie Valibot), wann immer Daten eine Vertrauensgrenze überschreiten: HTTP-Antworten, Formulareingaben, Webhooks, Nachrichtenwarteschlangen, alles, was Sie nicht selbst erzeugt haben. Für interne, vollständig typisierte Daten, die Sie Ende-zu-Ende kontrollieren, reichen einfache Interfaces.

Faustregel: Wenn das JSON von außerhalb Ihrer Codebasis kommt, validieren Sie es zur Laufzeit. Typen allein sind ein Versprechen, keine Garantie.

Benötigen Sie stattdessen ein Go Struct?#

Backend-Teams benötigen oft die gleiche Struktur in Go. Die Abbildung spiegelt TypeScript wider, wobei Struct-Tags die JSON-Schlüsselnamen tragen:

type Profile struct {
	DisplayName string  `json:"displayName"`
	AvatarURL   *string `json:"avatarUrl"`
}

type User struct {
	ID          int      `json:"id"`
	Username    string   `json:"username"`
	Email       string   `json:"email"`
	IsActive    bool     `json:"isActive"`
	Roles       []string `json:"roles"`
	Profile     Profile  `json:"profile"`
	LastLoginAt string   `json:"lastLoginAt"`
}

Beachten Sie den *string-Zeiger für avatarUrl: in Go repräsentiert ein Zeiger ein nullfähiges Feld, da der Nullwert von string "" ist, nicht nil. Dieselbe Nullfähigkeitsfrage von der TypeScript-Seite taucht hier in einer anderen Form wieder auf.

Generieren Sie es, ohne es in eine zufällige Website einzufügen#

Die manuelle Durchführung bei großen Datenmengen ist mühsam und fehleranfällig. Noch schlimmer ist es, Produktions-JSON, das Tokens, E-Mails oder Kundendaten enthalten kann, in einen unbekannten externen Dienst einzufügen. Ein datenschutzbewusster Konverter führt die Transformation vollständig in Ihrem Browser durch, sodass die Daten niemals einen Server erreichen.

Schritt 1: JSON einfügen und validieren#

Fügen Sie Ihre API-Antwort in einen kostenlosen JSON-Formatter und -Konverter ein. Dieser validiert das JSON zunächst und formatiert es hübsch, sodass Sie ein nachgestelltes Komma oder einen nicht in Anführungszeichen gesetzten Schlüssel erkennen, bevor Sie überhaupt über Typen nachdenken. Fehlerhaftes JSON ist der häufigste Grund, warum eine Konvertierung stillschweigend Müll produziert.

Schritt 2: Ausgabeformat wählen#

Wählen Sie das gewünschte Format: ein TypeScript-Interface, ein Zod-Schema oder eine Go-Struktur. Da der JSON-zu-TypeScript-Konverter clientseitig läuft, können Sie bedenkenlos echte, ungeschwärzte Antworten hineinwerfen, ohne sich Gedanken darüber zu machen, wohin die Daten gelangen. Die gesamte Transformation findet im Tab statt.

Schritt 3: Optionale Felder und Unions manuell verfeinern#

Die Generierung liefert ein korrektes Grundgerüst aus dem Beispiel. Wenden Sie nun die drei Fallstricke an: Markieren Sie wirklich optionale Schlüssel mit ?, erweitern Sie null-only oder leere Array-Felder auf ihre tatsächlichen Typen und konvertieren Sie gemischte Objekt-Arrays in diskriminierte Unions. Diese letzten 10 % erfordern Urteilsvermögen, das das Tool aus einer einzelnen Nutzlast nicht ableiten kann, und sie unterscheiden Typen, die kompilieren, von Typen, die tatsächlich zur API passen.

Wenn Ihr Workflow mehr als nur Typen umfasst, hilft das gleiche Toolkit: Validieren Sie Tokens mit den JWT-Decoder-ähnlichen Tools, testen Sie Extraktionsmuster im Regex-Tester oder verarbeiten Sie codierte Nutzlasten mit dem Base64-Encoder und -Decoder. Für einen tieferen Einblick in alltägliche JSON-Workflows lesen Sie unseren Leitfaden, warum ein JSON-Formatter ein tägliches Entwicklerwerkzeug ist.

Häufig gestellte Fragen#

Wie konvertiere ich JSON in ein TypeScript-Interface? Ordne jeden JSON-Wert seinem TypeScript-Äquivalent zu: Zeichenketten zu string, Zahlen zu number, Objekte zu verschachtelten Interfaces und Arrays zu T[]. Extrahiere wiederverwendete Objektformen in benannte Interfaces. Der schnellste zuverlässige Weg ist, das JSON in einen Konverter einzufügen und dann manuell optionale Felder, Null-Unionen und gemischte Arrays zu korrigieren, die das Beispiel nicht zeigen konnte.

Sollte ich ein Interface oder einen Typ-Alias für JSON-Daten verwenden? Verwende standardmäßig interface für Objektformen aus einer API, da Interfaces sauber erweitert werden und klarere Fehlermeldungen liefern. Verwende einen type-Alias, wenn die Daten selbst eine Union, Schnittmenge oder ein Tupel sind, das ein Interface nicht ausdrücken kann, wie z.B. ein Statusfeld, das "pending" | "complete" ist.

Wie behandle ich optionale Felder beim Generieren von Typen aus JSON? Ein einzelnes Beispiel kann optionale Felder nicht zeigen, daher markiert ein Generator alles als erforderlich. Entweder füttere ihn mit mehreren Antworten, damit er sieht, welche Schlüssel verschwinden, oder füge den ?-Modifikator selbst basierend auf der API-Dokumentation hinzu. Denke daran, dass field?: string (kann fehlen) sich von field: string | null (vorhanden, aber null) unterscheidet.

Brauche ich Zod, wenn ich bereits TypeScript-Typen habe? Ja, immer wenn Daten eine Vertrauensgrenze überschreiten. TypeScript-Typen werden zur Kompilierzeit gelöscht und können nicht validieren, was eine API zur Laufzeit tatsächlich zurückgibt. Zod validiert die tatsächlichen Nutzdaten und ermöglicht es dir, den statischen Typ aus demselben Schema mit z.infer abzuleiten, sodass der Typ und die Laufzeitprüfung nie auseinanderdriften.

Ist es sicher, JSON online in TypeScript zu konvertieren? Nur, wenn der Konverter in deinem Browser läuft. Viele Online-Tools senden dein eingefügtes JSON an einen Server, was riskant ist, wenn die Nutzdaten Tokens, E-Mails oder Kundendaten enthalten. Ein clientseitiger Konverter wie der Molixa JSON-Formatter führt die gesamte Transformation lokal durch, sodass die Daten deinen Tab nie verlassen.

Wie konvertiere ich verschachtelte JSON-Objekte in TypeScript? Extrahiere jedes verschachtelte Objekt in ein eigenes benanntes Interface und referenziere es vom Elternobjekt, anstatt alles tief zu verschachteln. Für das Benutzerbeispiel wird profile zu einem separaten Profile-Interface, das User referenziert. Benannte Interfaces sind wiederverwendbar, erzeugen kürzere Fehlermeldungen und machen die generierten Typen viel lesbarer.