JSON Schema in Go: Google's Official Package Guide

Why Google Built a New JSON Schema Package for Go

Google's Go team needed a complete JSON Schema implementation to build the official MCP Go SDK, and none of the existing open-source packages delivered all four capabilities they required: schema creation, serialization, validation, and inference from Go types. Rather than patch together multiple libraries, Jonathan Amsterdam and Sam Thanawalla built jsonschema-go from scratch with a stdlib-only dependency tree.

The existing Go ecosystem had solid options for individual tasks, but each left significant gaps. Understanding these gaps explains why a new package was necessary and why adoption has been rapid.

The Feature Gap in Existing Go Libraries

The Go team evaluated four established packages against the four core capabilities any production system needs from a JSON Schema library:

In enterprise projects, you typically need all four. You define schemas programmatically in code, generate them from your Go structs to keep contracts synchronized, serialize them for API documentation, and validate incoming payloads at runtime. Having to combine invopop for inference with santhosh-tekuri for validation introduces version conflicts, inconsistent behavior, and maintenance overhead that compounds across dozens of microservices.

Google's decision to build with zero external dependencies means the package relies exclusively on Go's standard library. In our experience delivering custom web development solutions and building large-scale Go systems, this design choice directly reduces supply chain risk and simplifies dependency audits - two factors that enterprise clients consistently prioritize. With 85% of enterprises planning to increase microservice adoption, having a validation library with no transitive dependencies means one fewer vector in your software supply chain to monitor and audit.

Core Architecture: How jsonschema-go Works Under the Hood

The package follows a compile-then-validate pattern where you define a Schema struct, resolve it once at application startup, and then validate repeatedly with near-zero cost per request. This is the exact pattern that high-throughput Go services need - compile expensive operations into a reusable object that handles concurrent validation across goroutines safely.

Schema Definition via Go Structs

Schemas in jsonschema-go are plain Go struct literals that map directly to the JSON Schema specification. You construct them in code with full type safety, catching schema definition errors at compile time rather than at runtime.

var orderSchema = &jsonschema.Schema{
    Type: "object",
    Properties: jsonschema.Properties{
        "order_id":    {Type: "string", MinLength: jsonschema.Ptr(1)},
        "customer_id": {Type: "integer", Minimum: jsonschema.Ptr(1.0)},
        "items": {
            Type:     "array",
            MinItems: jsonschema.Ptr(1),
            Items:    &jsonschema.Schema{
                Type: "object",
                Properties: jsonschema.Properties{
                    "sku":      {Type: "string"},
                    "quantity": {Type: "integer", Minimum: jsonschema.Ptr(1.0)},
                    "price":    {Type: "number", Minimum: jsonschema.Ptr(0.01)},
                },
                Required: []string{"sku", "quantity", "price"},
            },
        },
        "shipping_address": {Type: "string"},
    },
    Required: []string{"order_id", "customer_id", "items"},
}

This approach eliminates the need to load schema definitions from external JSON files. The schema lives next to the code it validates, making it easier to review changes in pull requests and trace validation rules back to business requirements. When a product manager asks "where is the validation for the order amount?" the answer is a specific line in a Go file, not a JSON document buried in a config directory.

Nested schemas and $ref references let you compose complex validation rules from reusable building blocks. A shared address schema, for example, can be referenced by both customer registration and order creation endpoints without duplication. The package resolves these references during the Resolve() step, so the runtime validation path never follows reference chains.

Compile Once, Validate Many

The two-step process separates expensive schema compilation from fast validation execution. Schema.Resolve() validates the schema itself, resolves all $ref references, and returns a Resolved object. This resolved object is safe for concurrent use and performs validation without any additional allocations for the schema structure.

// At startup - compile once
resolved, err := orderSchema.Resolve()
if err != nil {
    log.Fatalf("invalid schema: %v", err)
}

// Per request - validate many times concurrently
func validateOrder(data []byte) error {
    var value any
    if err := json.Unmarshal(data, &value); err != nil {
        return fmt.Errorf("invalid JSON: %w", err)
    }
    return resolved.Validate(value)
}

In production microservices handling thousands of requests per second, this separation is critical. We compile all API schemas during service initialization and store the Resolved objects in a registry. Each incoming request hits only the fast validation path, keeping latency predictable under load. On a recent client project processing 15,000 order events per second, the validation step added less than 50 microseconds per payload - invisible compared to network and database latency.

