jsonschema

Documentation

Overview

Package jsonschema converts JSON Schema to CUE

JSON Schema data is presented in CUE, so any of the supported encodings that can represent JSON Schema data can be used as a source.

Package jsonschema implements the JSON schema standard.

Mapping and Linking

JSON Schema are often defined in a single file. CUE, on the other hand idiomatically defines schema as a definition.

CUE:

$schema: which schema is used for validation.
$id: which validation does this schema provide.

Foo: _ @jsonschema(sc)
@source(https://...) // What schema is used to validate.

NOTE: JSON Schema is a draft standard and may undergo backwards incompatible changes.

Index

• Constants
• func DefaultMapRef(loc SchemaLoc) (importPath string, path cue.Path, err error)
• func DefaultMapURL(u *url.URL) (string, cue.Path, error)
• func Extract(data cue.InstanceOrValue, cfg *Config) (*ast.File, error)
• type Config
• type SchemaLoc
  • func (loc SchemaLoc) String() string
• type Version
  • func ParseVersion(sv string) (Version, error)
  • func (i Version) String() string

Constants

const (
	// DefaultRootID is used as the absolute base URI for a schema
	// when no value is provided in [Config.ID].
	DefaultRootID     = "https://" + DefaultRootIDHost
	DefaultRootIDHost = "cue.jsonschema.invalid"
)

const DefaultVersion = VersionDraft2020_12

DefaultVersion defines the default schema version used when there is no $schema field and no explicit [Config.DefaultVersion].

Functions

func DefaultMapRef

func DefaultMapRef(loc SchemaLoc) (importPath string, path cue.Path, err error)

DefaultMapRef implements the default logic for mapping a schema location to CUE. It uses a heuristic to map the URL host and path to an import path, and maps the fragment part according to the following:

#                    <empty path>
#/definitions/foo   #foo or #."foo"
#/$defs/foo   #foo or #."foo"

func DefaultMapURL

func DefaultMapURL(u *url.URL) (string, cue.Path, error)

DefaultMapURL implements the default schema ID to import path mapping. It trims off any ".json" suffix and uses the package name "schema" if the final component of the path isn't a valid CUE identifier.

Deprecated: The [Config.MapURL] API is superceded in factor of [Config.MapRef].

func Extract

func Extract(data cue.InstanceOrValue, cfg *Config) (*ast.File, error)

Extract converts JSON Schema data into an equivalent CUE representation.

The generated CUE schema is guaranteed to deem valid any value that is a valid instance of the source JSON schema.

Types

type Config

type Config struct {
	PkgName string

	// ID sets the URL of the original source, corresponding to the $id field.
	ID string

	// JSON reference of location containing schemas. The empty string indicates
	// that there is a single schema at the root. If this is non-empty,
	// the referred-to location should be an object, and each member
	// is taken to be a schema.
	//
	// Examples:
	//  "#/" or "#"                    top-level fields are schemas.
	//  "#/components/schemas"   the canonical OpenAPI location.
	//
	// Note: #/ should technically _not_ refer to the root of the
	// schema: this behavior is preserved for backwards compatibility
	// only. Just `#` is preferred.
	Root string

	// AllowNonExistentRoot prevents an error when there is no value at
	// the above Root path. Such an error can be useful to signal that
	// the data may not be a JSON Schema, but is not always a good idea.
	AllowNonExistentRoot bool

	// Map maps the locations of schemas and definitions to a new location.
	// References are updated accordingly. A returned label must be
	// an identifier or string literal.
	//
	// The default mapping is
	//    {}                     {}
	//    {"definitions", foo}   {#foo} or {#, foo}
	//    {"$defs", foo}         {#foo} or {#, foo}
	//
	// Deprecated: use [Config.MapRef].
	Map func(pos token.Pos, path []string) ([]ast.Label, error)

	// MapURL maps a URL reference as found in $ref to
	// an import path for a CUE package and a path within that package.
	// If this is nil, [DefaultMapURL] will be used.
	//
	// Deprecated: use [Config.MapRef].
	MapURL func(u *url.URL) (importPath string, path cue.Path, err error)

	// NOTE: this method is currently experimental. Its usage and type
	// signature may change.
	//
	// MapRef is used to determine how a JSON schema location maps to
	// CUE. It is used for both explicit references and for named
	// schemas inside $defs and definitions.
	//
	// For example, given this schema:
	//
	// 	{
	// 	    "$schema": "https://json-schema.org/draft/2020-12/schema",
	// 	    "$id": "https://my.schema.org/hello",
	// 	    "$defs": {
	// 	        "foo": {
	// 	            "$id": "https://other.org",
	// 	            "type": "object",
	// 	            "properties": {
	// 	                "a": {
	// 	                    "type": "string"
	// 	                },
	// 	                "b": {
	// 	                    "$ref": "#/properties/a"
	// 	                }
	// 	            }
	// 	        }
	// 	    },
	// 	    "allOf": [{
	// 	        "$ref": "#/$defs/foo"
	// 	    }, {
	// 	        "$ref": "https://my.schema.org/hello#/$defs/foo"
	// 	    }, {
	// 	        "$ref": "https://other.org"
	// 	    }, {
	// 	        "$ref": "https://external.ref"
	//	    }]
	// 	}
	//
	// ... MapRef will be called with the following locations for the
	// $ref keywords in order of appearance (no guarantees are made
	// about the actual order or number of calls to MapRef):
	//
	//	ID                                      RootRel
	//	https://other.org/properties/a          https://my.schema.org/hello#/$defs/foo/properties/a
	//	https://my.schema.org/hello#/$defs/foo  https://my.schema.org/hello#/$defs/foo
	//	https://other.org                       https://my.schema.org/hello#/$defs/foo
	//	https://external.ref                    <nil>
	//
	// It will also be called for the named schema in #/$defs/foo with these arguments:
	//
	//	https://other.org                       https://my.schema.org/hello#/$defs/foo
	//
	// MapRef should return the desired CUE location for the schema with
	// the provided IDs, consisting of the import path of the package
	// containing the schema, and a path within that package. If the
	// returned import path is empty, the path will be interpreted
	// relative to the root of the generated JSON schema.
	//
	// Note that MapRef is general enough to subsume use of [Config.Map] and
	// [Config.MapURL], which are both now deprecated. If all three fields are
	// nil, [DefaultMapRef] will be used.
	MapRef func(loc SchemaLoc) (importPath string, relPath cue.Path, err error)

	// NOTE: this method is currently experimental. Its usage and type
	// signature may change.
	//
	// DefineSchema is called, if not nil, for any schema that is defined
	// within the json schema being converted but is mapped somewhere
	// external via [Config.MapRef]. The invoker of [Extract] is
	// responsible for defining the schema e in the correct place as described
	// by the import path and its relative CUE path.
	//
	// The importPath and path are exactly as returned by [Config.MapRef].
	// If this or [Config.MapRef] is nil this function will never be called.
	// Note that importPath will never be empty, because if MapRef
	// returns an empty importPath, it's specifying an internal schema
	// which will be defined accordingly.
	DefineSchema func(importPath string, path cue.Path, e ast.Expr)

	// Strict reports an error for unsupported features and keywords,
	// rather than ignoring them. When true, this is equivalent to
	// setting both StrictFeatures and StrictKeywords to true.
	Strict bool

	// StrictFeatures reports an error for features that are known
	// to be unsupported.
	StrictFeatures bool

	// StrictKeywords reports an error when unknown keywords
	// are encountered.
	StrictKeywords bool

	// DefaultVersion holds the default schema version to use
	// when no $schema field is present. If it is zero, [DefaultVersion]
	// will be used.
	DefaultVersion Version
	// contains filtered or unexported fields
}

A Config configures a JSON Schema encoding or decoding.

type SchemaLoc

type SchemaLoc struct {
	// ID holds the canonical URI of the schema, as declared
	// by the schema or one of its parents.
	ID *url.URL

	// IsLocal holds whether the schema has been defined locally.
	// If true, then [SchemaLoc.Path] holds the path from the root
	// value, as passed to [Extract], to the schema definition.
	IsLocal bool
	Path    cue.Path
}

SchemaLoc defines the location of schema, both in absolute terms as its canonical ID and, optionally, relative to the root of the value passed to Extract.

func (SchemaLoc) String

func (loc SchemaLoc) String() string

type Version

type Version int

const (
	VersionUnknown Version = iota // unknown
	VersionDraft4                 // http://json-schema.org/draft-04/schema#
	// Note: draft 5 never existed and should not be used.
	VersionDraft6       // http://json-schema.org/draft-06/schema#
	VersionDraft7       // http://json-schema.org/draft-07/schema#
	VersionDraft2019_09 // https://json-schema.org/draft/2019-09/schema
	VersionDraft2020_12 // https://json-schema.org/draft/2020-12/schema

	// Note: OpenAPI stands alone: it's not in the regular JSON Schema lineage.
	VersionOpenAPI // OpenAPI 3.0
)

func ParseVersion

func ParseVersion(sv string) (Version, error)

ParseVersion parses a version URI that defines a JSON Schema version.

func (Version) String

func (i Version) String() string