Package schema

import "github.com/ornew/hff/schema"

Generated from this checkout's Go source. Released versions are also on pkg.go.dev.

Overview

Package schema builds immutable HFF input type descriptors with field helpers.

Helpers such as String("name") and Int("age") return named fields, not types. Struct combines those fields into an object type. StringType and IntType are type descriptors for list elements, map values, union members, or extension signatures. For example, List("tags", StringType) defines a named list field, while ListOf(StringType) describes a list wherever a type is required.

Optional and Nullable model different input states. Optional(String("name")) permits the key to be missing; Nullable(String("name")) permits a present null value. Input validation also accepts absence for a nullable field, while keeping an absent key distinct from explicit null. Optional does not itself permit null. The wrappers retain separate schema flags and can be composed; neither changes how a present, non-null string is validated.

A Struct has declared keys and per-field types. A MapOf(StringType) accepts arbitrary string keys whose values are strings. Union(IntType, StringType) accepts either representation without converting between them. AnyType accepts all valid HFF values and gives the compiler less static information; explicit type guards can narrow dynamic values in queries.

Constructors assemble descriptors without returning errors. Call Type.Check to validate a descriptor on its own, or pass it to engine.New, which validates the complete input schema and requires a struct or map root. Descriptors and their field/member snapshots are immutable and safe to reuse across engines.

Index

• NullType
• BoolType
• IntType
• FloatType
• StringType
• BytesType
• TimestampType
• DurationType
• AnyType
• NeverType
• type FieldDef
  • func Any(name string) FieldDef
  • func Bool(name string) FieldDef
  • func Bytes(name string) FieldDef
  • func Duration(name string) FieldDef
  • func Field(name string, t Type) FieldDef
  • func Float(name string) FieldDef
  • func Int(name string) FieldDef
  • func List(name string, element Type) FieldDef
  • func Map(name string, element Type) FieldDef
  • func Nullable(field FieldDef) FieldDef
  • func Optional(field FieldDef) FieldDef
  • func String(name string) FieldDef
  • func Timestamp(name string) FieldDef
• type Type
  • func ListOf(element Type) Type
  • func MapOf(element Type) Type
  • func NullableType(t Type) Type
  • func Struct(fields ...FieldDef) Type
  • func Union(members ...Type) Type
  • func (t Type) Check() error
  • func (t Type) Element() Type
  • func (t Type) Equal(other Type) bool
  • func (t Type) Fields() []Field
  • func (t Type) Key() string
  • func (t Type) Kind() TypeKind
  • func (t Type) Members() []Type
  • func (t Type) Parameters() []Type
  • func (t Type) Result() Type

Variables

Source

var (
	NullType	= hff.PrimitiveType(hff.NullType)
	BoolType	= hff.PrimitiveType(hff.BoolType)
	IntType		= hff.PrimitiveType(hff.IntType)
	FloatType	= hff.PrimitiveType(hff.FloatType)
	StringType	= hff.PrimitiveType(hff.StringType)
	BytesType	= hff.PrimitiveType(hff.BytesType)
	TimestampType	= hff.PrimitiveType(hff.TimestampType)
	DurationType	= hff.PrimitiveType(hff.DurationType)
	AnyType		= hff.PrimitiveType(hff.AnyType)
	NeverType	= hff.PrimitiveType(hff.NeverType)
)

Primitive type descriptors are useful as element and union types.

Types

type FieldDef

Source

type FieldDef = hff.Field

FieldDef describes a struct field; Optional and Nullable distinguish absence from explicit null.

func Any

Source

func Any(name string) FieldDef

Any creates a required field that accepts any valid HFF value, including explicit null. Use Optional(Any(name)) to also permit an absent key.

func Bool

Source

func Bool(name string) FieldDef

Bool creates a required Boolean field.

func Bytes

Source

func Bytes(name string) FieldDef

Bytes creates a required bytes field.

func Duration

Source

func Duration(name string) FieldDef

Duration creates a required duration field.

func Field

Source

func Field(name string, t Type) FieldDef

Field creates a field with the supplied type and Optional=false. Use Optional to set the independent optional marker and Nullable to add NullType. Input validation accepts a missing nullable field as well as a missing Optional field; a present null still requires a nullable type.

func Float

Source

func Float(name string) FieldDef

Float creates a required finite float64 field.

func Int

Source

func Int(name string) FieldDef

Int creates a required int64 field.

func List

Source

func List(name string, element Type) FieldDef

List creates a required field whose value is an ordered list of element type. Use Nullable(List(...)) to permit a null list, or Optional(List(...)) to permit the field to be absent.

func Map

Source

func Map(name string, element Type) FieldDef

Map creates a required field whose string keys map to element-type values. Map keys are strings; Optional and Nullable wrap the field in the same way as other field helpers.

func Nullable

Source

func Nullable(field FieldDef) FieldDef

Nullable permits an explicit null value by adding NullType to the field's value type. It does not set the Optional marker; input validation nevertheless accepts a missing nullable field as a normal null-safe absence case.

