gojsonschema

gojsonschema is a pure-Go library that implements the JSON Schema specification for validating JSON documents against a schema. It supports draft-04, draft-06, and draft-07, with automatic draft detection via the $schema keyword or a hybrid mode that merges functionality across drafts when no version is declared.

The library exposes several loader types — reference (file or HTTP URL), raw JSON string, and native Go struct/map — so schemas and documents can come from disk, the network, or in-memory data without extra marshaling steps. Validation results carry structured, typed errors (RequiredError, InvalidTypeError, StringLengthGTEError, and dozens more) with contextual field paths, making it straightforward to build user-facing error messages or feed results into other tooling.

Because it has no runtime dependencies beyond two sibling xeipuuv packages (gojsonpointer and gojsonreference) and testify for tests, it drops cleanly into API servers, config validators, and CLI tools that need to enforce a JSON contract without pulling in a heavier framework.

What You Get

• Support for JSON Schema draft-04, draft-06, and draft-07, with autodetection based on the $schema keyword
• Multiple loader types — file/HTTP references, raw JSON strings, and native Go structs or maps — for both schemas and documents
• A SchemaLoader for registering and resolving multiple interlinked schemas via $id and $ref before compiling
• Optional meta-schema validation so malformed schemas are caught at AddSchema/Compile time instead of failing silently later
• Built-in format checkers for email, hostname, ipv4/ipv6, uri, uuid, date-time, json-pointer, and more
• A customizable locale and template-function system for translating or reformatting validation error messages

Common Use Cases

• Validating incoming JSON request bodies in an HTTP API against a published schema before processing them
• Enforcing the shape of configuration files (YAML/JSON) at application startup, failing fast with field-level errors
• Checking that generated or third-party JSON payloads conform to a contract before they are persisted or forwarded
• Building developer tooling (linters, schema validators, CI checks) that need standards-compliant JSON Schema support in Go

Under The Hood

Architecture The library separates schema compilation from document validation across a small set of collaborating files: schemaLoader.go and schemaPool.go resolve and cache schema documents (including remote $ref fetches) into a schemaPool, schema.go recursively parses a loaded document into a tree of subSchema nodes attached to a Schema struct, and validation.go walks that tree against an input document via validateRecursive, accumulating typed errors into a Result. A schemaReferencePool prevents redundant re-resolution of repeated $ref targets. This produces a clear two-phase pipeline — compile once via NewSchema/SchemaLoader.Compile, then validate many documents cheaply against the same compiled *Schema — and the loader abstraction (JSONLoader interface) is the seam that would need to change if a new input source (e.g. streaming) were added.

Tech Stack Written in plain Go with no external runtime dependencies apart from two sibling libraries from the same author, gojsonpointer and gojsonreference, used respectively for JSON Pointer resolution and URI/reference handling; github.com/stretchr/testify is a test-only dependency. The module targets Go via go.mod with no build tooling beyond go build/go test, and CI (via .travis.yml) exercises Go 1.11 through 1.13, though the library itself uses no version-specific language features and continues to build on modern Go toolchains.

Code Quality The repository has substantial test coverage: schema_test.go, jsonschema_test.go, schemaLoader_test.go, format_checkers_test.go, and utils_test.go, backed by a testdata/ directory organized per draft (draft4, draft6, draft7) plus extra and remotes fixtures, indicating the official JSON Schema test suite is exercised directly. Errors are modeled as a family of typed structs (RequiredError, InvalidTypeError, NumberGTEError, etc.) implementing a common ResultError interface rather than being returned as opaque strings, which gives callers structured access to Type(), Field(), Value(), and Details(). Naming and file organization are consistent and domain-driven (one concern per file: errors.go, format_checkers.go, locales.go, result.go), though the project predates Go modules-era conventions like generics or contextual error wrapping.

What Makes It Unique Unlike many ad-hoc JSON validators, gojsonschema treats draft compliance as a first-class concern: it can autodetect a document’s declared draft version, validate schemas themselves against their meta-schema before use, and mix draft-04/06/07 schemas together via $ref as long as each declares $schema. Its locale system, including custom text/template error-message functions, is more extensive than typical validation libraries, letting consumers localize or reformat error output without forking the library.