jsonschema

README

jsonschema

Validation against families of JSON Schema documents, with every failure as a JSON pointer, a keyword and a short message, in a stable order. A layer over santhosh-tekuri/jsonschema/v6 with its own format checkers and an ECMA-262 pattern engine.

Published schema families, such as the Open Charge Alliance's OCPP and OSCP schemas, are sets of files that refer to each other by file name, $id or JSON pointer, and sometimes name a file differently from its $id. This module keeps such a set in memory as added (corrections can be applied to a decoded copy first), resolves the references, validates with santhosh-tekuri/jsonschema/v6, and reports each failure in a form a protocol reply can carry. Every format of JSON Schema 2020-12 is checked by this module's own code, and patterns are read as ECMA-262 regular expressions. A pre-pass (CheckSchemas) refuses schemas that use keywords outside a dialect; the OCA's OCPP dialect is included. No cgo. Written for SigmaM2M, a oneM2M platform, where it validates OCPP 1.6 to 2.1 and OSCP 2.0 messages and its OpenAPI requests.

Features

Feature	Status
Drafts 4, 6, 7, 2019-09 and 2020-12, chosen by each document's $schema (draft-07 when it names none)	yes (the library's)
Schema families: references by $id, by a document added under the whole URL, then by file name; nothing fetched from the network	yes
Failures as pointer, keyword and our message, in a stable order (ValidationError, Translate, Style)	yes
Numbers kept exact (Decode with json.Number; integer accepts any number whose fraction is zero)	yes
format as each draft says: an assertion in drafts 4, 6 and 7, an annotation in 2019-09 and 2020-12; Options.AssertFormat asserts it everywhere; the 2020-12 format-assertion vocabulary is honoured	yes
Formats date-time, date, time (ranges, offsets, leap seconds), duration, email, idn-email, hostname, idn-hostname, ipv4, ipv6, uri, uri-reference, iri, iri-reference, uri-template, json-pointer, relative-json-pointer, uuid, regex, all with our messages	yes
idn-hostname by IDNA2008 (RFC 5891 to 5893): Punycode round trip, derived property, CONTEXTJ and CONTEXTO rules, Bidi rule, after a lookup mapping	yes, see the notes below
pattern, patternProperties and format regex as ECMA-262 with the u flag: lookahead, lookbehind, back references, named groups, \p{...}, pattern modifiers (CompileRegexp); Options.GoRegexp keeps Go's RE2 syntax	yes
contentEncoding, contentMediaType and contentSchema as assertions (Options.AssertContent); annotations by default	yes
Dialects: refuse keywords outside an allowed set before use (Dialect, CheckSchemas, OCA())	yes
Output formats of the specification (flag, basic, detailed)	no: use the library directly
A number with a zero fraction refused as integer in draft-04	no, on purpose: one rule for every draft

Notes on the checkers:

• idn-hostname maps each label as a lookup would before checking it (default-ignorable characters other than the two joiners dropped, then NFKC and case folding). This approximates the UTS 46 mapping table rather than reading it. The IDNA2008 derived property is computed from Go's Unicode tables and golang.org/x/text, not read from the IANA registry, so it follows the Unicode version of the Go release used. The joining types for the CONTEXTJ rules come from golang.org/x/net/idna.
• Patterns that need no lookaround, back reference, multiline anchor or counted repeat above 1000 are translated to Go's RE2 syntax and match in linear time. Others run on a backtracking matcher that follows the ECMA-262 matching rules and gives up, as no match, after MaxSteps steps (about 40 ms on the laptop it was measured on), so a hostile input cannot hold a validator. Case folding under i is simple case folding. \p{Script=...} takes script names (Greek), not four-letter codes (Grek), and Script_Extensions is read as Script. Binary properties are those in Go's tables plus Any, ASCII, Assigned, Alphabetic, Lowercase, Uppercase, Math, ID_Start, ID_Continue and Default_Ignorable_Code_Point; emoji properties are refused at compile.
• email is an RFC 5321 mailbox: dot-string or quoted local part of at most 64 octets, a host name or an IPv4 or IPv6 address literal. Comments, display names and other address literals are refused.

