Help us shape the future of Go! Take the 2026 Go Developer Survey

contract

package
v0.5.3 Latest Latest
Warning

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

 Go to latest Published: Nov 3, 2026 License: MIT Imports: 29 Imported by: 0

Documentation

Overview

Package contract owns typed transport descriptions shared by runtime adapters and client exporters. Persistence models do not implicitly become public DTOs.

Index

Constants

View Source 
const MaxJSONDepth = jsonwire.MaxDepth

MaxJSONDepth is the shared parser's maximum child depth (the root is zero).

View Source 
const MaxPresentationKeyBytes = identifier.MaxSemanticBytes

MaxPresentationKeyBytes bounds each public translation key independently. It is the semantic message-key bound every key must also satisfy.

Variables

This section is empty.

Functions

func PasswordTypes 

func PasswordTypes(types []Type) map[TypeID]bool

PasswordTypes returns the types whose values can contain a property hinted as a password, following properties, elements, aliases and union variants, including recursive graphs. Only explicit password hints count; property names and persistence models are never scanned. Password hints are input-only, so output owners reject these types.

func RejectPasswordOutput 

func RejectPasswordOutput(schema Schema, output string) error

RejectPasswordOutput refuses an output schema whose root value can contain a property hinted as a password. Every output owner (HTTP responses and event streams, table rows, notification payloads, presence members and server events) calls it when a declaration registers, whether or not clients are exported; output names the owner's kind in the error.

func UnionVariant 

func UnionVariant[T, P any](stored UnionValue[T], tag string) (P, error)

UnionVariant returns a fresh concrete payload. It does not expose or share the stored snapshot. Generated accessors supply the exact payload and literal.

Types

type DecodeError 

type DecodeError struct {
	// contains filtered or unexported fields
}

DecodeError reports malformed input or a mismatch with the declared wire contract. Its message never includes received values or a codec's error text. Issues returns owned diagnostics; Unwrap preserves internal cause inspection.

func (*DecodeError) Error 

func (*DecodeError) Error() string

Error returns a fixed message without exposing JSON input.

func (*DecodeError) GoString 

func (e *DecodeError) GoString() string

GoString returns the same safe message as Error.

func (*DecodeError) Is 

func (*DecodeError) Is(target error) bool

Is reports whether the target is fault.Invalid.

func (*DecodeError) Issues 

func (e *DecodeError) Issues() []Issue

Issues returns a copy of the decoding issues.

func (*DecodeError) Unwrap 

func (e *DecodeError) Unwrap() error

Unwrap returns the underlying decoding cause.

type EncodeError 

type EncodeError struct {
	// contains filtered or unexported fields
}

EncodeError reports a value that could not satisfy its response contract. Its safe message contains no output fields or codec details. Issues returns an owned slice. Unwrap preserves internal cause inspection.

func (*EncodeError) Error 

func (*EncodeError) Error() string

Error returns a fixed message without exposing JSON output.

func (*EncodeError) GoString 

func (e *EncodeError) GoString() string

GoString returns the same safe message as Error.

func (*EncodeError) Is 

func (*EncodeError) Is(target error) bool

Is reports whether the target is fault.Internal.

func (*EncodeError) Issues 

func (e *EncodeError) Issues() []Issue

Issues returns a copy of the encoding issues.

func (*EncodeError) Unwrap 

func (e *EncodeError) Unwrap() error

Unwrap returns the underlying encoding cause.

type Format 

type Format string

Format is a supported scalar representation whose parser belongs to the corresponding framework value type. Empty format means an ordinary string. 

const (
	UUIDFormat          Format = jsonshape.UUIDFormat
	DecimalFormat       Format = jsonshape.DecimalFormat
	DateFormat          Format = jsonshape.DateFormat
	TimeFormat          Format = jsonshape.TimeFormat
	DateTimeFormat      Format = jsonshape.DateTimeFormat
	LocalDateTimeFormat Format = jsonshape.LocalDateTimeFormat
	IntervalFormat      Format = jsonshape.IntervalFormat
	Base64Format        Format = jsonshape.Base64Format
)

