schema

Schema

Decode HTTP requests into Go structs with OpenAPI 3.0/3.1 compliance. Define your request structure with struct tags, and Schema handles the rest.

Features

• OpenAPI 3.0/3.1 Compliant - Full support for all parameter serialization styles and locations
• Unified API - Query, path, header, cookie parameters and request bodies in one call
• Multiple Body Formats - JSON, XML, forms, multipart, file uploads
• Performance Optimized - Metadata caching, zero allocations where possible
• Extensible - Custom decoders, unmarshalers, and tag parsers
• Type Safe - Automatic type conversion with validation

Installation

go get github.com/talav/schema

Quick Start

Define your request structure and decode in one line:

package main

import (
    "fmt"
    "net/http"
    "github.com/talav/schema"
)

type CreateUserRequest struct {
    // Path parameter (from router)
    OrgID string `schema:"org_id,location=path"`
    
    // Query parameter
    Version string `schema:"version" default:"v1"`
    
    // Header parameter
    APIKey string `schema:"X-API-Key,location=header"`
    
    // Request body (JSON, XML, or form - auto-detected)
    Body struct {
        Name  string `schema:"name"`
        Email string `schema:"email"`
        Age   int    `schema:"age"`
    } `body:"structured"`
}

func main() {
    // Create codec once, reuse across all requests
    codec := schema.NewDefaultCodec()
    
    http.HandleFunc("/orgs/{org_id}/users", func(w http.ResponseWriter, r *http.Request) {
        // Router params come from your router (chi, gorilla, etc.)
        routerParams := map[string]string{"org_id": "123"}
        
        var req CreateUserRequest
        if err := codec.DecodeRequest(r, routerParams, &req); err != nil {
            http.Error(w, err.Error(), http.StatusBadRequest)
            return
        }
        
        // Request is decoded and validated
        fmt.Fprintf(w, "Creating user %s in org %s\n", req.Body.Name, req.OrgID)
    })
    
    http.ListenAndServe(":8080", nil)
}

Try it:

curl -X POST http://localhost:8080/orgs/acme/users?version=v2 \
  -H "X-API-Key: secret" \
  -H "Content-Type: application/json" \
  -d '{"name": "Alice", "email": "[email protected]", "age": 30}'

Documentation

Full Documentation

Getting Started

• Quick Start Guide - Build your first handler
• Core Concepts - Understand how it works

User Guides

• Parameters - Query, path, header, cookie parameters
• Request Bodies - JSON, XML, forms, file uploads
• Serialization Styles - OpenAPI styles and explode
• Type Conversion - Automatic type handling

Advanced

• Extensibility - Custom decoders and unmarshalers
• Custom Tag Parsers - Extend the metadata system

API Reference

• pkg.go.dev - Complete API documentation

Key Concepts

Parameter Locations

Parameters can be extracted from any part of the HTTP request:

type Request struct {
    ID      string `schema:"id,location=path"`        // /users/{id}
    Search  string `schema:"q,location=query"`        // ?q=golang
    APIKey  string `schema:"X-API-Key,location=header"` // Header: X-API-Key
    Session string `schema:"session,location=cookie"`   // Cookie: session=xyz
}

Learn more about parameters →

Request Bodies

Support for all common body formats with automatic content-type detection:

// JSON, XML, or URL-encoded forms
type JSONRequest struct {
    Body User `body:"structured"`
}

// File upload (small files)
type FileUpload struct {
    File []byte `body:"file"`
}

// File streaming (large files)
type StreamUpload struct {
    File io.ReadCloser `body:"file"`
}

// Multipart forms with files
type FormUpload struct {
    Body struct {
        Title    string        `schema:"title"`
        Document io.ReadCloser `schema:"document"`
    } `body:"multipart"`
}

// Multipart with file metadata (filename, size, content-type)
type MetadataUpload struct {
    Body struct {
        Title    string                `schema:"title"`
        Document *multipart.FileHeader `schema:"document"`
    } `body:"multipart"`
}

Learn more about request bodies →

OpenAPI Serialization Styles

Full support for OpenAPI 3.0/3.1 parameter serialization:

type Request struct {
    // Form style (default): ?ids=1&ids=2 or ?ids=1,2,3
    IDs []int `schema:"ids,style=form"`
    
    // Deep object: ?filter[status]=active&filter[type]=user
    Filter struct {
        Status string `schema:"status"`
        Type   string `schema:"type"`
    } `schema:"filter,style=deepObject"`
    
    // Space delimited: ?tags=go%20api%20http
    Tags []string `schema:"tags,style=spaceDelimited"`
}

Learn more about serialization →

Architecture

Schema consists of four main components:

