README
¶
Validate Arazzo workflows
The arazzo package validates Arazzo 1.0 and 1.1 documents. It checks document
structure, workflow and step names, parameters, actions, expressions, input
schemas and prerequisite cycles. Supply OpenAPI, AsyncAPI or Arazzo source
documents to check referenced operations, channels and workflows.
result, err := arazzo.ValidateBytes(ctx, spec, "workflows.yaml",
arazzo.WithSources(candidates...))
if err != nil {
return err
}
if !result.Valid() {
return fmt.Errorf("invalid Arazzo: %v", result.Diagnostics)
}
if !result.Complete {
return fmt.Errorf("validation incomplete: %v", result.Checks)
}
Validate accepts existing nodes through arazzo.Document. Source candidates
use libopenapi/arazzo.CandidateDocument; they can contain nodes, bytes, models
or adapters. See the complete example.
Always check the error, Valid() and Complete. Valid() means no conformance
errors were found. Complete means every applicable check ran. Missing sources,
partial adapter metadata and unsupported syntax can leave a valid document
incompletely checked. Checks gives the affected source, field and reason.
Errors return a non-nil incomplete result. Diagnostics include codes, source URIs,
JSON Pointers and line/column locations. Caller nodes and models stay unchanged.
The validator does not run workflows or fetch files or URLs by default.
WithResolver enables caller-controlled source retrieval. It does not retrieve
external input schemas. XPath, legacy JSONPath and conditions that need runtime
substitution report incomplete checks. Rootless Arazzo models also have partial
expression coverage; supply original nodes or bytes for full checks.
WithLimits bounds resource use; WithAdvisories enables optional authoring
warnings. Put whitespace around logical operators next to bare header
expressions: & and | are legal header-name characters.
The requirements ledger lists specification clauses, tests and known schema differences.
Documentation
¶
Overview ¶
Package arazzo validates Arazzo 1.0 and 1.1 descriptions without executing workflows. Validation performs no retrieval unless a caller supplies a resolver.
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Check ¶
type Check struct {
Name string `json:"name"`
Status CheckStatus `json:"status"`
URI string `json:"uri"`
Pointer string `json:"pointer,omitempty"`
Source string `json:"source,omitempty"`
Reason string `json:"reason,omitempty"`
}
Check identifies a completed or unavailable check at its affected source slot. Incomplete checks do not imply a malformed document.
type CheckStatus ¶
type CheckStatus string
CheckStatus records whether an applicable check ran.
const ( CheckComplete CheckStatus = "complete" CheckIncomplete CheckStatus = "incomplete" )
type Code ¶
type Code string
Code is a stable diagnostic identifier, suitable for rule suppression.
const ( CodeStructure Code = "arazzo-structure" CodeDuplicateID Code = "arazzo-duplicate-id" CodeReference Code = "arazzo-reference" CodeParameter Code = "arazzo-parameter" CodeExpression Code = "arazzo-expression" CodeSelector Code = "arazzo-selector" CodeDependency Code = "arazzo-dependency" CodeInputSchema Code = "arazzo-input-schema" CodeSourceType Code = "arazzo-source-type" CodeAdvisory Code = "arazzo-advisory" )
Diagnostic codes distinguish structural, identity, reference and syntax checks.
const CodeAction Code = "arazzo-action"
CodeAction identifies invalid contextual action targets or action fields.
const CodeForwardReference Code = "arazzo-forward-reference"
CodeForwardReference identifies optional guidance for sequential workflows.
type Diagnostic ¶
type Diagnostic struct {
Code Code `json:"code"`
Severity Severity `json:"severity"`
Message string `json:"message"`
Location
SchemaPointer string `json:"schemaPointer,omitempty"`
Related []Location `json:"related,omitempty"`
}
Diagnostic describes a document error without retaining source nodes or models.
type Document ¶
Document is an immutable source tree and its retrieval URI. Root can be a YAML document node or its object node. URI supplies the base for relative URLs.
type Error ¶
Error is a typed tool error. Invalid document fields normally produce diagnostics.
type ErrorKind ¶
type ErrorKind string
ErrorKind distinguishes input, feature, configuration and operational failures.
type Limits ¶
type Limits struct {
MaxBytes int
MaxNodes int
MaxDepth int
MaxSources int
MaxDiagnostics int
MaxPatternBytes int
}
Limits bounds each validation call, including alias expansion and source loads. Every field must be positive when passed to WithLimits.
type Location ¶
type Location struct {
URI string `json:"uri"`
Pointer string `json:"pointer"`
Line int `json:"line"`
Column int `json:"column"`
}
Location contains detached source coordinates and an RFC 6901 instance pointer. Line and column are one-based, or zero when the caller's nodes have no position.
type Option ¶
type Option func(*options) error
Option configures one validation call. Options do not modify shared state.
func WithAdvisories ¶
func WithAdvisories() Option
WithAdvisories enables optional authoring recommendations.
func WithBaseURI ¶
WithBaseURI provides an application base when the document URI is relative.
func WithLimits ¶
WithLimits replaces all resource limits for this call.
func WithResolver ¶
func WithResolver(resolver source.SourceDocumentResolver) Option
WithResolver enables explicit caller-owned retrieval. The resolver must honor context cancellation and enforce its own network and file access policy.
func WithSources ¶
func WithSources(candidates ...source.CandidateDocument) Option
WithSources supplies application-owned candidate documents. They must remain immutable during validation. Their roots and models are never modified.
type Result ¶
type Result struct {
Version string `json:"version"`
Diagnostics []Diagnostic `json:"diagnostics"`
Checks []Check `json:"checks"`
Complete bool `json:"complete"`
}
Result contains findings and coverage for the detected major.minor feature set. Complete is false if any applicable check was skipped or an operation failed.
func Validate ¶
Validate checks an existing immutable node tree. Document errors are findings; unsupported versions, cancellation, limits and resolver failures are tool errors. A partial result accompanies operational failure and always has Complete=false.
Example ¶
package main
import (
"context"
"fmt"
"os"
"github.com/pb33f/go-yaml"
"github.com/pb33f/libopenapi-validator/arazzo"
upstream "github.com/pb33f/libopenapi/arazzo"
)
func exampleNode(name string) *yaml.Node {
data, err := os.ReadFile("testdata/mixed-source/" + name)
if err != nil {
panic(err)
}
var root yaml.Node
if err := yaml.Unmarshal(data, &root); err != nil {
panic(err)
}
return &root
}
func main() {
// The application supplies parsed source documents. Validation needs no
// OpenAPI Doctor model and performs no retrieval or workflow execution.
document := arazzo.Document{Root: exampleNode("workflow.yaml"), URI: "https://retrieval.test/main.yaml"}
var sources []upstream.CandidateDocument
for _, name := range []string{"api.yaml", "events.yaml", "flows.yaml"} {
sources = append(sources, upstream.CandidateDocument{
RootNode: exampleNode(name), RetrievalURI: "https://example.test/" + name,
})
}
result, err := arazzo.Validate(context.Background(), document, arazzo.WithSources(sources...))
if err != nil {
panic(err)
}
fmt.Println(result.Version, result.Valid(), result.Complete)
}
Output: 1.1 true true
func ValidateBytes ¶
ValidateBytes parses exactly one JSON or YAML document and validates it through the same path as Validate. Parse failures and multiple documents are input errors. Every failure returns a non-nil incomplete result.
Source Files