The package supports both JSON Schema Draft 2020-12 and Draft-07, with Draft 2020-12 introducing improvements like prefixItems replacing additionalItems and $dynamicRef for more flexible schema composition. For new projects, Draft 2020-12 is the recommended choice.

Schema Inference from Go Types with For[T]()

The generic function For[T]() auto-generates a complete JSON Schema from any Go struct by reading json and jsonschema struct tags. This keeps your schema definitions synchronized with your Go types automatically - when a developer adds a field to the struct, the schema updates without any manual intervention.

In enterprise codebases with dozens of API endpoints, schema drift is a common source of production bugs. A struct field gets renamed, but someone forgets to update the corresponding schema file. For[T]() eliminates this entire category of errors by making the Go type definition the single source of truth.

type CreateOrderRequest struct {
    OrderID    string      `json:"order_id" jsonschema:"unique order identifier"`
    CustomerID int64       `json:"customer_id" jsonschema:"customer account ID"`
    Items      []OrderItem `json:"items" jsonschema:"at least one item required"`
    Priority   string      `json:"priority,omitzero" jsonschema:"standard or express"`
    Notes      string      `json:"notes,omitempty"`
}

type OrderItem struct {
    SKU      string  `json:"sku"`
    Quantity int     `json:"quantity"`
    Price    float64 `json:"price"`
}

// Generate schema from the struct
schema, err := jsonschema.For[CreateOrderRequest](nil)
if err != nil {
    log.Fatal(err)
}

Go Type to JSON Schema Mapping

The inference engine maps Go's type system to JSON Schema types following predictable rules. Understanding this mapping helps you design structs that produce exactly the schemas you need.

Pointer types like *string produce nullable schemas, and embedded structs get flattened into the parent schema's properties. The omitzero tag (introduced in Go 1.24) marks fields as optional in the generated schema, while fields without this tag become required. This level of control means you can express complex API contracts purely through Go type definitions.

In practice, this inference capability transforms how teams document their APIs, contributing to a stronger technical SEO foundation through accurate, machine-readable contracts. Instead of maintaining separate OpenAPI or JSON Schema files that inevitably drift from the actual Go types, the schema becomes a computed artifact. When you serialize the inferred schema to JSON and serve it as part of your API documentation, clients always see the current contract - never a stale version from a forgotten documentation update.

API Request Validation in Go Microservices

Compiling your API schemas at service startup and validating every incoming request before it reaches business logic catches malformed data at the boundary - where fixing a bad payload takes seconds, not hours of production debugging. This pattern is the foundation of reliable Go microservices, and jsonschema-go makes it straightforward to implement as HTTP middleware.

Building a Validation Middleware

The middleware pattern compiles schemas once during initialization and validates each request body before it reaches your handler. The Resolved object is goroutine-safe, so a single instance serves all concurrent requests without locking.

type SchemaRegistry struct {
    schemas map[string]*jsonschema.Resolved
}

func NewSchemaRegistry() *SchemaRegistry {
    registry := &SchemaRegistry{
        schemas: make(map[string]*jsonschema.Resolved),
    }

    // Register schemas at startup
    registry.MustRegister("POST /api/orders", jsonschema.MustFor[CreateOrderRequest]())
    registry.MustRegister("POST /api/customers", jsonschema.MustFor[CreateCustomerRequest]())
    registry.MustRegister("PATCH /api/orders/{id}", jsonschema.MustFor[UpdateOrderRequest]())

    return registry
}

func (r *SchemaRegistry) MustRegister(endpoint string, schema *jsonschema.Schema) {
    resolved, err := schema.Resolve()
    if err != nil {
        panic(fmt.Sprintf("invalid schema for %s: %v", endpoint, err))
    }
    r.schemas[endpoint] = resolved
}

func (r *SchemaRegistry) ValidationMiddleware(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, req *http.Request) {
        key := req.Method + " " + req.Pattern
        resolved, ok := r.schemas[key]
        if !ok {
            next.ServeHTTP(w, req)
            return
        }

        body, err := io.ReadAll(req.Body)
        if err != nil {
            http.Error(w, "failed to read body", http.StatusBadRequest)
            return
        }
        req.Body = io.NopCloser(bytes.NewReader(body))

        var value any
        if err := json.Unmarshal(body, &value); err != nil {
            http.Error(w, "invalid JSON", http.StatusBadRequest)
            return
        }

        if err := resolved.Validate(value); err != nil {
            writeValidationError(w, err)
            return
        }

        next.ServeHTTP(w, req)
    })
}