1. Codec - High-level API orchestrating the pipeline
2. Metadata - Parses and caches struct tags (fast lookups)
3. Decoder - Extracts HTTP parameters into maps
4. Unmarshaler - Converts maps to typed structs (uses mapstructure)

Examples

With Chi Router

import (
    "github.com/go-chi/chi/v5"
    "github.com/talav/schema"
)

func main() {
    codec := schema.NewDefaultCodec()
    r := chi.NewRouter()
    
    r.Get("/users/{id}", func(w http.ResponseWriter, r *http.Request) {
        type Request struct {
            ID   string `schema:"id,location=path"`
            Page int    `schema:"page" default:"1"`
        }
        
        var req Request
        if err := codec.DecodeRequest(r, chi.RouteContext(r.Context()).URLParams, &req); err != nil {
            http.Error(w, err.Error(), http.StatusBadRequest)
            return
        }
        
        // Use req.ID and req.Page
    })
    
    http.ListenAndServe(":8080", r)
}

File Upload with Streaming

type UploadRequest struct {
    Filename string        `schema:"filename"`
    File     io.ReadCloser `body:"file"` // Streams large files
}

func handler(w http.ResponseWriter, r *http.Request) {
    var req UploadRequest
    if err := codec.DecodeRequest(r, nil, &req); err != nil {
        http.Error(w, err.Error(), http.StatusBadRequest)
        return
    }
    defer req.File.Close()
    
    // Stream to disk
    out, _ := os.Create("/uploads/" + req.Filename)
    io.Copy(out, req.File)
    out.Close()
}

Multipart Form with Files

type FormRequest struct {
    Body struct {
        Title       string        `schema:"title"`
        Description string        `schema:"description"`
        Document    io.ReadCloser `schema:"document"`
    } `body:"multipart"`
}

func handler(w http.ResponseWriter, r *http.Request) {
    var req FormRequest
    if err := codec.DecodeRequest(r, nil, &req); err != nil {
        http.Error(w, err.Error(), http.StatusBadRequest)
        return
    }
    defer req.Body.Document.Close()
    
    // Process form + file
}

Multipart with File Metadata

Use *multipart.FileHeader when you need access to filename, size, or content-type before reading:

type UploadRequest struct {
    Body struct {
        Title string                `schema:"title"`
        File  *multipart.FileHeader `schema:"file"`
    } `body:"multipart"`
}

func handler(w http.ResponseWriter, r *http.Request) {
    var req UploadRequest
    if err := codec.DecodeRequest(r, nil, &req); err != nil {
        http.Error(w, err.Error(), http.StatusBadRequest)
        return
    }
    
    // Check metadata before reading
    if req.Body.File.Size > 10<<20 {
        http.Error(w, "file too large", http.StatusRequestEntityTooLarge)
        return
    }
    
    f, _ := req.Body.File.Open()
    defer f.Close()
    io.Copy(os.Stdout, f)
}

Extensibility

Customize behavior with your own decoders and unmarshalers:

// Custom decoder (e.g., add logging)
type LoggingDecoder struct {
    decoder schema.Decoder
}

func (d *LoggingDecoder) Decode(...) (map[string]any, error) {
    log.Println("Decoding request")
    return d.decoder.Decode(...)
}

// Custom unmarshaler (e.g., add validation)
type ValidatingUnmarshaler struct {
    unmarshaler schema.Unmarshaler
}

func (u *ValidatingUnmarshaler) Unmarshal(data map[string]any, result any) error {
    if err := u.unmarshaler.Unmarshal(data, result); err != nil {
        return err
    }
    // Add validation logic
    return validate(result)
}

// Use custom components
metadata := schema.NewDefaultMetadata()
decoder := NewLoggingDecoder(schema.NewDefaultDecoder())
unmarshaler := NewValidatingUnmarshaler(mapstructure.NewDefaultUnmarshaler())
codec := schema.NewCodec(metadata, unmarshaler, decoder)

Learn more about extensibility →

Testing

# Run all tests
go test ./...

# With race detector
go test -race ./...

# With coverage
go test -coverprofile=coverage.out
go tool cover -html=coverage.out

Contributing

Contributions are welcome!

Development Setup

Option 1: Local Go

Requirements: Go 1.18+

git clone https://github.com/talav/schema
cd schema
go mod download
go test ./...

Option 2: Dev Container

If you use VS Code, open the repository and it will prompt to reopen in a dev container with all tools pre-installed.

Making Changes

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Run tests: go test -race ./...
5. Run linter: golangci-lint run (or it runs in CI)
6. Commit with clear messages
7. Push and open a Pull Request

License

MIT License - see LICENSE file for details.

Acknowledgments

Built on top of:

• mapstructure - Flexible struct unmarshaling
• tagparser - Struct tag parsing utilities