invopop/jsonschema

Use the jsonschema.Reflect function to generate a JSON Schema from any Go type via reflection. The package supports complex types like interface{}, maps, and slices, and adheres to the JSON Schema Draft 2020-12 specification.

Key Features:

• Supports JSON Schema features: minLength, maxLength, pattern, format, etc.
• Supports string and numeric enums.
• Supports custom property fields via the jsonschema_extras struct tag.
• Automatically adds unique Schema IDs based on the Go package URL (can be disabled using the Anonymous option).

Requirements:

• Go version >= 1.24 is required.

import "github.com/invopop/jsonschema"

type TestUser struct {
  ID   int    `json:"id"`
  Name string `json:"name"`
}

schema := jsonschema.Reflect(&TestUser{})

When creating a jsonschema.Reflector instance, you can enable ExpandedStruct. If set to true, the top-level struct will not reference itself in the definitions (it will be rendered inline rather than via a $ref). Note that the type passed to Reflect must be a struct type.

// Example of how ExpandedStruct affects output
type SomeBaseType struct {
	SomeBaseProperty int `json:"some_base_property"` 
	// ...
}

// If ExpandedStruct is true, the top level struct is not a $ref to a definition.

When AddGoComments is called, it builds a CommentMap using fully qualified names as keys. This allows the Reflector to look up descriptions during schema generation.

The key format used in the CommentMap is:

• For Types: {package_path}.{Type_Name}
• For Fields: {package_path}.{Type_Name}.{Field_Name}

Example mapping:

• Package: github.com/acme/api
• Type: User
• Field: Email
• Key: github.com/acme/api.User.Email

To add arbitrary or custom properties to the generated JSON Schema object that are not part of the standard JSON Schema specification, use the jsonschema_extras struct tag. The values provided in the tag are mapped directly to the property in the resulting schema.

Example: jsonschema_extras:"a=b,foo=bar,foo=bar1" will result in a property a with value b, and a property foo with an array ["bar", "bar1"].

type TestUser struct {
  Tags map[string]interface{} `json:"tags,omitempty" jsonschema_extras:"a=b,foo=bar,foo=bar1"` 
}

If your JSON keys differ from your Go struct field names (e.g., using snake_case for APIs), you can provide a mapping function to the Reflector.KeyNamer option.

If a field has an explicit json:"..." tag, the KeyNamer function will receive the value of that tag as the input string instead of the Go field name.

import "github.com/stoewer/go-strcase"

r := new(jsonschema.Reflector)
r.KeyNamer = strcase.SnakeCase

s := r.Reflect(&User{})

You can use the AddGoComments(base, path string) method on a jsonschema.Reflector to parse your Go source files and automatically use existing Go comments as the description field in your JSON schema.

To use this, provide the fully qualified Go module URL as the base argument and the directory path containing the source files as the path argument.

r := new(Reflector)
if err := r.AddGoComments("github.com/invopop/jsonschema", "./"); err != nil {
  // handle error
}
s := r.Reflect(&User{})

Use the Validate() method on an ID to ensure it is a properly formatted URI. The validation checks that:

• The ID is a valid URL.
• It contains a hostname.
• The hostname contains at least one dot (.).
• It has a path.
• The scheme is either http or https.

err := myID.Validate()
if err != nil {
    // handle invalid schema ID
}

Use ReflectFromType to generate a root schema directly from a reflect.Type using default settings.

import (
	"reflect"
	"github.com/invopop/jsonschema"
)

schema := jsonschema.ReflectFromType(reflect.TypeOf(User{})