xsd

README

XSD 1.0 Validator for Go

XSD 1.0 validation for Go with io/fs schema loading and streaming XML validation.

Install

go get github.com/jacoelho/xsd

Quickstart (in-memory schema)

package main

import (
    "fmt"
    "strings"
    "testing/fstest"

    "github.com/jacoelho/xsd"
    "github.com/jacoelho/xsd/errors"
)

func main() {
    schemaXML := `<?xml version="1.0"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
           targetNamespace="http://example.com/simple"
           elementFormDefault="qualified">
  <xs:element name="person">
    <xs:complexType>
      <xs:sequence>
        <xs:element name="name" type="xs:string"/>
        <xs:element name="age" type="xs:integer"/>
      </xs:sequence>
    </xs:complexType>
  </xs:element>
</xs:schema>`

    fsys := fstest.MapFS{
        "simple.xsd": &fstest.MapFile{Data: []byte(schemaXML)},
    }

    schema, err := xsd.LoadWithOptions(fsys, "simple.xsd", xsd.NewLoadOptions())
    if err != nil {
        fmt.Printf("Load schema: %v\n", err)
        return
    }

    xmlDoc := `<?xml version="1.0"?>
<person xmlns="http://example.com/simple">
  <name>John Doe</name>
  <age>30</age>
</person>`

    if err := schema.Validate(strings.NewReader(xmlDoc)); err != nil {
        if violations, ok := errors.AsValidations(err); ok {
            for _, v := range violations {
                fmt.Println(v.Error())
            }
            return
        }
        fmt.Printf("Validate: %v\n", err)
        return
    }

    fmt.Println("Document is valid")
}

SchemaSet API

set := xsd.NewSchemaSet(xsd.NewLoadOptions())
if err := set.AddFS(fsys, "schema-a.xsd"); err != nil {
    // handle
}
if err := set.AddFS(fsys, "schema-b.xsd"); err != nil {
    // handle
}
schema, err := set.Compile()
if err != nil {
    // handle
}
if err := schema.Validate(strings.NewReader(xmlDoc)); err != nil {
    // handle
}

This snippet assumes fsys and xmlDoc are defined as in Quickstart. SchemaSet compiles all added roots into one runtime schema.

Validate from files

package main

import (
    "fmt"

    "github.com/jacoelho/xsd"
    "github.com/jacoelho/xsd/errors"
)

func main() {
    schema, err := xsd.LoadFile("schema.xsd")
    if err != nil {
        fmt.Printf("Load schema: %v\n", err)
        return
    }

    if err := schema.ValidateFile("document.xml"); err != nil {
        if violations, ok := errors.AsValidations(err); ok {
            for _, v := range violations {
                fmt.Println(v.Error())
            }
            return
        }
        fmt.Printf("Validate: %v\n", err)
        return
    }

    fmt.Println("Document is valid")
}

To validate from any fs.FS:

if err := schema.ValidateFSFile(fsys, "document.xml"); err != nil {
    // handle
}

Load options

opts := xsd.NewLoadOptions().
    WithAllowMissingImportLocations(true).
    WithRuntimeOptions(
        xsd.NewRuntimeOptions().
            WithMaxDFAStates(4096).
            WithMaxOccursLimit(1_000_000),
    )

schema, err := xsd.LoadWithOptions(fsys, "schema.xsd", opts)

Options:

• WithAllowMissingImportLocations: when true, imports without schemaLocation are skipped. Missing import files are also skipped when the filesystem returns fs.ErrNotExist.
• WithRuntimeOptions: applies runtime compilation/validation limits from RuntimeOptions.
• WithSchemaMaxDepth / WithSchemaMaxAttrs / WithSchemaMaxTokenSize / WithSchemaMaxQNameInternEntries: schema parser XML limits.
• instance limits (WithInstanceMaxDepth, WithInstanceMaxAttrs, WithInstanceMaxTokenSize, WithInstanceMaxQNameInternEntries) are set on RuntimeOptions.

Compile with Runtime Options

set := xsd.NewSchemaSet(xsd.NewLoadOptions())
if err := set.AddFS(fsys, "schema.xsd"); err != nil {
    // handle
}