type Issue 

type Issue struct {
	Path string    `json:"path"`
	Code IssueCode `json:"code"`
	// Message is approved public text supplied by a declared validation rule.
	// Wire-shape failures leave it empty. Never copy input or error text here.
	Message string `json:"message,omitempty"`
	// Label is an optional, declared display name. Path remains the API field
	// location; labels never substitute for paths or contain submitted values.
	Label    string          `json:"label,omitempty"`
	LabelKey i18n.MessageKey `json:"label_key,omitempty"`
}

Issue identifies a location by JSON Pointer (the empty string is the root). Unknown object fields produce one issue at the containing object; their submitted names are not reflected into diagnostics. Declared field names, array indices and declared map keys can appear in Path. Values never do.

type IssueCode 

type IssueCode string

IssueCode identifies a wire-shape failure independently of a public message. Business validation rules add their own metadata at the validation boundary. 

const (
	TypeIssue     IssueCode = "type"
	KeyIssue      IssueCode = "key"
	NullIssue     IssueCode = "null"
	RequiredIssue IssueCode = "required"
	UnknownIssue  IssueCode = "unknown"
	ValueIssue    IssueCode = "value"
	LengthIssue   IssueCode = "length"
)

type JSON 

type JSON[T any] struct {
	// contains filtered or unexported fields
}

JSON retains the concrete DTO type at a transport boundary. Its zero value is invalid. Generated declarations own schema discovery; consumers obtain the descriptor from generated code rather than maintaining a second schema.

func BooleanJSON 

func BooleanJSON[T ~bool]() JSON[T]

BooleanJSON returns a JSON codec for a boolean type.

func DefineGenericJSON 

func DefineGenericJSON[T any](source string, description Schema) JSON[T]

DefineGenericJSON is the generated generic DTO construction boundary. source retains the fully instantiated Go source expression. Schema nodes may coincide after substituting repeated equal arguments; the shared compiler accepts them only when their complete normalized wire definitions agree.

func DefineJSON 

func DefineJSON[T any](description Schema) JSON[T]

DefineJSON is the explicit metadata construction boundary used by generated declarations. It copies and validates the graph, requiring its root identity to match T's qualified Go name. Executable main packages retain the generated source namespace because Go reports their runtime package path as "main". T must be an exported named struct and must not implement model.Identifiable. Registries must Validate before accepting a descriptor. Generator analysis owns field/codec agreement and nested-model rejection; this function does not infer Go fields or execute custom codecs.

func DefineJSONField 

func DefineJSONField[T any](description Schema) JSON[T]

DefineJSONField declares an explicitly JSON-valued Go field as an independent document. Generated multipart declarations use it for scalars, ordinary/named collections, nullable values, custom codecs and structured fields. Complete public DTO declarations continue to use DefineJSON.

Like DefineScalar, this is a metadata construction boundary: generation or the declaration author owns agreement between T, its native serialization and this graph. It does not infer or duplicate a schema from reflection. It shares schema compilation, limits and all-or-zero decoding with every JSON contract. Persistence-model roots are rejected without invoking their identity methods; generation also rejects nested models and unsupported native representations.

func DefineJSONValue 

func DefineJSONValue[T any](description Schema) JSON[T]

DefineJSONValue describes the wire representation of a named custom value. Native Go JSON/text methods own serialization; this declaration owns the shape checked before decoding and after encoding. Ordinary DTOs use DefineJSON. T must provide a value encoder and a supported native JSON or text decoder on *T. A pointer-only encoder is insufficient because map elements and top-level values are not addressable under the framework's native JSON semantics. The descriptor cannot describe a persistence model as a public DTO.

func DynamicJSON 

func DynamicJSON() JSON[json.RawMessage]

