arazzo

package
v1.27.0 Latest Latest
Warning

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

Go to latest
Published: Nov 17, 2026 License: MIT Imports: 39 Imported by: 1

README

Arazzo

Arazzo Parser

An API for working with Arazzo documents including: read, walk, create, mutate, and validate

Arazzo reference Built by Speakeasy Release Go Doc
Go Report Card Software License

Supported versions

Arazzo version Support
1.1.x Read, write, walk and validate, including AsyncAPI steps (channelPath, action, correlationId), dependsOn, timeout, Selector Objects, action parameters, $self and the stricter 1.1 runtime expression grammar. AsyncAPI documents are not loaded, so references into them are only checked structurally.
1.0.x Read, write, walk and validate.

Any patch release of a supported minor version is accepted (including prerelease suffixes such as 1.1.0-rc1). Validation follows the version declared by the document, so using an Arazzo 1.1 feature in a document that declares arazzo: 1.0.x is reported as an error. Use arazzo.Upgrade (or openapi arazzo upgrade) to move a 1.0.x document to 1.1.0. The upgrade pins jsonpath and xpath criteria to the versions Arazzo 1.0 implied, so their meaning doesn't change.

Where the Arazzo Specification text and its JSON Schema disagree, validation follows the specification text.

Migrating step and workflow outputs

Arazzo 1.1 allows an output to be either a runtime expression or a Selector Object, so arazzo.Outputs is now a map of *arazzo.OutputValue instead of expression.Expression:

// Before
step.Outputs = sequencedmap.New(sequencedmap.NewElem[string, expression.Expression]("petId", "$response.body#/id"))

// After
step.Outputs = sequencedmap.New(sequencedmap.NewElem("petId", arazzo.NewOutputValueFromExpression("$response.body#/id")))

for name, output := range step.Outputs.All() {
	if output.IsExpression() {
		fmt.Println(name, *output.GetExpression())
	}
	if output.IsSelector() {
		fmt.Println(name, output.GetSelector().Selector)
	}
}

Read and parse an Arazzo document from a file

Shows loading a document, handling validation errors, and making simple modifications.

ctx := context.Background()

r, err := os.Open("testdata/simple.arazzo.yaml")
if err != nil {
	panic(err)
}
defer r.Close()

a, validationErrs, err := arazzo.Unmarshal(ctx, r)
if err != nil {
	panic(err)
}

for _, err := range validationErrs {
	fmt.Println(err.Error())
}

a.Info.Title = "Updated Simple Workflow"

buf := bytes.NewBuffer([]byte{})

if err := arazzo.Marshal(ctx, a, buf); err != nil {
	panic(err)
}

fmt.Println(buf.String())

Create an Arazzo document from scratch

Shows building a basic workflow document with info and version programmatically.

ctx := context.Background()

a := &arazzo.Arazzo{
	Arazzo: arazzo.Version,
	Info: arazzo.Info{
		Title:   "My Workflow",
		Summary: pointer.From("A summary"),
		Version: "1.0.1",
	},
}

buf := bytes.NewBuffer([]byte{})

err := arazzo.Marshal(ctx, a, buf)
if err != nil {
	panic(err)
}

fmt.Printf("%s", buf.String())

Modify an existing Arazzo document

Shows loading a document, changing properties, and marshaling it back to YAML.

ctx := context.Background()

f, err := os.Open("testdata/simple.arazzo.yaml")
if err != nil {
	panic(err)
}

a, _, err := arazzo.Unmarshal(ctx, f)
if err != nil {
	panic(err)
}

a.Info.Title = "Updated Simple Workflow"

buf := bytes.NewBuffer([]byte{})

if err := arazzo.Marshal(ctx, a, buf); err != nil {
	panic(err)
}

fmt.Printf("%s", buf.String())

Traverse an Arazzo document using the iterator API

Shows how to match different types of objects like workflows during traversal.

ctx := context.Background()

f, err := os.Open("testdata/simple.arazzo.yaml")
if err != nil {
	panic(err)
}

a, _, err := arazzo.Unmarshal(ctx, f)
if err != nil {
	panic(err)
}

for item := range arazzo.Walk(ctx, a) {
	err := item.Match(arazzo.Matcher{
		Workflow: func(workflow *arazzo.Workflow) error {
			fmt.Printf("Workflow: %s\n", workflow.WorkflowID)
			return nil
		},
	})
	if err != nil {
		panic(err)
	}
}

Upgrade an Arazzo 1.0.x document to the latest supported version

Shows loading a document, upgrading it and validating the result.

ctx := context.Background()

f, err := os.Open("testdata/simple.arazzo.yaml")
if err != nil {
	panic(err)
}
defer f.Close()

a, _, err := arazzo.Unmarshal(ctx, f, arazzo.WithSkipValidation())
if err != nil {
	panic(err)
}

originalVersion := a.Arazzo

upgraded, err := arazzo.Upgrade(ctx, a)
if err != nil {
	panic(err)
}

fmt.Printf("upgraded: %t, from: %s, to: %s\n", upgraded, originalVersion, a.Arazzo)
fmt.Printf("validation errors: %d\n", len(a.Validate(ctx)))

Validate an Arazzo document

Shows loading an invalid document and handling validation errors.

ctx := context.Background()

f, err := os.Open("testdata/invalid.arazzo.yaml")
if err != nil {
	panic(err)
}

_, validationErrs, err := arazzo.Unmarshal(ctx, f)
if err != nil {
	panic(err)
}

for _, err := range validationErrs {
	fmt.Printf("%s\n", err.Error())
}

Validate an Arazzo document against its source descriptions

Shows loading the OpenAPI and Arazzo documents a workflow references and checking its steps against them.

ctx := context.Background()

location := "testdata/sources/invalid.arazzo.yaml"

f, err := os.Open(location)
if err != nil {
	panic(err)
}
defer f.Close()

a, _, err := arazzo.Unmarshal(ctx, f)
if err != nil {
	panic(err)
}

sources, loadErrs := arazzo.LoadSourceDescriptions(ctx, a, arazzo.LoadSourcesOptions{DocumentLocation: location})
fmt.Printf("load errors: %d\n", len(loadErrs))

for i, err := range a.ValidateSources(ctx, sources) {
	if i == 3 {
		break
	}
	fmt.Printf("%s\n", err.Error())
}

