Ausführbare Go-Docs: JSON

Q: Wie konvertiere ich in Go ein Struct in JSON?

Ruf json.Marshal(v) auf, das []byte und einen Fehler zurückgibt. Nur exportierte Felder (Namen mit Großbuchstaben am Anfang) werden aufgenommen. Mit einem Struct Tag wie json:"name" an einem Feld bestimmst du seinen JSON-Schlüssel. Für eingerückte Ausgabe nimm json.MarshalIndent(v, "", " ").

Q: Warum fehlen meine Struct-Felder in der JSON-Ausgabe?

encoding/json sieht nur exportierte Felder. Ein Feld namens name (kleingeschrieben) ist für das Paket unsichtbar, sowohl beim Marshalling als auch beim Unmarshalling. Schreib das Feld groß und setz den JSON-Schlüssel mit einem Tag wie json:"name".

Q: Was macht omitempty bei Go-JSON?

omitempty lässt ein Feld in der Ausgabe weg, wenn es einen leeren Wert enthält: false, 0, "", einen nil-Pointer oder ein nil-Interface oder einen leeren Slice oder eine leere Map. Ein Struct oder time.Time behandelt es nicht als leer. Go 1.24 hat omitzero eingeführt, das jeden Wert weglässt, der der Nullwert seines Typs ist (oder dessen Methode IsZero() true liefert), auch Structs und time.Time.

Q: Wie parse ich in Go JSON mit unbekannter Struktur?

Unmarshalle in map[string]any (oder any). Objekte werden zu map[string]any, Arrays zu []any, Strings zu string, Booleans zu bool und jede Zahl zu float64. Die Werte liest du mit Type Assertions, und mit Decoder.UseNumber bleiben große Ganzzahlen exakt.

Marshal und Unmarshal

json.Marshal macht aus einem Go-Wert JSON-Bytes. json.Unmarshal füllt einen Go-Wert aus JSON-Bytes. Struct Tags wählen die Namen der JSON-Felder.

package main

import (
	"encoding/json"
	"fmt"
)

type User struct {
	ID    int      `json:"id"`
	Name  string   `json:"name"`
	Email string   `json:"email,omitempty"`
	Tags  []string `json:"tags"`
}

func main() {
	u := User{ID: 1, Name: "Ada", Tags: []string{"admin"}}

	data, err := json.Marshal(u)
	if err != nil {
		fmt.Println("marshal:", err)
		return
	}
	fmt.Println(string(data))

	var back User
	input := []byte(`{"id": 2, "name": "Linus", "email": "l@example.com", "tags": ["kernel", "git"]}`)
	if err := json.Unmarshal(input, &back); err != nil {
		fmt.Println("unmarshal:", err)
		return
	}
	fmt.Printf("%+v\n", back)
}

Email fehlt in der ersten Ausgabe wegen omitempty und eines leeren Strings. Unmarshal braucht einen Pointer (&back); übergibst du den Wert selbst, bekommst du einen InvalidUnmarshalError.

Struct Tags

Die Tag-Syntax ist json:"name,option,option".

Tag	Wirkung
`json:"user_id"`	`user_id` als Schlüssel verwenden
`json:"email,omitempty"`	weglassen bei false, 0, "", nil oder einem leeren Slice oder einer leeren Map
`json:",omitzero"` (Go 1.24)	weglassen, wenn der Wert sein Nullwert ist oder sein `IsZero()` true liefert
`json:"-"`	dieses Feld nie kodieren oder dekodieren
`json:"-,"`	den wörtlichen Schlüssel `-` verwenden
`json:"count,string"`	eine Zahl oder ein bool als JSON-String kodieren (`"42"`)
kein Tag	der Schlüssel ist der Go-Feldname, `UserID`

package main

import (
	"encoding/json"
	"fmt"
	"time"
)

type Account struct {
	ID        int       `json:"id"`
	Password  string    `json:"-"`
	Nickname  string    `json:"nickname,omitempty"`
	Balance   int64     `json:"balance,string"`
	CreatedAt time.Time `json:"created_at,omitempty"` // omitempty never omits a struct
	DeletedAt time.Time `json:"deleted_at,omitzero"`  // Go 1.24: omitted when zero
	internal  string    // unexported: always ignored
}

