schema

package
v1.12.0-alpha.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 20, 2026 License: Apache-2.0 Imports: 44 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	// OutputFieldName is the block of a component template declaring its workload.
	OutputFieldName = "output"
	// OutputsFieldName is the block of a component or trait template declaring
	// the other resources it applies, by name.
	OutputsFieldName = "outputs"
)
View Source 
const BaseTemplate = `
context: {
  name: string
  config?: [...{
    name: string
    value: string
  }]
  ...
}
`

BaseTemplate include base info provided by KubeVela for CUE template

View Source 
const ErrGenerateOpenAPIV2JSONSchemaForCapability = "cannot generate OpenAPI v3 JSON schema for capability %s: %v"

ErrGenerateOpenAPIV2JSONSchemaForCapability is the error while generating OpenAPI v3 schema

View Source 
const ExtensionConditions = "x-vela-conditions"

ExtensionConditions is the OpenAPI extension listing the conditions under which a property exists, in the form VelaUX's ui-schema conditions take.

View Source 
const ExtensionImmutable = "x-immutable"

ExtensionImmutable is the OpenAPI extension key that marks a parameter field as immutable

View Source 
const ExtensionUI = "x-vela-ui"

ExtensionUI is the OpenAPI extension carrying a property's UI hints.

View Source 
const SchemaContext = schemaContext

SchemaContext is the context stub the parameter schema generator compiles a template with, for a caller that compiles the template itself.

View Source 
const SourceFieldName = "schema"

SourceFieldName is the block of a SourceDefinition declaring the value it resolves to.

View Source 
const UIHintPrefix = "+ui:"

UIHintPrefix starts a doc comment line that tells VelaUX how to render a parameter, one hint per line: `// +ui:format=table`, `// +ui:advanced`.

Variables

View Source 
var ErrUnprunable = errors.New("parameter cannot be pruned from template")

ErrUnprunable reports a template whose `parameter` cannot be separated from the rest of it by reading the syntax alone.

Functions

func BareRead 

func BareRead(value string) (template.Reference, bool)

BareRead is the read a value consists of when it is one $( ) expression doing nothing but read, such as $(source.cfg.regions).

func ComponentReadKind 

func ComponentReadKind(produced map[string]Produced, ref template.Reference) (cue.Kind, bool)

ComponentReadKind is the kind the producer's schema declares for a component read, by component name. A placement call does not change what is read, so it is passed over.

func ConvertOpenAPISchema2SwaggerObject 

func ConvertOpenAPISchema2SwaggerObject(data []byte) (*openapi3.Schema, error)

ConvertOpenAPISchema2SwaggerObject converts OpenAPI v2 JSON schema to Swagger Object

func EachMayBeAbsent 

func EachMayBeAbsent(item func(path []string) bool, ref template.Reference) bool

EachMayBeAbsent reports whether an each read may find nothing, given item, what may be missing within one item of the loop: only each.item's fields can.

func EachReadKind 

func EachReadKind(item func(path []string) (cue.Kind, bool), ref template.Reference) (cue.Kind, bool)

EachReadKind is the kind of a read of the loop's iteration: each.index is an int, each.key a string, and item, when given, is the kind at a path within each.item.

func FixOpenAPISchema 

func FixOpenAPISchema(name string, schema *openapi3.Schema)

FixOpenAPISchema fixes tainted `description` filed, missing of title `field`.

func ImmutableFieldsFromTemplate added in v1.11.0 

func ImmutableFieldsFromTemplate(templateStr string) map[string]bool

ImmutableFieldsFromTemplate parses a CUE template string and returns the set of dotted parameter field paths that are marked with the +immutable comment marker.

func InstrumentClauses 

func InstrumentClauses(src string) string

InstrumentClauses marks every body of a comprehension made only of `if` clauses. A name several bodies declare has one position and one doc comment for all of them, so only the markers say which body a field came from. Bodies with a `for` clause are left alone: they can embed a scalar, which a definition field would conflict with.

func KindAt 

func KindAt(s *openapi3.Schema, path []string) (cue.Kind, bool)

KindAt is the kind s declares at path, one segment per field, map key or list index, when it declares one. A path s does not have, a value of any type and anything below one has none: a live object carries more than its schema says. Nor does a nullable value, or anything below one, since null is not its kind.

func LiteralSchema 

func LiteralSchema(v interface{}) *openapi3.Schema