Choosing a Go JSON Schema validator

Compared from each project's source or README at the versions named, in October 2026. Check the projects themselves before relying on a row.

	this module v0.2.0	santhosh-tekuri/jsonschema v6.0.3	kaptinlin/jsonschema v0.9.9	xeipuuv/gojsonschema v1.2.0
What it is	a layer over santhosh-tekuri v6	a validator	a validator	a validator
Drafts	4, 6, 7, 2019-09, 2020-12	4, 6, 7, 2019-09, 2020-12	4, 6, 7, 2019-09, 2020-12	4, 6, 7
Default draft without $schema	7	2020-12	2020-12	not compared
JSON Schema Test Suite	run here, required and optional (below)	run in its CI	not stated in its README	not compared
Formats idn-hostname, idn-email	yes	no checker	not compared	not compared
Patterns	ECMA-262 (u flag), RE2 where possible	Go RE2, or an engine you plug in	not compared	Go RE2
Families with mismatched file names and $id	yes	through a custom loader	not compared	not compared
Failure list in a stable order, own wording	yes	output formats of the specification	its own	its own
Keyword dialect refusal before use	yes	vocabularies (2019-09 and later)	not compared	no
Last release	v0.x	2026-08	2026-08	2019-10

Pick this module when you validate protocol messages against a family of published schemas and need failures you can put in a reply, in the same order every time, or when patterns and formats must follow the specification exactly. Pick santhosh-tekuri/jsonschema/v6 directly when you want the specification's output formats or your own extension vocabularies: it is the engine here. Pick kaptinlin/jsonschema to validate Go structs or to build schemas in code.

Install

go get github.com/cB-Sigma/jsonschema@latest

Requires Go 1.26 or later.

Quick start

import "github.com/cB-Sigma/jsonschema"

set := jsonschema.NewSet()
err := set.Add("meter.json", meterSchema)    // refers to "reading.json"
err = set.Add("reading.json", readingSchema)

err = set.ValidateJSON("meter.json", body)
var v jsonschema.ValidationError
if errors.As(err, &v) {
	for _, e := range v {
		fmt.Println(e.Path, e.Keyword, e.Message) // "/reading/kWh minimum ..."
	}
}

To assert format in 2019-09 and 2020-12 documents too:

set := jsonschema.NewSetWith(jsonschema.Options{AssertFormat: true})

Example and ExampleNewSetWith in example_test.go run these and check their output.

Documentation

API reference: https://pkg.go.dev/github.com/cB-Sigma/jsonschema

Package	What it does
jsonschema (module root)	NewSet, NewSetWith and Options, NewDialectSet, Set.Add, AddValue, Compile, ValidateJSON, Validate, Decode; ValidationError, Translate and Style (the wording of the library's failures, for callers that compile with the library themselves); CompileRegexp and Regexp (ECMA-262 patterns, usable as the library's regexp engine); Dialect, CheckSchemas, OCA()
testsuite (nested module, tests only)	runs the JSON Schema Test Suite against this module

Testing

go test -race ./...

Tests carry // Covers: SIG-... comments: these are requirement IDs of the SigmaM2M project's compliance report and have no meaning outside it. FuzzRegexp checks that a translated pattern matches as the backtracking matcher does; FuzzFormats runs every checker on arbitrary strings.

JSON Schema Test Suite

The JSON-Schema-Test-Suite (MIT) is vendored in the test-only nested module testsuite/, at commit 7de0e6a06031ede80028583dd45d0cd41105ae5b (2026-10-09). Its test runs every case of draft4, draft6, draft7, draft2019-09 and draft2020-12, required and optional, through NewSetWith, Set.Add, Set.Compile, Decode and Set.Validate, with the suite's remotes added to each set under their http://localhost:1234/ URLs. A schema without $schema is given the directory's draft before Add, which is how a caller picks a draft other than the draft-07 default.

Each file runs with the options its tests are written for: the files under optional/format/ with AssertFormat, draft7's optional/content with AssertContent, and every other file, the required format.json tests included, with the defaults (ECMA-262 patterns).