func main() {
	a := Account{ID: 7, Password: "hunter2", Balance: 1500, internal: "x"}
	out, err := json.MarshalIndent(a, "", "  ")
	if err != nil {
		fmt.Println(err)
		return
	}
	fmt.Println(string(out))
}

Das Passwort verlässt das Struct nie, der Kontostand steht in Anführungszeichen, und deleted_at verschwindet, während created_at die Null-Zeit 0001-01-01T00:00:00Z ausgibt. Genau wegen dieses Unterschieds kam omitzero hinzu: omitempty hat bei Structs nie funktioniert, und bei time.Time ist das eine altbekannte Überraschung. Unter Go 1.23 und älter erreichst du dasselbe mit einem *time.Time und omitempty.

MarshalIndent(v, prefix, indent) erzeugt lesbare Ausgabe. Nimm es für Konfigurationsdateien und beim Debuggen; APIs senden meist kompaktes JSON.

Nur exportierte Felder

encoding/json nutzt Reflection und kann nur exportierte Felder sehen. Das ist der häufigste JSON-Bug in Go:

type point struct {
	x, y int // lowercase: json.Marshal(point{1, 2}) gives {}
}

Kein Fehler, keine Warnung, nur {} in der einen Richtung und Felder, die in der anderen auf null bleiben. Schreib die Felder groß und füg Tags für kleingeschriebene Schlüssel hinzu.

Wie das Dekodieren Felder zuordnet

Beim Unmarshalling in ein Struct gilt:

Schlüssel werden dem Tag-Namen oder dem Feldnamen zugeordnet, ohne Beachtung der Groß- und Kleinschreibung. {"NAME": "x"} füllt ein Feld mit dem Tag json:"name".
Schlüssel ohne passendes Feld werden still ignoriert.
Felder ohne passenden Schlüssel behalten ihren aktuellen Wert. Unmarshal setzt sie nicht zurück, also wird beim Dekodieren in ein Struct mit vorhandenen Daten zusammengeführt.
Ein Typkonflikt (ein String, wo das Struct ein int hat) gibt einen *json.UnmarshalTypeError zurück, aber die anderen Felder werden trotzdem gefüllt.

Um unerwartete Schlüssel abzulehnen, etwa in einer strengen API oder einer Konfigurationsdatei mit Tippfehlern, nimm einen Decoder mit DisallowUnknownFields:

package main

import (
	"encoding/json"
	"fmt"
	"strings"
)

type Config struct {
	Port  int  `json:"port"`
	Debug bool `json:"debug"`
}

func main() {
	input := `{"port": 8080, "debgu": true}` // typo in "debug"

	var lenient Config
	err := json.Unmarshal([]byte(input), &lenient)
	fmt.Printf("Unmarshal: %+v, err=%v\n", lenient, err)

	var strict Config
	dec := json.NewDecoder(strings.NewReader(input))
	dec.DisallowUnknownFields()
	err = dec.Decode(&strict)
	fmt.Println("Decoder:", err)

	var typed Config
	err = json.Unmarshal([]byte(`{"port": "8080"}`), &typed)
	fmt.Println("type mismatch:", err)
}

Unbekannte Struktur: map[string]any

Kennst du die Form vorher nicht, dekodiere in map[string]any oder any. Die Zuordnung ist fest:

JSON	Go
Objekt	`map[string]any`
Array	`[]any`
String	`string`
Zahl	`float64`
true / false	`bool`
null	`nil`

package main

import (
	"encoding/json"
	"fmt"
	"strings"
)

