jsonschema Go Library

The jsonschema library is a Go implementation for JSON Schema validation. Key features include:

• Multi-Draft Support: Supports Draft 4, 6, 7, 2019-09, and 2020-12.
• Cycle Detection: Detects infinite loops in $schema cycles and validation cycles.
• Extensibility: Supports custom $schema URLs, custom regex engines, custom vocabularies, and custom format/content assertions.
• Format Assertions: Includes built-in formats like uuid, email, ipv4, date-time, semver, and more. Note that format assertions must be explicitly enabled for drafts >= 2019-09.
• Content Assertions: Supports contentEncoding (e.g., base64) and contentMediaType (e.g., application/json). These must be explicitly enabled for drafts >= 7.
• Error Handling: Provides introspectable errors with a hierarchy, including an alternative display using # for locating errors.

The jv command-line interface is versioned independently from the library. You can install the latest version using go install.

go install github.com/santhosh-tekuri/jsonschema/cmd/jv@latest

The jv CLI allows you to validate one or more JSON or YAML instances against a schema. It supports standard input via - and can fetch schemas via http(s) URLs.

Usage Pattern: jv [OPTIONS] SCHEMA [INSTANCE...]

Exit Codes:

• 1: Validation errors
• 2: Usage errors

To extend the JSON Schema validator with custom keywords, you must implement the Vocabulary struct. A Vocabulary defines a set of keywords, their syntax, and their semantics.

Key fields in the Vocabulary struct:

• URL: The unique identifier for the vocabulary.
• Schema: A schema used to validate the keywords introduced by this vocabulary.
• Subschemas: A list of SchemaPath locations where subschemas introduced by this vocabulary can be found.
• Compile: A function that takes a *CompilerContext and the keyword object (map[string]any) and returns a SchemaExt implementation. If the object contains no keywords from this vocabulary, return nil.

type Vocabulary struct {
	URL        string
	Schema     *Schema
	Subschemas []SchemaPath
	Compile    func(ctx *CompilerContext, obj map[string]any) (SchemaExt, error)
}

A SchemaPath is a sequence of Position tokens used to locate specific subschemas or data elements within a JSON structure. It allows for both direct access to specific properties or array indices and wildcard-style traversal of entire objects or arrays.

Commonly used tokens within a SchemaPath include:

• Prop: A specific property name in an object (e.g., "name").
• Item: A specific integer index in an array (e.g., 0).
• AllProp (*): A wildcard that matches all properties within an object.
• AllItem ([]): A wildcard that matches all items within an array.

You can use the collect method on a SchemaPath to traverse a JSON value and return a map of all matching locations, where keys are jsonPointers and values are the data found at those locations.

If a JSON schema is missing the $schema property, the compiler uses the latest draft supported by the library. You can force the compiler to use a specific draft version (e.g., Draft4) by calling DefaultDraft on the compiler instance.

compiler := jsonschema.NewCompiler()
compiler.DefaultDraft(jsonschema.Draft4)

The SchemaPath type implements a collect method that traverses a JSON value (any) based on the path's tokens. It returns a map[jsonPointer]any containing all values that match the path.

If the path is empty, it returns the input value itself mapped to the current jsonPointer.

Supported position types:

• Prop(string): Targets a specific key in a map.
• Item(int): Targets a specific index in a slice.
• AllProp{}: Targets all keys in a map (represented by * in string format).
• AllItem{}: Targets all elements in a slice (represented by [] in string format).