How omissis/go-jsonschema works
Project type and purpose
• This is a command-line tool (go-jsonschema) that reads one or more JSON Schema files (inputs) and produces Go source files (outputs).
• It’s not a web service or UI; it’s a code-generation utility with a layered internal architecture to parse, validate, model, and emit Go code.
File structure
• Top-level entrypoint: main.go implements CLI flags, parses arguments, hands off to core engine.
• Core libraries under pkg/:
• pkg/cmputil – CLI option parsing utilities
• pkg/schemas – JSON Schema loading, parsing, reference resolution
• pkg/codegen – Go code emitter (models → AST → source)
• pkg/generator – Orchestrates schema→model→formatter→output pipeline
• pkg/mathutils, pkg/types, pkg/yamlutils – supplemental utilities (date/time types, YAML quirks, math helpers)
• Internal helpers under internal/x/text for consistent casing.
• tests/data holds golden JSON+Go fixtures for validation and regeneration.
• Support files: ADRs in docs/arch, build & lint scripts, Dockerfile, GitHub CI workflows.
Key insights from README
• Emphasizes Go workspaces for testing generated code alongside generator logic.
• Usage patterns: single schema → stdout; multiple schemas → multiple packages and files, with inter-schema imports.
• Special built-in types (SerializableDate, SerializableTime) handled by custom code.
a. Main components:
1. CLI Layer (main.go)
2. Schema Loader & Parser (pkg/schemas)
3. Internal Model Builder (intermediate representation of schema)
4. Code Generator (pkg/generator + pkg/codegen)
5. Formatter & Output Writer (pkg/generator/formatter, file I/O)
6. Utility Libraries (text casing, mathutils, yamlutils, types)
7. Test Harness (tests/data + generation_test.go)
b. Relationships & data flow:
• CLI Layer reads flags → passes schema file paths to Schema Loader
• Schema Loader loads JSON/YAML, resolves $ref → produces a parsed schema tree
• Model Builder converts schema tree into an internal data model (pkg/schemas → schema model)
• Generator orchestrates:
• Validates model (validator)
• Feeds model to Codegen Emitter → produces Go AST / source snippets
• Applies formatters (JSON, YAML, Go formatting)
• Output Writer writes .go files to disk, sets package declarations and imports
• Tests load fixtures, invoke CLI or generator API, compare against expected golden files
c. Architectural patterns & principles:
• Pipeline pattern: schema → parse → model → code → format → write
• Separation of concerns: parsing vs. modeling vs. emitting vs. formatting
• Go workspace usage for in-tree testing of generated code
d. Key technologies/frameworks:
• Go (modules, workspaces)
• Standard encoding/json, gopkg.in/yaml.v3
• Cobra or flag package for CLI (built-in flags in main.go)
• Testing: Go’s testing package, golden files pattern
Details to capture
• ADRs folder indicating architecture-decision capture (optional annotation)
• Go workspace boundary (show go.mod + go.work)
• CI/CD flows (optional: GitHub Actions, Docker build)
• Special types handling (SerializableDate/Time) as a side component of the emitter