Generate starter workflows from an OpenAPI document

Shows generating a workflow calling some operations in order, wired together by the OpenAPI document's links.

ctx := context.Background()

location := "testdata/bootstrap/petstore.openapi.yaml"

f, err := os.Open(location)
if err != nil {
	panic(err)
}
defer f.Close()

doc, _, err := openapi.Unmarshal(ctx, f)
if err != nil {
	panic(err)
}

if _, err := doc.ResolveAllReferences(ctx, openapi.ResolveAllOptions{OpenAPILocation: location}); err != nil {
	panic(err)
}

a, err := arazzo.BootstrapFromOpenAPI(doc, arazzo.BootstrapOptions{
	SourceURL:    "./petstore.openapi.yaml",
	OperationIDs: []string{"listPets", "getPet"},
	WorkflowID:   "findPet",
})
if err != nil {
	panic(err)
}

for _, step := range a.Workflows[0].Steps {
	for _, parameter := range step.Parameters {
		fmt.Printf("%s: %s = %s\n", step.StepID, parameter.Object.Name, parameter.Object.Value.Value)
	}
}

Contributing

This repository is maintained by Speakeasy, but we welcome and encourage contributions from the community to help improve its capabilities and stability.

How to Contribute

  1. Open Issues: Found a bug or have a feature suggestion? Open an issue to describe what you'd like to see changed.

  2. Pull Requests: We welcome pull requests! If you'd like to contribute code:

    • Fork the repository
    • Create a new branch for your feature/fix
    • Submit a PR with a clear description of the changes and any related issues
  3. Feedback: Share your experience using the packages or suggest improvements.

All contributions, whether they're bug reports, feature requests, or code changes, help make this project better for everyone.

Please ensure your contributions adhere to our coding standards and include appropriate tests where applicable.

Documentation

Overview

Package arazzo provides an API for working with Arazzo documents including reading, creating, mutating, walking and validating them.

The Arazzo Specification is a mechanism for orchestrating API calls, defining their sequences and dependencies, to achieve specific outcomes when working with API descriptions like OpenAPI.

Example (Bootstrapping)

Example_bootstrapping demonstrates how to generate starter workflows from an OpenAPI document. Shows generating a workflow calling some operations in order, wired together by the OpenAPI document's links.

package main

import (
	"context"
	"fmt"
	"os"

	"github.com/speakeasy-api/openapi/arazzo"
	"github.com/speakeasy-api/openapi/openapi"
)

func main() {
	ctx := context.Background()

	location := "testdata/bootstrap/petstore.openapi.yaml"

	f, err := os.Open(location)
	if err != nil {
		panic(err)
	}
	defer f.Close()

	doc, _, err := openapi.Unmarshal(ctx, f)
	if err != nil {
		panic(err)
	}

	// Resolve references so parameters, request bodies and links declared as components are used.
	if _, err := doc.ResolveAllReferences(ctx, openapi.ResolveAllOptions{OpenAPILocation: location}); err != nil {
		panic(err)
	}

	a, err := arazzo.BootstrapFromOpenAPI(doc, arazzo.BootstrapOptions{
		SourceURL:    "./petstore.openapi.yaml",
		OperationIDs: []string{"listPets", "getPet"},
		WorkflowID:   "findPet",
	})
	if err != nil {
		panic(err)
	}

	for _, step := range a.Workflows[0].Steps {
		for _, parameter := range step.Parameters {
			fmt.Printf("%s: %s = %s\n", step.StepID, parameter.Object.Name, parameter.Object.Value.Value)
		}
	}
}
Output:
listPets: species = $inputs.species
getPet: petId = $steps.listPets.outputs.petId
Example (Creating)

Example_creating demonstrates how to create an Arazzo document from scratch. Shows building a basic workflow document with info and version programmatically.

package main

import (
	"bytes"
	"context"
	"fmt"

	"github.com/speakeasy-api/openapi/arazzo"
	"github.com/speakeasy-api/openapi/pointer"
)

func main() {
	ctx := context.Background()

	a := &arazzo.Arazzo{
		Arazzo: arazzo.Version,
		Info: arazzo.Info{
			Title:   "My Workflow",
			Summary: pointer.From("A summary"),
			Version: "1.0.1",
		},
		// ...
	}

	buf := bytes.NewBuffer([]byte{})

	err := arazzo.Marshal(ctx, a, buf)
	if err != nil {
		panic(err)
	}

	fmt.Printf("%s", buf.String())
}
Output:
arazzo: 1.1.0
info:
  title: My Workflow
  summary: A summary
  version: 1.0.1
Example (Mutating)

Example_mutating demonstrates how to modify an existing Arazzo document. Shows loading a document, changing properties, and marshaling it back to YAML.

package main

import (
	"bytes"
	"context"
	"fmt"
	"os"

	"github.com/speakeasy-api/openapi/arazzo"
)

func main() {
	ctx := context.Background()

	f, err := os.Open("testdata/simple.arazzo.yaml")
	if err != nil {
		panic(err)
	}

	a, _, err := arazzo.Unmarshal(ctx, f)
	if err != nil {
		panic(err)
	}

	a.Info.Title = "Updated Simple Workflow"

	buf := bytes.NewBuffer([]byte{})

	if err := arazzo.Marshal(ctx, a, buf); err != nil {
		panic(err)
	}

	fmt.Printf("%s", buf.String())
}
Output:
arazzo: 1.0.0
info:
  title: Updated Simple Workflow
  version: 1.0.0
sourceDescriptions:
  - name: api
    url: https://api.example.com/openapi.yaml
    type: openapi
workflows:
  - workflowId: simpleWorkflow
    summary: A simple workflow
    steps:
      - stepId: step1
        operationId: getUser
        parameters:
          - name: id
            in: path
            value: "123"
Example (Reading)

Example_reading demonstrates how to read and parse an Arazzo document from a file. Shows loading a document, handling validation errors, and making simple modifications.

package main

import (
	"bytes"
	"context"
	"fmt"
	"os"

	"github.com/speakeasy-api/openapi/arazzo"
)

