Arazzo Specification by philsturgeon · Pull Request #431 · bump-sh/docs

philsturgeon · 2026-01-26T12:23:20Z

The Arazzo Specification Guide is taking form.

Introduction

What is it?
History
Benefits

Understanding Structure

Working with Arazzo

Runtime Expressions

Misc

Cheatsheet

netlify · 2026-01-26T12:23:30Z

✅ Deploy Preview for bump-content-hub ready!

Name	Link
🔨 Latest commit	`c16eb16`
🔍 Latest deploy log	https://app.netlify.com/projects/bump-content-hub/deploys/699ecdfc9e2a940008458fb3
😎 Deploy Preview	https://deploy-preview-431--bump-content-hub.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

grossyoan

Hi there!

Some small typos/additions on the first pages ready to review. It's a great piece of work 🙏

src/_data/navbar.yml

src/_guides/arazzo/specification/v1.0/introduction/what-is-arazzo.md

src/_guides/arazzo/specification/v1.0/introduction/history.md

src/_guides/arazzo/specification/v1.0/understanding-structure/components-and-references.md

…zzo.md Co-authored-by: Yoan Gross <32864409+grossyoan@users.noreply.github.com>

grossyoan

Thanks a lot for the hard work, Phil 🙏

src/_guides/arazzo/specification/v1.0/understanding-structure/defining-sources.md

src/_guides/arazzo/specification/v1.0/understanding-structure/workflows.md

src/_guides/arazzo/specification/v1.0/understanding-structure/steps-inputs-outputs.md

src/_guides/arazzo/specification/v1.0/understanding-structure/success-and-failure.md

grossyoan · 2026-02-11T15:44:59Z

src/_guides/arazzo/specification/v1.0/understanding-structure/components-and-references.md

+## Component Types
+
+Arazzo supports several component types, each designed to reduce repetition and make workflows easier to maintain.
+


We might want to add an "Inputs" title here with a few sentences to have it in the table of contents on the right.

I find your comment completely accurate @grossyoan ler"'s add that subtitle?

src/_guides/arazzo/specification/v1.0/understanding-structure/components-and-references.md

src/_guides/arazzo/specification/v1.0/working-with-arazzo/runtime-expressions.md

complete guide from the guide page

src/_data/authors.yml

Polo2

The whole reading is very interesting, we learn a lot about Arazzo specification and use case, with a lot of clear examples and the cheatsheet, well done 👏

I left two suggestions in code example to stick with the specification:

clarification with string interpolation and runtime expression (based on sentence "Runtime expressions preserve the type of the referenced value. Expressions can be embedded into string values by surrounding the expression with {} curly braces.")
clarification about how component is referenced (favor the full path with $components.)

Beside that, all good to merge, and well done for the huge work 🙌

src/_guides/arazzo/specification/v1.0/understanding-structure/components-and-references.md

src/_guides/arazzo/specification/v1.0/understanding-structure/basic-structure.md

src/_guides/arazzo/specification/v1.0/understanding-structure/components-and-references.md

src/_guides/arazzo/specification/v1.0/understanding-structure/defining-sources.md

…components-and-references.md Co-authored-by: Polo <32060402+Polo2@users.noreply.github.com>

…basic-structure.md Co-authored-by: Polo <32060402+Polo2@users.noreply.github.com>

…components-and-references.md Co-authored-by: Polo <32060402+Polo2@users.noreply.github.com>

…defining-sources.md Co-authored-by: Polo <32060402+Polo2@users.noreply.github.com>

…components-and-references.md Co-authored-by: Polo <32060402+Polo2@users.noreply.github.com>

Polo2

Arazzo ready 🎉

paulRbr · 2026-02-27T08:57:06Z

src/_guides/arazzo/specification/v1.0/understanding-structure/components-and-references.md

+
+Here the `authHeader` parameter is reused as-is, while `query` and `limit` are defined inline for this one step.
+
+## Referencing inputs


Suggested change

## Referencing inputs

### Referencing inputs

paulRbr · 2026-02-27T08:57:34Z

src/_guides/arazzo/specification/v1.0/understanding-structure/components-and-references.md