schemaA, err := set.Compile()
if err != nil {
    // handle
}

runtimeOpts := xsd.NewRuntimeOptions().
    WithMaxDFAStates(2048).
    WithInstanceMaxDepth(512)
schemaB, err := set.CompileWithRuntimeOptions(runtimeOpts)
if err != nil {
    // handle
}

Loading behavior

• LoadWithOptions accepts any fs.FS; include/import locations resolve relative to the including schema path.
• Includes MUST resolve successfully.
• Imports without schemaLocation are rejected unless WithAllowMissingImportLocations(true) is set.

Validation behavior

• Schema.Validate is safe for concurrent use.
• Validation is streaming; the document is not loaded into a DOM.
• Instance-document schema hints (xsi:schemaLocation, xsi:noNamespaceSchemaLocation) are ignored.

Error handling

Schema.Validate returns errors.ValidationList for validation failures, XML parsing failures, and validation calls made without a loaded schema. Schema.ValidateFile can return file I/O errors before validation starts.

Each errors.Validation includes:

• Code (W3C codes like cvc-elt.1, or local codes like xsd-schema-not-loaded)
• Message
• Path (best-effort instance path)
• Line and Column when available
• Expected and Actual when available

Constraints and limits

• XSD 1.0 only.
• No HTTP imports.
• Regex patterns must be compatible with Go's regexp.
• xs:redefine is not supported.
• DateTime parsing uses time.Parse (years 0001-9999; no year 0, BCE, or >9999).
• DTDs and external entity resolution are not supported.
• Instance documents must be UTF-8.

CLI (xmllint)

make xmllint
./bin/xmllint --schema schema.xsd document.xml

Options:

• --schema (required): path to the XSD schema file
• --cpuprofile: write a CPU profile to a file
• --memprofile: write a heap profile to a file

Testing

go test -timeout 60s ./...
make w3c

Architecture

See docs/architecture.md.

License

MIT

Documentation

Overview

Package xsd provides XSD 1.0 schema loading and XML validation backed by io/fs.

Index

• type LoadOptions
  • func NewLoadOptions() LoadOptions
  • func (o LoadOptions) RuntimeOptions() RuntimeOptions
  • func (o LoadOptions) Validate() error
  • func (o LoadOptions) WithAllowMissingImportLocations(value bool) LoadOptions
  • func (o LoadOptions) WithRuntimeOptions(value RuntimeOptions) LoadOptions
  • func (o LoadOptions) WithSchemaMaxAttrs(value int) LoadOptions
  • func (o LoadOptions) WithSchemaMaxDepth(value int) LoadOptions
  • func (o LoadOptions) WithSchemaMaxQNameInternEntries(value int) LoadOptions
  • func (o LoadOptions) WithSchemaMaxTokenSize(value int) LoadOptions
• type QName
• type RuntimeOptions
  • func NewRuntimeOptions() RuntimeOptions
  • func (o RuntimeOptions) Validate() error
  • func (o RuntimeOptions) WithInstanceMaxAttrs(value int) RuntimeOptions
  • func (o RuntimeOptions) WithInstanceMaxDepth(value int) RuntimeOptions
  • func (o RuntimeOptions) WithInstanceMaxQNameInternEntries(value int) RuntimeOptions
  • func (o RuntimeOptions) WithInstanceMaxTokenSize(value int) RuntimeOptions
  • func (o RuntimeOptions) WithMaxDFAStates(value uint32) RuntimeOptions
  • func (o RuntimeOptions) WithMaxOccursLimit(value uint32) RuntimeOptions
• type Schema
  • func LoadFile(path string) (*Schema, error)
  • func LoadWithOptions(fsys fs.FS, location string, opts LoadOptions) (*Schema, error)
  • func (s *Schema) Validate(r io.Reader) error
  • func (s *Schema) ValidateFSFile(fsys fs.FS, path string) (err error)
  • func (s *Schema) ValidateFile(path string) (err error)
• type SchemaSet
  • func NewSchemaSet(opts ...LoadOptions) *SchemaSet
  • func (s *SchemaSet) AddFS(fsys fs.FS, location string) error
  • func (s *SchemaSet) Compile() (*Schema, error)
  • func (s *SchemaSet) CompileWithRuntimeOptions(opts RuntimeOptions) (*Schema, error)
  • func (s *SchemaSet) WithLoadOptions(opts LoadOptions) *SchemaSet