func main() {
	ctx := context.Background()

	r, err := os.Open("testdata/simple.arazzo.yaml")
	if err != nil {
		panic(err)
	}
	defer r.Close()

	// Unmarshal the Arazzo document which will also validate it against the Arazzo Specification
	a, validationErrs, err := arazzo.Unmarshal(ctx, r)
	if err != nil {
		panic(err)
	}

	// Validation errors are returned separately from any errors that block the document from being unmarshalled
	// allowing an invalid document to be mutated and fixed before being marshalled again
	for _, err := range validationErrs {
		fmt.Println(err.Error())
	}

	// Mutate the document by just modifying the returned Arazzo object
	a.Info.Title = "Updated Simple Workflow"

	buf := bytes.NewBuffer([]byte{})

	// Marshal the document to a writer
	if err := arazzo.Marshal(ctx, a, buf); err != nil {
		panic(err)
	}

	fmt.Println(buf.String())
}
Output:
arazzo: 1.0.0
info:
  title: Updated Simple Workflow
  version: 1.0.0
sourceDescriptions:
  - name: api
    url: https://api.example.com/openapi.yaml
    type: openapi
workflows:
  - workflowId: simpleWorkflow
    summary: A simple workflow
    steps:
      - stepId: step1
        operationId: getUser
        parameters:
          - name: id
            in: path
            value: "123"
Example (Upgrading)

Example_upgrading demonstrates how to upgrade an Arazzo 1.0.x document to the latest supported version. Shows loading a document, upgrading it and validating the result.

package main

import (
	"context"
	"fmt"
	"os"

	"github.com/speakeasy-api/openapi/arazzo"
)

func main() {
	ctx := context.Background()

	f, err := os.Open("testdata/simple.arazzo.yaml")
	if err != nil {
		panic(err)
	}
	defer f.Close()

	a, _, err := arazzo.Unmarshal(ctx, f, arazzo.WithSkipValidation())
	if err != nil {
		panic(err)
	}

	originalVersion := a.Arazzo

	upgraded, err := arazzo.Upgrade(ctx, a)
	if err != nil {
		panic(err)
	}

	fmt.Printf("upgraded: %t, from: %s, to: %s\n", upgraded, originalVersion, a.Arazzo)
	fmt.Printf("validation errors: %d\n", len(a.Validate(ctx)))
}
Output:
upgraded: true, from: 1.0.0, to: 1.1.0
validation errors: 0
Example (Validating)

Example_validating demonstrates how to validate an Arazzo document. Shows loading an invalid document and handling validation errors.

package main

import (
	"context"
	"fmt"
	"os"

	"github.com/speakeasy-api/openapi/arazzo"
)

func main() {
	ctx := context.Background()

	f, err := os.Open("testdata/invalid.arazzo.yaml")
	if err != nil {
		panic(err)
	}

	_, validationErrs, err := arazzo.Unmarshal(ctx, f)
	if err != nil {
		panic(err)
	}

	for _, err := range validationErrs {
		fmt.Printf("%s\n", err.Error())
	}
}
Output:
[3:3] error validation-required-field `info.version` is required
[13:9] error validation-required-field step at least one of operationId, operationPath or workflowId fields must be set
[22:13] error validation-required-field parameter.in is required within a step when workflowId is not set
Example (ValidatingSources)

Example_validatingSources demonstrates how to validate an Arazzo document against its source descriptions. Shows loading the OpenAPI and Arazzo documents a workflow references and checking its steps against them.

package main

import (
	"context"
	"fmt"
	"os"

	"github.com/speakeasy-api/openapi/arazzo"
)

func main() {
	ctx := context.Background()

	location := "testdata/sources/invalid.arazzo.yaml"

	f, err := os.Open(location)
	if err != nil {
		panic(err)
	}
	defer f.Close()

	a, _, err := arazzo.Unmarshal(ctx, f)
	if err != nil {
		panic(err)
	}

	// Relative source description URLs are resolved against $self, or the document's location.
	sources, loadErrs := arazzo.LoadSourceDescriptions(ctx, a, arazzo.LoadSourcesOptions{DocumentLocation: location})
	fmt.Printf("load errors: %d\n", len(loadErrs))

	// Only the first few errors are printed to keep the example short.
	for i, err := range a.ValidateSources(ctx, sources) {
		if i == 3 {
			break
		}
		fmt.Printf("%s\n", err.Error())
	}
}
Output:
load errors: 0
[16:9] error validation-invalid-reference workflow.dependsOn references workflowId `missingWorkflow` which doesn't exist in sourceDescription `shared`
[19:22] error validation-operation-not-found step.operationId `missingOperation` not found in sourceDescription `petstore`
[21:24] error validation-operation-not-found step.operationPath `{$sourceDescriptions.petstore.url}#/paths/~1missing/get` doesn't reference an operation in sourceDescription `petstore`
Example (Walking)

Example_walking demonstrates how to traverse an Arazzo document using the iterator API. Shows how to match different types of objects like workflows during traversal.

package main

import (
	"context"
	"fmt"
	"os"

	"github.com/speakeasy-api/openapi/arazzo"
)

func main() {
	ctx := context.Background()

	f, err := os.Open("testdata/simple.arazzo.yaml")
	if err != nil {
		panic(err)
	}

	a, _, err := arazzo.Unmarshal(ctx, f)
	if err != nil {
		panic(err)
	}

	for item := range arazzo.Walk(ctx, a) {
		err := item.Match(arazzo.Matcher{
			Workflow: func(workflow *arazzo.Workflow) error {
				fmt.Printf("Workflow: %s\n", workflow.WorkflowID)
				return nil
			},
		})
		if err != nil {
			panic(err)
		}
	}
}
Output:
Workflow: simpleWorkflow

Index

Examples

Constants

View Source
const (
	// DefaultBootstrapWorkflowID is the workflowId of the workflow generated for BootstrapOptions.OperationIDs.
	DefaultBootstrapWorkflowID = "main"
	// UntaggedWorkflowID is the workflowId of the workflow generated for operations without tags. It can be passed
	// in BootstrapOptions.Tags to select those operations.
	UntaggedWorkflowID = "default"
)
View Source
const (
	// SourceDescriptionTypeOpenAPI represents a SourceDescription that describes an OpenAPI document.
	SourceDescriptionTypeOpenAPI = "openapi"
	// SourceDescriptionTypeArazzo represents a SourceDescription that describes an Arazzo document.
	SourceDescriptionTypeArazzo = "arazzo"
	// SourceDescriptionTypeAsyncAPI represents a SourceDescription that describes an AsyncAPI document. Arazzo 1.1+ only.
	SourceDescriptionTypeAsyncAPI = "asyncapi"
)
View Source
const (
	Version = "1.1.0"
)