This registry approach scales cleanly. When a new endpoint is added, the developer registers its schema in one place. If the schema is invalid, the service fails fast at startup rather than accepting bad data in production. In a fleet of 30 microservices - whether serving a SaaS product or an appliance repair service platform - this pattern means every service validates its own API boundaries independently, without relying on an external API gateway to catch malformed requests.

Handling Validation Errors in Production

The validation errors returned by jsonschema-go contain field-level details that translate directly into developer-friendly API error responses. Instead of returning a generic "bad request," you can tell the caller exactly which field failed and why.

func writeValidationError(w http.ResponseWriter, err error) {
    w.Header().Set("Content-Type", "application/json")
    w.WriteHeader(http.StatusUnprocessableEntity)

    response := map[string]any{
        "error":  "validation_failed",
        "detail": err.Error(),
    }

    json.NewEncoder(w).Encode(response)
}

In our production systems, we also log validation failures with structured fields - endpoint, error details, and a hash of the payload. Combined with a well-planned digital marketing strategy, this gives the operations team visibility into API misuse patterns without exposing sensitive request data. Over time, these logs reveal which clients send malformed requests most often, guiding documentation improvements and SDK updates.

Contract Testing Between Microservices

Using JSON Schema as the contract between producer and consumer services means schema changes break tests before they break production. According to industry research, integration bugs discovered in production cost organizations an average of $8.2 million annually - contract testing catches these issues during CI, when the fix is a code change rather than an incident response.

Schema-Driven Contract Tests

The producer service generates its contract schema from the Go struct using For[T](). Consumer services validate their expected payloads against this schema in their test suites. When the producer changes a field type or removes a required property, the consumer's tests fail immediately.

// Producer: export schema as part of the service contract
func ExportOrderEventSchema() (*jsonschema.Schema, error) {
    return jsonschema.For[OrderCreatedEvent](nil)
}

// Consumer: test that expected payloads match the contract
func TestOrderEventContract(t *testing.T) {
    schema, err := orderservice.ExportOrderEventSchema()
    if err != nil {
        t.Fatal(err)
    }

    resolved, err := schema.Resolve()
    if err != nil {
        t.Fatal(err)
    }

    // Sample payload the consumer expects to receive
    payload := map[string]any{
        "event_type":  "order.created",
        "order_id":    "ord-12345",
        "customer_id": 42,
        "total":       99.99,
        "items":       []any{map[string]any{"sku": "WIDGET-1", "qty": 2}},
    }

    if err := resolved.Validate(payload); err != nil {
        t.Errorf("contract violation: %v", err)
    }
}

Because For[T]() generates the schema directly from Go types, there is no separate schema file to maintain. The contract evolves with the code. In CI pipelines, these contract tests run before deployment, ensuring that no service ships a breaking change without the consumer being updated first.

For teams managing 10 or more microservices, this approach replaces fragile integration test environments with fast, deterministic schema checks. We have seen contract testing reduce the time spent debugging cross-service issues by up to 70% on client projects, because the root cause is identified in the test output rather than in production logs.

Schema versioning becomes straightforward with this approach. When a producer needs to add a new required field, the contract test in every consumer immediately fails. The team reviews the change, updates their handling code, and the test goes green - all before anything reaches staging. For event-driven architectures using Kafka or NATS, this pattern is especially valuable because message schema mismatches can cause silent data corruption that only surfaces days later in downstream reports.

Configuration Validation with JSON Schema

Validating configuration files against schemas generated from your Go config structs at deploy time catches misconfigurations before they cause runtime failures. Every experienced Go developer has debugged a service that crashed minutes after deployment because of a missing or misspelled config field - schema validation at startup eliminates this entirely.

type ServiceConfig struct {
    Port        int      `json:"port" jsonschema:"HTTP port, 1024-65535"`
    DatabaseURL string   `json:"database_url" jsonschema:"PostgreSQL connection string"`
    CacheTTL    int      `json:"cache_ttl" jsonschema:"cache TTL in seconds"`
    AllowedCORSOrigins []string `json:"allowed_cors_origins,omitzero"`
    LogLevel    string   `json:"log_level,omitzero" jsonschema:"debug, info, warn, or error"`
    MaxBodySize int      `json:"max_body_size,omitzero" jsonschema:"max request body in bytes"`
}

