# JSON – strukturierte Daten für Anwendungen, APIs und KI-Agenten
> Ein umfassender praktischer Leitfaden zum JSON-Format: Syntaxregeln, Serialisierung über parse/stringify, Arbeit mit REST-APIs, JSON Schema und strukturierter Output für künstliche Intelligenz.
## 1. Was ist JSON und warum wurde es zum Standard
Das Format **JSON** (*JavaScript Object Notation*) ist ein universeller Standard für den Austausch strukturierter Daten zwischen Webservern, Client-Anwendungen, Datenbanken und modernen AI-Agenten.
Wenn Computerprogramme miteinander interagieren, ist die Übertragung von Informationen als unstrukturierter Text ineffizient:
> *„Olena Kowaltschuk, 29 Jahre alt, Kiew, Premium-Abonnement aktiv, Fähigkeiten: Python, SQL.“*
Ein Mensch versteht diese Beschreibung leicht, aber ein Algorithmus würde erhebliche Ressourcen für die Entitätserkennung aufwenden. Im JSON-Format sehen dieselben Daten streng und deterministisch aus:
```json
{
"id": 1042,
"name": "Олена Ковальчук",
"age": 29,
"city": "Київ",
"isPremium": true,
"skills": ["Python", "SQL"]
}
```
Jeder Parser in jeder Programmiersprache (JavaScript, Python, Go, Rust) liest sofort den Schlüssel `"city"` und erhält den Wert `"Kiew"`, ohne Mehrdeutigkeiten.
```mermaid
flowchart LR
A["Клієнтський UI
(React / Mobile App)"] -->|HTTP POST JSON| B["REST API Сервер
(Node.js / Python)"]
B -->|SQL / NoSQL JSONB| C["База даних
(PostgreSQL / MongoDB)"]
B -->|Structured Output JSON| D["LLM / AI-Агент
(Claude / OpenAI)"]
```
### Warum JSON nicht von JavaScript abhängt
Trotz des Namens ist JSON ein vollständig sprachunabhängiges Textformat. Es verfügt über einen eigenen RFC-Standard (RFC 8259) und wird von allen modernen Ökosystemen über den standardmäßigen MIME-Typ `application/json` unterstützt.
---
## 2. Anatomie von JSON: Syntax von Objekten, Arrays und Primitiven
Alle Daten im JSON-Format basieren auf zwei zentralen Containern (Objekte und Arrays) sowie sechs grundlegenden Wertetypen.
### Objekt (JSON Object)
Ein Objekt repräsentiert eine ungeordnete Menge von Paaren `Schlüssel: Wert`, die zwingend in geschweifte Klammern `{}` gesetzt werden. Der Schlüssel muss immer ein Textstring in doppelten Anführungszeichen sein.
```json
{
"username": "alex_dev",
"email": "alex@example.com",
"role": "admin"
}
```
### Array (JSON Array)
Ein Array ist eine geordnete Liste von Werten beliebigen Typs, eingeschlossen in eckige Klammern `[]`. Die Elemente eines Arrays werden bei null indiziert.
```json
{
"supportedLocales": ["uk", "en", "es", "de"],
"primeNumbers": [2, 3, 5, 7, 11]
}
```
### Zulässige Wertetypen (Values)
In JSON sind genau 6 Wertetypen erlaubt:
| Wertetyp | Beschreibung & Schreibregeln | Beispiel |
| :--- | :--- | :--- |
| **String** | Folge von Unicode-Zeichen in doppelten Anführungszeichen | `"Hello, World!"` |
| **Number** | Ganzzahl oder Dezimalzahl (ohne Anführungszeichen, keine Hexadezimalzahlen) | `42`, `-12.5`, `1.5e3` |
| **Boolean** | Nur Kleinbuchstaben: `true` oder `false` | `true`, `false` |
| **Null** | Kennzeichnung einer bewussten Abwesenheit eines Wertes | `null` |
| **Object** | Verschachtelter Container für Schlüssel-Wert-Paare | `{"nested": true}` |
| **Array** | Verschachtelte Liste von Elementen | `[1, 2, 3]` |
---
## 3. Strenge Syntaxregeln und typische Fallstricke
Die JSON-Syntax ist deutlich strenger als die flexible Syntax von JavaScript oder Python. Ein Fehler in nur einem Zeichen bricht die Validierung des gesamten Dokuments ab.
### Die fünf wichtigsten Syntaxregeln
1. **Nur doppelte Anführungszeichen:** Schlüssel und Textstrings müssen in `"doppelten Anführungszeichen"` stehen. Einfache Anführungszeichen `'text'` verursachen einen fatalen Parser-Fehler.
2. **Keine trailing commas:** Nach dem letzten Element eines Objekts oder Arrays darf kein Komma stehen. Dies ist strikt verboten.
3. **Doppelpunkt als einziger Trennzeichen:** Der Schlüssel wird vom Wert ausschließlich durch einen Doppelpunkt `:` getrennt.
4. **Vollständiges Fehlen von Kommentaren:** Die JSON-Spezifikation unterstützt keine Kommentare wie `//` oder `/* */`. Alle Erläuterungen müssen als normale Felder im Dokument formuliert werden (z. B. `"_comment": "Erläuterung"`).
5. **Verbotene Datentypen:** In JSON können keine `undefined`, `NaN`, `Infinity`, regulären Ausdrücke oder Funktionen übertragen werden.
### Vergleich von gültigem und ungültigem JSON
:::tabs
@tab Gültiges Beispiel
```json
{
"product": "MacBook Pro",
"price": 1999.99,
"inStock": true,
"tags": ["laptop", "apple", "m-series"]
}
```
@tab Ungültiges Beispiel (Typische Fehler)
```json
{
product: 'MacBook Pro', // Помилка: одинарні лапки та ключ без лапок
"price": 1999.99,
"inStock": true,
"tags": ["laptop", "apple",], // Помилка: висяча кома
} // Помилка: висяча кома перед закриваючою дужкою
```
:::
---
## 4. Unterschiede zwischen JSON und JavaScript-Objekten
Anfänger verwechseln oft das JavaScript-Objekt-Literal mit dem JSON-Format. Zwischen beiden besteht jedoch ein grundlegender Unterschied.
```mermaid
flowchart TD
subgraph Текстовий_Рядок["JSON (Символьний потік)"]
J["'{\"name\":\"Max\",\"age\":30}'"]
end
subgraph Пам'ять_Програми["JavaScript Object (Структура в RAM)"]
O["{ name: 'Max', age: 30 }"]
end
J -->|JSON.parse| O
O -->|JSON.stringify| J
```
### Tabelle der fundamentalen Unterschiede
| Merkmal | JavaScript-Objekt | JSON (Textformat) |
| :--- | :--- | :--- |
| **Existenzform** | Lebende Datenstruktur im Arbeitsspeicher | Textstring (Bytefolge) |
| **Anforderungen an Schlüssel** | Können ohne Anführungszeichen oder als Symbol sein | Müssen Strings in doppelten Anführungszeichen sein |
| **Unterstützte Typen** | Funktionen, Methoden, `Date`, `Map`, `Set`, `undefined` | Nur 6 Basistypen (Strings, Numbers, Booleans, Null, Objects, Arrays) |
| **Kommentare** | Erlaubt (`//` und `/* */`) | Vollständig verboten |
| **Trailing Commas** | Durch moderne JS-Standards erlaubt | Streng durch den Standard verboten |
---
## 5. Navigation und Lesen verschachtelter Datenstrukturen
In realen Projekten enthalten API-Antworten tiefe hierarchische Strukturen. Für den Zugriff auf einen bestimmten Wert verwendet man die Punkt-Notation (`.`) für Objekte und Indizes (`[]`) für Arrays.
### Beispiel eines komplexen Dokuments
```json
{
"orderId": "ORD-94821",
"customer": {
"fullName": "Тарас Шевченко",
"contacts": {
"email": "taras@example.org",
"phones": ["+380501112233", "+380679998877"]
}
},
"items": [
{ "id": 1, "title": "Монітор 4K", "price": 450, "qty": 1 },
{ "id": 2, "title": "Механічна клавіатура", "price": 120, "qty": 2 }
]
}
```
### Pfade zum Zugriff auf Elemente
- `order.orderId` $\rightarrow$ gibt `"ORD-94821"` zurück
- `order.customer.fullName` $\rightarrow$ gibt `"Taras Shevchenko"` zurück
- `order.customer.contacts.phones[0]` $\rightarrow$ gibt die erste Nummer `"+380501112233"` zurück
- `order.items[1].price` $\rightarrow$ gibt den Preis des zweiten Artikels `120` zurück
> [!TIP]
> Verwenden Sie im modernen JavaScript immer Optional Chaining (`order?.customer?.contacts?.email`), um Fehler wie `TypeError: Cannot read properties of undefined` zu vermeiden.
---
## 6. JSON in REST APIs: Anfragen, Antworten und Header
Praktisch alle modernen Webdienste nutzen JSON als Protokoll zur Übertragung der Nutzlast (Payload) über HTTP.
```mermaid
sequenceDiagram
autonumber
actor Client as Клієнт (Браузер / Додаток)
participant Server as REST API Сервер
Note over Client: Підготовка об'єкта та серіалізація
Client->>Server: POST /api/users (Header: Content-Type: application/json)
Note over Server: Десеріалізація JSON, валідація, запис у БД
Server-->>Client: 201 Created (Header: Content-Type: application/json)
Note over Client: Читання response.json()
```
### Wichtige HTTP-Header
1. **`Content-Type: application/json`:** Weist den Server oder Client darauf hin, dass im Request Body oder Response Body ein gültiger JSON-String übertragen wird.
2. **`Accept: application/json`:** Der Client teilt dem Server mit, dass er eine Antwort ausschließlich im JSON-Format erwartet (und nicht XML oder HTML).
---
## 7. Serialisierung und Deserialisierung: Parse und Stringify
Die Umwandlung lebender Speicherobjekte in Text wird als **Serialisierung** (*Serialization*) bezeichnet, die Rückumwandlung von Text in Objekte als **Deserialisierung** (*Deserialization*).
:::tabs
@tab JavaScript / TypeScript
```typescript
// 1. Десеріалізація (Текст -> Об'єкт)
const jsonString = '{"title":"Ноутбук","price":1200}';
const product = JSON.parse(jsonString);
console.log(product.title); // "Ноутбук"
// 2. Серіалізація (Об'єкт -> Текст)
const user = { name: "Данило", active: true };
const serialized = JSON.stringify(user, null, 2); // форматування з відступом у 2 пробіли
```
@tab Python
```python
import json
# 1. Десеріалізація
raw_text = '{"title": "Ноутбук", "price": 1200}'
product = json.loads(raw_text)
print(product["title"])
# 2. Серіалізація
user_dict = {"name": "Данило", "active": True}
json_string = json.dumps(user_dict, indent=2, ensure_ascii=False)
```
@tab Go
```go
package main
import (
"encoding/json"
"fmt"
)
type Product struct {
Title string `json:"title"`
Price int `json:"price"`
}
func main() {
raw := []byte(`{"title":"Ноутбук","price":1200}`)
var p Product
json.Unmarshal(raw, &p)
fmt.Println(p.Title)
}
```
:::
---
## 8. Diagnose von Syntaxfehlern und Validierung
Wenn der Text auch nur einen einzigen Syntaxfehler enthält, wirft der Aufruf von `JSON.parse()` eine Exception `SyntaxError`, was den Betrieb der Anwendung abrupt beenden kann.
```javascript
try {
const data = JSON.parse(untrustedUserInput);
} catch (error) {
console.error("Невалідний JSON:", error.message);
}
```
### Checkliste für die schnelle Diagnose
- [ ] Sind alle geschweiften `{}` und eckigen `[]` Klammern geschlossen?
- [ ] Stehen alle Schlüssel in doppelten Anführungszeichen `""`?
- [ ] Gibt es ein trailing comma vor der letzten Klammer?
- [ ] Enthalten die Werte `undefined`, `NaN` oder Kommentare?
- [ ] Sind innere Anführungszeichen in Strings escaped: `"quote": "Wort \"in Anführungszeichen\""`?
---
## 9. JSON Schema: Prüfung von Verträgen und Struktur
Ein syntaktisch korrektes JSON garantiert noch nicht, dass die Daten die richtige Geschäftsstruktur haben. Wenn eine API eine Zahl `age` erwartet, aber einen String `"zwanzig"` erhält, stürzt das Programm im Berechnungsschritt ab.
Für die formale Beschreibung der Anforderungen an die Struktur wird der Standard **JSON Schema** verwendet.
```json
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"title": "UserRegistrationSchema",
"type": "object",
"properties": {
"email": {
"type": "string",
"format": "email"
},
"age": {
"type": "integer",
"minimum": 18
},
"roles": {
"type": "array",
"items": { "type": "string" },
"minItems": 1
}
},
"required": ["email", "age"]
}
```
Jeder Validator (z. B. Ajv in JavaScript oder jsonschema in Python) prüft die Eingabedaten automatisch anhand dieses Vertrags, bevor sie an die Datenbank übergeben werden.
---
## 10. Strukturierte Daten für LLMs, Function Calling und AI-Agenten
In der modernen KI-Entwicklung weichen textuelle Antworten im freien Format zunehmend **Structured Outputs**.
AI-Agenten (wie Claude Code, OpenAI Function Calling, LangChain) nutzen JSON für den Aufruf externer Tools:
```json
{
"name": "sendEmailNotification",
"arguments": {
"recipient": "user@example.com",
"subject": "Рахунок сформовано",
"invoiceId": "INV-2026-09"
}
}
```
### Wie man sauberes JSON von einem Sprachmodell erzwingt
1. **Schema im System-Prompt angeben:** Übermitteln Sie immer das exakte TypeScript-Modell oder JSON Schema.
2. **Rohausgabe verlangen:** Nutzen Sie die Anweisung: *"Return ONLY a valid raw JSON object. Do not wrap in markdown code blocks or add introductory text."*
3. **Structured Outputs Mode nutzen:** Aktivieren Sie bei API-Providern (Anthropic Tool Use / OpenAI JSON Mode) die erzwungene Schema-Validierung auf Ebene des Token-Generators.
---
## 11. Formatvergleich: JSON, YAML, XML und TOML
| Format | Menschliche Lesbarkeit | Kommentarunterstützung | Markup-Volumen | Hauptanwendungsgebiet |
| :--- | :--- | :--- | :--- | :--- |
| **JSON** | Mittel / Hoch | Nein | Minimal | Web APIs, Client-Server-Kommunikation, AI-Calls |
| **YAML** | Sehr hoch | Ja | Null (Einrückungen) | CI/CD-Konfigurationen (GitHub Actions, K8s) |
| **TOML** | Sehr hoch | Ja | Niedrig | Projektkonfigurationen (Cargo, pyproject.toml) |
| **XML** | Niedrig | Ja | Hoch (Tags) | Legacy Enterprise-Systeme, SOAP, SVG |
---
## 12. Praktischer Workshop, Selbstprüfung und abschließende Checkliste
Festigen wir alle erworbenen Fähigkeiten im vollständigen Zyklus: von der Datenbeschaffung aus einer API bis zur Validierung und zum Lesen.
### Vollständiges Szenario für Datenabruf und -lesen
```typescript
// Отримання даних користувача через Fetch API
async function fetchUserProfile(userId: number) {
try {
const response = await fetch(`https://api.example.com/users/${userId}`, {
headers: { Accept: "application/json" }
});
if (!response.ok) {
throw new Error(`HTTP Error: ${response.status}`);
}
// Автоматична десеріалізація JSON
const user = await response.json();
// Безпечне читання значень
console.log(`Користувач: ${user.name}`);
console.log(`Основна навичка: ${user.skills?.[0] ?? 'відсутня'}`);
return user;
} catch (err) {
console.error("Помилка отримання профілю:", err);
}
}
```
### Schnelle Selbstprüfung
> **1. Welcher Fehler tritt auf, wenn im JSON-File einfache Anführungszeichen für Strings verwendet werden?**
>
> > [!TIP]
> > **Antwort:** Es tritt ein Parsing-Fehler `SyntaxError: Unexpected token ' in JSON` auf. Die JSON-Spezifikation erlaubt ausschließlich doppelte Anführungszeichen `""`.
> **2. Warum darf nach dem letzten Element eines JSON-Objekts kein Komma stehen?**
>
> > [!TIP]
> > **Antwort:** Der JSON-Standard verbietet trailing commas. Der Parser erwartet nach einem Komma das nächste Schlüssel-Wert-Paar; findet er stattdessen die schließende Klammer `}`, entsteht ein fataler Syntaxfehler.
> **3. Wozu dient der Standard JSON Schema?**
>
> > [!TIP]
> > **Antwort:** Zur Prüfung der Geschäftsstruktur und der Datentypen im Dokument (Vorhandensein Pflichtfelder, Mindestwerte für Zahlen, E-Mail-Format), nicht nur zur Basis-Syntaxvalidierung.
### Abschließende Checkliste für die Arbeit mit JSON
- [ ] Alle Strings und Schlüssel sind in doppelten Anführungszeichen `""` formatiert.
- [ ] Das Fehlen von trailing commas vor `}` und `]` wurde überprüft.
- [ ] Alle Kommentare wurden aus dem JSON-Dokument entfernt.
- [ ] Bei der Netzwerkübertragung wurde der Header `Content-Type: application/json` gesetzt.
- [ ] Alle `JSON.parse()`-Operationen sind durch `try/catch`-Blöcke geschützt.