Version is the latest version of the Arazzo Specification that this package conforms to.

Variables

View Source
var (
	// MinimumSupportedVersion is the earliest supported Arazzo Specification version.
	MinimumSupportedVersion = version.MustParse("1.0.0")
	// MaximumSupportedVersion is the latest Arazzo Specification version this package was built against.
	// As the Arazzo Specification states the patch version should not be considered by tooling, any
	// patch release of a supported minor version (see SupportedMinorVersions) is accepted.
	MaximumSupportedVersion = version.MustParse(Version)
	// SupportedMinorVersions are the `major.minor` Arazzo Specification versions supported by this package.
	SupportedMinorVersions = []string{"1.0", "1.1"}
)

Functions

func IsSupportedVersion added in v1.27.0

func IsSupportedVersion(v string) bool

IsSupportedVersion returns true if the provided Arazzo version string is a supported version. Any patch release (and prerelease suffix) of a supported minor version is accepted.

func Marshal

func Marshal(ctx context.Context, arazzo *Arazzo, w io.Writer) error

Marshal will marshal the provided Arazzo document to the provided io.Writer.

func Upgrade added in v1.27.0

func Upgrade(ctx context.Context, doc *Arazzo, opts ...Option[UpgradeOptions]) (bool, error)

Upgrade upgrades an Arazzo 1.0.x document to Arazzo 1.1.0 (the latest version currently supported), or to the version provided via WithUpgradeTargetVersion. It returns true if the document was modified.

Upgrading from 1.0.x to 1.1.x preserves the meaning of the document: criteria that use the `jsonpath` or `xpath` type without an explicit version are pinned to the version implied by Arazzo 1.0 (`draft-goessner-dispatch-jsonpath-00` and `xpath-30`), as the defaults changed to RFC 9535 and XPath 3.1 in Arazzo 1.1.

The document is not validated as part of the upgrade, runtime expressions that were accepted by Arazzo 1.0 but don't match the stricter Arazzo 1.1 grammar are left unchanged and will be reported when validating the upgraded document.

func Walk

func Walk(ctx context.Context, arazzo *Arazzo) iter.Seq[WalkItem]

Walk returns an iterator that yields MatchFunc items for each model in the Arazzo document. Users can iterate over the results using a for loop and break out at any time.

Types

type Arazzo

type Arazzo struct {
	marshaller.Model[core.Arazzo]

	// Arazzo is the version of the Arazzo Specification that this document conforms to.
	Arazzo string
	// Self is the canonical URI of this Arazzo document, used for identity-based referencing and as the base URI
	// for resolving relative references. Must not contain a fragment. Arazzo 1.1+ only.
	Self *string
	// Info provides metadata about the Arazzo document.
	Info Info
	// SourceDescriptions provides a list of SourceDescription objects that describe the source of the data that the workflow is orchestrating.
	SourceDescriptions SourceDescriptions
	// Workflows provides a list of Workflow objects that describe the orchestration of API calls.
	Workflows Workflows
	// Components provides a list of reusable components that can be used in the workflow.
	Components *Components
	// Extensions provides a list of extensions to the Arazzo document.
	Extensions *extensions.Extensions
}

Arazzo is the root object for an Arazzo document.

func Bootstrap added in v1.27.0

func Bootstrap() *Arazzo

Bootstrap creates a new Arazzo document with best practice examples. This serves as a template demonstrating a workflow with inputs and outputs, steps that pass values between each other, success criteria, and reusable components for parameters and failure actions.

func BootstrapFromOpenAPI added in v1.27.0

func BootstrapFromOpenAPI(doc *openapi.OpenAPI, opts BootstrapOptions) (*Arazzo, error)

BootstrapFromOpenAPI generates a starter Arazzo document for an OpenAPI document.

By default it generates one workflow per tag, calling the tag's operations in document order. Operations without tags are added to the workflow named UntaggedWorkflowID (along with any operations tagged with that name), and operations with several tags are added to the workflow for each of their tags. Each step:

  • targets the operation by operationId, or by operationPath if the operation doesn't have one
  • passes the operation's required parameters, and its request body if it's required
  • takes those values from workflow inputs typed from the operation's schemas, or from the outputs of an earlier step whose 2xx response declares an OpenAPI link to the operation
  • succeeds on one of the operation's documented 2xx status codes, or any 2xx status code if it documents the `2XX` range or no 2xx status codes

References in the OpenAPI document should be resolved first (see openapi.OpenAPI.ResolveAllReferences), as parameters, request bodies and links that are unresolved references are skipped.

func Unmarshal

func Unmarshal(ctx context.Context, doc io.Reader, opts ...Option[unmarshalOptions]) (*Arazzo, []error, error)

Unmarshal will unmarshal and validate an Arazzo document from the provided io.Reader. Validation can be skipped by using arazzo.WithSkipValidation() as one of the options when calling this function.

func (*Arazzo) Sync added in v0.1.1

func (a *Arazzo) Sync(ctx context.Context) error

Sync will sync any changes made to the Arazzo document models back to the core models.

func (*Arazzo) Validate

func (a *Arazzo) Validate(ctx context.Context, opts ...validation.Option) []error

Validate will validate the Arazzo document against the Arazzo Specification.

func (*Arazzo) ValidateSources added in v1.27.0

func (a *Arazzo) ValidateSources(ctx context.Context, sources *SourceDocuments) []error

ValidateSources validates the Arazzo document against the documents loaded for its sourceDescriptions (see LoadSourceDescriptions). It checks that:

  • operationId, operationPath and workflowId targets exist in the referenced source
  • step parameters match a parameter of the target operation by name and location
  • required operation parameters and required request bodies are supplied by the step
  • parameters passed to a workflow in an Arazzo source match the workflow's inputs

Sources that weren't loaded (unavailable, or AsyncAPI) are skipped. Problems that may still work at runtime, such as a header parameter the operation doesn't declare, are reported as warnings.

type BootstrapOptions added in v1.27.0

