expression

package
v0.39.0 Latest Latest
Warning

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

 Go to latest Published: Sep 22, 2026 License: MIT Imports: 6 Imported by: 1

Documentation

Overview

Package expression implements the Arazzo runtime expression parser, local symbol resolver, and evaluator. https://spec.openapis.org/arazzo/v1.1.0.html#runtime-expressions

Index

Constants

This section is empty.

Variables

View Source 
var ErrLocalSymbolNotFound = errors.New("local runtime-expression symbol not found")

ErrLocalSymbolNotFound identifies a runtime expression that references a symbol unavailable in its current Arazzo document scope.

Functions

func Evaluate 

func Evaluate(expr Expression, ctx *Context) (any, error)

Evaluate resolves a parsed Expression against a Context.

func EvaluateString 

func EvaluateString(input string, ctx *Context) (any, error)

EvaluateString parses and evaluates a runtime expression string in one call.

func ResolveLocal added in v0.39.0 

func ResolveLocal(expr Expression, symbols *LocalSymbols) error

ResolveLocal checks the document-local portion of an already parsed runtime expression. It never resolves or retrieves an external source document.

func SplitSimpleCondition added in v0.39.0 

func SplitSimpleCondition(input string) (left, operator, right string, found bool)

SplitSimpleCondition separates the operands and comparison operator in an Arazzo simple condition. Operators inside a runtime expression's JSON Pointer are ignored.

func UnescapeJSONPointer 

func UnescapeJSONPointer(s string) string

UnescapeJSONPointer applies RFC 6901 unescaping: ~1 -> /, ~0 -> ~

func Validate 

func Validate(input string) error

Validate checks whether a string is a valid runtime expression under the Arazzo 1.1 grammar, without allocating a full AST.

func ValidateLocal added in v0.39.0 

func ValidateLocal(input string, symbols *LocalSymbols) error

ValidateLocal parses a runtime expression and checks its document-local symbols without evaluating runtime values or resolving external documents.

func ValidateWithVersion added in v0.39.0 

func ValidateWithVersion(input string, version SpecVersion) error

ValidateWithVersion checks whether a string is a valid runtime expression under the grammar for the given specification version.

Types

type ComponentsContext 

type ComponentsContext struct {
	Parameters     map[string]any
	SuccessActions map[string]any
	FailureActions map[string]any
	Inputs         map[string]any
}

ComponentsContext holds resolved component data.

type Context 

type Context struct {
	Self            string
	URL             string
	Method          string
	StatusCode      int
	RequestHeaders  map[string]string
	RequestQuery    map[string]string
	RequestPath     map[string]string
	RequestBody     *yaml.Node
	RequestPayload  *yaml.Node
	ResponseHeaders map[string]string
	ResponseQuery   map[string]string
	ResponsePath    map[string]string
	ResponseBody    *yaml.Node
	ResponsePayload *yaml.Node
	MessageHeaders  map[string]string
	MessageQuery    map[string]string
	MessagePath     map[string]string
	MessageBody     *yaml.Node
	MessagePayload  *yaml.Node
	Inputs          map[string]any
	Outputs         map[string]any
	Steps           map[string]*StepContext
	Workflows       map[string]*WorkflowContext
	SourceDescs     map[string]*SourceDescContext
	Components      *ComponentsContext
}

Context holds runtime values for expression evaluation.

type Expression 

type Expression struct {
	Type        ExpressionType // The kind of expression
	Raw         string         // Original input string
	Name        string         // First segment after prefix (header name, step ID, etc.)
	Tail        string         // Everything after name for Steps/Workflows/SourceDescriptions/Components
	Property    string         // Sub-property for request/response sources (header/query/path name)
	JSONPointer string         // For body references: the #/path portion
}

Expression represents a parsed Arazzo runtime expression.

func Parse 

func Parse(input string) (Expression, error)

Parse parses a single Arazzo runtime expression under the Arazzo 1.1 grammar. Returns a value type to avoid heap allocation. Use ParseWithVersion for 1.0 documents.

func ParseWithVersion added in v0.39.0 

func ParseWithVersion(input string, version SpecVersion) (Expression, error)

ParseWithVersion parses a single Arazzo runtime expression under the grammar for the given specification version. See SpecVersion for what differs between them.

type ExpressionType 

type ExpressionType int

ExpressionType identifies the kind of runtime expression. 