func LoadAndValidateConfig(path string) (*ServiceConfig, error) {
    schema, err := jsonschema.For[ServiceConfig](nil)
    if err != nil {
        return nil, fmt.Errorf("schema generation failed: %w", err)
    }

    resolved, err := schema.Resolve()
    if err != nil {
        return nil, fmt.Errorf("schema resolution failed: %w", err)
    }

    data, err := os.ReadFile(path)
    if err != nil {
        return nil, fmt.Errorf("read config: %w", err)
    }

    var raw any
    if err := json.Unmarshal(data, &raw); err != nil {
        return nil, fmt.Errorf("parse config: %w", err)
    }

    if err := resolved.Validate(raw); err != nil {
        return nil, fmt.Errorf("config validation failed: %w", err)
    }

    var cfg ServiceConfig
    if err := json.Unmarshal(data, &cfg); err != nil {
        return nil, fmt.Errorf("decode config: %w", err)
    }

    return &cfg, nil
}

The ApplyDefaults feature adds another layer of convenience. When your schema defines default values, Resolved.ApplyDefaults() fills in missing fields before your application reads them. This means your config files can stay minimal while the schema ensures all required values are present.

We run this same validation in CI pipelines against environment-specific config files. A staging config that is missing a required field fails the pipeline before it ever reaches the cluster. This shift-left approach to configuration validation has prevented multiple production incidents on projects where config changes are frequent.

For teams managing multiple environments - development, staging, production, and per-client configurations such as real estate platform deployments - this validation pattern catches the most common deployment failures: a missing database URL in the new production config, a port number that conflicts with another service, or a cache TTL set to zero because someone forgot to update it from the test defaults. Each of these would cause a runtime error that is trivial to prevent with schema validation at deploy time.

JSON Schema for LLM Tool Integration and MCP

The Model Context Protocol (MCP) uses JSON Schema to define tool inputs and outputs, and Google's jsonschema-go is already the foundation of the official MCP Go SDK. This means any Go service that exposes tools to LLMs through MCP uses this package under the hood to validate AI-generated function calls against their expected schemas.

MCP is the emerging standard for connecting large language models to external tools and data sources. When an LLM decides to call a tool, MCP uses JSON Schema to describe what inputs that tool accepts. The LLM generates a JSON payload matching the schema, and the MCP runtime validates it before execution. Without reliable schema validation, an LLM could send malformed inputs that crash your service or produce incorrect results.

From Go Struct to AI Tool Definition

Defining MCP tools in Go follows the same struct-based pattern as API validation. You define your tool's input as a Go struct, and For[T]() generates the JSON Schema that MCP uses to constrain LLM-generated calls.

type SearchProductsInput struct {
    Query      string   `json:"query" jsonschema:"search query text"`
    Category   string   `json:"category,omitzero" jsonschema:"product category filter"`
    MinPrice   float64  `json:"min_price,omitzero" jsonschema:"minimum price in USD"`
    MaxPrice   float64  `json:"max_price,omitzero" jsonschema:"maximum price in USD"`
    InStock    bool     `json:"in_stock,omitzero" jsonschema:"filter to in-stock items only"`
    MaxResults int      `json:"max_results,omitzero" jsonschema:"maximum results to return"`
}

// The MCP SDK uses For[SearchProductsInput]() internally
// to generate the tool's input schema

The jsonschema struct tag serves double duty here: it provides field descriptions that LLMs read to understand what each parameter does, and it defines validation constraints that catch invalid tool calls before your handler executes. This type-safe chain from Go struct to LLM interaction reduces the surface area for AI integration bugs.

As AI-driven architectures become standard in enterprise systems, the ability to define tool contracts in Go and have them automatically validated against LLM outputs becomes a significant engineering advantage. Teams investing in GEO and AI SEO optimization benefit directly from services that participate reliably in LLM tool ecosystems. The jsonschema-go package positions Go services as first-class participants in the MCP ecosystem, with the same validation rigor that Go developers expect from their API boundaries.

