Standard Library

Files and JSON

Read and write files, stream data, and encode structured values as JSON.

What you will learn

  • choose whole-file or streaming I/O;
  • encode and decode JSON with explicit structs;
  • close resources and preserve useful errors;

Files provide bytes. JSON turns Go values into a portable text format. The standard library makes both tasks straightforward, but resource ownership and errors still matter.

Read a small file

data, err := os.ReadFile("config.json")
if err != nil {
    return fmt.Errorf("read config: %w", err)
}

fmt.Println(string(data))

os.ReadFile loads the entire file into memory. It is convenient for configuration and other reasonably small files.

Stream a large file

file, err := os.Open("events.log")
if err != nil {
    return err
}
defer file.Close()

scanner := bufio.NewScanner(file)
for scanner.Scan() {
    fmt.Println(scanner.Text())
}
if err := scanner.Err(); err != nil {
    return fmt.Errorf("scan events: %w", err)
}

Always check scanner.Err() after the loop. The default scanner has a token-size limit; increase its buffer or use bufio.Reader when lines may be very large.

Write a file

data := []byte("learning Go\n")
if err := os.WriteFile("progress.txt", data, 0o644); err != nil {
    return fmt.Errorf("write progress: %w", err)
}

0o644 is the requested Unix permission mode. Windows handles permissions differently.

For sensitive or critical data, consider restrictive permissions and an atomic-write strategy rather than replacing the destination directly.

Encode JSON

Only exported struct fields are encoded.

type Lesson struct {
    Title     string `json:"title"`
    Completed bool   `json:"completed"`
}

lesson := Lesson{Title: "Slices", Completed: true}
data, err := json.Marshal(lesson)
if err != nil {
    return err
}

fmt.Println(string(data))

Struct tags control JSON field names.

Decode JSON

var lesson Lesson
if err := json.Unmarshal(data, &lesson); err != nil {
    return fmt.Errorf("decode lesson: %w", err)
}

Pass a pointer so the decoder can fill the value.

For streams, use json.Decoder and json.Encoder:

decoder := json.NewDecoder(file)
if err := decoder.Decode(&lesson); err != nil {
    return err
}

When decoding untrusted API input, you may call DisallowUnknownFields to reject fields your struct does not recognise.

Missing and zero values

When a JSON field is missing, the Go field keeps its zero value. If an API must distinguish “missing” from “present with zero,” use a pointer, a custom type, or dedicated validation logic.

Practice

Create a slice of lessons, encode it to progress.json, read it back, and print only incomplete lessons. Add useful context to every returned error.

Summary

  • Whole-file helpers suit bounded small inputs; streams suit large or ongoing data.
  • The code that opens a resource normally owns closing it.
  • JSON zero values cannot always distinguish missing from explicitly zero.

Ready to wrap up?

Mark this complete when you can explain the main idea and finish the practice task.

Copyright © 2026