schemago

README

SchemaGo

JSON Schema to Go code generator with first-class union type support.

Overview

schemago is a JSON Schema to Go code generator that correctly handles union types (anyOf/oneOf). Unlike existing generators that degrade unions to interface{}, schemago produces idiomatic Go code with:

• Proper tagged union structs
• Discriminator-based UnmarshalJSON/MarshalJSON
• Nullable pointer types for anyOf [T, null]

Installation

go install github.com/grokify/schemago/cmd/schemago@latest

Usage

Lint Schema for Go Compatibility

Check a JSON Schema for patterns that cause problems in Go code generation:

schemago lint schema.json

Output formats:

schemago lint --output text schema.json   # Human-readable (default)
schemago lint --output json schema.json   # Machine-readable JSON
schemago lint --output github schema.json # GitHub Actions annotations

Exit Codes

Code	Meaning
0	No issues found
1	Errors found (schema has problems)
2	Warnings found but no errors

Lint Checks

Errors

Code	Description
union-no-discriminator	Union (anyOf/oneOf) has no discriminator field
inconsistent-discriminator	Variants use different discriminator field names
missing-const	Union variant lacks const value for discriminator
duplicate-const-value	Multiple variants have the same discriminator value

Warnings

Code	Description
large-union	Union has more than 10 variants
nested-union	Union nested more than 2 levels deep
additional-properties	Union variant has additionalProperties: true

Example

Given this schema with a union that lacks a discriminator:

{
  "$defs": {
    "Response": {
      "anyOf": [
        {"type": "object", "properties": {"data": {"type": "string"}}},
        {"type": "object", "properties": {"error": {"type": "string"}}}
      ]
    }
  }
}

Running schemago lint will report:

[error] $/$defs/Response/anyOf: anyOf union has no discriminator field
  suggestion: Add a const property (e.g., 'type' or 'kind') to each variant with a unique value

Summary: 1 error(s), 0 warning(s)

Fix by adding a discriminator:

{
  "$defs": {
    "Response": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "type": {"const": "success"},
            "data": {"type": "string"}
          }
        },
        {
          "type": "object",
          "properties": {
            "type": {"const": "error"},
            "error": {"type": "string"}
          }
        }
      ]
    }
  }
}

Roadmap

See ROADMAP.md for planned features including:

• schemago generate - Generate Go code from schemas
• Full Oracle Agent Spec compatibility
• OpenAPI 3.1 support

References

• PRD.md - Product requirements
• TRD.md - Technical requirements
• JSON Schema Draft 2020-12
• Oracle Agent Spec

License

MIT License - see LICENSE for details.