+
+Each input schema can define properties, and use `$ref` to pull in reusable input components mixed in with inline definitions for just that workflow.
+
+## Referencing actions


Suggested change

## Referencing actions

### Referencing actions

paulRbr · 2026-02-27T08:57:44Z

src/_guides/arazzo/specification/v1.0/understanding-structure/components-and-references.md

+
+Actions are where `reference` really shines: define consistent behavior once, then attach it to any step using `onSuccess` or `onFailure`.
+
+### Success actions


Suggested change

### Success actions

#### Success actions

paulRbr · 2026-02-27T08:57:55Z

src/_guides/arazzo/specification/v1.0/understanding-structure/components-and-references.md

+
+Because each success action has criteria, you can attach both and let runtime data decide whether the workflow continues (`goto`) or completes (`end`).
+
+### Failure actions


paulRbr · 2026-02-27T08:58:14Z

src/_guides/arazzo/specification/v1.0/understanding-structure/components-and-references.md

+
+This step reuses the failure actions from earlier: retry on transient server errors, retry more cautiously when rate limited, and then route to a logging step if it still fails.
+
+### Conditional action reuse


Suggested change

### Conditional action reuse

#### Conditional action reuse

paulRbr · 2026-02-27T08:59:17Z

src/_guides/arazzo/specification/v1.0/understanding-structure/components-and-references.md

+## Component Types
+
+Arazzo supports several component types, each designed to reduce repetition and make workflows easier to maintain.
+


I find your comment completely accurate @grossyoan ler"'s add that subtitle?

paulRbr · 2026-02-27T08:59:36Z

src/_guides/arazzo/specification/v1.0/understanding-structure/components-and-references.md

+## Component types
+
+Arazzo supports several component types, each designed to reduce repetition and make workflows easier to maintain.
+


Suggested change

### Inputs

paulRbr · 2026-02-27T09:11:48Z

src/_guides/arazzo/specification/v1.0/understanding-structure/steps-inputs-outputs.md

+    payload:
+      tripId: $steps.search.outputs.tripId
+      passengers:
+        - name: $inputs.passengers[0].name


It's quite unclear for me how runtine expressions when you need to access data within a payload (a payload being an object that is not described by the spec but by the API response or request bodies, parameters or inputs).

From what I understand from the spec it seems this line should be written:

Suggested change

- name: $inputs.passengers[0].name

- name: $inputs.passengers#/0/name

However, I pretty much dislike and disagree with this syntax and Im much more aligned to what you wrote.. Internally at Bump we have defined a custom spec which will allow to use jmespath (or maybe jsonpath) in those expressions so that dot notations work as we could expect.

What do you think? Is this something I misunderstood?

paulRbr · 2026-02-27T09:13:21Z

src/_guides/arazzo/specification/v1.0/working-with-arazzo/runtime-expressions.md

