Project 3: JSON Parser with Tagged Unions

A complete JSON parser using Odin’s tagged unions for the AST, or_return for error handling, and dynamic arrays for collections.

Quick Reference

Attribute Value
Primary Language Odin
Alternative Languages Rust, Go
Difficulty Level 2: Intermediate
Time Estimate 1 week
Knowledge Area Parsing / Type System
Tooling Custom implementation
Prerequisites Understanding of JSON format, basic parsing concepts

What You Will Build

A complete JSON parser using Odin’s tagged unions for the AST, or_return for error handling, and dynamic arrays for collections.

Why It Matters

This project builds core skills that appear repeatedly in real-world systems and tooling.

Core Challenges

  • Designing the Value union → maps to understanding tagged unions
  • Error propagation with or_return → maps to idiomatic error handling
  • Memory management for dynamic data → maps to allocator awareness
  • String handling and escapes → maps to Odin string types

Key Concepts

Real-World Outcome

$ odin run json_parser

Parsing test.json...
{
  "name": "Odin",
  "version": 1.0,
  "features": ["fast", "simple", "powerful"],
  "config": {
    "debug": true,
    "workers": 4
  }
}

Parsed successfully!

AST Structure:
Object {
  "name" → String("Odin")
  "version" → Number(1.0)
  "features" → Array [
    String("fast")
    String("simple")
    String("powerful")
  ]
  "config" → Object {
    "debug" → Bool(true)
    "workers" → Number(4)
  }
}

Type-safe access demo:
  name = "Odin"
  worker_count = 4
  first_feature = "fast"

Error handling demo:
  Input: {"broken": }
  Error at line 1, col 12: Expected value, got '}'

Implementation Guide

  1. Reproduce the simplest happy-path scenario.
  2. Build the smallest working version of the core feature.
  3. Add input validation and error handling.
  4. Add instrumentation/logging to confirm behavior.
  5. Refactor into clean modules with tests.

Milestones

  • Milestone 1: Minimal working program that runs end-to-end.
  • Milestone 2: Correct outputs for typical inputs.
  • Milestone 3: Robust handling of edge cases.
  • Milestone 4: Clean structure and documented usage.

Validation Checklist

  • Output matches the real-world outcome example
  • Handles invalid inputs safely
  • Provides clear errors and exit codes
  • Repeatable results across runs

References

  • Main guide: LEARN_ODIN_PROGRAMMING_LANGUAGE.md
  • “Crafting Interpreters” by Robert Nystrom