Example

{
	typ := schema.Struct(schema.Nullable(schema.String("nickname")))
	_, missing := hff.ValidateInput(context.Background(), typ, hff.Object(nil), hff.ValidationConfig{})
	_, null := hff.ValidateInput(context.Background(), typ,
		hff.Object(map[string]hff.Value{"nickname": hff.Null()}), hff.ValidationConfig{})
	fmt.Println("missing allowed:", missing == nil)
	fmt.Println("null allowed:", null == nil)

}

package main

import (
	"context"
	"fmt"

	"github.com/ornew/hff"
	"github.com/ornew/hff/schema"
)

func main() {
	typ := schema.Struct(schema.Nullable(schema.String("nickname")))
	_, missing := hff.ValidateInput(context.Background(), typ, hff.Object(nil), hff.ValidationConfig{})
	_, null := hff.ValidateInput(context.Background(), typ,
		hff.Object(map[string]hff.Value{"nickname": hff.Null()}), hff.ValidationConfig{})
	fmt.Println("missing allowed:", missing == nil)
	fmt.Println("null allowed:", null == nil)
}

Output:

missing allowed: true
null allowed: true

func Optional

Source

func Optional(field FieldDef) FieldDef

Optional sets the field's independent optional marker; it does not add NullType. A nullable field also accepts absence during input validation, but Optional records absence separately in the schema. Use Optional(Nullable(f)) when both schema markers are wanted.

Example

{
	typ := schema.Struct(schema.Optional(schema.String("nickname")))
	_, missing := hff.ValidateInput(context.Background(), typ, hff.Object(nil), hff.ValidationConfig{})
	_, null := hff.ValidateInput(context.Background(), typ,
		hff.Object(map[string]hff.Value{"nickname": hff.Null()}), hff.ValidationConfig{})
	fmt.Println("missing allowed:", missing == nil)
	fmt.Println("null allowed:", null == nil)

}

package main

import (
	"context"
	"fmt"

	"github.com/ornew/hff"
	"github.com/ornew/hff/schema"
)

func main() {
	typ := schema.Struct(schema.Optional(schema.String("nickname")))
	_, missing := hff.ValidateInput(context.Background(), typ, hff.Object(nil), hff.ValidationConfig{})
	_, null := hff.ValidateInput(context.Background(), typ,
		hff.Object(map[string]hff.Value{"nickname": hff.Null()}), hff.ValidationConfig{})
	fmt.Println("missing allowed:", missing == nil)
	fmt.Println("null allowed:", null == nil)
}

Output:

missing allowed: true
null allowed: false

func String

Source

func String(name string) FieldDef

String creates a required string field.

func Timestamp

Source

func Timestamp(name string) FieldDef

Timestamp creates a required timestamp field.

This alias exposes the following definition and methods.

type Field struct {
	// Name is the exact HFF object key.
	Name	string
	// Type is the required value type when the field is present.
	Type	Type
	// Optional permits the key to be absent; it does not permit explicit null.
	Optional	bool
}

Field describes one exact object key in a struct type. Optional marks the field as absence-capable without adding NullType. Add NullType to Type to permit a present null value; input validation also accepts absence for a nullable field. The flag and value type remain distinct parts of the schema.

type Type

Source

type Type = hff.Type

Type is an immutable HFF type descriptor.

func ListOf

Source

func ListOf(element Type) Type

ListOf creates an ordered list type. The list preserves element order and every element must satisfy element; call Type.Check before using a user-assembled descriptor as an input schema.

func MapOf

Source

func MapOf(element Type) Type

MapOf creates a string-keyed map type. Each present value must satisfy element; a missing key is distinct from a key whose value is NullType.

Example

{

	typ := schema.Struct(
		schema.Field("labels", schema.MapOf(schema.StringType)),
		schema.Field("batches", schema.ListOf(schema.ListOf(schema.IntType))),
	)
	record := hff.Object(map[string]hff.Value{
		"labels":	hff.Object(map[string]hff.Value{"app": hff.String("auth")}),
		"batches":	hff.List(hff.List(hff.Int(1), hff.Int(2))),
	})
	_, err := hff.ValidateInput(context.Background(), typ, record, hff.ValidationConfig{})
	fmt.Println(err == nil)

}

package main

import (
	"context"
	"fmt"

	"github.com/ornew/hff"
	"github.com/ornew/hff/schema"
)

func main() {
	// Arbitrary label names all carry strings; nested lists use ListOf.
	typ := schema.Struct(
		schema.Field("labels", schema.MapOf(schema.StringType)),
		schema.Field("batches", schema.ListOf(schema.ListOf(schema.IntType))),
	)
	record := hff.Object(map[string]hff.Value{
		"labels":	hff.Object(map[string]hff.Value{"app": hff.String("auth")}),
		"batches":	hff.List(hff.List(hff.Int(1), hff.Int(2))),
	})
	_, err := hff.ValidateInput(context.Background(), typ, record, hff.ValidationConfig{})
	fmt.Println(err == nil)
}