DynamicJSON is the explicit unrestricted JSON facility. It still enforces strict syntax, canonical value bounds and transport limits; no domain schema or concrete field shape is implied. Prefer generated DTO or primitive codecs.

func IntegerJSON 

func IntegerJSON[T JSONKeyInteger]() JSON[T]

IntegerJSON returns a JSON codec using the integer type's width and signedness.

func Nullable 

func Nullable[T any](element JSON[T]) JSON[value.Nullable[T]]

Nullable declares an explicit null or a present value of the concrete DTO described by element. It reuses value.Nullable rather than introducing a transport-specific wrapper. The resulting descriptor can be composed with Slice, and Decode retains the same limits and all-or-zero failure contract.

func NumberJSON 

func NumberJSON[T ~float32 | ~float64]() JSON[T]

NumberJSON returns a JSON codec using the floating-point type's width.

func ScalarJSON 

func ScalarJSON[T any](scalar Scalar[T]) JSON[T]

ScalarJSON reuses a typed scalar declaration as a custom JSON value contract. The value still supplies native serialization methods; the same declaration can describe its URL and JSON representations without another schema table.

func Slice 

func Slice[T any](element JSON[T]) JSON[[]T]

Slice declares an ordinary Go slice of the concrete DTO described by element. It derives its schema from that descriptor, including every element rule. JSON null decodes to a nil slice; [] decodes to an allocated empty slice. Native byte slices use base64 text; custom byte-value encoders retain arrays. Element nullability is independent: use Slice(Nullable(element)) when each item may itself be null. An invalid element produces an invalid descriptor.

func StringJSON 

func StringJSON[T ~string]() JSON[T]

Primitive JSON declarations reuse the scalar schema source and ordinary JSON field validation. Named primitive values retain their qualified identity; custom serialization must still match the declared primitive representation.

func (JSON[T]) Decode 

func (d JSON[T]) Decode(ctx context.Context, data []byte, limits JSONLimits) (T, error)

Decode validates exact names, required fields, nullability and declared value representations before constructing a fresh T. It rejects duplicate keys and lossy Unicode through the shared wire parser. Dynamic JSON numbers remain json.Number. Every failure returns zero T, never a partially decoded value.

Callers must bound buffering before supplying data and keep data unchanged until this call returns. Custom codecs must be deterministic, concurrency-safe and return owned values. Panic and Goexit become internal failures; cancellation is checked around bounded parsing and after a codec returns. An uncooperative codec is never abandoned while it still owns work or resources.

func (JSON[T]) DescribeScalarProperty 

func (d JSON[T]) DescribeScalarProperty(name string) (ScalarProperty, error)

DescribeScalarProperty resolves the existing compiled graph, without rediscovering Go fields or calling a value's codec. Structured/dynamic fields are not scalar columns. Returned metadata owns its enum case buffers.

func (JSON[T]) Description 

func (d JSON[T]) Description() (Schema, error)

Description returns an owned normalized graph for a contract exporter.

func (JSON[T]) Encode 

func (d JSON[T]) Encode(ctx context.Context, input T, limits JSONLimits) ([]byte, error)

Encode prepares an owned response body and checks the same schema used by Decode and Description. No bytes are returned until encoding and every schema check succeed. Transport adapters can therefore set success headers only after this operation finishes. Keep input unchanged until return. Native inspection and schema validation each receive the declared Steps budget; custom codecs own their internal work and must return bounded, owned representations.

func (JSON[T]) GoTypeName 

func (d JSON[T]) GoTypeName() string

GoTypeName returns the concrete source identity for generic substitution. Generated descriptors retain executable package names which native reflection reports as main. No JSON fields or schema are inferred here.

func (JSON[T]) IsZero 

func (d JSON[T]) IsZero() bool

IsZero reports an unconstructed descriptor, as opposed to one whose declaration failed. Callers use it to substitute an inferred descriptor.

func (JSON[T]) Validate 

func (d JSON[T]) Validate() error