func main() {
	input := `{"name": "widget", "price": 9.5, "stock": 3, "tags": ["a", "b"], "meta": {"id": 9007199254740993}}`

	var m map[string]any
	if err := json.Unmarshal([]byte(input), &m); err != nil {
		fmt.Println(err)
		return
	}

	name, _ := m["name"].(string)
	stock, _ := m["stock"].(float64) // numbers are float64, even 3
	tags, _ := m["tags"].([]any)
	fmt.Println(name, int(stock), len(tags))

	meta := m["meta"].(map[string]any)
	fmt.Printf("id as float64: %.0f\n", meta["id"]) // precision lost

	// UseNumber keeps numbers as json.Number (a string) for exact handling.
	dec := json.NewDecoder(strings.NewReader(input))
	dec.UseNumber()
	var exact map[string]any
	if err := dec.Decode(&exact); err != nil {
		fmt.Println(err)
		return
	}
	id, err := exact["meta"].(map[string]any)["id"].(json.Number).Int64()
	fmt.Println("id with UseNumber:", id, err)
}

In der Ausgabe sind zwei Fallen zu sehen. Jede Zahl ist float64, also würde m["stock"].(int) scheitern. Und Ganzzahlen über 2^53 verlieren als float64 Genauigkeit: Die ID 9007199254740993 kommt als ...992 zurück. UseNumber vermeidet beides.

Kennst du einen Teil der Struktur, dekodiere diesen Teil in ein Struct und nimm json.RawMessage für den Rest. Es enthält die rohen Bytes eines Felds, damit du es später dekodieren kannst, sobald du seinen Typ kennst.

Slices, Maps, Pointer und nil

Go-Wert	JSON
`nil`-Slice (`var s []int`)	`null`
leerer Slice (`[]int{}`)	`[]`
`nil`-Map	`null`
`nil`-Pointer	`null`
`[]byte`	ein Base64-String
`map[string]T`	ein Objekt, Schlüssel sortiert
`map[int]T`	ein Objekt mit den Ganzzahl-Schlüsseln als Strings

Der Unterschied zwischen nil und leerem Slice zählt für API-Clients, die ein Array erwarten. Initialisier mit []T{} oder make([]T, 0), wenn das Feld [] sein muss.

Nimm ein Pointer-Feld (*int, *bool), wenn du bei der Eingabe „fehlt“ von „null“ unterscheiden musst. Nach dem Unmarshalling bedeutet ein nil-Pointer, dass der Schlüssel fehlte oder null war; ein Pointer auf 0 bedeutet, dass der Client 0 gesendet hat.

Streams: Encoder und Decoder

json.Marshal und Unmarshal arbeiten auf ganzen Byte-Slices. Für einen io.Reader oder io.Writer (einen HTTP-Body, eine Datei, stdin) nimmst du json.NewDecoder und json.NewEncoder. Ein Decoder kann auch eine Folge von JSON-Werten einzeln lesen:

package main

import (
	"encoding/json"
	"errors"
	"fmt"
	"io"
	"os"
	"strings"
)

type Event struct {
	Type string `json:"type"`
	N    int    `json:"n"`
}

func main() {
	// Newline-delimited JSON, as in log files and many streaming APIs.
	stream := `{"type":"click","n":1}
{"type":"view","n":2}
{"type":"click","n":3}`

	dec := json.NewDecoder(strings.NewReader(stream))
	clicks := 0
	for {
		var e Event
		err := dec.Decode(&e)
		if errors.Is(err, io.EOF) {
			break
		}
		if err != nil {
			fmt.Println("decode:", err)
			return
		}
		if e.Type == "click" {
			clicks++
		}
	}
	fmt.Println("clicks:", clicks)

	enc := json.NewEncoder(os.Stdout)
	enc.SetEscapeHTML(false) // keep <, > and & readable
	enc.SetIndent("", "  ")
	if err := enc.Encode(map[string]any{"clicks": clicks, "note": "a < b & c"}); err != nil {
		fmt.Println("encode:", err)
	}
}

Encoder.Encode schreibt nach jedem Wert einen Zeilenumbruch. Standardmäßig escapen sowohl Marshal als auch Encoder die Zeichen <, > und & als \u003c, \u003e und \u0026, damit sich das JSON gefahrlos in HTML einbetten lässt. SetEscapeHTML(false) schaltet das ab. In HTTP-Handlern sind json.NewDecoder(r.Body).Decode(&v) und json.NewEncoder(w).Encode(v) das übliche Paar.

Eigene Kodierung