type BootstrapOptions struct {
	// SourceURL is the url of the OpenAPI document's sourceDescription, either absolute or relative to the generated
	// Arazzo document. Required.
	SourceURL string
	// SourceName is the name of the OpenAPI document's sourceDescription. Defaults to a name derived from the OpenAPI
	// document's title, or `api` if it doesn't have one.
	SourceName string
	// Tags limits the generated workflows to the workflows for these tags. Use UntaggedWorkflowID to select the
	// operations without tags. Can't be combined with OperationIDs.
	Tags []string
	// OperationIDs generates a single workflow calling these operations in order, instead of one workflow per tag.
	OperationIDs []string
	// WorkflowID is the workflowId of the workflow generated for OperationIDs. Defaults to DefaultBootstrapWorkflowID.
	WorkflowID string
}

BootstrapOptions configures BootstrapFromOpenAPI.

type Components

type Components struct {
	marshaller.Model[core.Components]

	// Inputs provides a list of reusable JSON Schemas that can be referenced from inputs and other JSON Schemas.
	Inputs *sequencedmap.Map[string, *oas3.JSONSchema[oas3.Referenceable]]
	// Parameters provides a list of reusable parameters that can be referenced from workflows and steps.
	Parameters *sequencedmap.Map[string, *Parameter]
	// SuccessActions provides a list of reusable success actions that can be referenced from workflows and steps.
	SuccessActions *sequencedmap.Map[string, *SuccessAction]
	// FailureActions provides a list of reusable failure actions that can be referenced from workflows and steps.
	FailureActions *sequencedmap.Map[string, *FailureAction]
	// Extensions provides a list of extensions to the Components object.
	Extensions *extensions.Extensions
}

Components holds reusable components that can be referenced in an Arazzo document.

func (*Components) Validate

func (c *Components) Validate(ctx context.Context, opts ...validation.Option) []error

Validate validates the Components object.

type FailureAction

type FailureAction struct {
	marshaller.Model[core.FailureAction]

	// Name is the case-sensitive name of the failure action.
	Name string
	// Type is the type of action to take on failure.
	Type FailureActionType
	// WorkflowID is the workflow ID of the workflow/step to go to on failure. Mutually exclusive to StepID.
	WorkflowID *expression.Expression
	// StepID is the step ID of the workflow/step to go to on failure. Mutually exclusive to WorkflowID.
	StepID *string
	// RetryAfter is the number of seconds to wait before retrying the workflow/step on failure.
	RetryAfter *float64
	// RetryLimit is the number of times to retry the workflow/step on failure. If not set a single retry will be attempted if type is retry.
	RetryLimit *int
	// Parameters is a list of parameters to pass to the workflow referenced by WorkflowID. Requires WorkflowID. Arazzo 1.1+ only.
	Parameters []*ReusableParameter
	// A list of assertions to check before taking the action.
	Criteria []criterion.Criterion
	// Extensions provides a list of extensions to the FailureAction object.
	Extensions *extensions.Extensions
}

FailureAction represents an action to take on failure of a workflow/step.

func (*FailureAction) Validate

func (f *FailureAction) Validate(ctx context.Context, opts ...validation.Option) []error

Validate will validate the failure action object. Requires an Arazzo object to be passed via validation options with validation.WithContextObject(). If a Workflow object is provided via validation options with validation.WithContextObject() then the FailureAction will be validated with the context of the workflow.

type FailureActionType

type FailureActionType string

FailureActionType represents the type of action to take on failure.

const (
	// FailureActionTypeEnd indicates that the workflow/step should end.
	FailureActionTypeEnd FailureActionType = "end"
	// FailureActionTypeGoto indicates that the workflow/step should go to another workflow/step on failure.
	FailureActionTypeGoto FailureActionType = "goto"
	// FailureActionTypeRetry indicates that the workflow/step should retry on failure.
	FailureActionTypeRetry FailureActionType = "retry"
)

type In

type In string

In represents the location of a parameter.

const (
	// InPath indicates that the parameter is in the path of the request.
	InPath In = "path"
	// InQuery indicates that the parameter is in the query of the request.
	InQuery In = "query"
	// InHeader indicates that the parameter is in the header of the request.
	InHeader In = "header"
	// InCookie indicates that the parameter is in the cookie of the request.
	InCookie In = "cookie"
	// InQuerystring indicates that the parameter represents the entire query string of the request. Arazzo 1.1+ only.
	InQuerystring In = "querystring"
)

type Info

type Info struct {
	marshaller.Model[core.Info]

	// Title is the name of the Arazzo document
	Title string
	// Summary is a short description of the Arazzo document
	Summary *string
	// Description is a longer description of the Arazzo document. May contain CommonMark syntax.
	Description *string
	// Version is the version of the Arazzo document
	Version string
	// Extensions provides a list of extensions to the Info object.
	Extensions *extensions.Extensions
}

Info represents metadata about the Arazzo document

func (*Info) Validate

func (i *Info) Validate(ctx context.Context, opts ...validation.Option) []error

Validate will validate the Info object against the Arazzo Specification.

type LoadSourcesOptions added in v1.27.0

type LoadSourcesOptions struct {
	// DocumentLocation is the location (file path or URL) of the Arazzo document. Relative source description URLs
	// are resolved against the document's `$self` if set, otherwise against this location. If empty, relative URLs
	// are resolved against the current working directory.
	DocumentLocation string
	// VirtualFS is an optional virtual file system used to load file based source descriptions. If not provided the
	// normal file system is used.
	VirtualFS system.VirtualFS
	// HTTPClient is an optional HTTP client used to load source descriptions served over HTTP(S). If not provided
	// a client with a 30 second timeout is used.
	HTTPClient system.Client
}

LoadSourcesOptions are the options for loading the documents referenced by an Arazzo document's sourceDescriptions.

type LocationContext added in v1.0.0

type LocationContext = walkpkg.LocationContext[MatchFunc]

Use the shared walking infrastructure

type Locations added in v1.0.0

type Locations = walkpkg.Locations[MatchFunc]

type MatchFunc

type MatchFunc func(Matcher) error

MatchFunc represents a particular model in the Arazzo document that can be matched. Pass it a Matcher with the appropriate functions populated to match the model type(s) you are interested in.

type Matcher

