Getting started

Optional: teach your coding agent

npx skills add tylergannon/go-gen-jsonschema

The skill gives Codex, Claude Code, and other compatible agents the complete setup, registration, validation, and CI workflow.

1. Add the pinned generator

The recommended installation uses Go’s tool directive. It pins the generator in go.mod, so developers and CI run the same version:

go get -tool github.com/tylergannon/go-gen-jsonschema/gen-jsonschema@latest

2. Define the type and generation command

package contacts

import jsonschema "github.com/tylergannon/go-gen-jsonschema"

//go:generate go tool gen-jsonschema --validate

// Person is a contact extracted from a document.
type Person struct {
    // Full legal name.
    Name string `json:"name"`

    // Email address. Omit when the source does not provide one.
    Email jsonschema.Optional[string] `json:"email,omitzero"`

    // Required key; null means no phone number was supplied.
    Phone jsonschema.Nullable[string] `json:"phone"`
}

Doc comments become schema descriptions, so write them for the model that will produce the JSON.

3. Create the build-tagged registration file

The CLI writes the stubs and can run generation immediately:

go tool gen-jsonschema new \
  -out schema.go \
  -methods 'Person=Schema' \
  --validate \
  --generate
go mod tidy

schema.go is compiled only during generation. The generated jsonschema_gen.go is compiled during normal builds, so the files never define the same methods together.

4. Use the generated schema

schema := Person{}.Schema()
if err := (Person{}).ValidateJSON(llmOutput); err != nil {
    return err
}

Commit schema.go, jsonschema_gen.go, and the entire jsonschema/ directory, including .json.sum files.

Next, choose the field semantics you need in Optional and nullable, or jump to Validation and CI.