jsonschematogo

README

jsonschematogo

A customizable JSON Schema to Go struct generator with support for custom extensions and type overrides.

Status

Early Development - This project is in active development and may not do what this README claims.

Overview

jsonschematogo converts JSON Schema definitions into Go struct types with proper JSON tags and type mapping. Inspired by oapi-codegen, it aims to be the JSON Schema equivalent - providing the same level of flexibility and customization for pure JSON Schema workflows that oapi-codegen provides for OpenAPI.

Unlike existing tools like go-jsonschema, jsonschematogo focuses heavily on customization and extensibility, allowing developers to control exactly how their Go types are generated through custom schema extensions.

Key Features

• Custom Type Overrides: Use x-go-type extensions to specify exact Go types
• Schema References: Full support for $ref references between schemas
• Flexible Input: Supports both JSON and YAML schema files
• Modular Architecture: Clean, extensible design for adding new features
• Built on Standards: Uses santhosh-tekuri/jsonschema/v6 for robust JSON Schema parsing

Install With bindown

bindown template-source add jsonschematogo https://github.com/WillAbides/jsonschematogo/releases/latest/download/bindown.yaml
bindown dependency add jsonschematogo --source jsonschematogo

Usage

Command Help

Usage: jsonschematogo <files> ... [flags]

jsonschematogo converts JSON Schema definitions into Go struct types with proper JSON tags and type
mapping.

Arguments:
  <files> ...    JSON/YAML schema files to process

Flags:
  -h, --help             Show context-sensitive help.
  -o, --output=STRING    Output file path (defaults to stdout)
  -p, --package="gen"    Package name for generated Go code
  -v, --version          Output the version and exit

Schema Parsing Options:
  --base-dir=STRING             Base directory for resolving relative schema references
  --url-map=prefix=directory    URL mappings for schema references
  --ca-cert=STRING              CA certificate file for HTTPS connections
  --insecure                    Skip TLS verification for HTTPS connections

Schema References

The generator handles $ref references between schemas. For example, a company.yaml that references person.yaml:

$schema: https://json-schema.org/draft/2020-12/schema
type: object
x-go-type: Company
properties:
  ceo:
    $ref: "person.yaml"
    description: The company's CEO
  name:
    type: string
    description: The company's name

Generate from multiple schemas:

jsonschematogo -o types.go -pkg company person.yaml company.yaml

Advanced Schema Loading

The generator supports advanced schema loading features:

URL Mappings

Map URL prefixes to local directories for better reference resolution:

jsonschematogo --url-map="https://example.com/schemas/=./schemas" \
               --url-map="file:///usr/share/schemas/=./external" \
               schema.yaml

HTTP/HTTPS Support

Load schemas from remote URLs:

jsonschematogo --insecure \
               https://api.example.com/schema.json \
               local-schema.yaml

Base Directory

Set a base directory for resolving relative references:

jsonschematogo --base-dir="/path/to/schemas" \
               --url-map="./=./schemas" \
               schema.yaml

Will generate both Company and Person structs:

package company

type Company struct {
	Ceo  Person `json:"ceo"`
	Name string `json:"name"`
}

type Person struct {
	Age   int    `json:"age"`
	Email string `json:"email"`
	Name  string `json:"name"`
}

Custom Extensions

x-go-type

Override the inferred Go type for any property or schema:

properties:
  timestamp:
    type: string
    x-go-type: time.Time
  userID:
    type: string
    x-go-type: UserID  # Custom type

x-go-type-import

Specify import paths for custom types used with x-go-type:

properties:
  id:
    type: string
    x-go-type: googleuuid.UUID
    x-go-type-import:
      path: github.com/google/uuid
      name: googleuuid

This will generate the necessary import statement and use the qualified type name.

x-go-name

Override the generated Go field name for a property:

properties:
  user_id:
    type: string
    x-go-name: UserID
  api_key:
    type: string
    x-go-name: APIKey

x-go-type-name

Override the generated Go type name for a schema:

type: object
x-go-type-name: CustomTypeName
properties:
  field:
    type: string

Architecture

The generator uses a modular architecture:

• SchemaCompiler: Compiles and validates JSON schemas
• ExtensionHandler: Extracts and processes custom x- extensions
• TypeInferrer: Determines appropriate Go types from schema definitions
• CodeRenderer: Renders the final Go struct code
• GoStructGenerator: Orchestrates the entire generation process

Contributing

This project is in early development. Contributions, ideas, and feedback are welcome!

License

[License TBD]

Alternatives

• atombender/go-jsonschema - The inspiration for this project
• ogen-go/ogen - OpenAPI/JSON Schema code generator