type Matcher struct {
	Arazzo                func(*Arazzo) error
	Info                  func(*Info) error
	SourceDescription     func(*SourceDescription) error
	Workflow              func(*Workflow) error
	ReusableParameter     func(*ReusableParameter) error
	JSONSchema            func(*oas3.JSONSchema[oas3.Referenceable]) error
	Step                  func(*Step) error
	ReusableSuccessAction func(*ReusableSuccessAction) error
	ReusableFailureAction func(*ReusableFailureAction) error
	Components            func(*Components) error
	Parameter             func(*Parameter) error
	SuccessAction         func(*SuccessAction) error
	FailureAction         func(*FailureAction) error
	Extensions            func(*extensions.Extensions) error
	Any                   func(any) error // Any will be called along with the other functions above on a match of a model
}

Matcher is a struct that can be used to match specific nodes in the Arazzo document.

type Option

type Option[T any] func(o *T)

func WithSkipValidation

func WithSkipValidation() Option[unmarshalOptions]

WithSkipValidation will skip validation of the Arazzo document during unmarshaling. Useful to quickly load a document that will be mutated and validated later.

func WithUpgradeSameMinorVersion added in v1.27.0

func WithUpgradeSameMinorVersion() Option[UpgradeOptions]

WithUpgradeSameMinorVersion will upgrade the same minor version of the Arazzo document. For example 1.0.0 to 1.0.1.

func WithUpgradeTargetVersion added in v1.27.0

func WithUpgradeTargetVersion(version string) Option[UpgradeOptions]

WithUpgradeTargetVersion will upgrade the Arazzo document to the provided version instead of the latest supported version.

type OutputValue added in v1.27.0

OutputValue is the value of a workflow or step output. It is either a runtime expression or, in Arazzo 1.1+, a Selector Object.

func NewOutputValueFromExpression added in v1.27.0

func NewOutputValueFromExpression(e expression.Expression) *OutputValue

NewOutputValueFromExpression creates an output value from a runtime expression.

func NewOutputValueFromSelector added in v1.27.0

func NewOutputValueFromSelector(s *Selector) *OutputValue

NewOutputValueFromSelector creates an output value from a Selector Object. Arazzo 1.1+ only.

func (*OutputValue) GetExpression added in v1.27.0

func (o *OutputValue) GetExpression() *expression.Expression

GetExpression returns the runtime expression, or nil if the output value is a Selector Object.

func (*OutputValue) GetSelector added in v1.27.0

func (o *OutputValue) GetSelector() *Selector

GetSelector returns the Selector Object, or nil if the output value is a runtime expression.

func (*OutputValue) IsExpression added in v1.27.0

func (o *OutputValue) IsExpression() bool

IsExpression returns true if the output value is a runtime expression.

func (*OutputValue) IsSelector added in v1.27.0

func (o *OutputValue) IsSelector() bool

IsSelector returns true if the output value is a Selector Object.

type Outputs

type Outputs = *sequencedmap.Map[string, *OutputValue]

Outputs is a map of friendly name to output values that extract data from the workflows/steps.

type Parameter

type Parameter struct {
	marshaller.Model[core.Parameter]

	// Name is the case-sensitive name of the parameter.
	Name string
	// In is the location of the parameter within an operation.
	In *In
	// Value represents either the static value of the parameter or an expression that will be evaluated to produce the value.
	Value expression.ValueOrExpression
	// Extensions provides a list of extensions to the Parameter object.
	Extensions *extensions.Extensions
}

Parameter represents parameters that will be passed to a workflow or operation referenced by a step.

func (*Parameter) Validate

func (p *Parameter) Validate(ctx context.Context, opts ...validation.Option) []error

Validate will validate the parameter object against the Arazzo specification. If an Workflow or Step object is provided via validation options with validation.WithContextObject() then it will be validated in the context of that object.

type PayloadReplacement

type PayloadReplacement struct {
	marshaller.Model[core.PayloadReplacement]

	// Target is a JSON Pointer, XPath expression or JSONPath (Arazzo 1.1+) to the value to be replaced.
	// How the target is interpreted is determined by TargetSelectorType, or the payload content type if not set.
	Target jsonpointer.JSONPointer
	// TargetSelectorType is the selector type of the target (`jsonpath`, `xpath` or `jsonpointer`) or an Expression Type Object. Arazzo 1.1+ only.
	TargetSelectorType *criterion.CriterionTypeUnion
	// Value represents either the static value of the replacement, an expression that will be evaluated to produce the value
	// or a Selector Object (Arazzo 1.1+).
	Value expression.ValueOrExpression
	// Extensions provides a list of extensions to the PayloadReplacement object.
	Extensions *extensions.Extensions
}

PayloadReplacement represents a replacement of a value within a payload such as a request body.

func (*PayloadReplacement) Validate

func (p *PayloadReplacement) Validate(ctx context.Context, opts ...validation.Option) []error

Validate will validate the payload replacement object against the Arazzo specification. If a RequestBody object is provided via validation options with validation.WithContextObject() then its content type is used to determine how the target is interpreted when targetSelectorType is not set.

type RequestBody

type RequestBody struct {
	marshaller.Model[core.RequestBody]

	// ContentType is the content type of the request body
	ContentType *string
	// Payload is a static value, an expression or a value containing inline expressions that will be used to populate the request body
	Payload expression.ValueOrExpression
	// Replacements is a list of expressions that will be used to populate the request body in addition to any in the Payload field
	Replacements []*PayloadReplacement
	// Extensions is a list of extensions to apply to the request body object
	Extensions *extensions.Extensions
}

RequestBody represents the request body to pass to an operation represented by a step

func (*RequestBody) Validate

func (r *RequestBody) Validate(ctx context.Context, opts ...validation.Option) []error

Validate will validate the request body object against the Arazzo specification.

type Reusable

type Reusable[T any, V interfaces.Validator[T], C marshaller.CoreModeler] struct {
	marshaller.Model[core.Reusable[C]]

	// Reference is the expression to the location of the reusable object.
	Reference *expression.Expression
	// Value is any value provided alongside a parameter reusable object.
	Value values.Value
	// If this reusable object is not a reference, this will be the inline object for this node.
	Object V
}

func (*Reusable[T, V, C]) Get added in v0.1.0

func (r *Reusable[T, V, C]) Get(components *Components) *T

Get will return either the inline object or the object referenced by the reference.

func (*Reusable[T, V, C]) GetReferencedObject added in v0.1.0

func (r *Reusable[T, V, C]) GetReferencedObject(components *Components) *T

func (*Reusable[T, V, C]) IsReference added in v0.1.0