Validate checks this immutable declaration without invoking DTO methods.

type JSONKey 

type JSONKey[K comparable] struct {
	// contains filtered or unexported fields
}

JSONKey ties map-key metadata and native codec behavior to exactly K. Its zero value is invalid. Construct it with the native helpers or DefineJSONKey.

func DefineJSONKey 

func DefineJSONKey[K comparable](scalar Scalar[K]) JSONKey[K]

DefineJSONKey declares a custom native key's string or integer representation. Native JSON/text methods own parsing and formatting; their canonical round trip is checked before the containing DTO can be decoded. This declaration does not introduce a second serialization method or accept a custom untyped key parser.

func EnumJSONKey 

func EnumJSONKey[K enum.Scalar](descriptor enum.Descriptor[K]) JSONKey[K]

EnumJSONKey reuses the same enum cases as value contracts. String enums use their exact names; integer enums use canonical decimal names. A custom enum text representation needs its own DefineJSONKey declaration.

func IntegerJSONKey 

func IntegerJSONKey[K JSONKeyInteger]() JSONKey[K]

IntegerJSONKey describes canonical decimal object names at the concrete width.

func ModelIDJSONKey 

func ModelIDJSONKey[M any]() JSONKey[model.ID[M]]

ModelIDJSONKey retains model ownership and rejects the nil UUID.

func ResolveJSONKey 

func ResolveJSONKey[K comparable](factory func() JSONKey[K]) JSONKey[K]

ResolveJSONKey evaluates a typed declaration factory during construction. It contains panic/Goexit and rejects an invalid returned key. Generated custom key bindings use it without invoking the factory during request handling.

func StringJSONKey 

func StringJSONKey[K ~string]() JSONKey[K]

StringJSONKey preserves ordinary/named strings and native string-key precedence.

func (JSONKey[K]) Description 

func (d JSONKey[K]) Description() (JSONKeyInfo, error)

Description returns independently owned key metadata.

func (JSONKey[K]) Validate 

func (d JSONKey[K]) Validate() error

Validate checks the immutable key declaration without invoking key methods.

type JSONKeyInfo 

type JSONKeyInfo struct {
	Value      Type          `json:"value"`
	Syntax     JSONKeySyntax `json:"syntax"`
	ServerOnly bool          `json:"server_only"`
	NonZero    bool          `json:"non_zero"`
}

JSONKeyInfo retains the key's logical scalar shape. Object member names are always strings; integer keys use canonical decimal spelling, preserving widths. ServerOnly identifies native code whose business rules cannot be exported as equivalent browser validation. NonZero applies to model identities.

type JSONKeyInteger 

type JSONKeyInteger interface {
	~int | ~int8 | ~int16 | ~int32 | ~int64 | ~uint | ~uint8 | ~uint16 | ~uint32 | ~uint64
}

JSONKeyInteger is the native integer set accepted by JSON object keys.

type JSONKeySyntax 

type JSONKeySyntax string

JSONKeySyntax describes how string object names represent a declared key. 

const (
	StringJSONKeySyntax  JSONKeySyntax = "string"
	IntegerJSONKeySyntax JSONKeySyntax = "integer"
	EnumJSONKeySyntax    JSONKeySyntax = "enum"
	ModelIDJSONKeySyntax JSONKeySyntax = "model_id"
	CustomJSONKeySyntax  JSONKeySyntax = "custom"
)

type JSONLimits 

type JSONLimits struct {
	Bytes  int
	Depth  int
	Nodes  int
	Steps  int
	Issues int
}

JSONLimits bounds one document. Bytes, Nodes, Steps and Issues must be positive; Depth is in [0, MaxJSONDepth]. Nodes bounds the wire tree, including object names. Steps bounds graph visits, including aliases and missing fields. Issues caps returned field diagnostics. Transport adapters own their defaults.

func (JSONLimits) Validate 

func (l JSONLimits) Validate() error

Validate checks positive transport budgets and the supported depth range.