Examples

• LoadWithOptions
• Schema.Validate

Types

type LoadOptions

type LoadOptions struct {
	// contains filtered or unexported fields
}

LoadOptions configures schema loading and default runtime compilation.

func NewLoadOptions

func NewLoadOptions() LoadOptions

NewLoadOptions returns a default, valid load options value.

func (LoadOptions) RuntimeOptions

func (o LoadOptions) RuntimeOptions() RuntimeOptions

RuntimeOptions returns the runtime options embedded in the load options.

func (LoadOptions) Validate

func (o LoadOptions) Validate() error

Validate validates load options values.

func (LoadOptions) WithAllowMissingImportLocations

func (o LoadOptions) WithAllowMissingImportLocations(value bool) LoadOptions

WithAllowMissingImportLocations controls whether imports without schemaLocation are skipped.

func (LoadOptions) WithRuntimeOptions

func (o LoadOptions) WithRuntimeOptions(value RuntimeOptions) LoadOptions

WithRuntimeOptions sets all runtime options in one call.

func (LoadOptions) WithSchemaMaxAttrs

func (o LoadOptions) WithSchemaMaxAttrs(value int) LoadOptions

WithSchemaMaxAttrs sets the schema XML max attributes limit (0 uses default).

func (LoadOptions) WithSchemaMaxDepth

func (o LoadOptions) WithSchemaMaxDepth(value int) LoadOptions

WithSchemaMaxDepth sets the schema XML max depth limit (0 uses default).

func (LoadOptions) WithSchemaMaxQNameInternEntries

func (o LoadOptions) WithSchemaMaxQNameInternEntries(value int) LoadOptions

WithSchemaMaxQNameInternEntries sets the schema QName interning cache size (0 leaves xmlstream default).

func (LoadOptions) WithSchemaMaxTokenSize

func (o LoadOptions) WithSchemaMaxTokenSize(value int) LoadOptions

WithSchemaMaxTokenSize sets the schema XML max token size limit (0 uses default).

type QName

type QName = qname.QName

QName is a public qualified name with namespace and local part.

type RuntimeOptions

type RuntimeOptions struct {
	// contains filtered or unexported fields
}

RuntimeOptions configures runtime compilation and instance XML limits.

func NewRuntimeOptions

func NewRuntimeOptions() RuntimeOptions

NewRuntimeOptions returns a default, valid runtime options value.

func (RuntimeOptions) Validate

func (o RuntimeOptions) Validate() error

Validate validates runtime options values.

func (RuntimeOptions) WithInstanceMaxAttrs

func (o RuntimeOptions) WithInstanceMaxAttrs(value int) RuntimeOptions

WithInstanceMaxAttrs sets the instance XML max attributes limit (0 uses default).

func (RuntimeOptions) WithInstanceMaxDepth

func (o RuntimeOptions) WithInstanceMaxDepth(value int) RuntimeOptions

WithInstanceMaxDepth sets the instance XML max depth limit (0 uses default).

func (RuntimeOptions) WithInstanceMaxQNameInternEntries

func (o RuntimeOptions) WithInstanceMaxQNameInternEntries(value int) RuntimeOptions

WithInstanceMaxQNameInternEntries sets the instance QName interning cache size (0 leaves xmlstream default).

func (RuntimeOptions) WithInstanceMaxTokenSize

func (o RuntimeOptions) WithInstanceMaxTokenSize(value int) RuntimeOptions

WithInstanceMaxTokenSize sets the instance XML max token size limit (0 uses default).

func (RuntimeOptions) WithMaxDFAStates

func (o RuntimeOptions) WithMaxDFAStates(value uint32) RuntimeOptions

WithMaxDFAStates sets the runtime DFA state limit (0 uses default).

func (RuntimeOptions) WithMaxOccursLimit

func (o RuntimeOptions) WithMaxOccursLimit(value uint32) RuntimeOptions

WithMaxOccursLimit sets the runtime maxOccurs compilation limit (0 uses default).

type Schema