Ein Typ kann sein eigenes JSON steuern, indem er json.Marshaler und json.Unmarshaler implementiert. Ein häufiger Fall ist ein Enum mit iota, das als Name erscheinen soll, nicht als Zahl:

package main

import (
	"encoding/json"
	"fmt"
	"strings"
)

type Level int

const (
	Low Level = iota
	High
)

var levelNames = []string{"low", "high"}

func (l Level) MarshalJSON() ([]byte, error) {
	return json.Marshal(levelNames[l])
}

func (l *Level) UnmarshalJSON(b []byte) error {
	var s string
	if err := json.Unmarshal(b, &s); err != nil {
		return err
	}
	for i, name := range levelNames {
		if strings.EqualFold(s, name) {
			*l = Level(i)
			return nil
		}
	}
	return fmt.Errorf("unknown level %q", s)
}

type Alert struct {
	Msg   string `json:"msg"`
	Level Level  `json:"level"`
}

func main() {
	out, _ := json.Marshal(Alert{Msg: "disk full", Level: High})
	fmt.Println(string(out))

	var a Alert
	err := json.Unmarshal([]byte(`{"msg":"cpu","level":"LOW"}`), &a)
	fmt.Printf("%+v %v\n", a, err)

	err = json.Unmarshal([]byte(`{"msg":"cpu","level":"urgent"}`), &a)
	fmt.Println(err)
}

MarshalJSON hat einen Value Receiver und funktioniert damit für Werte und Pointer; UnmarshalJSON braucht einen Pointer Receiver, weil es den Wert ändert. Typen, die nur eine String-Form brauchen, können stattdessen encoding.TextMarshaler (MarshalText) implementieren; damit lassen sie sich auch als Map-Schlüssel verwenden.

Häufige Fehler

Kleingeschriebene Feldnamen. Sie werden still übersprungen.
Einen Wert an Unmarshal übergeben. Es braucht einen Pointer.
Den Fehler ignorieren. Fehlerhaftes JSON und Typkonflikte werden nur darüber gemeldet.
Annehmen, dass Zahlen in map[string]any vom Typ int sind. Sie sind float64.
Erwarten, dass omitempty ein leeres Struct oder eine Null-time.Time weglässt. Nimm omitzero ab Go 1.24 oder einen Pointer.
Sich auf die Reihenfolge der Felder in Maps verlassen. Map-Schlüssel werden bei der Ausgabe sortiert; Struct-Felder behalten ihre Deklarationsreihenfolge.

Häufig gestellte Fragen

Wie konvertiere ich in Go ein Struct in JSON?

Ruf json.Marshal(v) auf, das []byte und einen Fehler zurückgibt. Nur exportierte Felder (Namen mit Großbuchstaben am Anfang) werden aufgenommen. Mit einem Struct Tag wie json:"name" an einem Feld bestimmst du seinen JSON-Schlüssel. Für eingerückte Ausgabe nimm json.MarshalIndent(v, "", " ").

Warum fehlen meine Struct-Felder in der JSON-Ausgabe?

encoding/json sieht nur exportierte Felder. Ein Feld namens name (kleingeschrieben) ist für das Paket unsichtbar, sowohl beim Marshalling als auch beim Unmarshalling. Schreib das Feld groß und setz den JSON-Schlüssel mit einem Tag wie json:"name".

Was macht omitempty bei Go-JSON?

omitempty lässt ein Feld in der Ausgabe weg, wenn es einen leeren Wert enthält: false, 0, "", einen nil-Pointer oder ein nil-Interface oder einen leeren Slice oder eine leere Map. Ein Struct oder time.Time behandelt es nicht als leer. Go 1.24 hat omitzero eingeführt, das jeden Wert weglässt, der der Nullwert seines Typs ist (oder dessen Methode IsZero() true liefert), auch Structs und time.Time.

Wie parse ich in Go JSON mit unbekannter Struktur?

Unmarshalle in map[string]any (oder any). Objekte werden zu map[string]any, Arrays zu []any, Strings zu string, Booleans zu bool und jede Zahl zu float64. Die Werte liest du mit Type Assertions, und mit Decoder.UseNumber bleiben große Ganzzahlen exakt.

Verwandte Konzepte