feat!: add Arazzo 1.1 support with source validation, lint, graph, bootstrap and explore commands

Merged
TR
4d ago
+20054-355

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:

SliceOriginally
Arazzo 1.1 support and arazzo upgradethis 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.x or 1.1.x patch (including prerelease suffixes such as 1.1.0-rc1) is accepted, and other minors are rejected. arazzo.Version is now 1.1.0. Validation follows the version the document declares. A 1.1-only feature in an arazzo: 1.0.x document is an error that points at openapi arazzo upgrade.
  • Model and validation: $self, the asyncapi source type, step channelPath/action/correlationId/timeout/dependsOn, in: querystring, success/failure action parameters, Selector Objects (outputs, parameter values, payload replacement values), payload replacement targetSelectorType, the jsonpointer selector 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/$components references). It is only applied to 1.1 documents, so 1.0 documents keep the existing lenient checks.
  • Upgrade: arazzo.Upgrade and openapi arazzo upgrade move 1.0.x documents to 1.1.0. Bare jsonpath/xpath criteria are pinned to draft-goessner-dispatch-jsonpath-00/xpath-30 because 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.in was never required for operation steps, sourceDescription.type was treated as required, CriterionTypeUnion didn't sync string to object changes, and workflow parameters had no duplicate check.

Source-aware validation

  • arazzo.LoadSourceDescriptions loads the referenced OpenAPI and Arazzo documents (relative to $self or 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 declared type that doesn't match is an error.
  • (*Arazzo).ValidateSources checks that operationId, operationPath, remote workflowId and dependsOn targets exist, that step parameters match the operation's by name and in, that required parameters and request bodies are supplied, and that parameters passed to other Arazzo documents match their inputs.
  • Validate now always checks that $steps, $workflows and $inputs references point at steps, outputs and inputs that exist, and that parameters passed to workflows in the same document match their inputs.
  • openapi arazzo validate checks sources by default (--skip-sources opts out), shows each finding's severity, and only fails on errors.

New CLI commands

  • openapi arazzo lint and list-rules: everything validate reports plus 11 semantic, style and security rules (unreachable steps, dependsOn cycles, unused components/inputs/outputs, missing success criteria, plain HTTP sources, etc.). Mirrors openapi spec lint: rulesets, --disable, text/JSON output, config at ~/.openapi/arazzo-lint.yaml, and --fix/--fix-interactive/--dry-run. Library in arazzo/linter.
  • openapi arazzo graph: renders workflows as a Mermaid flowchart or Graphviz DOT digraph, with edges for step order, success/failure goto, retries, dependsOn and nested workflows. Library in arazzo/graph, with an exported model for other renderers.
  • openapi arazzo bootstrap: --from openapi.yaml generates 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 OpenAPI links. The output passes validate and lint unchanged. Without --from it prints an example document. Library API arazzo.BootstrapFromOpenAPI.
  • openapi arazzo explore: an interactive terminal UI modelled on openapi spec explore, showing workflows, steps, inputs, outputs, parameters and the actions that actually apply to each step (including inherited workflow actions and resolved components).

Shared code outside arazzo/

  • linter/fix: Engine.ProcessDocumentErrors applies fixes to non-OpenAPI documents. ProcessErrors is unchanged.
  • marshaller: fixes an existing bug where an optional non-pointer scalar field (such as sourceDescription.type) was written out as type: "" 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/specversion and reads the document version from the validation context, so each model decides what it allows.
  • Spec fixtures: arazzo/arazzo_spec_test.go runs 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 $inputs schemas that can't be known statically ($ref, allOf/anyOf/oneOf, open additionalProperties). Reachability and fall-through in lint and graph share one reading of success/failure actions (arazzo/internal/actions): actions apply in order, the first match wins, and only an unconditional end or goto stops 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/operationId targets into them aren't resolved.
  • explore is a separate model rather than a generalisation of the OpenAPI explorer, because that one is also used by spec snip. It reuses its styles and key bindings.
  • cmd/openapi/go.mod is pinned to this branch's merge of main, 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: channel is 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 both context and selector keys 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: 10 example) are allowed even though both schemas say string or selector.
  • $message.payload.x and $response.body.x appear in spec examples but don't match the ABNF. They are rejected in 1.1 documents (#/x is required).
  • dependsOn step 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.
  • action isn'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/workflowId is enforced, as in the schema.
  • in on parameters: forbidden for inline action parameters (spec MUST NOT), but not for referenced component parameters, which may be shared with operation steps.
  • Criterion type: jsonpointer is schema-valid but not a criterion type in the text. It is rejected for criteria and allowed for selectors.
  • The 1.0 xpath default was never defined. The upgrade pins xpath-30, the newest version 1.0 allowed.
  • Empty successCriteria (schema minItems: 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: querystring and query together on one operation, the "condition string MUST be quoted" rule, and retryAfter/retryLimit on non-retry actions.

Testing

  • mise ci passed locally after merging main and repinning cmd/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-cli runs the new commands against local fixtures and diffs graph and bootstrap output 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.