LiteralSchema is the schema of a decoded JSON value as written: a list's elements share one schema, which declares a kind only where every element agrees on it, and an object's fields are merged the same way across the elements that have them, required only where every object element has them. A string that is one $( ) expression, and null, are of any type.

func LoopItemKind 

func LoopItemKind(items []byte, readKind func(template.Reference) (cue.Kind, bool)) func([]string) (cue.Kind, bool)

LoopItemKind is the kind at a path within one item of a forEach loop, given its items: a literal list is typed as written, and one expression that is exactly a read is typed by what that read declares one element down. Anything else, a computed list or items from a workflow variable, declares nothing.

func LoopItemMayBeAbsent 

func LoopItemMayBeAbsent(items []byte, mayBeAbsent func(template.Reference) bool) func([]string) bool

LoopItemMayBeAbsent reports whether a path within one item of a forEach loop may be missing, given its items: in a literal list, a field some object items leave out or an index past some items' lists; for one expression that is exactly a read, what mayBeAbsent says one element down. Like LoopItemKind, it is nil for any other items.

func MayBeAbsentAt 

func MayBeAbsentAt(s *openapi3.Schema, path []string) bool

MayBeAbsentAt reports whether a value s describes may lack path: an object's field it declares but does not require, a map's key, or a list index at or past the list's minItems, at any segment, so a read of one needs has(). A path s does not declare, or that runs below a value of any type, is not reported, as for a definition's schema.

func ParsePropertiesToSchema 

func ParsePropertiesToSchema(ctx context.Context, s string, templateFieldPath ...string) (*openapi3.Schema, error)

ParsePropertiesToSchema parse the properties in cue script to the openapi schema

func ParseValueToSchema 

func ParseValueToSchema(template cue.Value) (*openapi3.Schema, error)

ParseValueToSchema is ParsePropertiesToSchema for a value that has already been compiled.

A definition that extends another cannot be compiled from its own template: it writes `parameter: $super._parameter & {...}`, and `$super` is supplied by the chain rather than declared anywhere in the file. Such a definition is compiled by the inheritance renderer and handed here, so its published parameter schema is the one an application will actually be validated against.

func Patches 

func Patches(template string) (output, outputs bool)

Patches reports whether a trait template patches its component's workload (`patch`) and its other resources (`patchOutputs`), anywhere at the top level, under an `if` or a `for` included. It is read from the syntax, since a template depends on parameters that do not exist until it renders. A template that does not parse, or a top-level label only a render can name, may patch either.

func ProducedFor 

func ProducedFor(ctx context.Context, cli client.Client, namespace string, components []common.ApplicationComponent,
	annotations map[string]string) map[string]Produced

ProducedFor is what each of components applies, by name, as its component.<name> reads see it: its definition's output schemas, at the revision its type names and with what it extends, and the resources its traits add. A trait that patches the workload leaves it untyped, one that patches the resources leaves them untyped, and a trait that cannot be read may do either. A resource declared twice is untyped, since which one is applied is not known. A component whose definition cannot be read is left out, so its reads fit anything.

func PruneTo 

func PruneTo(src string, fields ...string) (string, error)

PruneTo is PruneToParameter keeping the named top-level fields, such as a SourceDefinition's `parameter` and `schema`.

func PruneToParameter 

func PruneToParameter(src string) (string, error)

PruneToParameter reduces a CUE template to its top-level `parameter` declarations and the top-level declarations and imports they reference.

Everything else (output, outputs, patch, and the imports only they use) is dropped, so it cannot fail the compile that reads the parameter schema. Comments stay attached, since the schema's descriptions come from them.

func SourceDefinitionFor 

func SourceDefinitionFor(ctx context.Context, cli client.Reader, namespace, sourceType string,
	annotations map[string]string) (*v1beta1.SourceDefinition, error)

SourceDefinitionFor is the SourceDefinition a source of sourceType reads.

func SourceSchemaText 

func SourceSchemaText(ctx context.Context, cli client.Reader, namespace, sourceType string,
	annotations map[string]string) (string, error)

SourceSchemaText is the `schema:` block of the SourceDefinition a source of sourceType reads, as CUE text: what $(source.<name>) reads. It is "" for a definition that declares none.

func TopLevelBlock 

func TopLevelBlock(template, name string) (string, error)

TopLevelBlock is the CUE source of a template's top-level field named name, or "" when it has none. The template is parsed, not evaluated.

Types

type Condition 

