schema.go

// Copyright 2025 The Go Authors. All rights reserved.
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.

// Package jsonschema implements JSON schemas.
package jsonschema

import (
	"net/url"

	_ "github.com/ianlancetaylor/jsonschema/draft202012"
	"github.com/ianlancetaylor/jsonschema/types"
)

// Schema is a JSON schema.
// A JSON schema determines whether an instance is valid or not.
//
// If you have a JSON schema in JSON format, unmarshal it into
// a value of this type:
//
//	var s jsonschema.Schema
//	if err := json.Unmarshal(data, &s); err != nil {
//		// handle error
//	}
//
// To create a JSON schema in Go code, use a Builder for the
// schema version you want to use; do not just fill in the Parts slice.
// For the current default JSON schema version use [draft202012.NewBuilder].
//
// You can also infer a JSON schema from a Go type.
// That is, given a Go type, you can build a JSON schema that tests
// that a JSON value can be unmarshaled into a value of that Go type.
// To do this create a Builder for the schema version you want to use,
// and call [builder.Infer] or [builder.InferType].
type Schema = types.Schema

// ResolveOpts is options that may be passed to [Schema.Resolve].
type ResolveOpts = types.ResolveOpts

// ValidateOpts describes validation options that may be passed to
// [Schema.ValidateWithOpts].
// These are uncommon so we use a different method for them.
type ValidateOpts = types.ValidateOpts

// IsValidationError reports whether err is a validation error.
// If this reports true on an error returned by [Schema.Validate],
// it means that the instance does not match the schema.
// If this reports false, it means that there is some error
// in the JSON schema itself.
func IsValidationError(err error) bool {
	return types.IsValidationError(err)
}

// SchemaFromJSON builds a [Schema] from a JSON value that has
// already been parsed. This could be used as something like
//
//	var v any
//	if err := json.Unmarshal(data, &v); err != nil { ... }
//	s, err := schema.SchemaFromJSON(v)
//
// This can be useful in cases where it's not clear whether the
// JSON encoding contains a schema or not.
//
// The optional schemaID argument is something like [draft202012.SchemaID].
// The optional uri is where the schema was loaded from.
//
// It is normally necessary to call Resolve on the result.
func SchemaFromJSON(schemaID string, uri *url.URL, v any) (*Schema, error) {
	return types.SchemaFromJSON(schemaID, uri, v)
}

// SetDefaultSchema sets the default schema.
// The argument should be something like "draft7" or "draft2020-12".
// This is a global property, as there is no way to pass the desired
// value into the JSON decoder. Callers should use appropriate locking.
// This is mainly for tests.
func SetDefaultSchema(s string) error {
	return types.SetDefaultSchema(s)
}

// SetLoader sets a function to call when resolving a $ref
// to an external schema. This is a global property,
// as there is no way to pass the desired value into the JSON decoder.
// Callers should use appropriate locking.
//
// Note that when unmarshaling user-written schemas,
// the loader function can be called with arbitrary URIs.
// It's probably unwise to simply call [net/http.Get] in all cases.
//
// To fully support JSON schema cross references, the loader should call
// [SchemaFromJSON]. The caller will handle calling [Schema.Resolve].
//
// This returns the old loader function.
// The default loader function is nil, which will produce an
// error for a $ref to an external schema.
func SetLoader(fn func(schemaID string, uri *url.URL) (*Schema, error)) func(string, *url.URL) (*Schema, error) {
	return types.SetLoader(fn)
}