Examples

The three pillars of our methodology: SPEC, EXAMPLES, IMPLEMENTATION.

Read the Spec

Browse Implementation Notes

API Reference

Basic Types

schema.go

schema.go

//go:build jsonschema
// +build jsonschema

package basictypes

import (
  "encoding/json"

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

// Schema method for SimpleInt.
// This stub will be replaced with a proper implementation during code generation.
// The method signature must match exactly: json.RawMessage
func (SimpleInt) Schema() json.RawMessage {
  panic("not implemented") // This will be replaced by the generator
}

// Schema method for SimpleString.
func (SimpleString) Schema() json.RawMessage {
  panic("not implemented")
}

// Schema method for SimpleFloat.
func (SimpleFloat) Schema() json.RawMessage {
  panic("not implemented")
}

// Schema method for SimpleStruct.
func (SimpleStruct) Schema() json.RawMessage {
  panic("not implemented")
}

// Schema method for TypeInNestedDecl.
func (TypeInNestedDecl) Schema() json.RawMessage {
  panic("not implemented")
}

// Schema method for AnotherNestedType.
func (AnotherNestedType) Schema() json.RawMessage {
  panic("not implemented")
}

// These marker variables register the types with the jsonschema generator.
// Each type that needs a schema must be registered here using NewJSONSchemaMethod.
var (
  // Register SimpleInt for schema generation
  _ = jsonschema.NewJSONSchemaMethod(SimpleInt.Schema)

  // Register SimpleString for schema generation
  _ = jsonschema.NewJSONSchemaMethod(SimpleString.Schema)

  // Register SimpleFloat for schema generation
  _ = jsonschema.NewJSONSchemaMethod(SimpleFloat.Schema)

  // Register SimpleStruct for schema generation
  _ = jsonschema.NewJSONSchemaMethod(SimpleStruct.Schema)

  // Register TypeInNestedDecl for schema generation
  _ = jsonschema.NewJSONSchemaMethod(TypeInNestedDecl.Schema)

  // Register AnotherNestedType for schema generation
  _ = jsonschema.NewJSONSchemaMethod(AnotherNestedType.Schema)
)

types.go

types.go

package basictypes

//go:generate gen-jsonschema

// SimpleInt demonstrates a basic integer type that will be represented
// as a number in the JSON schema.
// The description from this comment will be included in the schema.
type SimpleInt int

// SimpleString demonstrates a basic string type that will be represented
// as a string in the JSON schema.
type SimpleString string

// SimpleFloat demonstrates a basic float type that will be represented
// as a number in the JSON schema.
type SimpleFloat float64

// SimpleStruct demonstrates a basic struct with primitive fields.
// Each field can have its own documentation which will be included
// in the schema.
type SimpleStruct struct {
  // ID is a unique identifier for this struct.
  // This comment will be included in the schema description for this field.
  ID SimpleInt `json:"id"`

  // Name is the display name.
  // Multiline comments are supported and will be preserved in the schema.
  Name SimpleString `json:"name"`

  // Score is a numerical value between 0 and 100.
  Score SimpleFloat `json:"score"`

  // Tags are additional metadata for this struct.
  Tags []string `json:"tags,omitempty"`

  // InternalID is not exposed in JSON.
  InternalID string `json:"-"`
}

// NestedTypeDeclaration demonstrates how multiple types can be declared
// in a single type block, which is a common Go pattern.
type (
  // TypeInNestedDecl is a type declared in a group.
  TypeInNestedDecl int

  // AnotherNestedType is another type in the same declaration block.
  AnotherNestedType string
)

Enums

schema.go

schema.go

//go:build jsonschema
// +build jsonschema

package enums

import (
  "encoding/json"

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

// Schema method for Status.
// This stub will be replaced with a proper implementation during code generation.
func (Status) Schema() json.RawMessage {
  panic("not implemented")
}

// Schema method for Priority.
func (Priority) Schema() json.RawMessage {
  panic("not implemented")
}

// Schema method for Task.
func (Task) Schema() json.RawMessage {
  panic("not implemented")
}

// Schema method for SliceOfStatus.
func (SliceOfStatus) Schema() json.RawMessage {
  panic("not implemented")
}

// These marker variables register the types with the jsonschema generator.
var (
  // Register Status for schema generation
  _ = jsonschema.NewJSONSchemaMethod(Status.Schema)

  // Register Priority for schema generation
  _ = jsonschema.NewJSONSchemaMethod(Priority.Schema)

  // Register Task for schema generation
  _ = jsonschema.NewJSONSchemaMethod(Task.Schema)

  // Register SliceOfStatus for schema generation
  _ = jsonschema.NewJSONSchemaMethod(SliceOfStatus.Schema)

  // Mark Status as an enum type
  // This tells the generator to treat Status as an enum and include all defined
  // constant values of this type in the schema.
  _ = jsonschema.NewEnumType[Status]()

  // Mark Priority as an enum type
  _ = jsonschema.NewEnumType[Priority]()
)

types.go

types.go

package enums

//go:generate gen-jsonschema

// Status represents the state of an item in the system.
// This enum type will be represented as a string with a fixed set of possible values.
type Status string

// These constants define the possible values for the Status enum.
// Each constant will be included in the enum schema with its documentation.
const (
  // StatusPending indicates the item is waiting to be processed.
  StatusPending Status = "pending"

  // StatusInProgress indicates the item is currently being processed.
  StatusInProgress Status = "in_progress"

  // StatusCompleted indicates the item has been successfully processed.
  StatusCompleted Status = "completed"

  // StatusFailed indicates the processing of the item has failed.
  StatusFailed Status = "failed"
)

// Priority represents the importance level of an item.
type Priority string

const (
  // PriorityLow indicates minimal urgency.
  PriorityLow Priority = "low"

  // PriorityMedium indicates standard urgency.
  PriorityMedium Priority = "medium"

  // PriorityHigh indicates immediate attention required.
  PriorityHigh Priority = "high"
)

// Task demonstrates a struct that uses enum fields.
// This shows how enum types can be used within other structures.
type Task struct {
  // ID is a unique identifier for the task.
  ID string `json:"id"`

  // Name is the title of the task.
  Name string `json:"name"`

  // Description provides details about the task.
  Description string `json:"description,omitempty"`

  // Status indicates the current state of the task.
  // This will use the Status enum type defined above.
  Status Status `json:"status"`

  // Priority indicates how important this task is.
  Priority Priority `json:"priority"`

  // Tags are additional categorization for the task.
  Tags []string `json:"tags,omitempty"`
}

// SliceOfStatus demonstrates how to use a slice of enum values.
// This type will be represented as an array of enum values in the schema.
type SliceOfStatus []Status

More examples

• View all example folders in the repository: https://github.com/tylergannon/go-gen-jsonschema/tree/main/examples
• v1 options: enums as strings, interfaces, providers, and more.