type Condition struct {
	// Ref names the other field as VelaUX resolves it from the field's own
	// form: `type` for a sibling, `../mode` for a field of the enclosing
	// object, `storage.kind` for a field of a child object.
	Ref string
	// Values the other field must take, for a value condition.
	Values []any
	// Exists is set for a presence condition: true when the other field must
	// be set, false when it must not.
	Exists *bool
	// contains filtered or unexported fields
}

Condition limits a field to some values, or to the presence, of another field.

type Field 

type Field struct {
	Name        string
	Kind        Kind
	Description string
	Immutable   bool
	// Optional is true for a field that need not be supplied: marked `?`, or
	// carrying a default.
	Optional bool
	Nullable bool
	// HasDefault distinguishes a null default from none.
	HasDefault bool
	Default    any
	Enum       []any

	Min, Max                   *float64
	ExclusiveMin, ExclusiveMax bool
	MinLength, MaxLength       *uint64
	MinItems, MaxItems         *uint64
	MinProperties              *uint64
	MultipleOf                 *float64
	// Patterns must all match; NotPatterns must none.
	Patterns    []string
	NotPatterns []string
	NotEqual    []any
	UniqueItems bool

	// Fields are an object's fields, in declaration order.
	Fields []*Field
	// Items is an array's element.
	Items *Field
	// Values is a map's value.
	Values *Field
	// Variants are the alternatives of a disjunction that is not an enum.
	Variants []*Field
	// Open marks an object that accepts fields beyond those it declares.
	Open bool
	// Recursive marks an object cut short where its type refers to itself.
	Recursive bool
	// Conditions are set on a field that exists only for some values of
	// other fields; all of them must hold.
	Conditions []Condition

	// UI are the field's `+ui:` hints.
	UI UIHints
	// Discriminators name the siblings whose values decide which conditional
	// fields of this object exist.
	Discriminators []string
	// contains filtered or unexported fields
}

Field is one parameter, as read from the compiled template.

func BuildField 

func BuildField(v cue.Value, src string) *Field

BuildField reads a value of a compiled template, such as its parameter. src is the template's source, used only to find which fields an `if` reads.

func (*Field) OpenAPI 

func (f *Field) OpenAPI() *openapi3.Schema

OpenAPI renders the field as an OpenAPI 3.0 schema.

func (*Field) UIParameters 

func (f *Field) UIParameters() uischema.UISchema

UIParameters renders an object's fields as the default VelaUX form, in the order the template declares them.

type Kind 

type Kind string

Kind is the shape of a parameter field. 

const (
	KindString  Kind = "string"
	KindInt     Kind = "integer"
	KindNumber  Kind = "number"
	KindBool    Kind = "boolean"
	KindBytes   Kind = "bytes"
	KindObject  Kind = "object"
	KindMap     Kind = "map"
	KindArray   Kind = "array"
	KindOneOf   Kind = "oneOf"
	KindAny     Kind = "any"
	KindUnknown Kind = ""
)

Kinds a parameter field can take.

type OutputSchemas 

type OutputSchemas struct {
	// Output is the workload; nil for a template that declares none, such as a trait's.
	Output *openapi3.Schema
	// Outputs are the other resources, by the name the template gives each.
	Outputs map[string]*openapi3.Schema
}

OutputSchemas are the shapes of what a component or trait template applies, as component.<name>.output and component.<name>.outputs.<resource> read them.

func ChainOutputSchemas 

func ChainOutputSchemas(ctx context.Context, levels []inherit.Level) (*OutputSchemas, error)

ChainOutputSchemas is the output schemas of a definition and what it extends: levels are the definition and its ancestors, nearest first, each laid over the one it extends as its render merges them.

func GenerateOutputSchemas 

func GenerateOutputSchemas(ctx context.Context, template string) (*OutputSchemas, error)

GenerateOutputSchemas reads a template's `output` and `outputs` into the schema of each object: the fields the template writes, typed by the values or parameters it writes them from, and a `status` of any type, since the object's controller writes it and a reader casts what it takes from there. Fields written inside an `if` are included, typed from the template's source, since the evaluated value leaves them out while the parameter tested is unknown. A resource whose name the template computes is left out.

func (*OutputSchemas) Extend 

func (s *OutputSchemas) Extend(child *OutputSchemas, output, outputs bool) *OutputSchemas

Extend lays the output schemas of a definition that extends this one over this one's, as its render merges them: field by field, with outputs joining by name. output and outputs say whether the child inherits each; one it does not is the child's alone. A field the child writes untyped, such as one read from `$super`, keeps the type this one gives it.