type Kind 

type Kind string

Kind selects one wire-shape operation. References are explicit graph edges, so recursive DTOs do not require cyclic Go pointers in a schema declaration. 

const (
	BooleanKind Kind = "boolean"
	StringKind  Kind = "string"
	IntegerKind Kind = "integer"
	NumberKind  Kind = "number"
	ObjectKind  Kind = "object"
	ArrayKind   Kind = "array"
	MapKind     Kind = "map"
	AliasKind   Kind = "alias"
	QuotedKind  Kind = "quoted"
	DynamicKind Kind = "dynamic"
	UnionKind   Kind = "union"
)

type Presentation 

type Presentation struct {
	Kind     PresentationKind `json:"kind,omitempty"`
	LabelKey i18n.MessageKey  `json:"label_key,omitempty"`
	HelpKey  i18n.MessageKey  `json:"help_key,omitempty"`
}

Presentation contains public metadata only. LabelKey and HelpKey reference locale messages; there are deliberately no values, defaults or examples. Declare separate DTOs when input and output need different presentation.

func (Presentation) Validate 

func (p Presentation) Validate() error

Validate checks the closed kind set and bounded translation keys.

func (Presentation) ValidateFile 

func (p Presentation) ValidateFile() error

ValidateFile checks metadata on an actual multipart upload part.

func (Presentation) ValidateSchema 

func (p Presentation) ValidateSchema(schema Schema) error

ValidateSchema checks presentation of a complete JSON value, resolving its root aliases through the same schema compiler used by runtime codecs.

func (Presentation) ValidateType 

func (p Presentation) ValidateType(typ Type) error

ValidateType checks a resolved JSON/URL value shape. Schema normalization resolves aliases before calling this method. Files use ValidateFile instead.

type PresentationKind 

type PresentationKind string

PresentationKind is an optional public display hint. It never changes codecs, validation, authorization or storage. An empty kind leaves control selection to the consumer using the existing type, enum and rule descriptions. 

const (
	TextPresentation      PresentationKind = "text"
	MultilinePresentation PresentationKind = "multiline"
	PasswordPresentation  PresentationKind = "password"
	EmailPresentation     PresentationKind = "email"
	URLPresentation       PresentationKind = "url"
	MoneyPresentation     PresentationKind = "money"
	FilePresentation      PresentationKind = "file"
)

func PresentationKinds 

func PresentationKinds() []PresentationKind

PresentationKinds returns the closed kind set in declaration order. Generated clients derive their kind type from it.

type Property 

type Property struct {
	Name         string       `json:"name"`
	Type         TypeID       `json:"type"`
	Required     bool         `json:"required"`
	Presentation Presentation `json:"presentation,omitzero"`
}

Property binds an exact, case-sensitive JSON name to its declared wire type. Required describes presence independently of the target type's nullability.

type Scalar 

type Scalar[T any] struct {
	// contains filtered or unexported fields
}

Scalar binds one non-null scalar wire description to the concrete Go value T. Its zero value is invalid. Transport codecs and generated declarations retain this type instead of attaching an unrelated value's metadata to a parameter.

func DefineScalar 

func DefineScalar[T any](description Type) Scalar[T]

DefineScalar is the explicit metadata boundary used by transport declarations. It validates and copies a single string, boolean, integer or number description, reusing the JSON schema compiler and enum resolution. Generator analysis or the author of a custom codec owns agreement between T, its codec and this wire description; this function does not infer Go fields.

func (Scalar[T]) Description 

func (d Scalar[T]) Description() (Type, error)

Description returns owned normalized metadata, including copied enum values. Integer widths and enum cases use the same normalization as DTO schemas.

func (Scalar[T]) Validate 

func (d Scalar[T]) Validate() error

Validate reports an invalid or zero scalar declaration.

type ScalarProperty 

type ScalarProperty struct {
	Property Property `json:"property"`
	Value    Type     `json:"value"`
	Quoted   bool     `json:"quoted"`
}