const (
	URL                     ExpressionType = iota // $url
	Method                                        // $method
	StatusCode                                    // $statusCode
	RequestHeader                                 // $request.header.{name}
	RequestQuery                                  // $request.query.{name}
	RequestPath                                   // $request.path.{name}
	RequestBody                                   // $request.body{#/json-pointer}
	ResponseHeader                                // $response.header.{name}
	ResponseQuery                                 // $response.query.{name}
	ResponsePath                                  // $response.path.{name}
	ResponseBody                                  // $response.body{#/json-pointer}
	Inputs                                        // $inputs.{name}
	Outputs                                       // $outputs.{name}
	Steps                                         // $steps.{name}[.tail]
	Workflows                                     // $workflows.{name}[.tail]
	SourceDescriptions                            // $sourceDescriptions.{name}[.tail]
	Components                                    // $components.{name}[.tail]
	ComponentParameters                           // $components.parameters.{name}
	Self                                          // $self
	RequestPayload                                // $request.payload{#/json-pointer}
	ResponsePayload                               // $response.payload{#/json-pointer}
	MessageHeader                                 // $message.header.{name}
	MessageQuery                                  // $message.query.{name}
	MessagePath                                   // $message.path.{name}
	MessageBody                                   // $message.body{#/json-pointer}
	MessagePayload                                // $message.payload{#/json-pointer}
	ComponentSuccessActions                       // $components.successActions.{name}
	ComponentFailureActions                       // $components.failureActions.{name}
)

type LocalSymbolError added in v0.39.0 

type LocalSymbolError struct {
	Expression string
	Kind       string
	Name       string
}

LocalSymbolError reports the narrow local symbol that could not be resolved.

func (*LocalSymbolError) Error added in v0.39.0 

func (e *LocalSymbolError) Error() string

Error returns a stable diagnostic for an unresolved local symbol.

func (*LocalSymbolError) Unwrap added in v0.39.0 

func (e *LocalSymbolError) Unwrap() error

Unwrap exposes ErrLocalSymbolNotFound for errors.Is.

type LocalSymbols added in v0.39.0 

type LocalSymbols struct {
	HasSelf                 bool
	Inputs                  SymbolSet
	Outputs                 SymbolSet
	Steps                   map[string]StepSymbols
	Workflows               map[string]WorkflowSymbols
	SourceDescriptions      SymbolSet
	ComponentParameters     SymbolSet
	ComponentSuccessActions SymbolSet
	ComponentFailureActions SymbolSet
}

LocalSymbols contains the document-local names available to a runtime expression. It deliberately contains no document loader or external source adapter.

type SourceDescContext 

type SourceDescContext struct {
	URL        string
	Type       string
	Operations map[string]any
	Workflows  map[string]any
	Fields     map[string]any
}

SourceDescContext holds resolved source description data.

type SpecVersion added in v0.39.0 

type SpecVersion uint8

SpecVersion selects which Arazzo runtime-expression grammar a parse applies.

Arazzo 1.0.1 uses general name productions for $steps, $workflows, $sourceDescriptions and $components. Arazzo 1.1.0 replaces them with more structured forms and restricts component types. Callers that know the document version should pass it explicitly so legal 1.0 expressions are not rejected by the 1.1 grammar. 

const (
	// Arazzo11 applies the Arazzo 1.1.0 grammar. This is the default for the
	// version-free parser entry points.
	Arazzo11 SpecVersion = iota

	// Arazzo10 applies the Arazzo 1.0.1 grammar, which additionally accepts the
	// general "$components." name production.
	Arazzo10
)

type StepContext 

type StepContext struct {
	Inputs  map[string]any
	Outputs map[string]any
}

StepContext holds inputs and outputs for a specific step.

type StepSymbols added in v0.39.0 

type StepSymbols struct {
	Outputs SymbolSet
}

StepSymbols contains the locally declared outputs for a step.

type SymbolSet added in v0.39.0 

type SymbolSet map[string]struct{}

SymbolSet is an allocation-conscious lookup set for local Arazzo names.

type Token 

type Token struct {
	Literal      string     // Non-empty if this is a literal text segment
	Expression   Expression // Valid if IsExpression is true
	IsExpression bool       // True if this token is an expression
}

Token represents a segment in an embedded expression string like "prefix {$expr} suffix".

func ParseEmbedded 

func ParseEmbedded(input string) ([]Token, error)

ParseEmbedded parses a string that may contain embedded runtime expressions in {$...} blocks, under the Arazzo 1.1 grammar. Returns alternating literal and expression tokens.

func ParseEmbeddedWithVersion added in v0.39.0 

func ParseEmbeddedWithVersion(input string, version SpecVersion) ([]Token, error)

ParseEmbeddedWithVersion parses embedded runtime expressions under the grammar for the given specification version.

type WorkflowContext 

type WorkflowContext struct {
	Inputs  map[string]any
	Outputs map[string]any
}

WorkflowContext holds inputs and outputs for a specific workflow.

type WorkflowSymbols added in v0.39.0 

type WorkflowSymbols struct {
	Inputs  SymbolSet
	Outputs SymbolSet
}

WorkflowSymbols contains the locally declared inputs and outputs for a workflow.

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.