github.com/joomcode/cue@v0.4.4-0.20221111115225-539fe3512047/encoding/jsonschema/jsonschema.go (about)

     1  // Copyright 2020 CUE Authors
     2  //
     3  // Licensed under the Apache License, Version 2.0 (the "License");
     4  // you may not use this file except in compliance with the License.
     5  // You may obtain a copy of the License at
     6  //
     7  //     http://www.apache.org/licenses/LICENSE-2.0
     8  //
     9  // Unless required by applicable law or agreed to in writing, software
    10  // distributed under the License is distributed on an "AS IS" BASIS,
    11  // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    12  // See the License for the specific language governing permissions and
    13  // limitations under the License.
    14  
    15  // Package jsonschema implements the JSON schema standard.
    16  //
    17  // Mapping and Linking
    18  //
    19  // JSON Schema are often defined in a single file. CUE, on the other hand
    20  // idiomatically defines schema as a definition.
    21  //
    22  // CUE:
    23  //    $schema: which schema is used for validation.
    24  //    $id: which validation does this schema provide.
    25  //
    26  //    Foo: _ @jsonschema(sc)
    27  //    @source(https://...) // What schema is used to validate.
    28  //
    29  // NOTE: JSON Schema is a draft standard and may undergo backwards incompatible
    30  // changes.
    31  package jsonschema
    32  
    33  import (
    34  	"github.com/joomcode/cue/cue"
    35  	"github.com/joomcode/cue/cue/ast"
    36  	"github.com/joomcode/cue/cue/token"
    37  )
    38  
    39  // Extract converts JSON Schema data into an equivalent CUE representation.
    40  //
    41  // The generated CUE schema is guaranteed to deem valid any value that is
    42  // a valid instance of the source JSON schema.
    43  func Extract(data cue.InstanceOrValue, cfg *Config) (f *ast.File, err error) {
    44  	d := &decoder{cfg: cfg}
    45  
    46  	f = d.decode(data.Value())
    47  	if d.errs != nil {
    48  		return nil, d.errs
    49  	}
    50  	return f, nil
    51  }
    52  
    53  // A Config configures a JSON Schema encoding or decoding.
    54  type Config struct {
    55  	PkgName string
    56  
    57  	// ID sets the URL of the original source, corresponding to the $id field.
    58  	ID string
    59  
    60  	// JSON reference of location containing schema. The empty string indicates
    61  	// that there is a single schema at the root.
    62  	//
    63  	// Examples:
    64  	//  "#/"                     top-level fields are schemas.
    65  	//  "#/components/schemas"   the canonical OpenAPI location.
    66  	Root string
    67  
    68  	// Map maps the locations of schemas and definitions to a new location.
    69  	// References are updated accordingly. A returned label must be
    70  	// an identifier or string literal.
    71  	//
    72  	// The default mapping is
    73  	//    {}                     {}
    74  	//    {"definitions", foo}   {#foo} or {#, foo}
    75  	//    {"$defs", foo}         {#foo} or {#, foo}
    76  	Map func(pos token.Pos, path []string) ([]ast.Label, error)
    77  
    78  	// TODO: configurability to make it compatible with OpenAPI, such as
    79  	// - locations of definitions: #/components/schemas, for instance.
    80  	// - selection and definition of formats
    81  	// - documentation hooks.
    82  
    83  	// Strict reports an error for unsupported features, rather than ignoring
    84  	// them.
    85  	Strict bool
    86  
    87  	_ struct{} // prohibit casting from different type.
    88  }