ScalarProperty is a snapshot of one declared top-level property and the underlying scalar used by its Go value. Quoted distinguishes JSON's string representation of a scalar from its typed value. Value.Nullable includes nullable aliases; the full wire graph remains available through Description.

type Schema 

type Schema struct {
	Root  TypeID `json:"root"`
	Types []Type `json:"types"`
}

Schema is the normalized description at a serialization boundary. Construct typed JSON descriptors through generated code; definitions are validated and copied before use. Description returns another owned snapshot.

func (Schema) Normalize 

func (s Schema) Normalize() (Schema, error)

Normalize validates and copies a possibly serialized schema for inspection and client export. It shares the runtime graph compiler, including reference, alias-cycle, enum, resource and property checks. It does not install native Go map-key codecs: metadata alone cannot create a typed runtime JSON binding.

func (Schema) ScalarProperties 

func (s Schema) ScalarProperties(names ...string) ([]ScalarProperty, error)

ScalarProperties validates inspection metadata and describes selected top-level scalar properties in the supplied order. With no names it describes every property in normalized order. It shares alias/nullability/quoted resolution with typed JSON descriptors and rejects selected structured fields.

type TableID added in v0.3.0 

type TableID string

TableID identifies a registered datatable, never a SQL table name.

type TableOperationBinding added in v0.3.0 

type TableOperationBinding struct {
	Table        TableID            `json:"table"`
	Kind         TableOperationKind `json:"kind"`
	RequestField string             `json:"request_field,omitempty"`
}

TableOperationBinding explicitly associates an HTTP operation with a table. RequestField is the top-level JSON property containing Request for ticket exports.

type TableOperationKind added in v0.3.0 

type TableOperationKind string

TableOperationKind identifies the declared role of a table's HTTP operation. 

const (
	// TableQuery accepts a table request and returns its canonical numbered page.
	TableQuery TableOperationKind = "query"
	// TableTicketExport issues an application-defined JSON export ticket.
	TableTicketExport TableOperationKind = "ticket-export"
	// TableFileExport returns an exported file directly.
	TableFileExport TableOperationKind = "file-export"
	// TableDownload retrieves an exported file without a request body.
	TableDownload TableOperationKind = "download"
)

type Type 

type Type struct {
	ID            TypeID              `json:"id"`
	Kind          Kind                `json:"kind"`
	Nullable      bool                `json:"nullable"`
	Discriminator string              `json:"discriminator,omitempty"`
	Variants      []Variant           `json:"variants,omitempty"`
	Properties    []Property          `json:"properties,omitempty"`
	Key           *JSONKeyInfo        `json:"key,omitempty"`
	Element       TypeID              `json:"element,omitempty"`
	Length        value.Optional[int] `json:"length,omitzero"`
	Bits          uint8               `json:"bits,omitempty"`
	Signed        bool                `json:"signed,omitempty"`
	Format        Format              `json:"format,omitempty"`
	Cases         []json.RawMessage   `json:"cases,omitempty"`
	// contains filtered or unexported fields
}

Type is one normalized wire shape. Only fields appropriate for Kind may be set. Element describes array/map elements or an alias/quoted target. Integer Integer Bits==0 is normalized to the Go target's native int width. Number Bits==0 preserves json.Number lexemes; 32/64 describe concrete floating point. Length, when set, describes an exact array length, including an empty array. Cases are exact JSON string/integer constants, never floating-point metadata.

func EnumType 

func EnumType[E enum.Scalar](id TypeID, descriptor enum.Descriptor[E]) Type

EnumType uses an enum's existing typed descriptor as the source of its wire cases. Generated DTO declarations use this for local and imported enums. DefineJSON resolves and validates cases once, containing codec failures and retaining only owned normalized metadata. The returned Type is a declaration; use a validated JSON descriptor's Description for client export.

func JSONMapType 

