feat!: add Arazzo 1.1 support with source validation, lint, graph, bootstrap and explore commands
Why
The arazzo package and openapi arazzo validate only accepted Arazzo 1.0.0 and 1.0.1. Arazzo 1.1.0 is now published, so any 1.1 document (and any future 1.0.x patch release) was rejected outright, including AsyncAPI workflows, Selector Objects and step dependsOn. There was also no way to move an existing 1.0 document forward.
Beyond spec support, Arazzo had very little of the tooling we provide for OpenAPI. validate only checked a document on its own, so a workflow could call an operationId that doesn't exist or read an output that's never defined and still pass. There was no lint, no way to see a workflow's flow without reading the YAML, no starting point for writing a document against an existing API, and no way to browse one.
This PR started as the first of six stacked slices. #306 and #315 to #318 have been merged into it, so it now carries the whole set:
| Slice | Originally |
|---|---|
Arazzo 1.1 support and arazzo upgrade | this PR |
| Source-aware validation | #306 |
arazzo lint and list-rules | #315 |
arazzo graph | #316 |
arazzo bootstrap | #317 |
arazzo explore | #318 |
The review threads on each slice were addressed and resolved there. The slice PRs keep the detailed per-feature discussion.
What changed
Arazzo 1.1 support
- Version policy: any
1.0.xor1.1.xpatch (including prerelease suffixes such as1.1.0-rc1) is accepted, and other minors are rejected.arazzo.Versionis now1.1.0. Validation follows the version the document declares. A 1.1-only feature in anarazzo: 1.0.xdocument is an error that points atopenapi arazzo upgrade. - Model and validation:
$self, theasyncapisource type, stepchannelPath/action/correlationId/timeout/dependsOn,in: querystring, success/failure actionparameters, Selector Objects (outputs, parameter values, payload replacement values), payload replacementtargetSelectorType, thejsonpointerselector type and the new expression type versions (rfc9535,xpath-31,rfc6901). - Runtime expressions:
expression.WithArazzo11Grammar()adds the strict 1.1 ABNF ($message,$self,payload, strict$steps/$workflows/$componentsreferences). It is only applied to 1.1 documents, so 1.0 documents keep the existing lenient checks. - Upgrade:
arazzo.Upgradeandopenapi arazzo upgrademove 1.0.x documents to 1.1.0. Barejsonpath/xpathcriteria are pinned todraft-goessner-dispatch-jsonpath-00/xpath-30because the 1.1 defaults changed. The CLI validates the result and lists anything that needs a manual fix. - Existing bugs fixed (these affect 1.0 documents too): duplicate step parameters were never detected,
parameter.inwas never required for operation steps,sourceDescription.typewas treated as required,CriterionTypeUniondidn't sync string to object changes, and workflow parameters had no duplicate check.
Source-aware validation
arazzo.LoadSourceDescriptionsloads the referenced OpenAPI and Arazzo documents (relative to$selfor the document location, with virtual FS and custom HTTP client support). A source that can't be loaded is a warning, AsyncAPI sources get a hint, and a declaredtypethat doesn't match is an error.(*Arazzo).ValidateSourceschecks thatoperationId,operationPath, remoteworkflowIdanddependsOntargets exist, that step parameters match the operation's by name andin, that required parameters and request bodies are supplied, and that parameters passed to other Arazzo documents match theirinputs.Validatenow always checks that$steps,$workflowsand$inputsreferences point at steps, outputs and inputs that exist, and that parameters passed to workflows in the same document match theirinputs.openapi arazzo validatechecks sources by default (--skip-sourcesopts out), shows each finding's severity, and only fails on errors.
New CLI commands
openapi arazzo lintandlist-rules: everythingvalidatereports plus 11 semantic, style and security rules (unreachable steps,dependsOncycles, unused components/inputs/outputs, missing success criteria, plain HTTP sources, etc.). Mirrorsopenapi spec lint: rulesets,--disable, text/JSON output, config at~/.openapi/arazzo-lint.yaml, and--fix/--fix-interactive/--dry-run. Library inarazzo/linter.openapi arazzo graph: renders workflows as a Mermaid flowchart or Graphviz DOT digraph, with edges for step order, success/failuregoto, retries,dependsOnand nested workflows. Library inarazzo/graph, with an exported model for other renderers.openapi arazzo bootstrap:--from openapi.yamlgenerates one starter workflow per tag (or one workflow from--operations), with typed inputs, required parameters and bodies, 2xx success criteria, and values carried between steps via OpenAPIlinks. The output passesvalidateandlintunchanged. Without--fromit prints an example document. Library APIarazzo.BootstrapFromOpenAPI.openapi arazzo explore: an interactive terminal UI modelled onopenapi spec explore, showing workflows, steps, inputs, outputs, parameters and the actions that actually apply to each step (including inherited workflow actions and resolvedcomponents).
Shared code outside arazzo/
linter/fix:Engine.ProcessDocumentErrorsapplies fixes to non-OpenAPI documents.ProcessErrorsis unchanged.marshaller: fixes an existing bug where an optional non-pointer scalar field (such assourceDescription.type) was written out astype: ""when unset. It's now removed instead.
Breaking changes
arazzo.Outputs is now *sequencedmap.Map[string, *arazzo.OutputValue] (previously expression.Expression values), because a 1.1 output can be an expression or a Selector Object:
// 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() { /* *output.GetExpression() */ }
if output.IsSelector() { /* output.GetSelector() */ }
}
Validation is also stricter for some existing 1.0 documents: the bug fixes above (duplicate parameters, missing in on operation step parameters) and the new reference checks in Validate (dangling $steps/$workflows/$inputs references) can report errors on documents that used to pass. These references can't resolve at runtime, so that's intended, but it's the part most likely to surprise library users. The arazzo/README.md has a migration note.
Review notes
- Version gating lives in
arazzo/internal/specversionand reads the document version from the validation context, so each model decides what it allows. - Spec fixtures:
arazzo/arazzo_spec_test.goruns the 74 official 1.1 schema fixtures (vendored at a pinned upstream commit). All fail fixtures are rejected. Pass fixtures that are deliberately rejected are listed with a reason each, mostly upstream "characterization" fixtures and expressions the 1.1 ABNF doesn't allow. - Conservative checks: reference checks skip
$inputsschemas that can't be known statically ($ref,allOf/anyOf/oneOf, openadditionalProperties). Reachability and fall-through inlintandgraphshare one reading of success/failure actions (arazzo/internal/actions): actions apply in order, the first match wins, and only an unconditionalendorgotostops fall-through. - Severities for source checks are a judgement call: a bad path parameter can't work at runtime so it's an error, but an unknown header or query parameter may be deliberate, so it's a warning.
- AsyncAPI support is structural only. AsyncAPI documents aren't loaded, so
channelPath/operationIdtargets into them aren't resolved. exploreis a separate model rather than a generalisation of the OpenAPI explorer, because that one is also used byspec snip. It reuses its styles and key bindings.cmd/openapi/go.modis pinned to this branch's merge ofmain, following the AGENTS.md workflow.
Spec ambiguities and how they're handled
Where the spec text and the JSON Schema disagree, this follows the spec text.
in: channelis in the 1.1 schema enum but not the spec text. It is rejected.- Parameter values that are plain objects are allowed (the spec says
Any). A mapping with bothcontextandselectorkeys is treated as a Selector Object in 1.1 documents, because the spec gives no other way to tell them apart. - Non-string payload replacement values (the spec's own
value: 10example) are allowed even though both schemas say string or selector. $message.payload.xand$response.body.xappear in spec examples but don't match the ABNF. They are rejected in 1.1 documents (#/xis required).dependsOnstep references ($workflows.X.steps.Y,$sourceDescriptions.N.W.steps.S) aren't expressible in the ABNF. They are validated as their own patterns, and existence is checked where possible.actionisn't marked REQUIRED in the text, but the schema needs it to classify async steps. It is required for steps that target an AsyncAPI source.- Step target exclusivity is only partially stated in the text. Full exclusivity across
operationId/operationPath/channelPath/workflowIdis enforced, as in the schema. inon parameters: forbidden for inline action parameters (spec MUST NOT), but not for referenced component parameters, which may be shared with operation steps.- Criterion
type: jsonpointeris schema-valid but not a criterion type in the text. It is rejected for criteria and allowed for selectors. - The 1.0
xpathdefault was never defined. The upgrade pinsxpath-30, the newest version 1.0 allowed. - Empty
successCriteria(schemaminItems: 1) is rejected for 1.1 documents only, to avoid breaking existing 1.0 documents. - Not enforced because they're unspecified or can't be checked after parsing:
querystringandquerytogether on one operation, the "condition string MUST be quoted" rule, andretryAfter/retryLimiton non-retryactions.
Testing
mise cipassed locally after mergingmainand repinningcmd/openapi(format, mod-check, lint, examples check, tests, CLI integration, build).- Tests cover the official 1.1 fixtures, 1.0 vs 1.1 version gating for every 1.1 feature, source loading and validation (virtual FS and mock HTTP), every lint rule and fix, graph golden files (checked by rendering with mermaid and Graphviz), bootstrap output validating and linting clean against its source, and the explore UI's rows, keys and scrolling.
.mise-tasks/test-cliruns the new commands against local fixtures and diffsgraphandbootstrapoutput against goldens.- Patch coverage was 100% of changed library lines on each slice. The only untested CLI lines are the ones that start a real terminal UI or wire OS streams.