Output:

true

func NullableType

Source

func NullableType(t Type) Type

NullableType returns the union of t and explicit NullType. Use it when a present field may contain null. Input validation also accepts an absent nullable field; FieldDef.Optional is a separate schema marker and is not set by this helper.

func Struct

Source

func Struct(fields ...FieldDef) Type

Struct creates a fixed-key object type from field definitions. For example:

person := schema.Struct(
    schema.String("name"),
    schema.Optional(schema.Int("age")),
    schema.Nullable(schema.String("nickname")),
)

This requires name, marks age optional, and allows nickname to be null. Input validation also accepts a missing nullable nickname as a normal absence case. Optional remains an independent schema marker. The engine validates the resulting descriptor when configured.

Example

{
	typ := schema.Struct(
		schema.String("name"),
		schema.Int("age"),
		schema.List("tags", schema.StringType),
	)
	record := hff.Object(map[string]hff.Value{
		"name":	hff.String("Alice"), "age": hff.Int(25),
		"tags":	hff.List(hff.String("admin")),
	})
	_, err := hff.ValidateInput(context.Background(), typ, record, hff.ValidationConfig{})
	fmt.Println(err == nil)

}

package main

import (
	"context"
	"fmt"

	"github.com/ornew/hff"
	"github.com/ornew/hff/schema"
)

func main() {
	typ := schema.Struct(
		schema.String("name"),
		schema.Int("age"),
		schema.List("tags", schema.StringType),
	)
	record := hff.Object(map[string]hff.Value{
		"name":	hff.String("Alice"), "age": hff.Int(25),
		"tags":	hff.List(hff.String("admin")),
	})
	_, err := hff.ValidateInput(context.Background(), typ, record, hff.ValidationConfig{})
	fmt.Println(err == nil)
}

Output:

true

func Union

Source

func Union(members ...Type) Type

Union creates a normalized type accepting a value of any supplied member type. For example, Union(IntType, FloatType) accepts either numeric representation; add NullType to allow explicit null. Union does not make a struct field optional.

Example

{
	typ := schema.Struct(schema.Field("identifier", schema.Union(schema.IntType, schema.StringType)))
	for _, value := range []hff.Value{hff.Int(42), hff.String("item-42"), hff.Float(42)} {
		_, err := hff.ValidateInput(context.Background(), typ,
			hff.Object(map[string]hff.Value{"identifier": value}), hff.ValidationConfig{})
		fmt.Println(err == nil)
	}

}

package main

import (
	"context"
	"fmt"

	"github.com/ornew/hff"
	"github.com/ornew/hff/schema"
)

func main() {
	typ := schema.Struct(schema.Field("identifier", schema.Union(schema.IntType, schema.StringType)))
	for _, value := range []hff.Value{hff.Int(42), hff.String("item-42"), hff.Float(42)} {
		_, err := hff.ValidateInput(context.Background(), typ,
			hff.Object(map[string]hff.Value{"identifier": value}), hff.ValidationConfig{})
		fmt.Println(err == nil)
	}
}

Output:

true
true
false

This alias exposes the following definition and methods.

type Type core.Type

Type is an immutable description of values accepted by a schema or produced by a compiled expression. Its zero value is invalid; construct descriptors with PrimitiveType or the composite constructors, then call Check before using one as a host input schema. Function types are compiler metadata and are rejected by Check.

func (Type) Check

Source

func (t Type) Check() error

Check recursively validates a host-schema descriptor. It rejects invalid and function types, duplicate struct keys, and nesting beyond the supported schema depth. Engine input schemas additionally require a struct or map root.

func (Type) Element

Source

func (t Type) Element() Type

Element returns the declared element type for a list or map. It returns an invalid zero Type for other kinds or an invalid receiver.

func (Type) Equal

Source

func (t Type) Equal(other Type) bool

Equal reports structural equality, including field names, optionality, and nested member types. It does not infer compatibility or perform coercion.

func (Type) Fields

Source

func (t Type) Fields() []Field

Fields returns a defensive copy of a struct's fields. It returns nil for non-struct or invalid types; changing the returned slice does not change t.

func (Type) Key

Source

func (t Type) Key() string

Key returns the stable canonical structural key for descriptor comparison and caches. It is not a display format or serialization contract.

func (Type) Kind

Source

func (t Type) Kind() TypeKind

Kind returns the descriptor kind; an invalid zero Type reports InvalidType.

func (Type) Members

Source

func (t Type) Members() []Type

Members returns a defensive copy of union members, or nil when t is not a union. A normalized union has at least two members; singleton unions have already collapsed to their member type.

func (Type) Parameters

Source

func (t Type) Parameters() []Type

Parameters returns a defensive copy of function parameter types, or nil for a non-function type. Function types are compiler metadata, not host schema types accepted by Check.

func (Type) Result

Source

func (t Type) Result() Type

Result returns a function's result type, or an invalid zero Type for other kinds or an invalid receiver.