func (r *Reusable[T, V, C]) IsReference() bool

func (*Reusable[T, V, C]) Validate

func (r *Reusable[T, V, C]) Validate(ctx context.Context, opts ...validation.Option) []error

Validate will validate the reusable object against the Arazzo specification.

type ReusableFailureAction

type ReusableFailureAction = Reusable[FailureAction, *FailureAction, *core.FailureAction]

ReusableFailureAction represents a failure action that can either be referenced from components or declared inline in a workflow or step.

type ReusableParameter

type ReusableParameter = Reusable[Parameter, *Parameter, *core.Parameter]

ReusableParameter represents a parameter that can either be referenced from components or declared inline in a workflow or step.

type ReusableSuccessAction

type ReusableSuccessAction = Reusable[SuccessAction, *SuccessAction, *core.SuccessAction]

ReusableSuccessAction represents a success action that can either be referenced from components or declared inline in a workflow or step.

type Selector added in v1.27.0

type Selector struct {
	marshaller.Model[core.Selector]

	// Context is a runtime expression that evaluates to the structured data the selector is applied to.
	Context expression.Expression
	// Selector is the JSONPath, XPath or JSON Pointer used to select a value from the context.
	Selector string
	// Type is the selector type (`jsonpath`, `xpath` or `jsonpointer`) or an Expression Type Object with a version.
	Type criterion.CriterionTypeUnion
	// Extensions provides a list of extensions to the Selector object.
	Extensions *extensions.Extensions
}

Selector represents a Selector Object, which selects a value from structured data using JSONPath, XPath or JSON Pointer. Selector Objects can be used for workflow and step outputs, parameter values and payload replacement values. Arazzo 1.1+ only.

func (*Selector) Validate added in v1.27.0

func (s *Selector) Validate(ctx context.Context, opts ...validation.Option) []error

Validate will validate the selector object against the Arazzo specification.

type SourceDescription

type SourceDescription struct {
	marshaller.Model[core.SourceDescription]

	// Name is the case-sensitive name of the SourceDescription object used to reference it.
	Name string
	// URL is a URL or relative URI to the location of the referenced document.
	URL string
	// Type is the type of the referenced document.
	Type SourceDescriptionType
	// Extensions provides a list of extensions to the SourceDescription object.
	Extensions *extensions.Extensions
}

SourceDescription represents an Arazzo or OpenAPI document that is referenced by this Arazzo document.

func (*SourceDescription) Validate

func (s *SourceDescription) Validate(ctx context.Context, opts ...validation.Option) []error

Validate will validate the source description object against the Arazzo specification.

type SourceDescriptionType

type SourceDescriptionType string

SourceDescriptionType represents the type of the SourceDescription object.

type SourceDescriptions

type SourceDescriptions []*SourceDescription

SourceDescriptions represents a list of SourceDescription objects that describe the source of the data that the workflow is orchestrating.

func (SourceDescriptions) Find

Find will return the first SourceDescription object with the provided name.

type SourceDocument added in v1.27.0

type SourceDocument struct {
	// Name is the name of the source description the document was loaded for.
	Name string
	// Location is the resolved location (file path or URL) the document was loaded from.
	Location string
	// Type is the type of the loaded document, detected from its content.
	Type SourceDescriptionType
	// OpenAPI is the loaded document if it is an OpenAPI document, with its references resolved.
	OpenAPI *openapi.OpenAPI
	// Arazzo is the loaded document if it is an Arazzo document.
	Arazzo *Arazzo
}

SourceDocument is a loaded document referenced by a source description.

type SourceDocuments added in v1.27.0

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

SourceDocuments are the documents loaded for an Arazzo document's sourceDescriptions, keyed by source description name.

func LoadSourceDescriptions added in v1.27.0

func LoadSourceDescriptions(ctx context.Context, a *Arazzo, opts LoadSourcesOptions) (*SourceDocuments, []error)

LoadSourceDescriptions loads the OpenAPI and Arazzo documents referenced by the Arazzo document's sourceDescriptions so the document can be validated against them with ValidateSources.

Problems loading a source are returned as warnings rather than errors, as a source may be temporarily unavailable without the Arazzo document being invalid. AsyncAPI sources are not loaded and are reported with a hint. A source description declaring a type that doesn't match the loaded document is reported as an error.

func (*SourceDocuments) Get added in v1.27.0

func (s *SourceDocuments) Get(name string) *SourceDocument

Get returns the loaded document for the named source description, or nil if it wasn't loaded.

type Step

type Step struct {
	marshaller.Model[core.Step]

	// StepID is a unique identifier for the step within a workflow.
	StepID string
	// Description is a description of the step.
	Description *string
	// OperationID is an operationId or expression to an operation in a SourceDescription that the step relates to. Mutually exclusive with OperationPath & WorkflowID.
	OperationID *expression.Expression
	// OperationPath is an expression to an operation in a SourceDescription that the step relates to. Mutually exclusive with OperationID & WorkflowID.
	OperationPath *expression.Expression
	// WorkflowID is a workflowId or expression to a workflow in a SourceDescription that the step relates to. Mutually exclusive with OperationID, OperationPath & ChannelPath.
	WorkflowID *expression.Expression
	// ChannelPath is an expression to an AsyncAPI channel in a SourceDescription that the step relates to. Mutually exclusive with OperationID, OperationPath & WorkflowID. Arazzo 1.1+ only.
	ChannelPath *expression.Expression
	// Action indicates whether an AsyncAPI step sends or receives a message. Required for AsyncAPI steps. Arazzo 1.1+ only.
	Action *StepAction
	// CorrelationID is the correlation identifier used to match received messages. Only applicable to AsyncAPI steps with action `receive`. Arazzo 1.1+ only.
	CorrelationID expression.ValueOrExpression
	// Timeout is the maximum number of milliseconds to wait for the step to complete before failing the step. Arazzo 1.1+ only.
	Timeout *int
	// DependsOn is a list of steps that must complete before this step can be processed. Each value is a stepId in the current
	// workflow, a `$workflows.<workflowId>.steps.<stepId>` reference or a `$sourceDescriptions.<name>.<workflowId>.steps.<stepId>` reference. Arazzo 1.1+ only.
	DependsOn []string
	// Parameters is a list of Parameters that will be passed to the referenced operation or workflow. These will override any matching parameters defined at the workflow level.
	Parameters []*ReusableParameter
	// RequestBody is the request body to be passed to the referenced operation.
	RequestBody *RequestBody
	// SuccessCriteria is a list of criteria that must be met for the step to be considered successful.
	SuccessCriteria []*criterion.Criterion
	// OnSuccess is a list of SuccessActions that will be executed if the step is successful.
	OnSuccess []*ReusableSuccessAction
	// OnFailure is a list of FailureActions that will be executed if the step is unsuccessful.
	OnFailure []*ReusableFailureAction
	// Outputs is a list of outputs that will be returned by the step.
	Outputs Outputs
	// Extensions provides a list of extensions to the Step object.
	Extensions *extensions.Extensions
}