For enterprise teams already building Go microservices, adding MCP tool support becomes an incremental step rather than a separate integration project. The validation middleware you built for API requests and the contract testing patterns from your CI pipeline all use the same jsonschema-go primitives. This consistency across API validation, service contracts, and AI tool definitions simplifies the architecture and reduces the learning curve for developers moving between these domains.

Migration Guide: Moving from Existing Packages

Migrating to jsonschema-go from established packages is straightforward because the API surface maps closely to JSON Schema specification concepts. The primary benefit is consolidation - you replace one or more specialized libraries with a single package that covers all four capabilities while reducing your dependency tree.

From santhosh-tekuri/jsonschema

If you are currently using santhosh-tekuri/jsonschema for validation, you keep the same compile-then-validate pattern. The main gain is adding schema inference and programmatic construction, which santhosh-tekuri does not support.

// Before: santhosh-tekuri (validation only, schema from file)
sch, err := jsonschema.Compile("schema.json")
err = sch.Validate(v)

// After: google/jsonschema-go (validation + inference from Go types)
schema, err := jsonschema.For[MyRequest](nil)
resolved, err := schema.Resolve()
err = resolved.Validate(v)

From xeipuuv/gojsonschema

The xeipuuv package uses a loader-based API where you pass JSON documents for both schema and data. The migration replaces this with direct struct construction, eliminating the need for separate schema files.

// Before: xeipuuv (schema from JSON strings or files)
schemaLoader := gojsonschema.NewStringLoader(schemaJSON)
documentLoader := gojsonschema.NewStringLoader(documentJSON)
result, err := gojsonschema.Validate(schemaLoader, documentLoader)

// After: google/jsonschema-go (schema from Go types)
schema, err := jsonschema.For[MyStruct](nil)
resolved, err := schema.Resolve()
err = resolved.Validate(parsedValue)

From invopop/jsonschema

If you use invopop/jsonschema for inference, the transition adds validation and schema creation that invopop lacks. The struct tag syntax is similar but uses jsonschema for descriptions rather than invopop's custom tags. The key gain is that you can now validate data against the same schemas you infer, closing the loop between schema generation and runtime enforcement.

// Before: invopop (inference only, separate validation library needed)
reflector := jsonschema.Reflector{}
schema := reflector.Reflect(&MyStruct{})
// Cannot validate with this schema - need a second library

// After: google/jsonschema-go (inference + validation in one)
schema, err := jsonschema.For[MyStruct](nil)
resolved, err := schema.Resolve()
err = resolved.Validate(data) // Same library handles both

Limitations to Know Before Adopting

The package is at version v0.4.2 and has not reached v1 stability yet, meaning the API may change in future releases. Three specific limitations are worth evaluating for your use case:

• Regex engine differences: Go's regexp package is used instead of ECMA 262, which means back-references are not supported in pattern constraints. If your schemas rely on back-references, you will need to restructure those patterns.
• Format keyword behavior: The format keyword is recorded in the schema but not enforced during validation. Use pattern instead for string format constraints that must be validated.
• Content keywords: Section 8 keywords like contentMediaType and contentEncoding are stored but ignored during validation.

For most enterprise use cases, these limitations are not blockers. The regex difference is the most common one to encounter, and restructuring patterns from back-references to standard regex is typically a one-time migration effort.

Conclusion

Google's jsonschema-go fills a critical gap in the Go ecosystem by unifying schema creation, serialization, validation, and inference into a single package with zero external dependencies. For enterprise Go teams, this consolidation translates into fewer dependencies to audit, fewer integration points to maintain, and a single API for every JSON Schema operation across your services.

• Unified tooling: One package replaces two or three specialized libraries, reducing dependency management overhead across your microservice fleet
• Type-safe contracts: For[T]() keeps schemas synchronized with Go structs automatically, eliminating schema drift bugs that are expensive to diagnose in production
• Production-ready patterns: The compile-once-validate-many architecture handles high-throughput APIs without adding measurable latency per request
• AI integration foundation: As the backbone of the MCP Go SDK, this package positions Go services for first-class participation in LLM tool ecosystems
• Enterprise validation pipeline: From API boundaries through contract testing to configuration validation, a single library covers the entire data integrity chain

For teams building complex Go microservice architectures that require robust data validation, contract testing between services, and integration with AI tooling - Webdelo delivers production-grade systems designed around these exact patterns. Get in touch to discuss your project.