type Schema struct {
	// contains filtered or unexported fields
}

Schema wraps a compiled schema with convenience methods.

func LoadFile

func LoadFile(path string) (*Schema, error)

LoadFile loads and compiles a schema from a file path.

func LoadWithOptions

func LoadWithOptions(fsys fs.FS, location string, opts LoadOptions) (*Schema, error)

LoadWithOptions loads and compiles a schema with explicit configuration.

Example

package main

import (
	"fmt"
	"testing/fstest"

	"github.com/jacoelho/xsd"
)

func main() {
	schemaXML := `<?xml version="1.0"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
           targetNamespace="http://example.com/simple"
           elementFormDefault="qualified">
  <xs:element name="message" type="xs:string"/>
</xs:schema>`

	fsys := fstest.MapFS{
		"simple.xsd": &fstest.MapFile{Data: []byte(schemaXML)},
	}

	loaded, err := xsd.LoadWithOptions(fsys, "simple.xsd", xsd.NewLoadOptions())
	if err != nil {
		fmt.Printf("Error: %v\n", err)
		return
	}
	if loaded == nil {
		fmt.Println("Error: schema is nil")
		return
	}
	fmt.Println("Schema loaded successfully")
}

Output:

Schema loaded successfully

func (*Schema) Validate

func (s *Schema) Validate(r io.Reader) error

Validate validates a document against the schema.

Example

package main

import (
	"fmt"
	"strings"
	"testing/fstest"

	"github.com/jacoelho/xsd"
	"github.com/jacoelho/xsd/errors"
)

func main() {
	schemaXML := `<?xml version="1.0"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
           targetNamespace="http://example.com/simple"
           elementFormDefault="qualified">
  <xs:element name="person">
    <xs:complexType>
      <xs:sequence>
        <xs:element name="name" type="xs:string"/>
        <xs:element name="age" type="xs:integer"/>
      </xs:sequence>
    </xs:complexType>
  </xs:element>
</xs:schema>`

	fsys := fstest.MapFS{
		"simple.xsd": &fstest.MapFile{Data: []byte(schemaXML)},
	}

	schema, err := xsd.LoadWithOptions(fsys, "simple.xsd", xsd.NewLoadOptions())
	if err != nil {
		fmt.Printf("Error loading schema: %v\n", err)
		return
	}

	xmlDoc := `<?xml version="1.0"?>
<person xmlns="http://example.com/simple">
  <name>John Doe</name>
  <age>30</age>
</person>`

	if err := schema.Validate(strings.NewReader(xmlDoc)); err != nil {
		if violations, ok := errors.AsValidations(err); ok {
			for _, v := range violations {
				fmt.Printf("Validation: %s\n", v.Error())
			}
			return
		}
		fmt.Printf("Error: %v\n", err)
		return
	}
	fmt.Println("Document is valid")
}

Output:

Document is valid

func (*Schema) ValidateFSFile

func (s *Schema) ValidateFSFile(fsys fs.FS, path string) (err error)

ValidateFSFile validates an XML file from the provided filesystem.

func (*Schema) ValidateFile

func (s *Schema) ValidateFile(path string) (err error)

ValidateFile validates an XML file against the schema.

type SchemaSet

type SchemaSet struct {
	// contains filtered or unexported fields
}

SchemaSet owns schema sources and compiles them into a runtime schema.

func NewSchemaSet

func NewSchemaSet(opts ...LoadOptions) *SchemaSet

NewSchemaSet creates an empty schema set.

func (*SchemaSet) AddFS

func (s *SchemaSet) AddFS(fsys fs.FS, location string) error

AddFS adds one schema root location from fsys.

func (*SchemaSet) Compile

func (s *SchemaSet) Compile() (*Schema, error)

Compile compiles all added schema roots using set load options.

func (*SchemaSet) CompileWithRuntimeOptions

func (s *SchemaSet) CompileWithRuntimeOptions(opts RuntimeOptions) (*Schema, error)

CompileWithRuntimeOptions compiles all added roots with explicit runtime options.

func (*SchemaSet) WithLoadOptions

func (s *SchemaSet) WithLoadOptions(opts LoadOptions) *SchemaSet

WithLoadOptions replaces schema-set load options.