+
+```yaml
+inputs:
+  type: object


This doesnt look like an array input (as stated by the title). Can you change the example please?

paulRbr · 2026-02-27T09:15:40Z

src/_guides/arazzo/specification/v1.0/working-with-arazzo/runtime-expressions.md

+outputs:
+  # Extract simple values
+  bookingId: $response.body.id
+  customerEmail: $response.body.customer.email


As stated in a previous comment, Im completely aligned with your dot notation to access payload data. But I dont think it's how arazzo specifies it (even if it isnt really clear)...

philsturgeon added 3 commits January 23, 2026 16:20

arazzo: what is it

c6f8b1c

arazzo: history

aa43564

arazzo: benefits

388c379

philsturgeon added 2 commits January 27, 2026 10:21

added arazzo to topnav

b289b58

arazzo: basic structure

ab863de

philsturgeon mentioned this pull request Jan 27, 2026

feat: mermaid js support for guides #432

Merged

philsturgeon added 3 commits January 27, 2026 21:18

arazzo: components and reference

952f26b

arazzo: empty file structure

1956f61

arazzo: added all links to sidebar

7d14561

grossyoan reviewed Jan 29, 2026

View reviewed changes

philsturgeon and others added 4 commits February 1, 2026 18:27

Update src/_guides/arazzo/specification/v1.0/introduction/what-is-ara…

06c4d39

…zzo.md Co-authored-by: Yoan Gross <32864409+grossyoan@users.noreply.github.com>

steps, workflows, and success/fail

cce02c4

arazzo: few bits and bobs

735a3b1

arazzo: runtime expressions

4a1ca59

philsturgeon requested a review from grossyoan February 1, 2026 19:54

philsturgeon changed the title ~~[WIP] Arazzo Specification~~ Arazzo Specification Feb 1, 2026

Update src/_guides/arazzo/specification/v1.0/introduction/what-is-ara…

0b8bb62

…zzo.md Co-authored-by: Yoan Gross <32864409+grossyoan@users.noreply.github.com>

philsturgeon marked this pull request as ready for review February 1, 2026 19:55

Merge branch 'main' into guide/arazzo

271861e

grossyoan reviewed Feb 11, 2026

View reviewed changes

grossyoan and others added 9 commits February 24, 2026 14:33

Add module to access Arazzo

9a49a19

complete guide from the guide page

Capitalized titles removed from topnav

ec28e9e

Typos and syntax fixes

a10ec17

Empty pages removed

6751b71

Example category in runtime expression renamed

71fe7b8

Capitalized titles removed

4f0070d

Merge branch 'main' into guide/arazzo

09deac2

Arazzo cheatsheet page added

7e92920

Typos fixed

1b40b3f

Complete guide title updated

0b27a26

Polo2 reviewed Feb 24, 2026

View reviewed changes

src/_data/authors.yml Show resolved Hide resolved

Polo2 reviewed Feb 25, 2026

View reviewed changes

grossyoan and others added 7 commits February 25, 2026 11:19

Update src/_guides/arazzo/specification/v1.0/understanding-structure/…

1b97e23

…components-and-references.md Co-authored-by: Polo <32060402+Polo2@users.noreply.github.com>

Update src/_guides/arazzo/specification/v1.0/understanding-structure/…

b26a4b9

…components-and-references.md Co-authored-by: Polo <32060402+Polo2@users.noreply.github.com>

Update src/_guides/arazzo/specification/v1.0/understanding-structure/…

2c1f19b

…basic-structure.md Co-authored-by: Polo <32060402+Polo2@users.noreply.github.com>

Update src/_guides/arazzo/specification/v1.0/understanding-structure/…

4f1baf9

…components-and-references.md Co-authored-by: Polo <32060402+Polo2@users.noreply.github.com>

Update src/_guides/arazzo/specification/v1.0/understanding-structure/…

605fc7b

…defining-sources.md Co-authored-by: Polo <32060402+Polo2@users.noreply.github.com>

Update src/_guides/arazzo/specification/v1.0/understanding-structure/…

91afc45

…components-and-references.md Co-authored-by: Polo <32060402+Polo2@users.noreply.github.com>

Fix components reference syntax

c16eb16

Polo2 approved these changes Feb 25, 2026

View reviewed changes

paulRbr reviewed Feb 27, 2026

View reviewed changes

		## Component Types

		Arazzo supports several component types, each designed to reduce repetition and make workflows easier to maintain.


		Here the `authHeader` parameter is reused as-is, while `query` and `limit` are defined inline for this one step.

		## Referencing inputs


		Each input schema can define properties, and use `$ref` to pull in reusable input components mixed in with inline definitions for just that workflow.

		## Referencing actions


		Actions are where `reference` really shines: define consistent behavior once, then attach it to any step using `onSuccess` or `onFailure`.

		### Success actions


		Because each success action has criteria, you can attach both and let runtime data decide whether the workflow continues (`goto`) or completes (`end`).

		### Failure actions


		This step reuses the failure actions from earlier: retry on transient server errors, retry more cautiously when rate limited, and then route to a logging step if it still fails.

		### Conditional action reuse

	- name: $inputs.passengers[0].name
	- name: $inputs.passengers#/0/name

Conversation

philsturgeon commented Jan 26, 2026 • edited by grossyoan Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

netlify bot commented Jan 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for bump-content-hub ready!

Uh oh!

grossyoan left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

grossyoan left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Polo2 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Polo2 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

philsturgeon commented Jan 26, 2026 •

edited by grossyoan

Loading

netlify bot commented Jan 26, 2026 •

edited

Loading