type ParameterSchemaPath 

type ParameterSchemaPath string

ParameterSchemaPath reports how ParseParameterSchema compiled a template. 

const (
	// PathPlain compiled the pruned template with plain CUE.
	PathPlain ParameterSchemaPath = "plain"
	// PathCuex compiled the pruned template with the cuex compiler, because
	// `parameter` itself needs a package plain CUE does not have.
	PathCuex ParameterSchemaPath = "cuex"
	// PathFull compiled the whole template, as ParsePropertiesToSchema does.
	PathFull ParameterSchemaPath = "full"
)

func ParseParameterSchema 

func ParseParameterSchema(ctx context.Context, s string) (*openapi3.Schema, ParameterSchemaPath, error)

ParseParameterSchema is ParsePropertiesToSchema reading only `parameter` and what it references. A template it cannot prune is compiled whole.

type ParameterSchemas 

type ParameterSchemas struct {
	OpenAPI *openapi3.Schema
	UI      uischema.UISchema
}

ParameterSchemas are the two schemas generated from a template's parameter.

func GenerateParameterSchemas 

func GenerateParameterSchemas(ctx context.Context, template string) (*ParameterSchemas, error)

GenerateParameterSchemas reads a template's `parameter` into both its OpenAPI schema and the default UI schema VelaUX renders a form from.

func GenerateParameterSchemasAt 

func GenerateParameterSchemasAt(ctx context.Context, template, path string) (*ParameterSchemas, error)

GenerateParameterSchemasAt is GenerateParameterSchemas for a template whose parameter sits under path rather than at the top, such as a config template's `template.parameter`.

func GenerateParameterSchemasFromValue 

func GenerateParameterSchemasFromValue(val cue.Value, src string) (*ParameterSchemas, error)

GenerateParameterSchemasFromValue is GenerateParameterSchemas for a template already compiled, such as one that extends another.

type Produced 

type Produced struct {
	Output  *openapi3.Schema
	Outputs map[string]*openapi3.Schema
}

Produced is what one component applies, as component.<name> reads it: its workload and its other resources by name. A nil Output, or a resource missing from Outputs, declares no kinds.

type SourceSchemas 

type SourceSchemas struct {
	Parameter *ParameterSchemas
	// Output is the OpenAPI schema of the template's `schema`, the value an
	// Application reads with $(source.<name>); nil when there is none.
	Output *openapi3.Schema
}

SourceSchemas are the schemas generated from a SourceDefinition template.

func GenerateSourceSchemas 

func GenerateSourceSchemas(ctx context.Context, template string) (*SourceSchemas, error)

GenerateSourceSchemas reads a SourceDefinition template's `parameter` and `schema` from one compile.

type UIHints 

type UIHints struct {
	// Type names the VelaUX widget, overriding the one the shape implies.
	Type string `json:"type,omitempty"`
	// Format is how a list of structs is laid out: `table` for one row each.
	Format string `json:"format,omitempty"`
	// RowKey names the field that identifies a row of a list: unique, and
	// the row's title.
	RowKey string `json:"rowKey,omitempty"`
	// ItemLabel names the field that titles each item of a list.
	ItemLabel   string `json:"itemLabel,omitempty"`
	Label       string `json:"label,omitempty"`
	Placeholder string `json:"placeholder,omitempty"`
	// Error is the message shown when a value fails the parameter's
	// constraints, in place of one naming the raw constraint.
	Error string `json:"error,omitempty"`
	// Section names the collapsible section of the form the parameter is
	// shown in; the value keeps its place in the parameter.
	Section string `json:"section,omitempty"`
	// OptionsFrom names where the parameter's choices are read when the form
	// opens: configs:<template>, clusters or envs.
	OptionsFrom string `json:"optionsFrom,omitempty"`
	// Expression is `never` for a parameter that must be written as a
	// literal, even in an Application that reads $( ) expressions.
	Expression string   `json:"expression,omitempty"`
	Suggest    []string `json:"suggest,omitempty"`
	ColSpan    int      `json:"colSpan,omitempty"`
	// Order places the parameter among its siblings, ahead of declaration
	// order.
	Order *int `json:"order,omitempty"`
	// Advanced puts the parameter behind VelaUX's Advanced toggle.
	Advanced bool `json:"advanced,omitempty"`
	Hidden   bool `json:"hidden,omitempty"`
}

UIHints are the `+ui:` markers of a parameter.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.