func JSONMapType[M ~map[K]V, K comparable, V any](id, element, keyID TypeID, key JSONKey[K]) Type

JSONMapType is the generated map declaration boundary. M retains both key and value types; an unrelated JSONKey cannot bind to this map. IDs describe the generated map, its element and source key type respectively. Generation owns those source identities, including executable main-package namespaces.

func JSONParameter 

func JSONParameter[T any](id TypeID, argument JSON[T]) Type

JSONParameter includes a typed argument in a generated generic graph. The generated identity names the actual Go type; the argument owns its wire shape. A different root name (for example Slice's synthetic root) is rewritten in an owned snapshot. Invalid arguments remain invalid, including unused arguments.

func JSONSliceType 

func JSONSliceType[S ~[]E, E any](id, element TypeID) Type

JSONSliceType specializes the native byte-slice representation after generic substitution, including named generic slice types. Ordinary slices retain their element contract and nullability. No element values or schema fields are inspected.

func JSONType 

func JSONType[T any](id TypeID, factory func() JSON[T]) Type

JSONType includes a custom value's typed contract in a generated DTO graph. The factory must describe T using the exact supplied qualified identity. It is called once during descriptor construction, never while decoding a request. A runtime main package (including a named generic argument) keeps its source identity through a generated alias; other qualified names must match exactly. Factories must be deterministic, bounded and independent of receiver state. Failure, panic, Goexit, conflicting definitions and an invalid zero descriptor reject the containing contract. Generated declarations supply this boundary.

type TypeID 

type TypeID string

TypeID identifies a declaration or derived wire shape within a schema graph. Generated identities use qualified Go names; exporters own target-language naming and must not mistake these identifiers for OpenAPI component names.

func GoTypeID 

func GoTypeID(source string, named bool) TypeID

GoTypeID is the identity boundary used by generated generic DTO declarations. source is a qualified Go type expression, not a wire schema or a sample value. Named and primitive values use named=true; composite expressions use false.

func JSONArgumentID 

func JSONArgumentID[T any](argument JSON[T]) TypeID

JSONArgumentID retains the actual type of a supplied generic argument.

type UnionValue 

type UnionValue[T any] struct {
	// contains filtered or unexported fields
}

UnionValue is immutable generated-union storage, scoped to its concrete union. A validated wire snapshot prevents mutable payload aliases and recursive custom encoders from changing a previously constructed union. Zero is invalid. Consumers use generated constructors/accessors, never a dynamic variant bag.

func DecodeUnion 

func DecodeUnion[T any](descriptor JSON[T], data []byte) (UnionValue[T], error)

DecodeUnion validates the complete tagged wire object without calling T's decoder recursively. Generated code then checks the selected native Go payload.

func EncodeUnion 

func EncodeUnion[T, P any](descriptor JSON[T], tag string, input P) (UnionValue[T], error)

EncodeUnion captures an owned typed variant once. Its generated caller chooses the literal; the shared graph rejects undeclared tags and incorrect wire shapes. Union payload accessors decode owned values, like value.JSON's snapshot API.

func (UnionValue[T]) IsZero 

func (v UnionValue[T]) IsZero() bool

IsZero reports whether the union value has no encoded representation.

func (UnionValue[T]) MarshalJSON 

func (v UnionValue[T]) MarshalJSON() ([]byte, error)

MarshalJSON returns the stored JSON representation, rejecting the zero value.

func (UnionValue[T]) Tag 

func (v UnionValue[T]) Tag() string

Tag returns the selected literal, or empty for an unset union.

type Variant 

type Variant struct {
	Tag  string `json:"tag"`
	Type TypeID `json:"type"`
}

Variant binds one closed discriminator literal to an ordinary object payload. Payload properties come from that object's existing schema.

Source Files

View all Source files

Directories

Path Synopsis
Package manifest assembles feature-owned transport metadata into one versioned client contract.
 Package manifest assembles feature-owned transport metadata into one versioned client contract.

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.