Draft	Required	Optional	Optional, format
draft4	618/618	99/100	291/291
draft6	841/841	106/106	414/414
draft7	929/929	118/118	804/804
draft2019-09	1261/1261	158/158	885/885
draft2020-12	1301/1301	162/162	885/885

v0.1.0 passed 1292/1301 required tests of draft2020-12 (format was always asserted) and failed 841 optional tests (formats not checked, laxer email and URI checkers, Go RE2 patterns, content not asserted).

Run it with cd testsuite && go test -v ./.... The test fails when a test outside testsuite/testdata/known-failures.txt fails, when a listed test passes, or when a listed test is no longer in the suite, for required and optional tests alike. The one listed failure:

Cause	Tests	What it is
integer with zero fraction	1	draft4 optional: 1.0 counts as an integer in every draft, as JSON has one number type; the suite marks this behaviour as language-dependent

The run found and fixed, in v0.1.0, two bugs in this module: a document added under a full URL without an $id (as the suite's remotes are) was not found by that URL, and the time and date-time checks accepted hours, minutes and offsets out of range and refused leap seconds. In v0.2.0 it found that the translation of a failed contentSchema reported the decoded content's failures at the instance's pointers.

Interop tested against

• The JSON Schema Test Suite, above.
• The OCA OSCP 2.0 schemas and OCPP 1.6, 2.0.1 and 2.1 schemas, through SigmaM2M's tests. On 2026-10-06 SigmaM2M's earlier hand-written validator and this module gave identical failure lists, in order, for 146,000 generated OCPP messages (68,113 of them failing) across all OCA schemas.

Related repositories

None. This module has no simulator.

Status

v0.x: the API may change before v1. See CHANGELOG.md.

Contributing

See CONTRIBUTING.md.

Security

See SECURITY.md to report a vulnerability privately.

Licence

Apache-2.0 (see LICENSE and NOTICE). Copyright 2026 Abhinav Gautam.

Documentation

Overview

Package jsonschema validates JSON documents against families of JSON Schema documents (the Open Charge Alliance's OCPP and OSCP schemas) with github.com/santhosh-tekuri/jsonschema/v6, and reports each failure as a JSON pointer, the schema keyword and a short message of our own.

A Set holds a family of schema documents that refer to each other by relative file name ("phase-indicator.json") or JSON pointer ("#/definitions/X", "other.json#/definitions/Y"). References are resolved against the referring document's $id; when no document carries the resolved $id, the document added under that whole URL is used, then the one added under the same file name (some published sets name a file differently from its $id). Each document is validated by the draft its $schema names (draft-04 to 2020-12; draft-07 when it names none).

What this package adds to the library: the documents are kept in memory as added (corrections can be applied to a decoded copy before Add), every format of JSON Schema 2020-12 is checked by our own checkers with our messages (formats.go, uri.go, idna.go), patterns are ECMA-262 regular expressions (ecma.go), failures are listed in a stable order (see Translate), and CheckSchemas walks the schemas before use to refuse keywords outside a dialect (dialect.go).

format is an assertion in drafts 4, 6 and 7 and an annotation in drafts 2019-09 and 2020-12, as those drafts say; Options.AssertFormat asserts it in every draft.

Instances are decoded with json.Number (Decode), so integers keep their precision and "integer" accepts any number whose fraction is zero.

Example

A family of two schema documents that refer to each other by file name; every failure comes back as pointer, keyword and message, in order.

package main

import (
	"errors"
	"fmt"

	"github.com/cB-Sigma/jsonschema"
)

func main() {
	set := jsonschema.NewSet()
	_ = set.Add("meter.json", []byte(`{
		"$schema": "http://json-schema.org/draft-07/schema#",
		"type": "object",
		"properties": {
			"id": {"type": "string", "minLength": 1},
			"reading": {"$ref": "reading.json"}
		},
		"required": ["id", "reading"]
	}`))
	_ = set.Add("reading.json", []byte(`{
		"type": "object",
		"properties": {"kWh": {"type": "number", "minimum": 0}, "at": {"type": "string", "format": "date-time"}},
		"required": ["kWh"]
	}`))

	fmt.Println(set.ValidateJSON("meter.json", []byte(`{"id": "m1", "reading": {"kWh": 12.5}}`)))

	err := set.ValidateJSON("meter.json", []byte(`{"id": "", "reading": {"kWh": -1, "at": "yesterday"}}`))
	var v jsonschema.ValidationError
	if errors.As(err, &v) {
		for _, e := range v {
			fmt.Println(e.Path, e.Keyword)
		}
	}
}

Output:
<nil>
/id minLength
/reading/at format
/reading/kWh minimum

Index

• Constants
• Variables
• func Decode(data []byte) (any, error)
• type CheckContext
  • func (c *CheckContext) Fail(format string, a ...any)
  • func (c *CheckContext) FailAt(pointer, format string, a ...any)
  • func (c *CheckContext) Pointer() string
• type Dialect
  • func OCA() *Dialect
• type Error
  • func (e Error) String() string
• type Keyword
• type Options
• type Regexp
  • func CompileRegexp(src string) (*Regexp, error)
  • func (r *Regexp) MatchString(s string) bool
  • func (r *Regexp) String() string
• type Set
  • func NewDialectSet(d *Dialect) *Set
  • func NewSet() *Set
  • func NewSetWith(o Options) *Set
  • func (s *Set) Add(name string, raw []byte) error
  • func (s *Set) AddValue(name string, root any) error
  • func (s *Set) CheckSchemas(name string, pointers ...string) ([]string, error)
  • func (s *Set) Compile(name string) (*v6.Schema, error)
  • func (s *Set) Names() []string
  • func (s *Set) Validate(name string, instance any) error
  • func (s *Set) ValidateJSON(name string, data []byte) error
• type Style
• type ValidationError
  • func Translate(err error, instance any, st *Style, schemaAt func(loc string) map[string]any) ValidationError
  • func (v ValidationError) Error() string

Examples

• Package
• NewSetWith

Constants

const MaxSteps = 1 << 22

MaxSteps bounds the work of the backtracking matcher for one MatchString. A pattern that needs more steps does not match.

Variables

var Keywords = map[string]bool{
	"type": true, "enum": true, "const": true, "properties": true, "required": true, "additionalProperties": true,
	"patternProperties": true, "propertyNames": true, "minProperties": true, "maxProperties": true, "dependencies": true,
	"items": true, "additionalItems": true, "contains": true, "minItems": true, "maxItems": true, "uniqueItems": true,
	"minimum": true, "maximum": true, "exclusiveMinimum": true, "exclusiveMaximum": true, "multipleOf": true,
	"minLength": true, "maxLength": true, "pattern": true, "format": true, "allOf": true, "anyOf": true, "oneOf": true,
	"not": true, "if": true, "then": true, "else": true, "$ref": true,
	"$schema": true, "$id": true, "$comment": true, "title": true, "description": true, "default": true, "examples": true,
	"definitions": true, "readOnly": true, "writeOnly": true, "contentMediaType": true, "contentEncoding": true,
}

Keywords are the draft-07 keywords (and $schema, $id, $comment, title, description, default, examples, definitions, readOnly, writeOnly and contentMediaType/contentEncoding, which carry no check) that a dialect accepts by default in CheckSchemas.

Functions

func Decode

func Decode(data []byte) (any, error)

Decode parses JSON the way Validate expects instances (numbers as json.Number); trailing data is an error.

Types

type CheckContext

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

CheckContext is what a keyword's Check sees while CheckSchemas walks.

func (*CheckContext) Fail

func (c *CheckContext) Fail(format string, a ...any)

Fail reports a problem with the keyword's value.

func (*CheckContext) FailAt

func (c *CheckContext) FailAt(pointer, format string, a ...any)

FailAt reports a problem at another pointer of the document.

func (*CheckContext) Pointer

func (c *CheckContext) Pointer() string

Pointer is the JSON pointer of the keyword in its document.

type Dialect

type Dialect struct {
	// Keywords adds keywords to those CheckSchemas accepts, with a check
	// of their value.
	Keywords map[string]Keyword

	// Allowed says which keywords CheckSchemas accepts beside those in
	// Keywords; nil accepts the package's Keywords list.
	Allowed func(keyword string) bool

	// ObjectSchemasOnly makes CheckSchemas refuse boolean schemas (other
	// than additionalProperties: false/true, which is a keyword form).
	ObjectSchemasOnly bool
}

A Dialect is what CheckSchemas accepts in a family of schemas: the keywords allowed, and checks of a keyword's value. Validation itself is the library's (see jsonschema.go); a dialect only refuses, before use, schemas the validator would not check as their authors meant. Every field is optional.

func OCA

func OCA() *Dialect

OCA is the dialect of the Open Charge Alliance's OCPP schemas: OCPP 1.6 (draft-04), OCPP 2.0.1 and 2.1 (draft-06). What they use is a subset of draft-07 with the same meaning, plus annotations: "id" (the draft-04 document identifier), "javaType" and "comment". Any other keyword is refused by CheckSchemas, so a later schema that relies on a keyword this package does not implement cannot be checked only halfway. The draft-04 boolean form of exclusiveMinimum/exclusiveMaximum means something else in draft-07 and is refused too.

type Error

type Error struct {
	// Path is the JSON pointer of the failing value in the instance.
	Path string
	// Keyword is the schema keyword that failed ("false" for a false
	// schema, "json" for a document that is not JSON).
	Keyword string
	Message string
}

Error is one failed check.

func (Error) String

func (e Error) String() string

type Keyword

type Keyword struct {
	// Check runs when CheckSchemas meets the keyword in a schema, to
	// report a value of the wrong shape.
	Check func(c *CheckContext, schema map[string]any, value any)
}

Keyword is the dialect's treatment of one keyword.

type Options

type Options struct {
	// Dialect, when set, is applied by CheckSchemas (see NewDialectSet).
	Dialect *Dialect

	// AssertFormat makes "format" an assertion in every draft. Without
	// it, format is an assertion in drafts 4, 6 and 7, and an annotation
	// in drafts 2019-09 and 2020-12 unless the document's meta-schema
	// requires the format-assertion vocabulary (2020-12) or the format
	// vocabulary (2019-09). Unknown formats are never asserted.
	AssertFormat bool

	// AssertContent makes contentEncoding (base64) and contentMediaType
	// (application/json) assertions, and contentSchema with them (2019-09
	// and later). Without it they are annotations.
	AssertContent bool

	// GoRegexp reads "pattern", "patternProperties" and format "regex"
	// with Go's regexp syntax (RE2), as v0.1 did, instead of ECMA-262
	// (CompileRegexp).
	GoRegexp bool
}

Options choose how a Set made by NewSetWith validates. The zero value is what NewSet gives.

type Regexp

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

Regexp is an ECMA-262 regular expression, read with the u flag (code points, strict escapes), as JSON Schema's "pattern", "patternProperties" and format "regex" use them.

A pattern without lookaround, back references, multiline anchors or counted repeats above 1000 is translated to Go's regexp (RE2) syntax and matched in linear time; the ECMA-262 meaning of \s, ".", "$", \cX, empty classes and the rest is kept by the translation. Any other pattern is matched by a backtracking matcher that follows ECMA-262's matching rules, lookbehind included; a match that takes more than a fixed number of steps (see MaxSteps) is reported as no match.

func CompileRegexp

func CompileRegexp(src string) (*Regexp, error)

CompileRegexp parses an ECMA-262 regular expression (with the u flag) and refuses one the specification refuses: unknown escapes such as \a, inline flag groups such as (?i), Python's (?P<name>), ranges out of order, a quantifier with nothing to repeat, references to groups that do not exist, and unknown Unicode properties.

func (*Regexp) MatchString

func (r *Regexp) MatchString(s string) bool

MatchString reports whether the pattern matches anywhere in s.

func (*Regexp) String

func (r *Regexp) String() string

String returns the source of the pattern.

type Set

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

Set is a family of schema documents. It is safe for concurrent use once every document is added.

func NewDialectSet

func NewDialectSet(d *Dialect) *Set

NewDialectSet returns an empty set whose CheckSchemas applies the dialect; it is NewSetWith(Options{Dialect: d}).

func NewSet

func NewSet() *Set

NewSet returns an empty set. format is asserted in drafts 4, 6 and 7 only (see Options.AssertFormat).

func NewSetWith

func NewSetWith(o Options) *Set

NewSetWith returns an empty set with the options.

Example

In a 2020-12 document format is an annotation unless the set asserts it; patterns are ECMA-262.

package main

import (
	"fmt"

	"github.com/cB-Sigma/jsonschema"
)

func main() {
	schema := []byte(`{
		"$schema": "https://json-schema.org/draft/2020-12/schema",
		"type": "string",
		"format": "hostname",
		"pattern": "^(?!-)[a-z0-9.-]+$"
	}`)
	for _, assert := range []bool{false, true} {
		set := jsonschema.NewSetWith(jsonschema.Options{AssertFormat: assert})
		_ = set.Add("host.json", schema)
		fmt.Println(assert, set.ValidateJSON("host.json", []byte(`"gw..example"`)))
	}
}

Output:
false <nil>
true /: gw..example is not a host name

func (*Set) Add

func (s *Set) Add(name string, raw []byte) error

Add parses a schema document and adds it under name (its file name).

func (*Set) AddValue

func (s *Set) AddValue(name string, root any) error

AddValue adds a schema document that is already decoded (map[string]any, []any, string, bool, nil and json.Number values), for instance one read from YAML.

func (*Set) CheckSchemas

func (s *Set) CheckSchemas(name string, pointers ...string) ([]string, error)

CheckSchemas walks the schemas at the given JSON pointers of document name, and every schema they contain or reference, before any validation: keywords the dialect does not allow are refused, each keyword's Check runs, references must resolve, and a schema must not reach itself through $ref, allOf, anyOf, oneOf, not, if, then or else alone (validating it would never reach a value). Errors carry pointers into the documents. It returns the pointers of the schemas it visited in document name.

func (*Set) Compile

func (s *Set) Compile(name string) (*v6.Schema, error)

Compile compiles the named document (and what it references) once, so that a schema the library refuses is reported before any validation. The first call freezes the set.

func (*Set) Names

func (s *Set) Names() []string

Names lists the documents in the set.

func (*Set) Validate

func (s *Set) Validate(name string, instance any) error

Validate checks an instance decoded with Decode (or any value built of map[string]any, []any, string, bool, nil, json.Number and float64). A failed check is a ValidationError; a schema that cannot be compiled is another error.

func (*Set) ValidateJSON

func (s *Set) ValidateJSON(name string, data []byte) error

ValidateJSON decodes data and validates it against the named document.

type Style

type Style struct {
	// Bound prints the limit of minimum, maximum and the exclusive bounds
	// (default: eight decimals); Multiple prints multipleOf's divisor
	// (default: a fraction such as 1/100).
	Bound, Multiple func(*big.Rat) string
	// Pattern starts the message of a failed pattern (default "does not
	// match "); the pattern follows.
	Pattern string
	// ClosestBranch adds, after an anyOf or oneOf that no branch passes,
	// the failures of the branch with the fewest, each message starting
	// "(closest branch) ".
	ClosestBranch bool
	// Max caps the failures listed (0: no cap).
	Max int
	// Last lists keywords whose failures at a location come after every
	// other failure there and below it, in this order.
	Last []string
}

Style is how Translate words its messages. The zero value is the wording of a Set.

type ValidationError

type ValidationError []Error

ValidationError lists every failed check of one validation.

func Translate

func Translate(err error, instance any, st *Style, schemaAt func(loc string) map[string]any) ValidationError

Translate turns a validation failure of github.com/santhosh-tekuri/jsonschema/v6 into a ValidationError: one Error per failed check, with our messages, listed depth first by instance location (members by name, items by index), and at one location in keyword order: type, enum, const, the object, array, string and number keywords, then dependencies, contains, anyOf, oneOf and not. Failures under allOf, $ref, if/then/else and propertyNames are listed where they occur; anyOf and oneOf report one failure each (with the closest branch if the style asks). schemaAt, when not nil, finds a schema object by the location the library reports, to name multiple types in the schema's order. Any other error is returned as nil.

func (ValidationError) Error

func (v ValidationError) Error() string