Step represents a step in a workflow that describes the operation to be performed.

func (*Step) Validate

func (s *Step) Validate(ctx context.Context, opts ...validation.Option) []error

Validate will validate the step object against the Arazzo specification. Requires an Arazzo object to be passed via validation options with validation.WithContextObject(). Requires a Workflow object to be passed via validation options with validation.WithContextObject().

type StepAction added in v1.27.0

type StepAction string

StepAction indicates whether an AsyncAPI step sends or receives a message.

const (
	// StepActionSend indicates the step sends (publishes) a message.
	StepActionSend StepAction = "send"
	// StepActionReceive indicates the step receives (subscribes to) a message.
	StepActionReceive StepAction = "receive"
)

type Steps

type Steps []*Step

Steps represents a list of Step objects that describe the operations to be performed in the workflow.

func (Steps) Find

func (s Steps) Find(id string) *Step

Find will return the first Step object with the provided id.

type SuccessAction

type SuccessAction struct {
	marshaller.Model[core.SuccessAction]

	// Name is a case-sensitive name for the SuccessAction.
	Name string
	// Type is the type of action to take on success.
	Type SuccessActionType
	// WorkflowID is the workflow/step to go to on success. Mutually exclusive to StepID.
	WorkflowID *expression.Expression
	// StepID is the workflow/step to go to on success. Mutually exclusive to WorkflowID.
	StepID *string
	// Parameters is a list of parameters to pass to the workflow referenced by WorkflowID. Requires WorkflowID. Arazzo 1.1+ only.
	Parameters []*ReusableParameter
	// Criteria is a list of criteria that must be met for the action to be taken.
	Criteria []criterion.Criterion
	// Extensions provides a list of extensions to the SuccessAction object.
	Extensions *extensions.Extensions
}

SuccessAction represents an action to take on success of a workflow/step.

func (*SuccessAction) Validate

func (s *SuccessAction) Validate(ctx context.Context, opts ...validation.Option) []error

Validate will validate the success action object against the Arazzo specification. Requires an Arazzo object to be passed via validation options with validation.WithContextObject().

type SuccessActionType

type SuccessActionType string

SuccessActionType represents the type of action to take on success.

const (
	// SuccessActionTypeEnd indicates that the workflow/step should end.
	SuccessActionTypeEnd SuccessActionType = "end"
	// SuccessActionTypeGoto indicates that the workflow/step should go to another workflow/step on success.
	SuccessActionTypeGoto SuccessActionType = "goto"
)

type UpgradeOptions added in v1.27.0

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

UpgradeOptions configures how an Arazzo document is upgraded.

type WalkItem added in v1.0.0

type WalkItem struct {
	Match    MatchFunc
	Location Locations
	Arazzo   *Arazzo
}

WalkItem represents a single item yielded by the Walk iterator.

type Workflow

type Workflow struct {
	marshaller.Model[core.Workflow]

	// WorkflowID is a unique identifier for the workflow.
	WorkflowID string
	// Summary is a short description of the purpose of the workflow.
	Summary *string
	// Description is a longer description of the purpose of the workflow. May contain CommonMark syntax.
	Description *string
	// Parameters is a list of Parameters that will be passed to the referenced operation or workflow.
	Parameters []*ReusableParameter
	// Inputs is a JSON Schema containing a set of inputs that will be passed to the referenced workflow.
	Inputs *oas3.JSONSchema[oas3.Referenceable]
	// DependsOn is a list of workflowIds (or expressions to workflows) that must succeed before this workflow can be executed.
	DependsOn []expression.Expression
	// Steps is a list of steps that will be executed in the order they are listed.
	Steps Steps
	// SuccessActions is a list of actions that will be executed by each step in the workflow if the step succeeds. Can be overridden by the step.
	SuccessActions []*ReusableSuccessAction
	// FailureActions is a list of actions that will be executed by each step in the workflow if the step fails. Can be overridden by the step.
	FailureActions []*ReusableFailureAction
	// Outputs is a set of outputs that will be returned by the workflow.
	Outputs Outputs
	// Extensions provides a list of extensions to the Workflow object.
	Extensions *extensions.Extensions
}

Workflow represents a set of steps that orchestrates the execution of API calls.

func (*Workflow) Validate

func (w *Workflow) Validate(ctx context.Context, opts ...validation.Option) []error

Validate will validate the workflow object against the Arazzo specification. Requires an Arazzo object to be passed via validation options with validation.WithContextObject().

type Workflows

type Workflows []*Workflow

Workflows provides a list of Workflow objects that describe the orchestration of API calls.

func (Workflows) Find

func (w Workflows) Find(id string) *Workflow

Find will return the first workflow with the matching workflowId.

Directories

Path Synopsis
Package graph builds a graph of the workflows in an Arazzo document, showing how steps flow into each other and how workflows and steps depend on each other, and renders it as a Mermaid flowchart or a Graphviz DOT digraph.
Package graph builds a graph of the workflows in an Arazzo document, showing how steps flow into each other and how workflows and steps depend on each other, and renders it as a Mermaid flowchart or a Graphviz DOT digraph.
internal
actions
Package actions resolves the success and failure actions that apply to a step.
Package actions resolves the success and failure actions that apply to a step.
specversion
Package specversion provides helpers for version-aware validation of Arazzo documents.
Package specversion provides helpers for version-aware validation of Arazzo documents.
Package linter lints Arazzo documents for semantic issues, style and security concerns beyond what arazzo.Validate reports, using the shared linter engine, configuration and output formats.
Package linter lints Arazzo documents for semantic issues, style and security concerns beyond what arazzo.Validate reports, using the shared linter engine, configuration and output formats.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL