Repository: OAI/Arazzo-Specification Branch: main Commit: 1abe8cba3860 Files: 48 Total size: 310.6 KB Directory structure: gitextract_s0wd0_vf/ ├── .github/ │ ├── CODEOWNERS │ ├── ISSUE_TEMPLATE/ │ │ └── use-case-template.yml │ ├── dependabot.yml │ ├── templates/ │ │ └── agenda.md │ └── workflows/ │ ├── auto-merge-dependabot.yml │ ├── respec.yaml │ ├── schema-publish.yaml │ ├── schema-tests.yaml │ └── validate-markdown.yaml ├── .gitignore ├── .markdownlint.yaml ├── CONTRIBUTING.md ├── LICENSE ├── MAINTAINERS.md ├── README.md ├── SPECIAL_INTEREST_GROUP.md ├── _archive_/ │ └── schemas/ │ └── v1.0/ │ ├── readme.md │ ├── schema.json │ └── schema.yaml ├── examples/ │ └── 1.0.0/ │ ├── ExtendedParametersExample.arazzo.yaml │ ├── FAPI-PAR.arazzo.yaml │ ├── FAPI-PAR.openapi.yaml │ ├── LoginAndRetrievePets.arazzo.yaml │ ├── README.md │ ├── bnpl-arazzo.yaml │ ├── bnpl-openapi.yaml │ ├── oauth.arazzo.yaml │ ├── oauth.openapi.yaml │ ├── pet-coupons.arazzo.yaml │ └── pet-coupons.openapi.yaml ├── package.json ├── scripts/ │ ├── md2html/ │ │ ├── .gitignore │ │ ├── analytics/ │ │ │ └── google.html │ │ ├── build.sh │ │ ├── gist.css │ │ ├── main.css │ │ ├── md2html.js │ │ ├── style-finish.html │ │ ├── style-start.html │ │ └── syntax-github.css │ ├── schema-publish.sh │ ├── schema-test-coverage.mjs │ ├── schema-test-coverage.sh │ ├── validate.mjs │ └── yaml2json/ │ └── yaml2json.js ├── spec.markdownlint.yaml └── versions/ ├── 1.0.0.md └── 1.0.1.md ================================================ FILE CONTENTS ================================================ ================================================ FILE: .github/CODEOWNERS ================================================ * @OAI/arazzo-maintainers ================================================ FILE: .github/ISSUE_TEMPLATE/use-case-template.yml ================================================ name: "Workflow-SIG Usecase Create Form" description: "Request form to describe a Workflow-SIG use case. Inorder to create a comprehensive solution Please provide a brief title, description, and fill out the details below and we'll get back to you ASAP." title: "[Workflow-SIG Usecases, draft version]: " labels: use-case assignees: @OAI/sig-workflows-admins - body: - type: markdown attributes: value: Thank you for contributing to the OAI work-flow SIG, please use this issue form to describe use cases in your industry. - type: input id: contact attributes: label: Contact Details description: Please share the name(s) / handle(s) so we can followup with any additional questions comments. validations: required: true - type: textarea id: Title attributes: label: Give your usecase a unique name so we may refer to it in discussions description: Each usecase needs a unique name starting with "USECASE-" validations: required: true - type: textarea id: description attributes: label: Give an overview of your use case. description: A brief description that outlines your usecase. validations: required: true - type: textarea id: Industry attributes: label: Industry description: Let us know if this is an industry specific usecase and any specific circumstances such as regulations that restrict the use case. validations: required: true - type: textarea id: Documentation attributes: label: Documentation description: Share any existing documention, examples, or any other materials that will help the SIG understand the requirements. validations: required: false - type: checkboxes id: terms attributes: label: Code of Conduct description: By submitting this issue, you agree to follow our [Code of Conduct](https://github.com/OAI/Arazzo-Specification?tab=coc-ov-file#code-of-conduct) options: - label: I agree to follow this project's Code of Conduct required: true ================================================ FILE: .github/dependabot.yml ================================================ version: 2 updates: - package-ecosystem: github-actions directory: "/" schedule: interval: daily open-pull-requests-limit: 10 - package-ecosystem: npm directory: "/" schedule: interval: daily open-pull-requests-limit: 10 groups: vitest: patterns: - "*vitest*" ================================================ FILE: .github/templates/agenda.md ================================================ ## Bi-Weekly meetings happen on Wednesdays at 5PM GMT This agenda gives visibility into discussion topics for the bi-weekly Arazzo Specification Technical Developer Community (TDC) meetings. Sharing agenda items in advance allows people to plan to attend meetings where they have an interest in specific topics. Whether attending or not, **anyone can comment on this issue prior to the meeting to suggest topics or to add comments on planned topics or proposals**. Meetings take place over Zoom: [https://zoom.us/j/91426197903](https://zoom.us/j/91426197903?pwd=cjNGcjgzWmRqZ1YyRW9PM3FFNFVFUT09), dial-in passcode: 763054 ### Accessibility & Etiquette * Participants must abide by our [Code-of-Conduct](https://github.com/OAI/Arazzo-Specification?tab=coc-ov-file#code-of-conduct). * We invite you to feel comfortable to challenge any language or behaviour that is harmful or not inclusive during this meeting. * We look forward to your participation, but please consider these acts of etiquette: * Remain on mute when not speaking to prevent interruptions. * Blur your background to reduce visual distractions. * Use the Zoom meeting "Raise Hand" feature to notify the group when you wish to speak. | Blur My Background | Raise Hand | |-|-| | Screenshot of Zoom UI showing the 'Stop Video' and 'Blur My Background' control | Screenshot of Zoom UI showing the 'Reaction' and 'Raise Hand' control | ### Agenda Structure | Topic | Owner | Decision/NextStep | |-|-|-| Intros and governance meta-topics (5 mins) | TDC / Arazzo maintainers | | Any other business (add comments below to suggest topics) | TDC / Arazzo maintainers | | [Approved spec PRs](https://github.com/OAI/Arazzo-Specification/pulls?q=is%3Apr+is%3Aopen+review%3Aapproved) | Arazzo maintainers| | [Active Projects](https://github.com/OAI/Arazzo-Specification/projects?query=is%3Aopen) | Arazzo maintainers | | [New issues needing attention](https://github.com/search?q=repo%3Aoai%2Farazzo-specification+is%3Aissue+comments%3A0+no%3Alabel+is%3Aopen) | Arazzo maintainers | | /cc [@OAI/tsc](https://github.com/orgs/OAI/teams/tsc) please suggest items for inclusion. ================================================ FILE: .github/workflows/auto-merge-dependabot.yml ================================================ name: Auto-merge dependabot updates on: pull_request: branches: [ main ] permissions: pull-requests: write contents: write jobs: dependabot-merge: runs-on: ubuntu-latest if: ${{ github.actor == 'dependabot[bot]' }} steps: - name: Dependabot metadata id: metadata uses: dependabot/fetch-metadata@v3.0.0 with: github-token: "${{ secrets.GITHUB_TOKEN }}" - name: Enable auto-merge for Dependabot PRs # Only if version bump is not a major version change if: ${{steps.metadata.outputs.update-type != 'version-update:semver-major'}} run: gh pr merge --auto --merge "$PR_URL" env: PR_URL: ${{github.event.pull_request.html_url}} GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}} ================================================ FILE: .github/workflows/respec.yaml ================================================ name: respec # author: @frankkilcommins (inspired by work from @MikeRalphson) # # This workflow creates a pull request for publishing HTML spec versions to the spec.openapis.org site. # # run this on push to main with changes to files in the versions folder on: push: paths: - "versions/**" branches: - main workflow_dispatch: {} jobs: respec: runs-on: ubuntu-22.04 steps: - name: Generate access token id: generate-token uses: actions/create-github-app-token@v3 with: app-id: ${{ secrets.OAI_SPEC_PUBLISHER_APPID }} private-key: ${{ secrets.OAI_SPEC_PUBLISHER_PRIVATE_KEY }} owner: OAI repositories: spec.openapis.org - uses: actions/checkout@v6 # checkout main branch of this repo with: fetch-depth: 0 - uses: actions/setup-node@v6 # setup Node.js with: node-version: "22.x" - name: Install dependencies run: npm ci - uses: actions/checkout@v6 # checkout main branch of website repo with: token: ${{ steps.generate-token.outputs.token }} repository: OAI/spec.openapis.org ref: main path: deploy - name: run main script run: scripts/md2html/build.sh - name: Create Pull Request uses: peter-evans/create-pull-request@v8 with: token: ${{ steps.generate-token.outputs.token }} branch: arazzo-spec-version base: main delete-branch: true path: deploy labels: Arazzo,Specification reviewers: earth2marsh,lornajane,mikekistler,miqui,ralfhandl,whitlockjc,handrews,karenetheridge,frankkilcommins title: Arazzo - update ReSpec-rendered specification versions commit-message: Update ReSpec-rendered specification versions signoff: true body: | This pull request is automatically generated by GitHub action `respec`. The `versions/*.md` files of the Arazzo Specification have changed and the corresponding HTML files are regenerated. ================================================ FILE: .github/workflows/schema-publish.yaml ================================================ name: schema-publish # author: @ralfhandl, @frankkilcommins # # This workflow creates a pull request for publishing schema iterations to the spec.openapis.org site. # # run this on push to vX.Y-dev branches or manually on: push: branches: - "v[0-9].[0-9]-dev" paths: - "src/schemas/validation/*.yaml" - "scripts/schema-publish.sh" - ".github/workflows/schema-publish.yaml" workflow_dispatch: {} jobs: publish: runs-on: ubuntu-latest steps: - name: Generate access token id: generate-token uses: actions/create-github-app-token@v3 with: app-id: ${{ secrets.OAI_SPEC_PUBLISHER_APPID }} private-key: ${{ secrets.OAI_SPEC_PUBLISHER_PRIVATE_KEY }} owner: OAI repositories: spec.openapis.org - uses: actions/checkout@v6 # checkout main branch of this repo with: fetch-depth: 0 - uses: actions/setup-node@v6 # setup Node.js with: node-version: "22.x" - name: Install dependencies run: npm ci - uses: actions/checkout@v6 # checkout main branch of website repo with: token: ${{ steps.generate-token.outputs.token }} repository: OAI/spec.openapis.org ref: main path: deploy - name: run main script run: scripts/schema-publish.sh - name: Create Pull Request uses: peter-evans/create-pull-request@v8 with: token: ${{ steps.generate-token.outputs.token }} branch: arazzo-${{ github.ref_name }}-schema-iterations base: main delete-branch: true path: deploy labels: Arazzo,Schema reviewers: earth2marsh,lornajane,mikekistler,miqui,ralfhandl,whitlockjc,handrews,karenetheridge,frankkilcommins title: "Arazzo - publish ${{ github.ref_name }} schema iterations" commit-message: "New Arazzo schema iterations published from ${{ github.ref_name }}" signoff: true body: | This pull request is automatically generated by GitHub action `schema-publish` in the OAI/Arazzo-Specification repo. The `src/schemas/validation/*.yaml` files have changed and JSON files are automatically generated. ================================================ FILE: .github/workflows/schema-tests.yaml ================================================ name: schema-tests # Author: @MikeRalphson / runs @jdesrosiers tests # Issue: https://github.com/OAI/OpenAPI-Specification/pull/2489 # # This workflow runs the npm test script to validate passing and failing # testcases for the metaschemas # # run this on push to any branch and creation of pull-requests on: push: {} pull_request: {} workflow_dispatch: {} jobs: test: runs-on: ubuntu-latest steps: - uses: actions/checkout@v6 # checkout repo content with: fetch-depth: 0 - uses: actions/setup-node@v6 # setup Node.js with: node-version: '20.x' - name: Install dependencies from main run: npm ci - name: Run tests run: npm run test ================================================ FILE: .github/workflows/validate-markdown.yaml ================================================ name: validate-markdown # Author: @MikeRalphson # Issue: https://github.com/OAI/OpenAPI-Specification/issues/2130 # # This workflow validates markdown files in the project root. # It also validates the work-in-progress specification file src/arazzo.md with slightly different rules. # # run this on push to any branch and creation of pull-requests on: [push, pull_request] jobs: mdv: runs-on: ubuntu-latest steps: - uses: actions/checkout@v6 # checkout repo content with: fetch-depth: 0 - uses: actions/setup-node@v6 # setup Node.js with: node-version: '20.x' - name: Lint work-in-progress spec run: npx --yes markdownlint-cli2 --config spec.markdownlint.yaml src/arazzo.md - name: Lint other files run: npx --yes markdownlint-cli2 *.md ================================================ FILE: .gitignore ================================================ .vscode/settings.json .idea *.iml *.ipr *.iws target atlassian-ide-plugin.xml node_modules/ deploy/ deploy-preview/ history Gemfile.lock coverage/ ================================================ FILE: .markdownlint.yaml ================================================ # First heading is a top-level heading MD002: true # Heading style (ATX is leading # symbols) MD003: style: atx # Unordered list symbol can be anything MD004: false # Unordered list indentation size MD007: indent: 2 # Allow additional blank lines MD012: false # Maximum line length MD013: line_length: 800 tables: false # Headings need blank lines before and after MD022: true # Duplicate headings are allowed MD024: false # Surround lists with blank lines MD032: true # Allow inline HTML MD033: false ================================================ FILE: CONTRIBUTING.md ================================================ # Contribute to the Arazzo Specification We welcome contributions and discussion. Bug reports and feature requests are welcome, please add an issue explaining your use case. Pull requests are also welcome, but it is recommended to create an issue first, to allow discussion. Questions and comments are also welcome - use the GitHub Discussions feature. You will also find notes from past meetings in the Discussion tab. ## Key information This project is covered by our [Code of Conduct](https://github.com/OAI/OpenAPI-Specification?tab=coc-ov-file#readme). All participants are expected to read and follow this code. No changes, however trivial, are ever made to the contents of published specifications (the files in the `versions/` folder). Exceptions may be made when links to external documents have been changed by a 3rd party, in order to keep our documents accurate. Published versions of the specification are in the `versions/` folder. The under-development versions of the specification are in the file `src/arazzo.md` on the appropriately-versioned branch. For example, work on the next release for 1.1 is on `v1.1-dev` in the file `src/arazzo.md`. The [spec site](https://spec.openapis.org) is the source of truth for the Arazzo specification as it contains all the citations and author credits. The OpenAPI project (which Arazzo sits under) is almost entirely staffed by volunteers. Please be patient with the people in this project, who all have other jobs and are active here because we believe this project has a positive impact in the world. ### Active branches The current active specification releases are: | Version | Branch | Notes | | ------- | ------ | ----- | | 1.0.2 | `v1.0-dev` | active patch release line | | 1.1.0 | `v1.1-dev` | minor release in development | ## Pull Requests Pull requests are always welcome but please read the section below on [branching strategy](#branching-strategy) before you start. Pull requests MUST come from a fork; create a fresh branch on your fork based on the target branch for your change. ### Branching Strategy Overview of branches: - `main` holds the published versions of the specification, utility scripts and supporting documentation. - `dev` is for development infrastructure and other changes that apply to multiple versions of development. - Branches named `vX.Y-dev` are the active development branches for future releases. - Branches name `vX.Y.Z-rel` are release branches (including when Z == 0). They exist primarily for `git mv`-ing `src/oas.md` to the appropriate `versions/X.Y.Z.md` location before merging back to `main`, and can also be used for any emergency post-release fixes that come up, such as when a 3rd party changes URLs in a way that breaks published links. > All changes should be applied to the _earliest_ branch where the changes are relevant in the first instance. ## Release Process and Scope ### Minor Releases Our roadmap for Arazzo releases is community-driven, meaning the specification is open for proposed additions by anyone. Changes in minor releases (such as 1.1) meet the following criteria: - Are **backwards-compatible** and be reasonably easy to implement in tooling that already supports the previous minor version. For example, new optional fields can be added. - Drive quality-of-life improvements to support how Arazzo is used by practitioners, so that Arazzo evolves to continue to meet user needs. For example, adding fields to support changes in other standards, or adopting common `x-*` extension fields into the specification. - Make the specification document clearer or easier to understand. A minor release is due when there are some meaningful features (including one or a small number of headline features). ### Patch Releases Patch releases reflect a constant quest for improving the active minor versions of Arazzo. Since we do not edit specification documents after publication, even the smallest change has to be in a new release. Changes in patch releases meet the following criteria: - Editorial changes such as spelling or formatting fixes, including link updates. - Clarifications or additions that do not change the meaning of the specification. Patch releases are created as often as there are changes to the specification worth releasing. ## Get in touch To get in touch with other people on the project, ask questions, or anything else: - Find us [on the OpenAPI Slack](https://communityinviter.com/apps/open-api/openapi) and join the `#arazzo` channel. - Start a [GitHub Discussion](https://github.com/OAI/Arazzo-Specification/discussions/). - Join one of our weekly meetings by checking the [issues list for an upcoming meetings](https://github.com/OAI/Arazzo-Specification/issues?q=is%3Aissue%20state%3Aopen%20label%3AHouse-keeping). ## Appendix ### Build the HTML version to publish We use ReSpec to render the markdown specification as HTML for publishing and easier reading. These instructions explain how you can build the HTML locally. You will need NodeJS 18 or later. Install dependencies: ```sh npm install ``` Produce stand-alone HTML files in the local `deploy/arazzo` folder: ```sh npm run build ``` Note that Linux users may need to add `--no-sandbox` to run `npx respec` as found in the `scripts/md2html/build.sh` file. ================================================ FILE: LICENSE ================================================ Apache License Version 2.0, January 2004 http://www.apache.org/licenses/ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION 1. Definitions. "License" shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1 through 9 of this document. "Licensor" shall mean the copyright owner or entity authorized by the copyright owner that is granting the License. "Legal Entity" shall mean the union of the acting entity and all other entities that control, are controlled by, or are under common control with that entity. For the purposes of this definition, "control" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity. "You" (or "Your") shall mean an individual or Legal Entity exercising permissions granted by this License. "Source" form shall mean the preferred form for making modifications, including but not limited to software source code, documentation source, and configuration files. "Object" form shall mean any form resulting from mechanical transformation or translation of a Source form, including but not limited to compiled object code, generated documentation, and conversions to other media types. "Work" shall mean the work of authorship, whether in Source or Object form, made available under the License, as indicated by a copyright notice that is included in or attached to the work (an example is provided in the Appendix below). "Derivative Works" shall mean any work, whether in Source or Object form, that is based on (or derived from) the Work and for which the editorial revisions, annotations, elaborations, or other modifications represent, as a whole, an original work of authorship. For the purposes of this License, Derivative Works shall not include works that remain separable from, or merely link (or bind by name) to the interfaces of, the Work and Derivative Works thereof. "Contribution" shall mean any work of authorship, including the original version of the Work and any modifications or additions to that Work or Derivative Works thereof, that is intentionally submitted to Licensor for inclusion in the Work by the copyright owner or by an individual or Legal Entity authorized to submit on behalf of the copyright owner. For the purposes of this definition, "submitted" means any form of electronic, verbal, or written communication sent to the Licensor or its representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, the Licensor for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by the copyright owner as "Not a Contribution." "Contributor" shall mean Licensor and any individual or Legal Entity on behalf of whom a Contribution has been received by Licensor and subsequently incorporated within the Work. 2. Grant of Copyright License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form. 3. Grant of Patent License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by such Contributor that are necessarily infringed by their Contribution(s) alone or by combination of their Contribution(s) with the Work to which such Contribution(s) was submitted. If You institute patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Work or a Contribution incorporated within the Work constitutes direct or contributory patent infringement, then any patent licenses granted to You under this License for that Work shall terminate as of the date such litigation is filed. 4. Redistribution. You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without modifications, and in Source or Object form, provided that You meet the following conditions: (a) You must give any other recipients of the Work or Derivative Works a copy of this License; and (b) You must cause any modified files to carry prominent notices stating that You changed the files; and (c) You must retain, in the Source form of any Derivative Works that You distribute, all copyright, patent, trademark, and attribution notices from the Source form of the Work, excluding those notices that do not pertain to any part of the Derivative Works; and (d) If the Work includes a "NOTICE" text file as part of its distribution, then any Derivative Works that You distribute must include a readable copy of the attribution notices contained within such NOTICE file, excluding those notices that do not pertain to any part of the Derivative Works, in at least one of the following places: within a NOTICE text file distributed as part of the Derivative Works; within the Source form or documentation, if provided along with the Derivative Works; or, within a display generated by the Derivative Works, if and wherever such third-party notices normally appear. The contents of the NOTICE file are for informational purposes only and do not modify the License. You may add Your own attribution notices within Derivative Works that You distribute, alongside or as an addendum to the NOTICE text from the Work, provided that such additional attribution notices cannot be construed as modifying the License. You may add Your own copyright statement to Your modifications and may provide additional or different license terms and conditions for use, reproduction, or distribution of Your modifications, or for any such Derivative Works as a whole, provided Your use, reproduction, and distribution of the Work otherwise complies with the conditions stated in this License. 5. Submission of Contributions. Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and conditions of this License, without any additional terms or conditions. Notwithstanding the above, nothing herein shall supersede or modify the terms of any separate license agreement you may have executed with Licensor regarding such Contributions. 6. Trademarks. This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor, except as required for reasonable and customary use in describing the origin of the Work and reproducing the content of the NOTICE file. 7. Disclaimer of Warranty. Unless required by applicable law or agreed to in writing, Licensor provides the Work (and each Contributor provides its Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determining the appropriateness of using or redistributing the Work and assume any risks associated with Your exercise of permissions under this License. 8. Limitation of Liability. In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall any Contributor be liable to You for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising as a result of this License or out of the use or inability to use the Work (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if such Contributor has been advised of the possibility of such damages. 9. Accepting Warranty or Additional Liability. While redistributing the Work or Derivative Works thereof, You may choose to offer, and charge a fee for, acceptance of support, warranty, indemnity, or other liability obligations and/or rights consistent with this License. However, in accepting such obligations, You may act only on Your own behalf and on Your sole responsibility, not on behalf of any other Contributor, and only if You agree to indemnify, defend, and hold each Contributor harmless for any liability incurred by, or claims asserted against, such Contributor by reason of your accepting any such warranty or additional liability. END OF TERMS AND CONDITIONS APPENDIX: How to apply the Apache License to your work. To apply the Apache License to your work, attach the following boilerplate notice, with the fields enclosed by brackets "[]" replaced with your own identifying information. (Don't include the brackets!) The text should be enclosed in the appropriate comment syntax for the file format. We also recommend that a file or class name and description of purpose be included on the same "printed page" as the copyright notice for easier identification within third-party archives. Copyright [yyyy] [name of copyright owner] Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. ================================================ FILE: MAINTAINERS.md ================================================ # Arazzo Specification Maintainers ## Active * Frank Kilcommins [@frankkilcommins](https://github.com/frankkilcommins) * Nick Denny [@ndenny](https://github.com/ndenny) * Kevin Duffey [@kevinduffey](https://github.com/kevinduffey) ================================================ FILE: README.md ================================================ # The Arazzo Specification ![alt Arazzo logo](./images/Arazzo-logo.png) The Arazzo Specification is a community-driven open specification within the [OpenAPI Initiative](https://www.openapis.org/), a Linux Foundation Collaborative Project. The Arazzo Specification defines a standard, programming language-agnostic mechanism to express sequences of calls and articulate the dependencies between them to achieve a particular outcome, or set of outcomes, when dealing with API descriptions (such as OpenAPI descriptions). The Arazzo Specification can articulate these workflows in a deterministic human-readable and machine-readable manner, thus improving provider and consumer experiences when working with APIs. Similar to what OpenAPI has done for describing HTTP interfaces, the Arazzo Specification enables the ability to articulate the functional use cases offered by an API (or group of APIs) thus removing the guesswork for both human and machine consumers. Use cases for machine-readable API workflow definition documents include, but are not limited to: - interactive _living_ workflow documentation - automated documentation generation (e.g. Developer Portal documentation) - code and SDK generation driven by functional use cases - automation of test cases - automated regulatory compliance checks - deterministic API invocation by AI-based LLMs The Arazzo Specification does not mandate a specific development process such as _design-first_ or _code-first_. It does facilitate either technique by establishing clear workflow interactions with HTTP APIs described using the OpenAPI Specification. This GitHub project is the starting point for Arazzo. Here you will find the information you need about the Arazzo Specification, simple examples of what it looks like, and some general information regarding the project. ## Current Version - 1.0.1 The latest version of the Arazzo Specification can be viewed at [Arazzo Specification - latest](https://spec.openapis.org/arazzo/latest.html). ![alt The Arazzo Specification Structure](./images/Arazzo-Specification-Structure.png) ## See Arazzo in Action If you just want to see it work, check out the [list of current examples](./examples/1.0.0/). ![alt Pet Adoption Workflow](./images/Arazzo-PetAdoption-Workflow.gif) ![alt Access Scope for an Arazzo Workflow](./images/Workflows-Access-Scope-for-Inputs-and-Outputs.png) ## Getting Involved The OpenAPI Initiative encourages participation from individuals and companies alike. If you want to participate in the evolution of the Arazzo Specification, check out the channels below. - [Bi-weekly Call](https://github.com/OAI/Arazzo-Specification/discussions/5) - Wednesdays at 09:00 AM PDT - [Discussions](https://github.com/OAI/Arazzo-Specification/discussions) - Use the GitHub discussions to ask questions, provide opinions and engage with the group - [Issues](https://github.com/OAI/Arazzo-Specification/issues) - Feel free to submit a Github issue with any question or comment about the working group - Slack - if you have access to the OpenAPI slack workspace, then join the `arazzo` channel. If you do not have access, [you're welcome to join](https://communityinviter.com/apps/open-api/openapi) ## Licensing See: License [Apache-2.0](https://github.com/OAI/Arazzo-Specification/blob/main/LICENSE) ================================================ FILE: SPECIAL_INTEREST_GROUP.md ================================================ # OpenAPI Initiative (OAI) Workflows Special Interest Group Work on the Arazzo Specification started under the remit of the OAI Workflows Special Interest Group (SIG-Workflows). The Workflows SIG provides a single place to manage artifacts, discussions, projects, and other aspects relating to how workflows can be represented using, or in combination with, the OpenAPI specification. ## OpenAPI Special Interest Groups (SIGs) OpenAPI Special Interest Groups, or "SIGs", are the OpenAPI Initiative's way of focusing work in particular areas. SIGs may start with just a Slack channel to determine interest. SIGs with enough traction to produce work may have their own GitHub repositories and regular Zoom calls, and ultimately produce work that becomes part of, or a companion to, the OpenAPI Specification. For more information, see [OAI Special Interest Groups](https://github.com/OAI/OpenAPI-Specification/blob/main/SPECIAL_INTEREST_GROUPS.md). ## Workflows Special Interest Group - Charter / Motivation Being able to express specific sequences of calls and articulate the dependencies between them to achieve a particular goal is desirable in the context of an API specification. Our aim is to propose an enhancement to the current OpenAPI, or accompanying specification (or means), that can define sequences of calls and their dependencies to be expressed in the context of delivering a particular outcome or set of outcomes. The creation of the SIG-Workflows group is inspired by the need to store sequences of calls in the context of specific tests, and in order to communicate the particulars of a complex set of security related calls such as when using OAuth2 and the Financial-grade API security profile of OpenID Connect. However, such a definition will be useful for understanding how to implement any dependent sequence of functional calls for any user of an API such as authorization calls, redirects and web hooks in order to achieve a certain technical or functional outcome. Optimally, it should be possible to articulate these workflows in a human and machine readable manner, thus improving the capability of API specifications to tell the story of the API in a manner that can improve the consuming developer experience and understanding of an API specified using OpenAPI (or other supported specifications). ### Key focus areas - **Context** - How to define quickly and easily what goal and key functions of an API are, and how to represent that in a specification - **Workflows** - Handling key and complex sequences which may involve the reuse of endpoints for multiple uses, like token calls in a FAPI compliant sequence, in both a human and machine readable way, supporting both understanding and automation - **Tooling** - How to best integrate to tools and provide machine readable context for those tools so that the spec can integrate with the tools used by developers ## Special Interest Group (SIG) The initial Workflows SIG was made up of the following individuals. ### Champions - David O'Neill ([COO, APIContext](https://www.linkedin.com/in/davidon/)) - Kin Lane ([API Governance Lead, Bloomberg](https://www.linkedin.com/in/kinlane/)) - Frank Kilcommins ([API Evangelist, SmartBear](https://www.linkedin.com/in/frank-kilcommins)) ### Contributors - Nick Denny ([Chief Engineer, APIContext](https://www.linkedin.com/in/nickdenny/)) - Frank Kilcommins ([API Evangelist, SmartBear](https://www.linkedin.com/in/frank-kilcommins)) - Mike Ralphson ([OpenAPI Specification Lead, Postman](https://www.linkedin.com/in/mikeralphson/)) - Alessandro Duminuco ([Senior Technical Leader, Cisco](https://www.linkedin.com/in/alessandroduminuco/)) - Mark Haine ([Founder, Considrd Consulting](https://www.linkedin.com/in/mark-haine/)) - Phil Sturgeon ([API Consultant](https://www.linkedin.com/in/philipsturgeon/)) - Kevin Duffey ([Tech Lead](https://www.linkedin.com/in/kmd/)) - Shai Sachs ([Staff Engineer, Chewy](https://linkedin.com/in/shaisachs/)) ================================================ FILE: _archive_/schemas/v1.0/readme.md ================================================ # Archive of outdated JSON Schema Files > [!TIP] > JSON Schema files for validating Arazzo descriptions using current Arazzo versions are available at [https://spec.openapis.org/#arazzo-schemas](https://spec.openapis.org/#arazzo-schemas). > > These schema files are maintained in the `src/schemas` folder of the corresponding `vX.Y-dev` branch in this repository. > [!CAUTION] > Schema files in this folder are not maintained any more and are not intended for productive use. ================================================ FILE: _archive_/schemas/v1.0/schema.json ================================================ { "$id": "https://spec.openapis.org/arazzo/1.0/schema/2024-08-01", "$schema": "https://json-schema.org/draft/2020-12/schema", "description": "The description of Arazzo v1.0.x documents", "type": "object", "properties": { "arazzo": { "description": "The version number of the Arazzo Specification", "type": "string", "pattern": "^1\\.0\\.\\d+(-.+)?$" }, "info": { "$ref": "#/$defs/info" }, "sourceDescriptions": { "description": "A list of source descriptions such as Arazzo or OpenAPI", "type": "array", "uniqueItems": true, "minItems": 1, "items": { "$ref": "#/$defs/source-description-object" } }, "workflows": { "description": "A list of workflows", "type": "array", "uniqueItems": true, "minItems": 1, "items": { "$ref": "#/$defs/workflow-object" } }, "components": { "$ref": "#/$defs/components-object" } }, "required": [ "arazzo", "info", "sourceDescriptions", "workflows" ], "$ref": "#/$defs/specification-extensions", "unevaluatedProperties": false, "$defs": { "info": { "$comment": "https://spec.openapis.org/arazzo/v1.0#info-object", "description": "Provides metadata about the Arazzo description", "type": "object", "properties": { "title": { "description": "A human readable title of the Arazzo Description", "type": "string" }, "summary": { "description": "A short summary of the Arazzo Description", "type": "string" }, "description": { "description": "A description of the purpose of the workflows defined. CommonMark syntax MAY be used for rich text representation", "type": "string" }, "version": { "description": "The version identifier of the Arazzo document (which is distinct from the Arazzo Specification version)", "type": "string" } }, "required": [ "title", "version" ], "$ref": "#/$defs/specification-extensions", "unevaluatedProperties": false }, "source-description-object": { "$comment": "https://spec.openapis.org/arazzo/v1.0#source-description-object", "description": "Describes a source description (such as an OpenAPI description) that will be referenced by one or more workflows described within an Arazzo description", "type": "object", "properties": { "name": { "description": "A unique name for the source description", "type": "string", "pattern": "^[A-Za-z0-9_\\-]+$" }, "url": { "description": "A URL to a source description to be used by a workflow", "type": "string", "format": "uri-reference" }, "type": { "description": "The type of source description", "enum": [ "arazzo", "openapi" ] } }, "required": [ "name", "url" ], "$ref": "#/$defs/specification-extensions", "unevaluatedProperties": false }, "workflow-object": { "$comment": "https://spec.openapis.org/arazzo/v1.0#workflow-object", "description": "Describes the steps to be taken across one or more APIs to achieve an objective", "type": "object", "properties": { "workflowId": { "description": "Unique string to represent the workflow", "$anchor": "workflowId", "type": "string" }, "summary": { "description": "A summary of the purpose or objective of the workflow", "type": "string" }, "description": { "description": "A description of the workflow. CommonMark syntax MAY be used for rich text representation", "type": "string" }, "inputs": { "description": "A JSON Schema 2020-12 object representing the input parameters used by this workflow", "$ref": "#/$defs/schema" }, "dependsOn": { "description": "A list of workflows that MUST be completed before this workflow can be processed", "type": "array", "uniqueItems": true, "items": { "type": "string" } }, "steps": { "description": "An ordered list of steps where each step represents a call to an API operation or to another workflow", "type": "array", "uniqueItems": true, "minItems": 1, "items": { "$ref": "#/$defs/step-object" } }, "successActions": { "description": "A list of success actions that are applicable for all steps described under this workflow", "type": "array", "uniqueItems": true, "items": { "oneOf": [ { "$ref": "#/$defs/success-action-object" }, { "$ref": "#/$defs/reusable-object" } ] } }, "failureActions": { "description": "A list of failure actions that are applicable for all steps described under this workflow", "type": "array", "uniqueItems": true, "items": { "oneOf": [ { "$ref": "#/$defs/failure-action-object" }, { "$ref": "#/$defs/reusable-object" } ] } }, "outputs": { "description": "A map between a friendly name and a dynamic output value", "type": "object", "patternProperties": { "^[a-zA-Z0-9\\.\\-_]+$": { "type": "string" } } }, "parameters": { "description": "A list of parameters that are applicable for all steps described under this workflow", "type": "array", "uniqueItems": true, "items": { "oneOf": [ { "$ref": "#/$defs/parameter-object" }, { "$ref": "#/$defs/reusable-object" } ] } } }, "required": [ "workflowId", "steps" ], "$ref": "#/$defs/specification-extensions", "unevaluatedProperties": false }, "step-object": { "$comment": "https://spec.openapis.org/arazzo/v1.0#step-object'", "description": "Describes a single workflow step which MAY be a call to an API operation (OpenAPI Operation Object or another Workflow Object)", "type": "object", "properties": { "stepId": { "description": "Unique string to represent the step", "$anchor": "stepId", "type": "string" }, "description": { "description": "A description of the step. CommonMark syntax MAY be used for rich text representation", "type": "string" }, "operationId": { "description": "The name of an existing, resolvable operation, as defined with a unique operationId and existing within one of the sourceDescriptions", "type": "string" }, "operationPath": { "description": "A reference to a Source combined with a JSON Pointer to reference an operation", "type": "string" }, "workflowId": { "description": "The workflowId referencing an existing workflow within the Arazzo description", "$ref": "#workflowId" }, "parameters": { "description": "A list of parameters that MUST be passed to an operation or workflow as referenced by operationId, operationPath, or workflowId", "type": "array", "uniqueItems": true, "items": true }, "requestBody": { "$ref": "#/$defs/request-body-object" }, "successCriteria": { "description": "A list of assertions to determine the success of the step", "type": "array", "uniqueItems": true, "minItems": 1, "items": { "$ref": "#/$defs/criterion-object" } }, "onSuccess": { "description": "An array of success action objects that specify what to do upon step success", "type": "array", "uniqueItems": true, "items": { "oneOf": [ { "$ref": "#/$defs/success-action-object" }, { "$ref": "#/$defs/reusable-object" } ] } }, "onFailure": { "description": "An array of failure action objects that specify what to do upon step failure", "type": "array", "uniqueItems": true, "items": { "oneOf": [ { "$ref": "#/$defs/failure-action-object" }, { "$ref": "#/$defs/reusable-object" } ] } }, "outputs": { "description": "A map between a friendly name and a dynamic output value defined using a runtime expression", "type": "object", "patternProperties": { "^[a-zA-Z0-9\\.\\-_]+$": { "type": "string" } } } }, "required": [ "stepId" ], "oneOf": [ { "required": [ "operationId" ] }, { "required": [ "operationPath" ] }, { "required": [ "workflowId" ] } ], "allOf": [ { "if": { "oneOf": [ { "required": [ "operationPath" ] }, { "required": [ "operationId" ] } ] }, "then": { "properties": { "parameters": { "items": { "oneOf": [ { "$ref": "#/$defs/reusable-object" }, { "$ref": "#/$defs/parameter-object", "required": [ "in" ] } ] } } } } }, { "if": { "required": [ "workflowId" ] }, "then": { "properties": { "parameters": { "items": { "oneOf": [ { "$ref": "#/$defs/parameter-object" }, { "$ref": "#/$defs/reusable-object" } ] } } } } } ], "$ref": "#/$defs/specification-extensions", "unevaluatedProperties": false }, "request-body-object": { "$comment": "https://spec.openapis.org/arazzo/v1.0#request-body-object", "description": "The request body to pass to an operation as referenced by operationId or operationPath", "type": "object", "properties": { "contentType": { "description": "The Content-Type for the request content", "type": "string" }, "payload": true, "replacements": { "description": "A list of locations and values to set within a payload", "type": "array", "uniqueItems": true, "items": { "$ref": "#/$defs/payload-replacement-object" } } }, "$ref": "#/$defs/specification-extensions", "unevaluatedProperties": false }, "criterion-object": { "$comment": "https://spec.openapis.org/arazzo/v1.0#criterion-object", "description": "An object used to specify the context, conditions, and condition types that can be used to prove or satisfy assertions specified in Step Object successCriteria, Success Action Object criteria, and Failure Action Object criteria", "type": "object", "properties": { "context": { "description": "A runtime expression used to set the context for the condition to be applied on", "type": "string" }, "condition": { "description": "The condition to apply", "type": "string" } }, "anyOf": [ { "type": "object", "properties": { "type": { "description": "The type of condition to be applied", "enum": [ "simple", "regex", "jsonpath", "xpath" ], "default": "simple" } } }, { "$ref": "#/$defs/criterion-expression-type-object" } ], "required": [ "condition" ], "dependentRequired": { "type": [ "context" ] }, "$ref": "#/$defs/specification-extensions", "unevaluatedProperties": false }, "criterion-expression-type-object": { "$comment": "https://spec.openapis.org/arazzo/v1.0#criterion-expression-type-object", "description": "An object used to describe the type and version of an expression used within a Criterion Object", "type": "object", "properties": { "type": { "description": "The type of condition to be applied", "enum": [ "jsonpath", "xpath" ] }, "version": { "description": "A short hand string representing the version of the expression type", "type": "string" } }, "required": [ "type", "version" ], "allOf": [ { "if": { "required": [ "type" ], "properties": { "type": { "const": "jsonpath" } } }, "then": { "properties": { "version": { "const": "draft-goessner-dispatch-jsonpath-00" } } } }, { "if": { "required": [ "type" ], "properties": { "type": { "const": "xpath" } } }, "then": { "properties": { "version": { "enum": [ "xpath-10", "xpath-20", "xpath-30" ] } } } } ], "$ref": "#/$defs/specification-extensions" }, "success-action-object": { "$comment": "https://spec.openapis.org/arazzo/v1.0#success-action-object", "description": "A single success action which describes an action to take upon success of a workflow step", "type": "object", "properties": { "name": { "description": "The name of the success action", "type": "string" }, "type": { "description": "The type of action to take", "enum": [ "end", "goto" ] }, "workflowId": { "description": "The workflowId referencing an existing workflow within the Arazzo description to transfer to upon success of the step", "$ref": "#workflowId" }, "stepId": { "description": "The stepId to transfer to upon success of the step", "$ref": "#stepId" }, "criteria": { "description": "A list of assertions to determine if this action SHALL be executed", "type": "array", "uniqueItems": true, "minItems": 1, "items": { "$ref": "#/$defs/criterion-object" } } }, "allOf": [ { "if": { "properties": { "type": { "const": "goto" } } }, "then": { "oneOf": [ { "required": [ "workflowId" ] }, { "required": [ "stepId" ] } ] } } ], "required": [ "name", "type" ], "$ref": "#/$defs/specification-extensions", "unevaluatedProperties": false }, "failure-action-object": { "$comment": "https://spec.openapis.org/arazzo/v1.0#failure-action-object", "description": "A single failure action which describes an action to take upon failure of a workflow step", "type": "object", "properties": { "name": { "description": "The name of the failure action", "type": "string" }, "type": { "description": "The type of action to take", "enum": [ "end", "goto", "retry" ] }, "workflowId": { "description": "The workflowId referencing an existing workflow within the Arazzo description to transfer to upon failure of the step", "$ref": "#workflowId" }, "stepId": { "description": "The stepId to transfer to upon failure of the step", "$ref": "#stepId" }, "retryAfter": { "description": "A non-negative decimal indicating the seconds to delay after the step failure before another attempt SHALL be made", "type": "number", "minimum": 0 }, "retryLimit": { "description": "A non-negative integer indicating how many attempts to retry the step MAY be attempted before failing the overall step", "type": "integer", "minimum": 0 }, "criteria": { "description": "A list of assertions to determine if this action SHALL be executed", "type": "array", "uniqueItems": true, "items": { "$ref": "#/$defs/criterion-object" } } }, "allOf": [ { "if": { "properties": { "type": { "enum": [ "goto", "retry" ] } } }, "then": { "oneOf": [ { "required": [ "workflowId" ] }, { "required": [ "stepId" ] } ] } }, { "if": { "properties": { "type": { "const": "retry" } } }, "then": { "required": [ "retryAfter" ] } } ], "required": [ "name", "type" ], "$ref": "#/$defs/specification-extensions", "unevaluatedProperties": false }, "reusable-object": { "$comment": "https://spec.openapis.org/arazzo/v1.0#reusable-object", "description": "A simple object to allow referencing of objects contained within the Components Object", "type": "object", "properties": { "reference": { "description": "A runtime expression used to reference the desired object", "type": "string" }, "value": { "description": "Sets a value of the referenced parameter", "type": [ "string", "boolean", "object", "array", "number", "null" ] } }, "required": [ "reference" ], "unevaluatedProperties": false }, "parameter-object": { "$comment": "https://spec.openapis.org/arazzo/v1.0#parameter-object", "description": "Describes a single step parameter", "type": "object", "properties": { "name": { "description": "The name of the parameter", "type": "string" }, "in": { "description": "The named location of the parameter", "enum": [ "path", "query", "header", "cookie" ] }, "value": { "description": "The value to pass in the parameter", "type": [ "string", "boolean", "object", "array", "number", "null" ] } }, "required": [ "name", "value" ], "$ref": "#/$defs/specification-extensions", "unevaluatedProperties": false }, "payload-replacement-object": { "$comment": "https://spec.openapis.org/arazzo/v1.0#payload-replacement-object", "description": "Describes a location within a payload (e.g., a request body) and a value to set within the location", "type": "object", "properties": { "target": { "description": "A JSON Pointer or XPath Expression which MUST be resolved against the request body", "type": "string" }, "value": { "description": "The value set within the target location", "type": "string" } }, "required": [ "target", "value" ], "unevaluatedProperties": false, "$ref": "#/$defs/specification-extensions" }, "components-object": { "$comment": "https://spec.openapis.org/arazzo/v1.0#components-object", "description": "Holds a set of reusable objects for different aspects of the Arazzo Specification", "type": "object", "properties": { "inputs": { "description": "An object to hold reusable JSON Schema 2020-12 schemas to be referenced from workflow inputs", "type": "object", "additionalProperties": { "$ref": "#/$defs/schema" } }, "parameters": { "description": "An object to hold reusable Parameter Objects", "type": "object", "additionalProperties": { "$ref": "#/$defs/parameter-object" } }, "successActions": { "description": "An object to hold reusable Success Actions Objects", "type": "object", "additionalProperties": { "$ref": "#/$defs/success-action-object" } }, "failureActions": { "description": "An object to hold reusable Failure Actions Objects", "type": "object", "additionalProperties": { "$ref": "#/$defs/failure-action-object" } } }, "patternProperties": { "^(inputs|parameters|successActions|failureActions)$": { "$comment": "Enumerating all of the property names in the regex is necessary for unevaluatedProperties to work as expected", "propertyNames": { "pattern": "^[a-zA-Z0-9\\.\\-_]+$" } } }, "unevaluatedProperties": false, "$ref": "#/$defs/specification-extensions" }, "specification-extensions": { "$comment": "https://spec.openapis.org/arazzo/v1.0#specification-extensions", "description": "While the Arazzo Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points", "patternProperties": { "^x-": true } }, "schema": { "$comment": "https://spec.openapis.org/arazzo/v1.0#schema-object", "$ref": "https://json-schema.org/draft/2020-12/schema" } } } ================================================ FILE: _archive_/schemas/v1.0/schema.yaml ================================================ $id: 'https://spec.openapis.org/arazzo/1.0/schema/2024-08-01' $schema: 'https://json-schema.org/draft/2020-12/schema' description: |- The description of Arazzo v1.0.x documents type: object properties: arazzo: description: The version number of the Arazzo Specification type: string pattern: '^1\.0\.\d+(-.+)?$' info: $ref: '#/$defs/info' sourceDescriptions: description: A list of source descriptions such as Arazzo or OpenAPI type: array uniqueItems: true minItems: 1 items: $ref: '#/$defs/source-description-object' workflows: description: A list of workflows type: array uniqueItems: true minItems: 1 items: $ref: '#/$defs/workflow-object' components: $ref: '#/$defs/components-object' required: - arazzo - info - sourceDescriptions - workflows $ref: '#/$defs/specification-extensions' unevaluatedProperties: false $defs: info: $comment: https://spec.openapis.org/arazzo/v1.0#info-object description: Provides metadata about the Arazzo description type: object properties: title: description: A human readable title of the Arazzo Description type: string summary: description: A short summary of the Arazzo Description type: string description: description: A description of the purpose of the workflows defined. CommonMark syntax MAY be used for rich text representation type: string version: description: The version identifier of the Arazzo document (which is distinct from the Arazzo Specification version) type: string required: - title - version $ref: '#/$defs/specification-extensions' unevaluatedProperties: false source-description-object: $comment: https://spec.openapis.org/arazzo/v1.0#source-description-object description: |- Describes a source description (such as an OpenAPI description) that will be referenced by one or more workflows described within an Arazzo description type: object properties: name: description: A unique name for the source description type: string pattern: '^[A-Za-z0-9_\-]+$' url: description: A URL to a source description to be used by a workflow type: string format: uri-reference type: description: The type of source description enum: - arazzo - openapi required: - name - url $ref: '#/$defs/specification-extensions' unevaluatedProperties: false workflow-object: $comment: https://spec.openapis.org/arazzo/v1.0#workflow-object description: Describes the steps to be taken across one or more APIs to achieve an objective type: object properties: workflowId: description: Unique string to represent the workflow $anchor: workflowId type: string summary: description: A summary of the purpose or objective of the workflow type: string description: description: A description of the workflow. CommonMark syntax MAY be used for rich text representation type: string inputs: description: A JSON Schema 2020-12 object representing the input parameters used by this workflow $ref: '#/$defs/schema' dependsOn: description: A list of workflows that MUST be completed before this workflow can be processed type: array uniqueItems: true items: type: string steps: description: An ordered list of steps where each step represents a call to an API operation or to another workflow type: array uniqueItems: true minItems: 1 items: $ref: '#/$defs/step-object' successActions: description: A list of success actions that are applicable for all steps described under this workflow type: array uniqueItems: true items: oneOf: - $ref: '#/$defs/success-action-object' - $ref: '#/$defs/reusable-object' failureActions: description: A list of failure actions that are applicable for all steps described under this workflow type: array uniqueItems: true items: oneOf: - $ref: '#/$defs/failure-action-object' - $ref: '#/$defs/reusable-object' outputs: description: A map between a friendly name and a dynamic output value type: object patternProperties: '^[a-zA-Z0-9\.\-_]+$': type: string parameters: description: A list of parameters that are applicable for all steps described under this workflow type: array uniqueItems: true items: oneOf: - $ref: '#/$defs/parameter-object' - $ref: '#/$defs/reusable-object' required: - workflowId - steps $ref: '#/$defs/specification-extensions' unevaluatedProperties: false step-object: $comment: https://spec.openapis.org/arazzo/v1.0#step-object' description: |- Describes a single workflow step which MAY be a call to an API operation (OpenAPI Operation Object or another Workflow Object) type: object properties: stepId: description: Unique string to represent the step $anchor: stepId type: string description: description: A description of the step. CommonMark syntax MAY be used for rich text representation type: string operationId: description: The name of an existing, resolvable operation, as defined with a unique operationId and existing within one of the sourceDescriptions type: string operationPath: description: A reference to a Source combined with a JSON Pointer to reference an operation type: string workflowId: description: The workflowId referencing an existing workflow within the Arazzo description $ref: '#workflowId' parameters: description: A list of parameters that MUST be passed to an operation or workflow as referenced by operationId, operationPath, or workflowId type: array uniqueItems: true items: true requestBody: $ref: '#/$defs/request-body-object' successCriteria: description: A list of assertions to determine the success of the step type: array uniqueItems: true minItems: 1 items: $ref: '#/$defs/criterion-object' onSuccess: description: An array of success action objects that specify what to do upon step success type: array uniqueItems: true items: oneOf: - $ref: '#/$defs/success-action-object' - $ref: '#/$defs/reusable-object' onFailure: description: An array of failure action objects that specify what to do upon step failure type: array uniqueItems: true items: oneOf: - $ref: '#/$defs/failure-action-object' - $ref: '#/$defs/reusable-object' outputs: description: A map between a friendly name and a dynamic output value defined using a runtime expression type: object patternProperties: '^[a-zA-Z0-9\.\-_]+$': type: string required: - stepId oneOf: - required: - operationId - required: - operationPath - required: - workflowId allOf: - if: oneOf: - required: - operationPath - required: - operationId then: properties: parameters: items: oneOf: - $ref: '#/$defs/reusable-object' - $ref: '#/$defs/parameter-object' required: - in - if: required: - workflowId then: properties: parameters: items: oneOf: - $ref: '#/$defs/parameter-object' - $ref: '#/$defs/reusable-object' $ref: '#/$defs/specification-extensions' unevaluatedProperties: false request-body-object: $comment: https://spec.openapis.org/arazzo/v1.0#request-body-object description: The request body to pass to an operation as referenced by operationId or operationPath type: object properties: contentType: description: The Content-Type for the request content type: string payload: true replacements: description: A list of locations and values to set within a payload type: array uniqueItems: true items: $ref: '#/$defs/payload-replacement-object' $ref: '#/$defs/specification-extensions' unevaluatedProperties: false criterion-object: $comment: https://spec.openapis.org/arazzo/v1.0#criterion-object description: |- An object used to specify the context, conditions, and condition types that can be used to prove or satisfy assertions specified in Step Object successCriteria, Success Action Object criteria, and Failure Action Object criteria type: object properties: context: description: A runtime expression used to set the context for the condition to be applied on type: string condition: description: The condition to apply type: string anyOf: - type: object properties: type: description: The type of condition to be applied enum: - simple - regex - jsonpath - xpath default: simple - $ref: '#/$defs/criterion-expression-type-object' required: - condition dependentRequired: type: - context $ref: '#/$defs/specification-extensions' unevaluatedProperties: false criterion-expression-type-object: $comment: https://spec.openapis.org/arazzo/v1.0#criterion-expression-type-object description: An object used to describe the type and version of an expression used within a Criterion Object type: object properties: type: description: The type of condition to be applied enum: - jsonpath - xpath version: description: A short hand string representing the version of the expression type type: string required: - type - version allOf: - if: required: - type properties: type: const: jsonpath then: properties: version: const: draft-goessner-dispatch-jsonpath-00 - if: required: - type properties: type: const: xpath then: properties: version: enum: - xpath-10 - xpath-20 - xpath-30 $ref: '#/$defs/specification-extensions' success-action-object: $comment: https://spec.openapis.org/arazzo/v1.0#success-action-object description: A single success action which describes an action to take upon success of a workflow step type: object properties: name: description: The name of the success action type: string type: description: The type of action to take enum: - end - goto workflowId: description: The workflowId referencing an existing workflow within the Arazzo description to transfer to upon success of the step $ref: '#workflowId' stepId: description: The stepId to transfer to upon success of the step $ref: '#stepId' criteria: description: A list of assertions to determine if this action SHALL be executed type: array uniqueItems: true minItems: 1 items: $ref: '#/$defs/criterion-object' allOf: - if: properties: type: const: goto then: oneOf: - required: - workflowId - required: - stepId required: - name - type $ref: '#/$defs/specification-extensions' unevaluatedProperties: false failure-action-object: $comment: https://spec.openapis.org/arazzo/v1.0#failure-action-object description: A single failure action which describes an action to take upon failure of a workflow step type: object properties: name: description: The name of the failure action type: string type: description: The type of action to take enum: - end - goto - retry workflowId: description: The workflowId referencing an existing workflow within the Arazzo description to transfer to upon failure of the step $ref: '#workflowId' stepId: description: The stepId to transfer to upon failure of the step $ref: '#stepId' retryAfter: description: A non-negative decimal indicating the seconds to delay after the step failure before another attempt SHALL be made type: number minimum: 0 retryLimit: description: A non-negative integer indicating how many attempts to retry the step MAY be attempted before failing the overall step type: integer minimum: 0 criteria: description: A list of assertions to determine if this action SHALL be executed type: array uniqueItems: true items: $ref: '#/$defs/criterion-object' allOf: - if: properties: type: enum: - goto - retry then: oneOf: - required: - workflowId - required: - stepId - if: properties: type: const: retry then: required: - retryAfter required: - name - type $ref: '#/$defs/specification-extensions' unevaluatedProperties: false reusable-object: $comment: https://spec.openapis.org/arazzo/v1.0#reusable-object description: A simple object to allow referencing of objects contained within the Components Object type: object properties: reference: description: A runtime expression used to reference the desired object type: string value: description: Sets a value of the referenced parameter type: - string - boolean - object - array - number - 'null' required: - reference unevaluatedProperties: false parameter-object: $comment: https://spec.openapis.org/arazzo/v1.0#parameter-object description: Describes a single step parameter type: object properties: name: description: The name of the parameter type: string in: description: The named location of the parameter enum: - path - query - header - cookie value: description: The value to pass in the parameter type: - string - boolean - object - array - number - 'null' required: - name - value $ref: '#/$defs/specification-extensions' unevaluatedProperties: false payload-replacement-object: $comment: https://spec.openapis.org/arazzo/v1.0#payload-replacement-object description: Describes a location within a payload (e.g., a request body) and a value to set within the location type: object properties: target: description: A JSON Pointer or XPath Expression which MUST be resolved against the request body type: string value: description: The value set within the target location type: string required: - target - value unevaluatedProperties: false $ref: '#/$defs/specification-extensions' components-object: $comment: https://spec.openapis.org/arazzo/v1.0#components-object description: Holds a set of reusable objects for different aspects of the Arazzo Specification type: object properties: inputs: description: An object to hold reusable JSON Schema 2020-12 schemas to be referenced from workflow inputs type: object additionalProperties: $ref: '#/$defs/schema' parameters: description: An object to hold reusable Parameter Objects type: object additionalProperties: $ref: '#/$defs/parameter-object' successActions: description: An object to hold reusable Success Actions Objects type: object additionalProperties: $ref: '#/$defs/success-action-object' failureActions: description: An object to hold reusable Failure Actions Objects type: object additionalProperties: $ref: '#/$defs/failure-action-object' patternProperties: '^(inputs|parameters|successActions|failureActions)$': $comment: Enumerating all of the property names in the regex is necessary for unevaluatedProperties to work as expected propertyNames: pattern: '^[a-zA-Z0-9\.\-_]+$' unevaluatedProperties: false $ref: '#/$defs/specification-extensions' specification-extensions: $comment: https://spec.openapis.org/arazzo/v1.0#specification-extensions description: While the Arazzo Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points patternProperties: '^x-': true schema: $comment: https://spec.openapis.org/arazzo/v1.0#schema-object $ref: 'https://json-schema.org/draft/2020-12/schema' ================================================ FILE: examples/1.0.0/ExtendedParametersExample.arazzo.yaml ================================================ arazzo: 1.0.0 info: title: Public Zoo API version: '1.0' sourceDescriptions: - name: animals type: openapi url: ./animals.yaml workflows: - workflowId: animal-workflow parameters: - in: cookie name: workflowLevelParamOne value: someValue - in: header name: workflowLevelParamTwo value: someValue steps: - stepId: post-step parameters: - in: cookie name: authentication value: SUPER_SECRET operationId: $sourceDescriptions.animals.postAnimal - stepId: get-step operationId: $sourceDescriptions.animals.getRandomAnimal ================================================ FILE: examples/1.0.0/FAPI-PAR.arazzo.yaml ================================================ arazzo: 1.0.0 info: title: PAR, Authorization and Token workflow version: 1.0.0 description: >- A workflow describing how to obtain a token from an OAuth2 and OpenID Connect Financial Grade authorization server which can be common for PSD2 API journeys sourceDescriptions: - name: auth-api url: ./FAPI-PAR.openapi.yaml type: openapi workflows: - workflowId: OIDC-PAR-AuthzCode summary: PAR, Authorization and Token workflow description: >- PAR - Pushed Authorization Request - API Call - https://www.rfc-editor.org/rfc/rfc9126.html Authorize - A web interaction that needs to be passed to a user agent (such as a browser) https://openid.net/specs/openid-connect-core-1_0.html Token - An API call requesting the tokens inputs: type: object properties: client_id: type: string description: The identifier of the third party provider OAuth client. ClientId is returned during the TPP registration. client_assertion: type: object description: | Used for PAR client authentication. The assertion contains a JWS, in this an object `base64(JWS)` signed with JWT signing private key related to the TPP OAuth client. See the Model and the Assertion object for a detailed description of the content. properties: iss: type: string sub: type: string aud: type: string exp: type: string iat: type: string jti: type: string redirect_uri: type: string description: The value of the redirect URI that was used in the previous `/as/authorize.oauth2` call. code_verifier: type: string description: The code verifier Proof Key of Code Exchange (PKCE) PARrequestBody: type: object description: | Parameters that comprise an authorization request are sent directly to the pushed authorization request endpoint in the request body [PAR Request](https://tools.ietf.org/html/draft-ietf-oauth-par-07#section-2.1) properties: response_type: type: string client_id: type: string sub: type: string scope: type: string prompt: type: string code_challenge_method: type: string code_challenge: type: string state: type: string nonce: type: string redirect_uri: type: string consent_id: type: string TokenRequestBody: type: object description: Request Schema for the token endpoint in the context of an OAuth2 Authorization code flow (**Note** this is place holder object that will have values replaced dynamically) properties: grant_type: type: string code: type: string redirect_uri: type: string code_verifier: type: string required: - grant_type - code - redirect_uri - code_verifier required: - PARrequestBody - TokenRequestBody steps: - stepId: PARStep description: Pushed Authorization Request operationId: $sourceDescriptions.auth-api.PAR parameters: - name: client_id in: query value: $inputs.client_id - name: client_assertion_type in: query value: 'urn:ietf:params:oauth:grant-type:jwt-bearer' - name: client_assertion in: query value: $inputs.client_assertion requestBody: payload: $inputs.PARrequestBody successCriteria: # assertions to determine step was successful - condition: $statusCode == 200 outputs: request_uri: $response.body#/request_uri - stepId: AuthzCodeStep description: OIDC Authorization code request operationId: $sourceDescriptions.auth-api.Authorization parameters: - name: request_uri in: query value: $steps.PARStep.outputs.request_uri - name: client_id in: query value: $inputs.client_id successCriteria: # assertions to determine step was successful - condition: $statusCode == 302 outputs: code: $response.body#/code # Not really, this is a query parameter (need a way to represent out-of-band props) - stepId: TokenStep description: Get token from the OIDC Token endpoint operationId: $sourceDescriptions.auth-api.Token parameters: - name: client_id in: query value: $inputs.client_id - name: client_assertion_type in: query value: 'urn:ietf:params:oauth:grant-type:jwt-bearer' - name: client_assertion in: query value: $inputs.client_assertion requestBody: payload: | { "grant_type": "authorization_code", "code": "{$steps.AuthzCodeStep.outputs.code}", "redirect_uri": "{$inputs.redirect_uri}", "code_verifier": "{$inputs.code_verifier}" } successCriteria: # assertions to determine step was successful - condition: $statusCode == 200 outputs: tokenResponse: $response.body outputs: access_token: $steps.TokenStep.outputs.tokenResponse ================================================ FILE: examples/1.0.0/FAPI-PAR.openapi.yaml ================================================ openapi: '3.0.0' info: version: '1.0.0' title: 'Authentication API' description: | ## OAuth2 and OpenID Connect are used to handle the security flows relating to API access. These interfaces are used as part of the PSD2 API journeys there is a [Getting Started Guide](https://developer.example.com) and use case focussed developer documentation is available for the following cases: 1. [Delegated SCA](https://developer.example.com) 2. [Redirect based Account Access](https://developer.example.com) 3. [Redirect based Payments](https://developer.example.com) The OAuth2 and OpenID interfaces are used in three sequences depending on the particular requirements of the use cases. When the third party app needs to get access without end-user involvement the Token endpoint is used to get an access token. This is called the "Client Credentials Grant" of OAuth2. The result of this is an access token than can be used to call some functional APIs. When user interaction is required the "Authorization Code" grant is used. In this implementation it consists of a sequence of calls. *how far do we take this? include Create Consent and Init Payment at the start? include account and payment APIs at the end?* 1. PAR - Pushed Authorization Request - API Call 2. Authorize - A web interaction that needs to be passed to a user agent (such as a browser) 3. Token - An API call requesting the tokens ![sequence](https://lh3.googleusercontent.com/fBWv0qA9a-HFCXSpEQrUDyFj-xSSFDw4UmG2ACqnvaC8aClExjE9gmDsdgonSHZBGQ_CZ9T-mYB31w=w3000-h886) This sequence of calls returns an Access token, ID_Token and potentially a refresh token. The access token provided as a result of the authorization code grant can access other APIs. The refresh token can be used to request replacement access tokens with the same level of access. This request is ### References * [RFC6749 OAuth 2.0 Authorization Framework](https://tools.ietf.org/html/rfc6749) * [RFC6750 The OAuth 2.0 Authorization Framework: Bearer Token Usage](https://tools.ietf.org/html/rfc6750) * [OpenID Connect Core 1.0 incorporating errata set 1](https://openid.net/specs/openid-connect-core-1_0.html) * [Financial-grade API Security Profile 1.0 - Part 1: Baseline](https://openid.net/specs/openid-financial-api-part-1-1_0.html) * [Financial-grade API Security Profile 1.0 - Part 2: Advanced](https://openid.net/specs/openid-financial-api-part-2-1_0.html) * [OAuth 2.0 Pushed Authorization Requests draft-ietf-oauth-par-07](https://tools.ietf.org/html/draft-ietf-oauth-par-07) * [JOSE Related specs (including JWT, JWT, JWE)](https://datatracker.ietf.org/wg/jose/documents/) servers: - url: https://api.uat.example.com/ description: Sandbox - Test Server for registered external parties to use for testing and development - url: https://api.example.com description: Production - Live Server providing APIs to registered third parties paths: /.well-known/openid-configuration: get: summary: RFC 8414 Well known OAuth 2.0 configuration endpoint description: | The standard "OAuth 2.0 Authorization Server Metadata" describing the configuration including endpoint addresses. The content of this file is used by clients to confirm details of the configuration of the OpenID Provider. Generally speaking the OpenID configuration is not directly required for delivery of use cases. externalDocs: url: https://tools.ietf.org/html/rfc8414 security: [] operationId: WellKnown tags: - OAuth2 responses: 200: description: OK content: application/json: schema: $ref: "#/components/schemas/WellKnown" /public/jwks: get: summary: JSON Web Key set description: | Retrieve the public server JSON Web Key (JWK) to verify the signature of an issued token or to encrypt request objects to it. externalDocs: url: https://datatracker.ietf.org/doc/rfc7517/ operationId: JWKS tags: - OAuth2 responses: 200: description: OK content: application/json: schema: $ref: '#/components/schemas/JWKResponse' 404: description: Not Found 500: description: Internal Server Error /as/par.oauth2: post: summary: Submits the OAuth 2.0 authorisation request parameters to obtain a request_uri handle for use at the authorisation endpoint. description: | A Pushed Authorization request is used to set the parameters for the subsequent Authorization call The OAuth2 client sends the signed request object in the POST to the PAR interface to avoid leakage of request parmeters. ![PAR](https://lh3.googleusercontent.com/bxiF_yvjeIIDFHxWR8Avae0efhqigSAOPM0t1XzuBihfFWv_yEyZwz1uMCejR7RCl1ytUcvxmFWhVw=w3000-h886) This implementation requires PAR to be used. **Mutual TLS client authentication is required to access this endpoint** As stated in the draft spec : "The pushed authorization request can be composed of any of the parameters applicable for use at authorization endpoint including those defined in [RFC6749] as well as all applicable extensions." For the purposes of the implementation there are a set of parameters that will be required for a successful authorization request and these are listed below in the request object parameter. The `consent_id` key in the request body is found in response to the "Init Payment" or "Create Consent" APIs externalDocs: url: https://tools.ietf.org/html/draft-ietf-oauth-par-07 operationId: Par tags: - OAuth2 parameters: - name: Content-Type in: header schema: type: string default: application/x-www-form-urlencoded enum: - application/x-www-form-urlencoded required: true - name: client_id in: query required: true description: The identifier of the third party provider OAuth client. ClientId is returned during the TPP registration. schema: type: string - name: client_assertion_type in: query required: true description: Type of assertion be used. In this case it must be "urn:ietf:params:oauth:grant-type:jwt-bearer" schema: type: string default: urn:ietf:params:oauth:grant-type:jwt-bearer enum: - urn:ietf:params:oauth:grant-type:jwt-bearer allowEmptyValue: false - name: client_assertion in: query description: | Used for PAR client authentication. The assertion contains a JWS, in this an object (base64(JWS)) signed with JWT signing private key related to the TPP OAuth client. See the Model and the Assertion object for a detailed description of the content. required: true content: application/json: schema: type: object properties: iss: type: string sub: type: string aud: type: string exp: type: string iat: type: string jti: type: string requestBody: description: | parameters that comprise an authorization request are sent directly to the pushed authorization request endpoint in the request body [PAR Request](https://tools.ietf.org/html/draft-ietf-oauth-par-07#section-2.1) required: true content: application/json: schema: type: object properties: response_type: type: string client_id: type: string sub: type: string scope: type: string prompt: type: string code_challenge_method: type: string code_challenge: type: string state: type: string nonce: type: string redirect_uri: type: string consent_id: type: string responses: 200: description: OK content: application/json: schema: $ref: '#/components/schemas/ParResponse' links: PAR_returned_request_uri: operationId: Authorization parameters: request_uri: '$response.body#/request_uri' description: > The `request_uri` value returned in the response MUST be used as the `request_uri` input parameter in `GET /as/authorize.oauth2` when using the authorization code flow, before it expires. 400: description: Bad Request 401: description: Unauthorized 500: description: Internal Server Error /as/authorize.oauth2: get: summary: OAuth 2.0 Authorization endpoint description: | The OAuth 2.0 authorisation endpoint is where the end-user is redirected to Perform SCA using their browser. **This is a Web interface not a REST API** This is the standard RFC 6749 authorization endpoint. In this case the request parameters are pushed in via the PAR endpoint prior to the authorize call and only the request_uri returned from the PAR request and the client_id is given as input parameters to this call. The call is normally triggered from the backend via browser based redirect to the authorization server authorize endpoint. ![Authorize](https://lh5.googleusercontent.com/G7vvCF3kSwI5IFleYNjBPBVUB-4tYkfnhHr7FUfsGTL9ffxMr8EzH6CQ_V76YYb1qdfTuZ3-emqnMw=w3000-h886) ### External Documentation: [OpenID Connect Core](https://openid.net/specs/openid-connect-core-1_0.html) [OAuth2](https://tools.ietf.org/html/rfc6749) security: [] operationId: Authorization tags: - OAuth2 parameters: - name: request_uri in: query required: true description: This parameter is returned by the preceeding /as/par.oauth2 call schema: type: string - name: client_id in: query required: true description: The Client ID issued when the app was registered in the developer portal schema: type: string responses: 302: description: | Redirect to defined redirect uri with the authorization code as a standard OIDC response. >**https://**_{your app redirect_uri}_ >**?code=**_{Arbirary String}_ >**&state=**_{state value from authorization request}_ >**&iss=**_https://api.example.com_ links: Authorization_Response: description: > The `code` value returned in the response MUST be used as the `request_uri` input parameter in `GET /as/authorize.oauth2` when using the authorization code flow, before it expires. operationId: Token parameters: code: '$response.path#/code' 500: description: Internal Server Error /as/token.oauth2: post: summary: Token endpoint with client authentication description: | There are three different cases where the token endpoint is used 1. Client Credentials Grant 2. Authorisation Code Grant 3. Refresh Grant As a result there are different types of token endpoint request and response There are three request types and two response types. All of these types use the same interaction but with different request and responses ![token](https://lh3.googleusercontent.com/3W6rTo7zGvIj2O0Dm0sTnItr9EDKC6WEn_fN9b8E0hv1vPSNfdyewPzUJBJLuoGMaVNyLnW1PNVA0w=w3000-h886) **Mutual TLS client authentication is required to access this endpoint** When the **client credentials grant** is being used the Token request has no other calls as pre-requisities. When the authorization code grant or refresh grant are being exercised there are dependancies on previous calls. In the implementation the **Authorization code flow** depends upon previous calls to: - /as/par.oauth2 - /as/authorize.oauth2 **The Refresh grant** depends on there being a previous authorization code flow that returned a refresh token. operationId: Token tags: - OAuth2 parameters: - name: Content-Type in: header schema: type: string default: application/x-www-form-urlencoded enum: - application/x-www-form-urlencoded required: true - name: client_id in: query required: true description: The identifier of the third party provider OAuth client. ClientId is returned during the TPP registration. schema: type: string - name: client_assertion_type in: query required: true description: Type of assertion be used. In this case it must be "urn:ietf:params:oauth:grant-type:jwt-bearer" schema: type: string default: urn:ietf:params:oauth:grant-type:jwt-bearer enum: - urn:ietf:params:oauth:grant-type:jwt-bearer allowEmptyValue: false - name: client_assertion in: query description: | Used for PAR client authentication. The assertion contains a JWS, in this an object (base64(JWS)) signed with JWT signing private key related to the TPP OAuth client. See the Model and the Assertion object for a detailed description of the content. required: true content: application/json: schema: type: object properties: iss: type: string sub: type: string aud: type: string exp: type: string iat: type: string jti: type: string requestBody: description: | Body of the request made to the Token endpoint - 3 schemas available for different flows required: true content: application/json: schema: oneOf: - $ref: '#/components/schemas/TokenClientCredsRequest' - $ref: '#/components/schemas/TokenAuthzCodeRequest' - $ref: '#/components/schemas/TokenRefreshRequest' responses: 200: description: OK content: application/json: schema: oneOf: - $ref: '#/components/schemas/TokenClientCredsResponse' - $ref: '#/components/schemas/TokenAuthzResponse' 400: description: Bad Request with a token error code 401: description: Unauthorized with a token error code 500: description: Internal Server Error components: schemas: WellKnown: required: - issuer - authorization_endpoint - token_endpoint - response_types_supported properties: issuer: type: string authorization_endpoint: type: string token_endpoint: type: string revocation_endpoint: type: string userinfo_endpoint: type: string introspection_endpoint: type: string jwks_uri: type: string registration_endpoint: type: string ping_revoked_sris_endpoint: type: string ping_end_session_endpoint: type: string device_authorization_endpoint: type: string scopes_supported: type: string claims_supported: type: string response_types_supported: type: string response_modes_supported: type: string grant_types_supported: type: string subject_types_supported: type: string id_token_signing_alg_values_supported: type: string token_endpoint_auth_methods_supported: type: string token_endpoint_auth_signing_alg_values_supported: type: string claim_types_supported: type: string claims_parameter_supported: type: string request_parameter_supported: type: string request_uri_parameter_supported: type: string request_object_signing_alg_values_supported: type: string id_token_encryption_alg_values_supported: type: string id_token_encryption_enc_values_supported: type: string backchannel_authentication_endpoint: type: string backchannel_token_delivery_modes_supported: type: string backchannel_authentication_request_signing_alg_values_supported: type: string backchannel_user_code_parameter_supported: type: string tls_client_certificate_bound_access_tokens: type: string mtls_endpoint_aliases: type: string JWKResponse: description: | A JSON object containing the server public JWK set in the form of an array of properties: keys: type: array items: type: object properties: kty: type: string use: type: string key_ops: type: string alg: type: string kid: type: string x5c: type: string x5u: type: string x5t: type: string x5t#s256: type: string ParResponse: properties: expires_in: type: string description: The expires in parameter defines the number of seconds when the reference uri expires. request_uri: type: string description: The request uri to the request object in the request to the par endpoint. AuthCodeRequest: required: - test properties: expires_in: type: string description: The expires in paremeter defines the number of seconds when the reference uri expires. request_uri: type: string description: The request uri to the request object in the request to the par endpoint. AuthCodeResponse1: properties: code: type: string description: The authorization code that will be used when making the subsequent request to the /as/token.oauth endpoint state: type: string description: The request uri to the request object in the request to the par endpoint. iss: type: string description: The request uri to the request object in the request to the par endpoint. TokenClientCredsRequest: description: Request Schema for the token endpoint in the context of a Client Credentials OAuth2 flow required: - grant_type - scope properties: grant_type: type: string description: String that defines which OAuth2 grant this request is part of enum: - client_credentials default: client_credentials scope: type: string description: Space delimited list of OAuth2 scopes TokenAuthzCodeRequest: description: Request Schema for the token endpoint in the context of an OAuth2 Authorization code flow required: - grant_type - code - redirect_uri - code_verifier properties: grant_type: description: String that defines which OAuth2 grant this request is part of type: string default: authorization_code code: type: string description: The authorization code provided as a parameter in the redirect back from the preceeding /as/authorize.oauth2 call redirect_uri: type: string description: The value of the redirect URI that was used in the preceeding /as/authorize.oauth2 call code_verifier: type: string description: The code verifier Proof Key of Code Exchange (PKCE). TokenRefreshRequest: description: Request Schema for the token endpoint in the context of an OAuth2 Refresh flow required: - grant_type - refresh_token properties: grant_type: description: String that defines which OAuth2 grant this request is part of type: string enum: - refresh_token default: refresh_token refresh_token: type: string description: The refresh_token provided as a parameter in the response from a preceeding /as/token.oauth2 call scope: type: string description: OPTIONAL - space delimited list of scopes that is equal to or a subset of the scopes requested by the preceeding authorization code flow TokenClientCredsResponse: required: - access_token - token_type properties: access_token: type: string description: The access token issued by the server. token_type: type: string description: "bearer" expires_in: type: integer description: The expires in paremeter defines the number of seconds when the access token expires. scope: type: string description: space delimited list of scopes TokenAuthzResponse: required: - access_token - token_type properties: access_token: type: string description: The access token issued by the server. refresh_token: type: string description: The refresh token issued by the server. token_type: type: string description: "bearer" expires_in: type: integer description: The expires in paremeter defines the number of seconds when the access token expires. scope: type: string description: space delimited list of scopes id_token: type: string description: The id token issued by the server. ================================================ FILE: examples/1.0.0/LoginAndRetrievePets.arazzo.yaml ================================================ arazzo: 1.0.0 info: title: A pet purchasing workflow summary: This workflow showcases how to purchase a pet through a sequence of API calls description: | This workflow walks you through the steps of `searching` for, `selecting`, and `purchasing` an available pet. version: 1.0.1 sourceDescriptions: - name: petStoreDescription url: https://raw.githubusercontent.com/swagger-api/swagger-petstore/master/src/main/resources/openapi.yaml type: openapi workflows: - workflowId: loginUserRetrievePet summary: Login User and then retrieve pets description: This procedure lays out the steps to login a user and then retrieve pets inputs: type: object properties: username: type: string password: type: string steps: - stepId: loginStep description: This step demonstrates the user login step operationId: $sourceDescriptions.petStoreDescription.loginUser parameters: # parameters to inject into the loginUser operation (parameter name must be resolvable at the referenced operation and the value is determined using {expression} syntax) - name: username in: query value: $inputs.username - name: password in: query value: $inputs.password successCriteria: # assertions to determine step was successful - condition: $statusCode == 200 outputs: # outputs from this step tokenExpires: $response.header.X-Expires-After rateLimit: $response.header.X-Rate-Limit sessionToken: $response.body - stepId: getPetStep description: retrieve a pet by status from the GET pets endpoint operationPath: '{$sourceDescriptions.petStoreDescription.url}#/paths/~1pet~1findByStatus' parameters: - name: status in: query value: 'available' - name: Authorization in: header value: $steps.loginStep.outputs.sessionToken successCriteria: - condition: $statusCode == 200 outputs: # outputs from this step availablePets: $response.body outputs: available: $steps.getPetStep.outputs.availablePets ================================================ FILE: examples/1.0.0/README.md ================================================ # Workflows Specification Examples ## Purpose This README will provide details on the examples found in this directory as well as examples to be added to cover a variety of use case scenarios. ## Examples ### FAPI *needs description* ### OAuth *needs description* ### Pet Coupons *needs description* ## Examples to be added * An example where a workflow imports another workflow both of which have components defined to show that the entry/root workflow can not reference components defined in the imported workflow. Components are scoped to the workflow they are defined in. ================================================ FILE: examples/1.0.0/bnpl-arazzo.yaml ================================================ arazzo: 1.0.0 info: title: BNPL Workflow description description: >- Describes the steps to secure a loan at checkout from a BNPL platform. It is a multi-step process that requires multiple API calls across several API providers to be completed successfully. version: 1.0.0 sourceDescriptions: - name: BnplApi url: https://raw.githubusercontent.com/OAI/Arazzo-Specification/main/examples/1.0.0/bnpl-openapi.yaml type: openapi workflows: - workflowId: ApplyForLoanAtCheckout summary: Apply for a loan at checkout using a BNPL platform description: Describes the steps to secure a loan at checkout from a BNPL platform. It is a multistep process that requires multiple API calls across several API providers to be completed successfully. inputs: type: object required: - customer - products properties: customer: description: | Customer can either be the customer details, which will be used for enrollment, or a link to an existing customer resource as the customer already uses the BNPL platform oneOf: - type: object required: - firstName - lastName - dateOfBirth - postalCode properties: firstName: description: First name of customer type: string minLength: 1 maxLength: 70 lastName: description: Last name of customer type: string minLength: 1 maxLength: 70 dateOfBirth: description: Customer date of birth type: string format: date-time postalCode: description: Zip code or postal code of customer type: string minLength: 1 maxLength: 70 additionalProperties: false - type: object required: - uri properties: uri: description: URI that points to an existing customer resource, as customer already enrolled on platform type: string format: uri additionalProperties: false products: type: array minItems: 1 items: type: object required: - productCode - purchaseAmount properties: merchantCategoryCode: description: Merchant category code of merchant. Only required for marketplace ecommerce platforms type: string pattern: '^[0-9]{4}$' productCode: description: Product code for loan application. Required for eligibility check type: string purchaseAmount: description: Product purchase amount and currency code type: object required: - currency - amount properties: currency: description: Currency code type: string pattern: "^[A-Z]{3}$" amount: description: Amount type: number steps: - stepId: checkLoanCanBeProvided description: | Call the BNPL API to filter the basket for products qualifying for checkout loans. Pass in the array of products from the workflow input as the payload for the API call. Act on the response payload: - If a list of qualifying products is returned then submit customer choices. - If the list of qualifying products is empty then end the workflow operationId: findEligibleProducts requestBody: contentType: application/json payload: | { "customer": "{$inputs.customer}", "products": "{$inputs.products}" } successCriteria: - condition: $statusCode == 200 onSuccess: - name: existingCustomerNotEligible type: end criteria: - condition: $statusCode == 200 - condition: $response.body#/existingCustomerNotEligible == false - name: qualifyingProductsFound type: goto stepId: getCustomerTermsAndConditions criteria: - condition: $statusCode == 200 - context: $response.body type: jsonpath condition: $[?count(@.products) > 0] - name: qualifyingProductsNotFound type: end criteria: - condition: $statusCode == 200 - context: $response.body type: jsonpath condition: $[?count(@.products) == 0] outputs: eligibilityCheckRequired: $response.body#/eligibilityCheckRequired eligibleProducts: $response.body#/products totalLoanAmount: $response.body#/totalAmount - stepId: getCustomerTermsAndConditions description: | Get the terms and conditions for the BNPL loans. This is static data and therefore has no arguments. The data will be displayed to the customer and they'll accept the terms out-of-band. After this step the flow will need to do a customer eligibility check if required. operationId: getTermsAndConditions successCriteria: - condition: $statusCode == 200 onSuccess: - name: eligibilityCheckRequired type: goto stepId: createCustomer criteria: - condition: $steps.checkLoanCanBeProvided.outputs.eligibilityCheckRequired == true - name: eligibilityCheckNotRequired type: goto stepId: initiateBnplTransaction criteria: - condition: $steps.checkLoanCanBeProvided.outputs.eligibilityCheckRequired == false outputs: termsAndConditions: $response.body - stepId: createCustomer description: | Call the BNPL platform and verify the customer is eligible for the loan, which creates a customer resource. This step is skipped if the customer is already enrolled in the BNPL platform. Accepting the terms and conditions is set to true as the assumption is they have been accepted when this step is invoked. If the customer is eligible for the BNPL loan then a customer resource is created operationId: createCustomer requestBody: contentType: application/json payload: | { "firstName": "{$inputs.customer.firstName}", "lastName": "{$inputs.customer.lastName}", "dateOfBirth": "{$inputs.customer.dateOfBirth}", "postalCode": "{$inputs.customer.postalCode}" "termsAndConditionsAccepted": true } successCriteria: - condition: $statusCode == 200 || $statusCode == 201 onSuccess: - name: customerIsEligible type: goto stepId: initiateBnplTransaction criteria: - condition: $statusCode == 201 - name: customerIsNotEligible type: end criteria: - condition: $statusCode == 200 outputs: customer: $response.body#/links/self - stepId: initiateBnplTransaction description: Initiate the BNPL transaction by sending the customer identifier, eligible products, and indicative loan amount to initiate the loan process operationId: createBnplTransaction requestBody: contentType: application/json payload: | { "enrolledCustomer": "{$inputs.customer.uri}", "newCustomer": "{$steps.createCustomer.outputs.customer}", "products": "{$steps.checkLoanCanBeProvided.outputs.eligibleProducts}" } successCriteria: - condition: $statusCode == 202 onSuccess: - name: CustomerAuthorizationRequired type: goto stepId: authenticateCustomerAndAuthorizeLoan criteria: - condition: $response.body#/redirectAuthToken != null - name: CustomerAuthorizationNotRequired type: goto stepId: retrieveFinalizedPaymentPlan criteria: - condition: $response.body#/redirectAuthToken == null outputs: redirectAuthToken: $response.body#/redirectAuthToken loanTransactionResourceUrl: $response.body#/links/self - stepId: authenticateCustomerAndAuthorizeLoan description: | Authenticate the customer and seek authorization for the loan. Notes: - Authenticate in this case does not necessarily mean with a valid set of credentials. It could be to prove the identity of the end user, possibly doing an UMA style interaction (which is too complex to tie into this example). - A redirect is returned for to be sent to the customer. The customer should follow this, but the success of the authorisation is out-of-band. - This flow mimics OAuth style authorization but is not an exact match as it does not rely on an authorisation code/access token exchange (as this seems somewhat artificial in this context). operationId: getAuthorization parameters: - name: redirectAuthToken in: query value: $steps.authenticateCustomerAndAuthorizeLoan.outputs.redirectAuthToken successCriteria: - condition: $statusCode == 302 outputs: redirectUrl: $response.header.Location - stepId: retrieveFinalizedPaymentPlan description: Retrieve finalized payment plan to show to customer once authorization is complete operationId: retrieveBnplLoanTransaction parameters: - name: loanTransactionId in: path value: $steps.initiateBnplTransaction.outputs.loanTransactionId successCriteria: - condition: $statusCode == 200 outputs: finalizedPaymentPlan: $response.body - stepId: updateOrderStatus description: Send update from eCommerce platform to indicate order fulfilled and loan is therefore active operationId: updateBnplLoanTransactionStatus parameters: - name: loanTransactionId in: path value: $steps.initiateBnplTransaction.outputs.loanTransactionId requestBody: contentType: application/json payload: { "loanStatus": "Completed" } successCriteria: - condition: $statusCode == 204 outputs: finalizedPaymentPlan: $steps.retrieveFinalizedPaymentPlan.finalizedPaymentPlan ================================================ FILE: examples/1.0.0/bnpl-openapi.yaml ================================================ openapi: 3.0.0 info: title: Arazzo Buy-now, Pay-later Loan API description: | This OpenAPI description provides an example of a buy-now, pay-later (BNPL) API that contains multiple operations that allow eCommerce platforms to facilitate loans on behalf of customers version: 1.0.0 servers: - url: /bnpl/v1 description: Default BNPL instance tags: - name: Loan Initiation description: Allows a loan to initiated and finalized paths: /auth: get: summary: Get customer authorisation description: | Used to initiate authentication of the End User and authorisation by the customer. Mimics an OAuth 2.0 style redirect, but cutdown for the purpose of an example. operationId: getAuthorization parameters: - name: AuthorizationToken in: query description: Authorization token value elicited from loan initiation endpoint required: true schema: $ref: '#/components/schemas/AuthorizationToken' responses: "302": description: Instruction to redirect End User, based on validation of the authorisation token headers: Location: description: URL to which the customer is redirected schema: type: string default: $ref: '#/components/responses/ErrorResponse' /customers: post: summary: Create a customer description: | Create a customer for a BNPL loan if they are eligible for the loan in question. If a customer is eligible a customer resource is created, a 201 returned, and the a link to the customer resource returned. If the customer is not eligible a 200 is returned and a reason code indicating why the customer was rejected. operationId: createCustomer requestBody: description: The customer properties content: application/json: schema: allOf: - $ref: '#/components/schemas/CustomerProperties' - description: Terms and conditions have been reviewed and accepted type: object required: - termsAndConditionsAccepted properties: termsAndConditionsAccepted: type: boolean responses: "200": description: Customer is not eligible for BNPL loan content: application/json: schema: type: object required: - reasonCode properties: reasonCode: type: string additionalProperties: false "201": description: Customer resource has been created and can be linked to loan transaction content: application/json: schema: type: object required: - customerId - links properties: customerId: description: Unique identifier for the newly created customer resource type: string links: type: object required: - self properties: self: description: URL identifying this resource allOf: - $ref: '#/components/schemas/CustomerUri' additionalProperties: false additionalProperties: false default: $ref: '#/components/responses/ErrorResponse' /loan-transactions: post: summary: Initiate a new loan transaction description: | Initiate a new loan based on customer details and in-scope products. For the sake of this example: * There is one error response, defined using the `default` keyword. operationId: createBnplTransaction requestBody: content: application/json: schema: description: Properties for the loan. the `enrolledCustomer` and `newCustomer` properties are required to support the two different sources in the calling Arazzo description type: object required: - products - totalAmount properties: enrolledCustomer: description: The customer resource URI for a previously enrolled customer allOf: - $ref: '#/components/schemas/CustomerUri' newCustomer: description: A newly-created customer resource URI for this loan allOf: - $ref: '#/components/schemas/CustomerUri' products: description: Product codes for products included in loan. Supplied to ensure any special terms are included in loan agreement type: array minItems: 1 items: $ref: '#/components/schemas/ProductCode' totalAmount: description: Loan amount being requested allOf: - $ref: '#/components/schemas/CurrencyAndAmount' responses: "202": description: New loan initiated. This may require authorization before it is finalized content: application/json: schema: type: object required: - loanTransactionId - links properties: redirectAuthToken: description: A token that allows the loan to be completed without further authorisation. Is omitted if authentication and authorisation by the End User is required loanTransactionId: $ref: '#/components/schemas/LoanTransactionId' links: type: object required: - self properties: self: description: Link to this resource type: string additionalProperties: false additionalProperties: false default: $ref: '#/components/responses/ErrorResponse' /loan-transactions/{loanTransactionId}: parameters: - $ref: '#/components/parameters/loanTransactionId' get: summary: Retrieve loan description: Retrieve the finalised BNPL loan transaction with all installments operationId: retrieveBnplLoanTransaction responses: "200": description: Details of the loan transaction content: application/json: schema: $ref: '#/components/schemas/LoanTransaction' default: $ref: '#/components/responses/ErrorResponse' /loan-transactions/{loanTransactionId}/status: parameters: - $ref: '#/components/parameters/loanTransactionId' patch: summary: Update loan status description: Update the loan status to indicate order fulfilled and loan is active operationId: updateBnplLoanTransactionStatus requestBody: content: application/json: schema: type: object required: - status properties: status: $ref: '#/components/schemas/LoanTransactionStatuses' additionalProperties: false responses: "204": description: Update to status acknowledged and applied to loan transaction default: $ref: '#/components/responses/ErrorResponse' /products: post: summary: Retrieve eligible products description: | Retrieve the list of products that are eligible for a buy-now, pay-later loan. Implemented as a not particularly RESTful, RPC-style post operation for simplicity operationId: findEligibleProducts requestBody: content: application/json: schema: type: object required: - products properties: customer: description: If the customer is already enrolled on the BNPL platform the customer URI can be supplied, which can be used to perform an upfront eligibility check allOf: - $ref: '#/components/schemas/CustomerUri' products: $ref: '#/components/schemas/Products' additionalProperties: false responses: "200": description: | List of eligible products with information for subsequent steps content: application/json: schema: type: object required: - productCodes properties: existingCustomerNotEligible: description: Flag to indicate existing customer found and is eligible. Associated workflows will stop if this flag is returned type: boolean productCodes: description: This list of product codes that are eligible for a BNPL loan. Allows merchant to render screen showing matching products. Array will be empty if customer not eligible type: array items: $ref: '#/components/schemas/ProductCode' eligibilityCheckRequired: description: Indicates whether the customer needs to be checked for eligibility. Required for new customers type: boolean default: false totalAmount: description: The total loan value for the products that are eligible allOf: - $ref: '#/components/schemas/CurrencyAndAmount' additionalProperties: false default: $ref: '#/components/responses/ErrorResponse' /terms-and-conditions: get: summary: Retrieve the terms and conditions for BNPL products description: > Retrieve the terms and conditions for BNPL products. For the sake of this example: * There is one set of customer T&Cs. * There is one error response, defined using the `default` keyword. operationId: getTermsAndConditions responses: "200": description: The terms and conditions document as an array of `string` values content: application/json: schema: type: array items: type: string minItems: 1 default: $ref: '#/components/responses/ErrorResponse' components: parameters: loanTransactionId: name: loanTransactionId description: Unique identifier for a given loan agreement in: path required: true schema: $ref: '#/components/schemas/LoanTransactionId' responses: ErrorResponse: description: The error response details, encoded in the ProblemDetails format (RFC9457) content: application/json: schema: $ref: '#/components/schemas/ProblemDetails' schemas: AuthorizationToken: description: An authorisation token used to tee up a customer for authentication and authorisation of the loan as required type: string format: uuid CustomerProperties: type: object required: - firstName - lastName - dateOfBirth - postalCode properties: firstName: description: First name of customer type: string minLength: 1 maxLength: 70 lastName: description: Last name of customer type: string minLength: 1 maxLength: 70 dateOfBirth: description: Customer date of birth type: string format: date-time postalCode: description: Zip code or postal code of customer type: string minLength: 1 maxLength: 70 additionalProperties: false CustomerUri: description: The URI that identifies the customer resource for the loan transaction type: string format: uri LoanTransaction: description: Details of the loan transaction including product codes, total amount and repayment schedule type: object required: - customer - products - totalAmount - paymentSchedule properties: customer: description: Link to customer resource type: string format: uri products: description: List of products and purchase amounts included in BNPL loan transaction allOf: - $ref: '#/components/schemas/Products' status: $ref: '#/components/schemas/LoanTransactionStatuses' totalAmount: description: The total loan amount including interest allOf: - $ref: '#/components/schemas/CurrencyAndAmount' paymentSchedule: description: Schedule of payments for loan repayment type: array minItems: 1 items: type: object required: - paymentDate - amount - lastPayment properties: paymentDate: description: The date on which the payment is due type: string format: date amount: description: The currency and amount due allOf: - $ref: '#/components/schemas/CurrencyAndAmount' lastPayment: description: Indicator of whether this is the last payment that completes the loan repayment type: boolean default: false additionalProperties: false additionalProperties: false LoanTransactionStatuses: description: | Loan transaction status values. Explanation * Pending: Loan transaction is pending authorisation by the End User * Finalised: Loan transaction has been finalised and is awaiting completion * Completed: Loan transaction has been issued following completion of order and payments will be collected type: string enum: - Pending - Finalised - Completed LoanTransactionId: description: Type for unique loan identifier type: string ProductCode: description: Product code for loan application. Required for eligibility check type: string ProblemDetails: type: object required: - type properties: type: description: The problem type, expressed as a URI type: string status: description: The HTTP return code generated by the server type: string pattern: "^[1-5][0-9]{2}$" title: description: The title of the problem, designed to be consumed by humans type: string detail: description: A verbose error message, designed to be consumed by humans type: string instance: description: A URI that identifies a specific occurrence of the problem type: string additionalProperties: true CurrencyAndAmount: description: Amount and currency code type: object required: - currency - amount properties: currency: description: Currency code type: string pattern: "^[A-Z]{3}$" amount: description: Amount type: number Products: type: array minItems: 1 items: type: object required: - productCode - netAmount properties: merchantCategoryCode: description: Merchant category code of merchant. Only required for marketplace eCommerce platforms type: string pattern: '^[0-9]{4}$' productCode: $ref: '#/components/schemas/ProductCode' purchaseAmount: description: Product purchase amount and currency code allOf: - $ref: '#/components/schemas/CurrencyAndAmount' ================================================ FILE: examples/1.0.0/oauth.arazzo.yaml ================================================ arazzo: 1.0.0 info: title: Example OAuth service version: 1.0.0 description: >- Example OAuth service sourceDescriptions: - name: apim-auth url: ./oauth.openapi.yaml type: openapi # This is how you can reference another workflow file # - name: sample # url: ./sample.arazzo.yml # type: arazzo workflows: - workflowId: refresh-token-flow summary: Refresh an access token description: >- This is how you can refresh an access token. inputs: type: object properties: my_client_id: type: string description: The client id my_client_secret: type: string description: The client secret my_redirect_uri: type: string description: The redirect uri # refresh_token: # type: string # description: The refresh token # # From authorization-code-flow.outputs.refresh_token # # Or a previous refresh-token-flow.outputs.refresh_token steps: - stepId: do-the-auth-flow description: >- This is where you do the authorization code flow workflowId: authorization-code-flow parameters: - name: client_id value: $inputs.my_client_id - name: redirect_uri value: $inputs.my_redirect_uri - name: client_secret value: $inputs.my_client_secret outputs: my_refresh_token: $outputs.refresh_token - stepId: do-the-refresh description: >- This is where you do the refresh operationId: get-token requestBody: contentType: application/x-www-form-urlencoded payload: grant_type: refresh_token refresh_token: $steps.do-the-auth-flow.outputs.my_refresh_token successCriteria: - condition: $statusCode == 200 - context: $response.body condition: $.access_token != null type: jsonpath outputs: access_token: $response.body#/access_token refresh_token: $response.body#/refresh_token expires_in: $response.body#/expires_in outputs: access_token: $steps.do-the-refresh.outputs.access_token refresh_token: $steps.do-the-refresh.outputs.refresh_token expires_in: $steps.do-the-refresh.outputs.expires_in - workflowId: client-credentials-flow summary: Get an access token using client credentials description: >- This is how you can get an access token using client credentials. inputs: type: object properties: client_id: type: string description: The client id client_secret: type: string description: The client secret steps: - stepId: get-client-creds-token description: >- This is where you get the token operationId: get-token requestBody: contentType: application/x-www-form-urlencoded payload: client_id: $inputs.client_id client_secret: $inputs.client_secret grant_type: client_credentials successCriteria: - condition: $statusCode == 200 - context: $response.body condition: $.access_token != null type: jsonpath outputs: access_token: $response.body#/access_token outputs: access_token: $steps.get-client-creds-token.outputs.access_token - workflowId: authorization-code-flow summary: Get an access token using an authorization code description: >- This is how you can get an access token using an authorization code. inputs: type: object properties: client_id: type: string description: The client id client_secret: type: string description: The client secret redirect_uri: type: string description: The redirect uri steps: - stepId: browser-authorize description: >- This URL is opened in the browser and redirects you back to the registered redirect URI with an authorization code. operationId: authorize parameters: - name: client_id in: query value: $inputs.client_id - name: redirect_uri in: query value: $inputs.redirect_uri - name: response_type in: query value: 'code' - name: scope in: query value: 'read' - name: state in: query value: '12345' successCriteria: - condition: $statusCode == 200 - context: $response.body condition: $.access_token != null type: jsonpath outputs: code: $response.body#/code # Not really, this is a query parameter - stepId: get-access-token description: >- This is where you get the token operationId: get-token requestBody: contentType: application/x-www-form-urlencoded payload: grant_type: authorization_code code: $steps.browser-authorize.outputs.code redirect_uri: $inputs.redirect_uri client_id: $inputs.client_id client_secret: $inputs.client_secret successCriteria: - condition: $statusCode == 200 - context: $response.body condition: $.access_token != null type: jsonpath outputs: access_token: $response.body#/access_token refresh_token: $response.body#/refresh_token expires_in: $response.body#/expires_in outputs: access_token: $steps.get-access-token.outputs.access_token refresh_token: $steps.get-access-token.outputs.refresh_token expires_in: $steps.get-access-token.outputs.expires_in ================================================ FILE: examples/1.0.0/oauth.openapi.yaml ================================================ openapi: 3.1.0 info: title: Example OAuth service version: 1.0.0 contact: email: info@example.com description: >- OAuth service x-optic-path-ignore: - "**/*.+(ico|png|jpeg|jpg|gif)" servers: - url: https://auth.example.com description: Example OAuth Production paths: /authorize: get: operationId: authorize description: >- This endpoint is used to authorize a user to access the Example API. The user will be redirected to the login page if they are not already logged in. If they are logged in, they will be asked to authorize the application to access their account. If they accept, they will be redirected back to the application with an authorization code. parameters: - name: client_id in: query required: true schema: type: string - name: redirect_uri in: query required: true schema: type: string - name: response_type in: query required: true schema: type: string - name: scope in: query required: true schema: type: string - name: state in: query required: true schema: type: string responses: "200": description: 200 response /oauth/token: post: operationId: get-token description: >- This endpoint is used to get an access token from an authorization code. The authorization code is obtained from the authorize endpoint. requestBody: content: application/x-www-form-urlencoded: schema: type: object properties: grant_type: type: string code: type: string redirect_uri: type: string client_id: type: string client_secret: type: string required: - grant_type - client_id responses: "200": description: 200 response # callback: # myCallback: # '{$request.query.queryUrl}': # post: # requestBody: # description: Callback payload # content: # 'application/json': # schema: # $ref: '#/components/schemas/SomePayload' # responses: # '200': # description: callback successfully processed ================================================ FILE: examples/1.0.0/pet-coupons.arazzo.yaml ================================================ arazzo: 1.0.0 info: title: Petstore - Apply Coupons version: 1.0.0 description: >- Illustrates a workflow whereby a client a) finds a pet in the petstore, b) finds coupons for that pet, and finally c) orders the pet while applying the coupons from step b. sourceDescriptions: - name: pet-coupons url: ./pet-coupons.openapi.yaml type: openapi workflows: - workflowId: apply-coupon summary: Apply a coupon to a pet order. description: >- This is how you can find a pet, find an applicable coupon, and apply that coupon in your order. The workflow concludes by outputting the ID of the placed order. inputs: $ref: "#/components/inputs/apply_coupon_input" steps: - stepId: find-pet description: Find a pet based on the provided tags. operationId: findPetsByTags parameters: - name: pet_tags in: query value: $inputs.my_pet_tags successCriteria: - condition: $statusCode == 200 outputs: my_pet_id: $response.body#/0/id # there is some implied selection here - findPetsByTags responds with a list of pets, # but the client only wants to choose one, and that's what will be provided to the next step. # not totally sure how to indicate that. - stepId: find-coupons description: Find a coupon available for the selected pet. operationId: getPetCoupons parameters: - name: pet_id in: path value: $steps.find-pet.outputs.my_pet_id successCriteria: - condition: $statusCode == 200 outputs: my_coupon_code: $response.body#/couponCode - stepId: place-order description: Place an order for the pet, applying the coupon. workflowId: place-order parameters: - name: pet_id value: $steps.find-pet.outputs.my_pet_id - name: coupon_code value: $steps.find-coupons.outputs.my_coupon_code successCriteria: - condition: $statusCode == 200 outputs: my_order_id: $outputs.workflow_order_id outputs: apply_coupon_pet_order_id: $steps.place-order.outputs.my_order_id - workflowId: buy-available-pet summary: Buy an available pet if one is available. description: This workflow demonstrates a workflow very similar to `apply-coupon`, by intention. It's meant to indicate how to reuse a step (`place-order`) as well as a parameter (`page`, `pageSize`). inputs: $ref: "#/components/inputs/buy_available_pet_input" steps: - stepId: find-pet description: Find a pet that is available for purchase. operationId: findPetsByStatus parameters: - name: status in: query value: "available" - reference: $components.parameters.page value: 1 - reference: $components.parameters.pageSize value: 10 successCriteria: - condition: $statusCode == 200 outputs: my_pet_id: $response.body#/0/id - stepId: place-order description: Place an order for the pet. workflowId: place-order parameters: - name: pet_id value: $steps.find-pet.outputs.my_pet_id successCriteria: - condition: $statusCode == 200 outputs: my_order_id: $outputs.workflow_order_id outputs: buy_pet_order_id: $steps.place-order.outputs.my_order_id - workflowId: place-order summary: Place an order for a pet. description: This workflow places an order for a pet. It may be reused by other workflows as the "final step" in a purchase. inputs: type: object properties: pet_id: type: integer format: int64 description: The ID of the pet to place in the order. quantity: type: integer format: int32 description: The number of pets to place in the order. coupon_code: type: string description: The coupon code to apply to the order. steps: - stepId: place-order description: Place an order for the pet. operationId: placeOrder requestBody: contentType: application/json payload: petId: $inputs.pet_id quantity: $inputs.quantity couponCode: $inputs.coupon_code status: placed complete: false successCriteria: - condition: $statusCode == 200 outputs: step_order_id: $response.body#/id outputs: workflow_order_id: $steps.place-order.outputs.step_order_id components: inputs: apply_coupon_input: type: object properties: my_pet_tags: type: array items: type: string description: Desired tags to use when searching for a pet, in CSV format (e.g. "puppy, dalmatian") store_id: $ref: "#/components/inputs/store_id" buy_available_pet_input: type: object properties: store_id: $ref: "#/components/inputs/store_id" store_id: type: string description: Indicates the domain name of the store where the customer is browsing or buying pets, e.g. "pets.example.com" or "pets.example.co.uk". parameters: page: name: page in: query value: 1 pageSize: name: pageSize in: query value: 100 ================================================ FILE: examples/1.0.0/pet-coupons.openapi.yaml ================================================ openapi: 3.0.3 info: title: Swagger Petstore - OpenAPI 3.0 description: Modifies the standard Petstore example to illustrate a workflow in which coupons are discovered and then used in an order. license: name: Apache 2.0 url: http://www.apache.org/licenses/LICENSE-2.0.html version: 1.0.0 tags: - name: pet description: Everything about your Pets externalDocs: description: Find out more url: http://swagger.io - name: store description: Access to Petstore orders externalDocs: description: Find out more about our store url: http://swagger.io paths: /pet: put: tags: - pet summary: Update an existing pet description: Update an existing pet by Id operationId: updatePet requestBody: description: Update an existent pet in the store content: application/json: schema: $ref: '#/components/schemas/Pet' application/xml: schema: $ref: '#/components/schemas/Pet' application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/Pet' required: true responses: '200': description: Successful operation content: application/json: schema: $ref: '#/components/schemas/Pet' application/xml: schema: $ref: '#/components/schemas/Pet' '400': description: Invalid ID supplied '404': description: Pet not found '405': description: Validation exception security: - petstore_auth: - write:pets - read:pets post: tags: - pet summary: Add a new pet to the store description: Add a new pet to the store operationId: addPet requestBody: description: Create a new pet in the store content: application/json: schema: $ref: '#/components/schemas/Pet' application/xml: schema: $ref: '#/components/schemas/Pet' application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/Pet' required: true responses: '200': description: Successful operation content: application/json: schema: $ref: '#/components/schemas/Pet' application/xml: schema: $ref: '#/components/schemas/Pet' '405': description: Invalid input security: - petstore_auth: - write:pets - read:pets /pet/findByStatus: get: tags: - pet summary: Finds Pets by status description: Multiple status values can be provided with comma separated strings operationId: findPetsByStatus parameters: - name: status in: query description: Status values that need to be considered for filter required: false explode: true schema: type: string default: available enum: - available - pending - sold - name: page in: query description: Which page of results to display. First page is 1. required: true schema: type: integer format: int32 - name: pageSize in: query description: Number of results to display per page. required: false schema: type: integer format: int32 default: 10 responses: '200': description: successful operation content: application/json: schema: type: array items: $ref: '#/components/schemas/Pet' application/xml: schema: type: array items: $ref: '#/components/schemas/Pet' '400': description: Invalid status value security: - petstore_auth: - write:pets - read:pets /pet/findByTags: get: tags: - pet summary: Finds Pets by tags description: Multiple tags can be provided with comma separated strings. Use tag1, tag2, tag3 for testing. operationId: findPetsByTags parameters: - name: tags in: query description: Tags to filter by required: false explode: true schema: type: array items: type: string responses: '200': description: successful operation content: application/json: schema: type: array items: $ref: '#/components/schemas/Pet' application/xml: schema: type: array items: $ref: '#/components/schemas/Pet' '400': description: Invalid tag value security: - petstore_auth: - write:pets - read:pets /pet/{petId}: get: tags: - pet summary: Find pet by ID description: Returns a single pet operationId: getPetById parameters: - name: petId in: path description: ID of pet to return required: true schema: type: integer format: int64 responses: '200': description: successful operation content: application/json: schema: $ref: '#/components/schemas/Pet' application/xml: schema: $ref: '#/components/schemas/Pet' '400': description: Invalid ID supplied '404': description: Pet not found security: - api_key: [] - petstore_auth: - write:pets - read:pets post: tags: - pet summary: Updates a pet in the store with form data description: '' operationId: updatePetWithForm parameters: - name: petId in: path description: ID of pet that needs to be updated required: true schema: type: integer format: int64 - name: name in: query description: Name of pet that needs to be updated schema: type: string - name: status in: query description: Status of pet that needs to be updated schema: type: string responses: '405': description: Invalid input security: - petstore_auth: - write:pets - read:pets delete: tags: - pet summary: Deletes a pet description: delete a pet operationId: deletePet parameters: - name: api_key in: header description: '' required: false schema: type: string - name: petId in: path description: Pet id to delete required: true schema: type: integer format: int64 responses: '400': description: Invalid pet value security: - petstore_auth: - write:pets - read:pets /pet/{petId}/coupons: get: tags: - pet summary: Find a coupon available for a pet description: Returns a coupon available for the pet, if applicable operationId: getPetCoupons parameters: - name: petId in: path description: ID of pet with available coupons required: true schema: type: integer format: int64 responses: '200': description: successful operation content: application/json: schema: $ref: '#/components/schemas/Coupon' application/xml: schema: $ref: '#/components/schemas/Coupon' '400': description: Invalid ID supplied '404': description: Pet not found or coupon not available security: - api_key: [] - petstore_auth: - read:pets /store/order: post: tags: - store summary: Place an order for a pet description: Place a new order in the store operationId: placeOrder requestBody: content: application/json: schema: $ref: '#/components/schemas/Order' application/xml: schema: $ref: '#/components/schemas/Order' application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/Order' responses: '200': description: successful operation content: application/json: schema: $ref: '#/components/schemas/Order' '400': description: Invalid input /store/order/{orderId}: get: tags: - store summary: Find purchase order by ID description: For valid response try integer IDs with value <= 5 or > 10. Other values will generate exceptions. operationId: getOrderById parameters: - name: orderId in: path description: ID of order that needs to be fetched required: true schema: type: integer format: int64 responses: '200': description: successful operation content: application/json: schema: $ref: '#/components/schemas/Order' application/xml: schema: $ref: '#/components/schemas/Order' '400': description: Invalid ID supplied '404': description: Order not found delete: tags: - store summary: Delete purchase order by ID description: For valid response try integer IDs with value < 1000. Anything above 1000 or nonintegers will generate API errors operationId: deleteOrder parameters: - name: orderId in: path description: ID of the order that needs to be deleted required: true schema: type: integer format: int64 responses: '400': description: Invalid ID supplied '404': description: Order not found components: schemas: Order: type: object properties: id: type: integer format: int64 example: 10 petId: type: integer format: int64 example: 198772 quantity: type: integer format: int32 example: 7 status: type: string description: Order Status example: approved enum: - placed - approved - delivered complete: type: boolean couponCode: type: string example: "SUMMERSALE" xml: name: order Category: type: object properties: id: type: integer format: int64 example: 1 name: type: string example: Dogs xml: name: category Tag: type: object properties: id: type: integer format: int64 name: type: string xml: name: tag Pet: required: - name - price - photoUrls type: object properties: id: type: integer format: int64 example: 10 name: type: string example: doggie category: $ref: '#/components/schemas/Category' photoUrls: type: array xml: wrapped: true items: type: string xml: name: photoUrl price: type: number tags: type: array xml: wrapped: true items: $ref: '#/components/schemas/Tag' status: type: string description: pet status in the store enum: - available - pending - sold xml: name: pet ApiResponse: type: object properties: code: type: integer format: int32 type: type: string message: type: string xml: name: '##default' Coupon: type: object properties: id: type: integer format: int64 example: 10 description: type: string example: "Summer Sale - 10% off!" couponCode: type: string example: "SUMMERSALE" xml: name: coupon requestBodies: Pet: description: Pet object that needs to be added to the store content: application/json: schema: $ref: '#/components/schemas/Pet' application/xml: schema: $ref: '#/components/schemas/Pet' securitySchemes: petstore_auth: type: oauth2 flows: implicit: authorizationUrl: https://petstore3.swagger.io/oauth/authorize scopes: write:pets: modify pets in your account read:pets: read your pets api_key: type: apiKey name: api_key in: header ================================================ FILE: package.json ================================================ { "name": "arazzo", "version": "1.0.0", "description": "Arazzo Specification", "scripts": { "build": "bash ./scripts/md2html/build.sh", "build-src": "npm run validate-markdown && bash ./scripts/md2html/build.sh src && bash ./scripts/schema-publish.sh src", "test": "(c8 --100 vitest --watch=false || echo 'No vitest tests found — skipping...') && bash scripts/schema-test-coverage.sh", "format-markdown": "npx markdownlint-cli2 --config spec.markdownlint.yaml --fix src/arazzo.md && npx markdownlint-cli2 --fix *.md", "validate-markdown": "npx markdownlint-cli2 --config spec.markdownlint.yaml src/arazzo.md && npx markdownlint-cli2 *.md" }, "repository": { "type": "git", "url": "https://github.com/OAI/Arazzo-Specification.git" }, "keywords": [ "Arazzo", "Workflows", "Specification", "API", "Swagger", "OpenAPI", "OAS", "OAI" ], "author": { "name": "OpenAPI Initiative - Arazzo Working Group", "email": "tsc@openapis.org", "url": "https://openapis.org/" }, "readmeFilename": "README.md", "license": "Apache-2.0", "bugs": { "url": "https://github.com/OAI/Arazzo-Specification/issues" }, "homepage": "https://github.com/yourusername/your-project-name#readme", "dependencies": { "cheerio": "^1.2.0", "highlight.js": "^11.11.1", "markdown-it": "^14.1.1", "respec": "35.9.0", "yargs": "^18.0.0" }, "devDependencies": { "markdownlint-cli2": "^0.22.0", "yaml": "2.8.3", "@hyperjump/json-schema": "^1.17.5", "c8": "^11.0.0", "vitest": "^4.1.4" } } ================================================ FILE: scripts/md2html/.gitignore ================================================ *.err input.bs ================================================ FILE: scripts/md2html/analytics/google.html ================================================ ================================================ FILE: scripts/md2html/build.sh ================================================ #!/bin/bash # Author: @frankkilcommins (inspired by the work of @MikeRalphson) # Author: @MikeRalphson # run this script from the root of the repo. It is designed to be run by a GitHub workflow. # # When run with no arguments, it builds artifacts for all published specification versions. # It may also be run with a specific version argument, such as "1.0.1" or "latest" # Finally, it may be run with "src" to build "src/arazzo.md" # # It contains bashisms if [ "$1" = "src" ]; then deploydir="deploy-preview" else deploydir="deploy/arazzo" fi mkdir -p $deploydir mkdir -p $deploydir/js mkdir -p $deploydir/temp cp -p node_modules/respec/builds/respec-w3c.* $deploydir/js/ latest=$(git describe --abbrev=0 --tags) allVersions=$(ls -1 versions/[123456789].*.md | sort -r) if [ -z "$1" ]; then specifications=$allVersions elif [ "$1" = "latest" ]; then specifications=$(ls -1 versions/$latest.md) elif [ "$1" = "src" ]; then specifications="src/arazzo.md" else specifications=$(ls -1 versions/$1.md) fi latestCopied="none" lastMinor="-" for specification in $specifications; do version=$(basename $specification .md) if [ "$1" = "src" ]; then destination="$deploydir/$version.html" else destination="$deploydir/v$version.html" fi minorVersion=${version:0:3} tempfile="$deploydir/temp/$version.html" tempfile2="$deploydir/temp/$version-2.html" echo === Building $version to $destination node scripts/md2html/md2html.js --maintainers MAINTAINERS.md $specification "$allVersions" > $tempfile npx respec --no-sandbox --use-local --src $tempfile --out $tempfile2 # remove unwanted Google Tag Manager and Google Analytics scripts sed -e 's/'; preface += ``; try { preface += fs.readFileSync('./analytics/google.html','utf8'); } catch (ex) {} preface += ''; preface += ''; preface += `

${title.split('|')[0]}

`; preface += `

Copyright © ${options.publishDate.getFullYear()} the Linux Foundation

`; preface += `

${abstract}

`; preface += 'The Arazzo Specification provides a mechanism that can define sequences of calls and their dependencies to be woven together and expressed in the context of delivering a particular outcome or set of outcomes when dealing with API descriptions (such as OpenAPI descriptions).'; preface += '
'; preface += '
'; preface += '

Status of This Document

'; preface += 'The source-of-truth for the specification is the GitHub markdown file referenced above.'; preface += '
'; } else { preface += ''; } return preface; } function doMaintainers() { let m = fs.readFileSync(argv.maintainers,'utf8'); let h = md.render(m); let $ = cheerio.load(h); let u = $('ul').first(); $(u).children('li').each(function(e){ let t = $(this).text().split('@')[0]; maintainers.push({name:t}); }); if ($("ul").length < 2) return; u = $("ul").last(); $(u).children('li').each(function(e){ let t = $(this).text().split('@')[0]; emeritus.push({name:t}); }); } function getPublishDate(m) { let result = new Date(); let h = md.render(m); let $ = cheerio.load(h); $('table').each(function(i,table){ const h = $(table).find('th'); const headers = []; $(h).each(function(i,header){ headers.push($(header).text()); }); if (headers.length >= 2 && headers[0] === 'Version' && headers[1] === 'Date') { let c = $(table).find('tr').find('td'); let v = $(c[0]).text(); let d = $(c[1]).text(); argv.subtitle = v; if (d !== 'TBA') result = new Date(d); } }); return result; } if (argv.maintainers) { doMaintainers(); } let s = fs.readFileSync(argv._[0],'utf8'); if (argv.respec) { argv.publishDate = getPublishDate(s); } let lines = s.split(/\r?\n/); let prevHeading = 0; let lastIndent = 0; let inTOC = false; let inDefs = false; let inCodeBlock = false; let bsFix = true; let indents = [0]; // process the markdown for (let l in lines) { let line = lines[l]; let linkTarget; if (line.startsWith('## Table of Contents')) inTOC = true; if (line.startsWith(' ## Table of Contents - [Definitions](#definitions) - [Arazzo Description](#arazzo-description) - [Specification](#specification) - [Versions](#versions) - [Format](#format) - [Arazzo Description Structure](#arazzo-description-structure) - [Data Types](#data-types) - [Relative References in URLs](#relative-references-in-urls) - [Schema](#schema) - [Arazzo Specification Object](#arazzo-specification-object) - [Info Object](#info-object) - [Source Description Object](#source-description-object) - [Workflow Object](#workflow-object) - [Step Object](#step-object) - [Parameter Object](#parameter-object) - [Success Action Object](#success-action-object) - [Failure Action Object](#failure-action-object) - [Components Object](#components-object) - [Reusable Object](#reusable-object) - [Criterion Object](#criterion-object) - [Request Body Object](#request-body-object) - [Payload Replacement Object](#payload-replacement-object) - [Runtime Expressions](#runtime-expressions) - [Specification Extensions](#specification-extensions) - [Security Considerations](#security-considerations) - [IANA Considerations](#iana-considerations) - [Appendix A: Revision History](#appendix-a-revision-history) ## Definitions ##### Arazzo Description A self-contained document (or set of documents) which defines or describes API workflows (specific sequence of calls to achieve a particular goal in the context of an API definition). An Arazzo Description uses and conforms to the Arazzo Specification, and `MUST` contain a valid Arazzo Specification version field (`arazzo`), an [Info](#info-object) field, a `sourceDescriptions` field with at least one defined [Source](#source-description-object), and there `MUST` be at least one [Workflow](#workflow-object) defined in the `workflows` fixed field. ## Specification ### Versions The Arazzo Specification is versioned using a `major`.`minor`.`patch` versioning scheme. The `major`.`minor` portion of the version string (for example 1.0) SHALL designate the Arazzo feature set. `.patch` versions address errors in, or provide clarifications to, this document, not the feature set. The patch version SHOULD NOT be considered by tooling, making no distinction between 1.0.0 and 1.0.1 for example. ### Format An Arazzo Description that conforms to the Arazzo Specification is itself a JSON object, which may be represented either in JSON or YAML format. All field names in the specification are **case sensitive**. This includes all fields that are used as keys in a map, except where explicitly noted that keys are **case insensitive**. In order to preserve the ability to round-trip between YAML and JSON formats, YAML version [1.2](https://yaml.org/spec/1.2/spec.html) is RECOMMENDED along with some additional constraints: - Tags MUST be limited to those allowed by the [JSON Schema ruleset](https://yaml.org/spec/1.2/spec.html#id2803231). - Keys used in YAML maps MUST be limited to a scalar string, as defined by the [YAML Failsafe schema ruleset](https://yaml.org/spec/1.2/spec.html#id2802346). ### Arazzo Description Structure It is RECOMMENDED that the entry Arazzo document be named: `arazzo.json` or `arazzo.yaml`. An Arazzo Description MAY be made up of a single document or be divided into multiple, connected parts at the discretion of the author. If workflows from other documents are being referenced, they must by included as a [Source Description Object](#source-description-object). In a multi-document description, the document containing the [Arazzo Specification Object](#arazzo-specification-object) is known as the **entry Arazzo document**. ### Data Types Data types in the Arazzo Specification are based on the types supported by the [JSON Schema Specification Draft 2020-12](https://tools.ietf.org/html/draft-bhutton-json-schema-00#section-4.2.1). Note that integer as a type is also supported and is defined as a JSON number without a fraction or exponent part. As defined by the [JSON Schema Validation vocabulary](https://tools.ietf.org/html/draft-bhutton-json-schema-validation-00#section-7), data types can have an optional modifier property: `format`. Arazzo additionally supports the formats (similar to the OpenAPI specification) to provide fine detail for primitive data types. The formats defined are: [`type`](#data-types) | `format` | Comments ------ | -------- | -------- `integer` | `int32` | signed 32 bits `integer` | `int64` | signed 64 bits (a.k.a long) `number` | `float` | | `number` | `double` | | `string` | `password` | A hint to UIs to obscure input. ### Relative References in URLs Unless specified otherwise, all properties that are URLs MAY be relative references as defined by [RFC3986](https://tools.ietf.org/html/rfc3986#section-4.2). Unless specified otherwise, relative references are resolved using the URL of the referring document. ### Schema In the following description, if a field is not explicitly **REQUIRED** or described with a MUST or SHALL, it can be considered OPTIONAL. #### Arazzo Specification Object This is the root object of the [Arazzo Description](#arazzo-description). ##### Fixed Fields Field Name | Type | Description ---|:---:|--- arazzo | `string` | **REQUIRED**. This string MUST be the [version number](#versions) of the Arazzo Specification that the Arazzo Description uses. The `arazzo` field MUST be used by tooling to interpret the Arazzo Description. info | [Info Object](#info-object) | **REQUIRED**. Provides metadata about the workflows contain within the Arazzo Description. The metadata MAY be used by tooling as required. sourceDescriptions | [[Source Description Object](#source-description-object)] | **REQUIRED**. A list of source descriptions (such as an OpenAPI description) this Arazzo Description SHALL apply to. The list MUST have at least one entry. workflows | [[Workflow Object](#workflow-object)] | **REQUIRED**. A list of workflows. The list MUST have at least one entry. components | [Components Object](#components-object) | An element to hold various schemas for the Arazzo Description. This object MAY be extended with [Specification Extensions](#specification-extensions). ##### Arazzo Specification Object Example ```yaml arazzo: 1.0.0 info: title: A pet purchasing workflow summary: This Arazzo Description showcases the workflow for how to purchase a pet through a sequence of API calls description: | This Arazzo Description walks you through the workflow and steps of `searching` for, `selecting`, and `purchasing` an available pet. version: 1.0.1 sourceDescriptions: - name: petStoreDescription url: https://github.com/swagger-api/swagger-petstore/blob/master/src/main/resources/openapi.yaml type: openapi workflows: - workflowId: loginUserAndRetrievePet summary: Login User and then retrieve pets description: This workflow lays out the steps to login a user and then retrieve pets inputs: type: object properties: username: type: string password: type: string steps: - stepId: loginStep description: This step demonstrates the user login step operationId: loginUser parameters: # parameters to inject into the loginUser operation (parameter name must be resolvable at the referenced operation and the value is determined using {expression} syntax) - name: username in: query value: $inputs.username - name: password in: query value: $inputs.password successCriteria: # assertions to determine step was successful - condition: $statusCode == 200 outputs: # outputs from this step tokenExpires: $response.header.X-Expires-After rateLimit: $response.header.X-Rate-Limit sessionToken: $response.body - stepId: getPetStep description: retrieve a pet by status from the GET pets endpoint operationPath: '{$sourceDescriptions.petstoreDescription.url}#/paths/~1pet~1findByStatus/get' parameters: - name: status in: query value: 'available' - name: Authorization in: header value: $steps.loginUser.outputs.sessionToken successCriteria: - condition: $statusCode == 200 outputs: # outputs from this step availablePets: $response.body outputs: available: $steps.getPetStep.availablePets ``` #### Info Object The object provides metadata about API workflows defined in this Arazzo document. The metadata MAY be used by the clients if needed. ##### Fixed Fields Field Name | Type | Description ---|:---:|--- title | `string` | **REQUIRED**. A human readable title of the Arazzo Description. summary | `string` | A short summary of the Arazzo Description. description | `string` | A description of the purpose of the workflows defined. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. version | `string` | **REQUIRED**. The version identifier of the Arazzo document (which is distinct from the [Arazzo Specification version](#versions)). This object MAY be extended with [Specification Extensions](#specification-extensions). ##### Info Object Example ```yaml title: A pet purchasing workflow summary: This workflow showcases how to purchase a pet through a sequence of API calls description: | This workflow walks you through the steps of searching for, selecting, and purchasing an available pet. version: 1.0.1 ``` #### Source Description Object Describes a source description (such as an OpenAPI description) that will be referenced by one or more workflows described within an Arazzo Description. An object storing a map between named description keys and location URLs to the source descriptions (such as an OpenAPI description) this Arazzo Description SHALL apply to. Each source location `string` MUST be in the form of a URI-reference as defined by [RFC3986](https://tools.ietf.org/html/rfc3986#section-4.1). ##### Fixed Fields Field Name | Type | Description ---|:---:|--- name | `string` | **REQUIRED**. A unique name for the source description. Tools and libraries MAY use the `name` to uniquely identify a source description, therefore, it is RECOMMENDED to follow common programming naming conventions. SHOULD conform to the regular expression `[A-Za-z0-9_\-]+`. url | `string` | **REQUIRED**. A URL to a source description to be used by a workflow. If a relative reference is used, it MUST be in the form of a URI-reference as defined by [RFC3986](https://tools.ietf.org/html/rfc3986#section-4.2). type | `string` | The type of source description. Possible values are `"openapi"` or `"arazzo"`. This object MAY be extended with [Specification Extensions](#specification-extensions). ##### Source Description Object Example ```yaml name: petStoreDescription url: https://github.com/swagger-api/swagger-petstore/blob/master/src/main/resources/openapi.yaml type: openapi ``` #### Workflow Object Describes the steps to be taken across one or more APIs to achieve an objective. The workflow object MAY define inputs needed in order to execute workflow steps, where the defined steps represent a call to an API operation or another workflow, and a set of outputs. ##### Fixed Fields Field Name | Type | Description ---|:---:|--- workflowId | `string` | **REQUIRED**. Unique string to represent the workflow. The id MUST be unique amongst all workflows describe in the Arazzo Description. The `workflowId` value is **case-sensitive**. Tools and libraries MAY use the `workflowId` to uniquely identify a workflow, therefore, it is RECOMMENDED to follow common programming naming conventions. SHOULD conform to the regular expression `[A-Za-z0-9_\-]+`. summary | `string` | A summary of the purpose or objective of the workflow. description | `string` | A description of the workflow. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. inputs | `JSON Schema` | A JSON Schema 2020-12 object representing the input parameters used by this workflow. dependsOn | [`string`] | A list of workflows that MUST be completed before this workflow can be processed. The values provided MUST be a `workflowId`. If the workflow depended on is defined within the current Workflow Document, then specify the `workflowId` of the relevant local workflow. If the workflow is defined in a separate Arazzo Document then the workflow MUST be defined in the `sourceDescriptions` and the `workflowId` MUST be specified using a [runtime expression](#runtime-expressions) (e.g., `$sourceDescriptions..`) to avoid ambiguity or potential clashes. steps | [[Step Object](#step-object)] | **REQUIRED**. An ordered list of steps where each step represents a call to an API operation or to another workflow. successActions | [[Success Action Object](#success-action-object) \| [Reusable Object](#reusable-object)] | A list of success actions that are applicable for all steps described under this workflow. These success actions can be overridden at the step level but cannot be removed there. If a Reusable Object is provided, it MUST link to success actions defined in the [components/successActions](#components-object) of the current Arazzo document. The list MUST NOT include duplicate success actions. failureActions | [[Failure Action Object](#failure-action-object) \| [Reusable Object](#reusable-object)] | A list of failure actions that are applicable for all steps described under this workflow. These failure actions can be overridden at the step level but cannot be removed there. If a Reusable Object is provided, it MUST link to failure actions defined in the [components/failureActions](#components-object) of the current Arazzo document. The list MUST NOT include duplicate failure actions. outputs | Map[`string`, {expression}] | A map between a friendly name and a dynamic output value. The name MUST use keys that match the regular expression: `^[a-zA-Z0-9\.\-_]+$`. parameters | [[Parameter Object](#parameter-object) \| [Reusable Object](#reusable-object)] | A list of parameters that are applicable for all steps described under this workflow. These parameters can be overridden at the step level but cannot be removed there. Each parameter MUST be passed to an operation or workflow as referenced by `operationId`, `operationPath`, or `workflowId` as specified within each step. If a Reusable Object is provided, it MUST link to a parameter defined in the [components/parameters](#components-object) of the current Arazzo document. The list MUST NOT include duplicate parameters. This object MAY be extended with [Specification Extensions](#specification-extensions). ##### Workflow Object Example ```yaml workflowId: loginUser summary: Login User description: This workflow lays out the steps to login a user inputs: type: object properties: username: type: string password: type: string steps: - stepId: loginStep description: This step demonstrates the user login step operationId: loginUser parameters: # parameters to inject into the loginUser operation (parameter name must be resolvable at the referenced operation and the value is determined using {expression} syntax) - name: username in: query value: $inputs.username - name: password in: query value: $inputs.password successCriteria: # assertions to determine step was successful - condition: $statusCode == 200 outputs: # outputs from this step tokenExpires: $response.header.X-Expires-After rateLimit: $response.header.X-Rate-Limit outputs: tokenExpires: $steps.loginStep.outputs.tokenExpires ``` #### Step Object Describes a single workflow step which MAY be a call to an API operation ([OpenAPI Operation Object](https://spec.openapis.org/oas/latest.html#operation-object) or another [Workflow Object](#workflow-object)). ##### Fixed Fields Field Name | Type | Description ---|:---:|--- description | `string` | A description of the step. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. stepId | `string` | **REQUIRED**. Unique string to represent the step. The `stepId` MUST be unique amongst all steps described in the workflow. The `stepId` value is **case-sensitive**. Tools and libraries MAY use the `stepId` to uniquely identify a workflow step, therefore, it is RECOMMENDED to follow common programming naming conventions. SHOULD conform to the regular expression `[A-Za-z0-9_\-]+`. operationId | `string` | The name of an existing, resolvable operation, as defined with a unique `operationId` and existing within one of the `sourceDescriptions`. The referenced operation will be invoked by this workflow step. If multiple (non `arazzo` type) `sourceDescriptions` are defined, then the `operationId` MUST be specified using a [runtime expression](#runtime-expressions) (e.g., `$sourceDescriptions..`) to avoid ambiguity or potential clashes. This field is mutually exclusive of the `operationPath` and `workflowId` fields respectively. operationPath | `string` | A reference to a [Source](#source-description-object) combined with a [JSON Pointer](https://tools.ietf.org/html/rfc6901) to reference an operation. This field is mutually exclusive of the `operationId` and `workflowId` fields respectively. The operation being referenced MUST be described within one of the `sourceDescriptions` descriptions. A [runtime expression](#runtime-expressions) syntax MUST be used to identify the source description document. If the referenced operation has an `operationId` defined then the `operationId` SHOULD be preferred over the `operationPath`. workflowId | `string` | The [workflowId](#fixed-fields-2) referencing an existing workflow within the Arazzo Description. If multiple `arazzo` type `sourceDescriptions` are defined, then the `workflowId` MUST be specified using a [runtime expression](#runtime-expressions) (e.g., `$sourceDescriptions..`) to avoid ambiguity or potential clashes. The field is mutually exclusive of the `operationId` and `operationPath` fields respectively. parameters | [[Parameter Object](#parameter-object) \| [Reusable Object](#reusable-object)] | A list of parameters that MUST be passed to an operation or workflow as referenced by `operationId`, `operationPath`, or `workflowId`. If a parameter is already defined at the [Workflow](#workflow-object), the new definition will override it but can never remove it. If a Reusable Object is provided, it MUST link to a parameter defined in the [components/parameters](#components-object) of the current Arazzo document. The list MUST NOT include duplicate parameters. requestBody | [Request Body Object](#request-body-object) | The request body to pass to an operation as referenced by `operationId` or `operationPath`. The `requestBody` is fully supported in HTTP methods where the HTTP 1.1 specification [RFC7231](https://tools.ietf.org/html/rfc7231#section-4.3.1) has explicitly defined semantics for request bodies. In other cases where the HTTP spec is vague (such as [GET](https://tools.ietf.org/html/rfc7231#section-4.3.1), [HEAD](https://tools.ietf.org/html/rfc7231#section-4.3.2) and [DELETE](https://tools.ietf.org/html/rfc7231#section-4.3.5)), `requestBody` is permitted but does not have well-defined semantics and SHOULD be avoided if possible. successCriteria | [[Criterion Object](#criterion-object)] | A list of assertions to determine the success of the step. Each assertion is described using a [Criterion Object](#criterion-object). All assertions `MUST` be satisfied for the step to be deemed successful. onSuccess | [[Success Action Object](#success-action-object) \| [Reusable Object](#reusable-object)] | An array of success action objects that specify what to do upon step success. If omitted, the next sequential step shall be executed as the default behavior. If multiple success actions have similar `criteria`, the first sequential action matching the criteria SHALL be the action executed. If a success action is already defined at the [Workflow](#workflow-object), the new definition will override it but can never remove it. If a Reusable Object is provided, it MUST link to a success action defined in the [components](#components-object) of the current Arazzo document. The list MUST NOT include duplicate success actions. onFailure | [[Failure Action Object](#failure-action-object) \| [Reusable Object](#reusable-object)] | An array of failure action objects that specify what to do upon step failure. If omitted, the default behavior is to break and return. If multiple failure actions have similar `criteria`, the first sequential action matching the criteria SHALL be the action executed. If a failure action is already defined at the [Workflow](#workflow-object), the new definition will override it but can never remove it. If a Reusable Object is provided, it MUST link to a failure action defined in the [components](#components-object) of the current Arazzo document. The list MUST NOT include duplicate failure actions. outputs | Map[`string`, {expression}] | A map between a friendly name and a dynamic output value defined using a [runtime expression](#runtime-expressions). The name MUST use keys that match the regular expression: `^[a-zA-Z0-9\.\-_]+$`. This object MAY be extended with [Specification Extensions](#specification-extensions). ##### Step Object Example **Single step** ```yaml stepId: loginStep description: This step demonstrates the user login step operationId: loginUser parameters: # parameters to inject into the loginUser operation (parameter name must be resolvable at the referenced operation and the value is determined using {expression} syntax) - name: username in: query value: $inputs.username - name: password in: query value: $inputs.password successCriteria: # assertions to determine step was successful - condition: $statusCode == 200 outputs: # outputs from this step tokenExpires: $response.header.X-Expires-After rateLimit: $response.header.X-Rate-Limit ``` **Multiple steps** ```yaml steps: - stepId: loginStep description: This step demonstrates the user login step operationId: loginUser parameters: # parameters to inject into the loginUser operation (parameter name must be resolvable at the referenced operation and the value is determined using {expression} syntax) - name: username in: query value: $inputs.username - name: password in: query value: $inputs.password successCriteria: # assertions to determine step was successful - condition: $statusCode == 200 outputs: # outputs from this step tokenExpires: $response.header.X-Expires-After rateLimit: $response.header.X-Rate-Limit sessionToken: $response.body - stepId: getPetStep description: retrieve a pet by status from the GET pets endpoint operationPath: '{$sourceDescriptions.petStoreDescription.url}#/paths/~1pet~1findByStatus/get' parameters: - name: status in: query value: 'available' - name: Authorization in: header value: $steps.loginUser.outputs.sessionToken successCriteria: - condition: $statusCode == 200 outputs: # outputs from this step availablePets: $response.body ``` #### Parameter Object Describes a single step parameter. A unique parameter is defined by the combination of a `name` and `in` fields. There are four possible locations specified by the `in` field: - path - Used together with OpenAPI style [Path Templating](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#path-templating), where the parameter value is actually part of the operation's URL. This does not include the host or base path of the API. For example, in /items/{itemId}, the path parameter is itemId. - query - Parameters that are appended to the URL. For example, in `/items?id=###`, the query parameter is `id`. - header - Custom headers that are expected as part of the request. Note that [RFC7230](https://tools.ietf.org/html/rfc7230#page-22) states header names are case insensitive. - cookie - Used to pass a specific cookie value to the source API. ##### Fixed Fields Field Name | Type | Description ---|:---:|--- name | `string` | **REQUIRED**. The name of the parameter. Parameter names are _case sensitive_. in | `string` | The name location of the parameter. Possible values are `"path"`, `"query"`, `"header"`, `"cookie"`, or `"body"`. When the step in context specifies a `workflowId`, then all parameters map to workflow inputs. In all other scenarios (e.g., a step specifies an `operationId`), the `in` field MUST be specified. value | Any \| {expression} | **REQUIRED**. The value to pass in the parameter. The value can be a constant or an [Runtime Expression](#runtime-expressions) to be evaluated and passed to the referenced operation or workflow. This object MAY be extended with [Specification Extensions](#specification-extensions). ##### Parameter Object Example **Query Example** ```yaml - name: username in: query value: $inputs.username ``` **Header Example** ```yaml - name: X-Api-Key in: header value: $inputs.x-api-key ``` #### Success Action Object A single success action which describes an action to take upon success of a workflow step. There are two possible values for the `type` field. - end - The workflow ends, and context returns to the caller with applicable outputs - goto - A one-way transfer of workflow control to the specified label (either a `workflowId` or `stepId`) ##### Fixed Fields Field Name | Type | Description ---|:---:|--- name | `string` | **REQUIRED**. The name of the success action. Names are _case sensitive_. type | `string` | **REQUIRED**. The type of action to take. Possible values are `"end"` or `"goto"`. workflowId | `string` | The [workflowId](#fixed-fields-2) referencing an existing workflow within the Arazzo Description to transfer to upon success of the step. This field is only relevant when the `type` field value is `"goto"`. If multiple `arazzo` type `sourceDescriptions` are defined, then the `workflowId` MUST be specified using a [runtime expression](#runtime-expressions) (e.g., `$sourceDescriptions..`) to avoid ambiguity or potential clashes. This field is mutually exclusive to `stepId`. stepId | `string` | The `stepId` to transfer to upon success of the step. This field is only relevant when the `type` field value is `"goto"`. The referenced `stepId` MUST be within the current workflow. This field is mutually exclusive to `workflowId`. criteria | [[Criterion Object](#criterion-object)] | A list of assertions to determine if this action SHALL be executed. Each assertion is described using a [Criterion Object](#criterion-object). All criteria assertions `MUST` be satisfied for the action to be executed. This object MAY be extended with [Specification Extensions](#specification-extensions). ##### Success Action Object Example ```yaml name: JoinWaitingList type: goto stepId: joinWaitingListStep criteria: # assertions to determine if this success action should be executed - context: $response.body condition: $[?count(@.pets) > 0] type: jsonpath ``` #### Failure Action Object A single failure action which describes an action to take upon failure of a workflow step. There are three possible values for the `type` field. - end - The workflow ends, and context returns to the caller with applicable outputs - retry - The current step will be retried. The retry will be constrained by the `retryAfter` and `retryLimit` fields. If a `stepId` or `workflowId` are specified, then the reference is executed and the context is returned, after which the current step is retried. - goto - A one-way transfer of workflow control to the specified label (either a `workflowId` or `stepId`) ##### Fixed Fields Field Name | Type | Description ---|:---:|--- name | `string` | **REQUIRED**. The name of the failure action. Names are _case sensitive_. type | `string` | **REQUIRED**. The type of action to take. Possible values are `"end"`, `"retry"`, or `"goto"`. workflowId | `string` | The [workflowId](#fixed-fields-2) referencing an existing workflow within the Arazzo Description to transfer to upon failure of the step. This field is only relevant when the `type` field value is `"goto"` or `"retry"`. If multiple `arazzo` type `sourceDescriptions` are defined, then the `workflowId` MUST be specified using a [runtime expression](#runtime-expressions) (e.g., `$sourceDescriptions..`) to avoid ambiguity or potential clashes. This field is mutually exclusive to `stepId`. When used with `"retry"`, context transfers back upon completion of the specified workflow. stepId | `string` | The `stepId` to transfer to upon failure of the step. This field is only relevant when the `type` field value is `"goto"` or `"retry"`. The referenced `stepId` MUST be within the current workflow. This field is mutually exclusive to `workflowId`. When used with `"retry"`, context transfers back upon completion of the specified step. retryAfter | `number` | A non-negative decimal indicating the seconds to delay after the step failure before another attempt SHALL be made. **Note:** if an HTTP [Retry-After](https://tools.ietf.org/html/rfc9110.html#name-retry-after) response header was returned to a step from a targeted operation, then it SHOULD overrule this particular field value. This field only applies when the `type` field value is `"retry"` or `"function"`. retryLimit | `integer` | A non-negative integer indicating how many attempts to retry the step MAY be attempted before failing the overall step. If not specified then a single retry SHALL be attempted. This field only applies when the `type` field value is `"retry"`. The `retryLimit` MUST be exhausted prior to executing subsequent failure actions. criteria | [[Criterion Object](#criterion-object)] | A list of assertions to determine if this action SHALL be executed. Each assertion is described using a [Criterion Object](#criterion-object). This object MAY be extended with [Specification Extensions](#specification-extensions). ##### Failure Action Object Example ```yaml name: retryStep type: retry retryAfter: 1 retryLimit: 5 criteria: # assertions to determine if this action should be executed - condition: $statusCode == 503 ``` #### Components Object Holds a set of reusable objects for different aspects of the Arazzo Specification. All objects defined within the components object will have no effect on the Arazzo Description unless they are explicitly referenced from properties outside the components object. Components are scoped to the Arazzo document they are defined in. For example, if a step defined in Arazzo document "A" references a workflow defined in Arazzo document "B", the components in "A" are not considered when evaluating the workflow referenced in "B". ##### Fixed Fields Field Name | Type | Description ---|:---|--- inputs | Map[`string`, `JSON Schema`] | An object to hold reusable JSON Schema objects to be referenced from workflow inputs. parameters | Map[`string`, [Parameter Object](#parameter-object)] | An object to hold reusable Parameter Objects successActions | Map[`string`, [Success Action Object](#success-action-object)] | An object to hold reusable Success Actions Objects. failureActions | Map[`string`, [Failure Action Object](#failure-action-object)] | An object to hold reusable Failure Actions Objects. This object MAY be extended with [Specification Extensions](#specification-extensions). All the fixed fields declared above are objects that MUST use keys that match the regular expression: `^[a-zA-Z0-9\.\-_]+$`. The key is used to refer to the input or parameter in other parts of the Workflow Description. Field Name Examples: ``` User User_1 User_Name user-name my.org.User ``` ##### Components Object Example ```yaml components: parameters: storeId: name: storeId in: header value: $inputs.x-store-id inputs: pagination: type: object properties: page: type: integer format: int32 pageSize: type: integer format: int32 failureActions: refreshToken: name: refreshExpiredToken type: retry retryAfter: 1 retryLimit: 5 workflowId: refreshTokenWorkflowId criteria: # assertions to determine if this action should be executed - condition: $statusCode == 401 ``` ```json "components": { "parameters": { "storeId": { "name": "storeId", "in": "header", "value": "$inputs.x-store-id" } }, "inputs": { "pagination": { "type": "object", "properties": { "page": { "type": "integer", "format": "int32" }, "pageSize": { "type": "integer", "format": "int32" } } } }, "failureActions": { "refreshToken": { "name": "refreshExpiredToken", "type": "retry", "retryAfter": 1, "retryLimit": 5, "workflowId": "refreshTokenWorkflowId", "criteria": [ { "condition": "{$statusCode == 401}" } ] } } } ``` #### Reusable Object A simple object to allow referencing of objects contained within the [Components Object](#components-object). It can be used from locations within steps or workflows in the Arazzo Description. **Note** - Input Objects MUST use standard JSON Schema referencing via the `$ref` keyword while all non JSON Schema objects use this object and its expression based referencing mechanism. ##### Fixed Fields Field Name | Type | Description ---|:---:|--- reference | `{expression}` | **REQUIRED**. A [runtime expression](#runtime-expressions) used to reference the desired object. value | `string` | Sets a value of the referenced parameter. This is only applicable for parameter object references. This object cannot be extended with additional properties and any properties added MUST be ignored. ##### Reusable Object Example ```yaml reference: $components.successActions.notify ``` ```json { "reference": "$components.successActions.notify" } ``` ```yaml reference: $components.parameters.page value: 1 ``` ```json { "reference": "$components.parameters.page", "value": 1 } ``` #### Criterion Object An object used to specify the context, conditions, and condition types that can be used to prove or satisfy assertions specified in [Step Object](#step-object) `successCriteria`, [Success Action Object](#success-action-object) `criteria`, and [Failure Action Object](#failure-action-object) `criteria`. There are four flavors of conditions supported: - simple - where basic literals, operators, and loose comparisons are used in combination with [Runtime Expressions](#runtime-expressions). - regex - where a regex pattern is applied on the supplied context. The context is defined by a [Runtime Expression](#runtime-expressions). - jsonpath - where a JSONPath expression is applied. The root node context is defined by a [Runtime Expression](#runtime-expressions). - xpath - where an XPath expression is applied. The root node context is defined by a [Runtime Expression](#runtime-expressions). ##### Literals As part of a condition expression, you can use `boolean`, `null`, `number`, or `string` data types. Type | Literal value ---|--- `boolean` | `true` or `false` `null` | `null` `number` | Any number format supported in [Data Types](#data-types) `string` | Strings MUST use single quotes (') around the string. To use a literal single quote, escape the literal single quote using an additional single quote (''). ##### Operators Operator | Description ---|--- `<`| Less than `<=`| Less than or equal `>`| Greater than `>=`| Greater than or equal `==`| Equal `!=`| Not equal `!`| Not `&&`| And \|\|| Or `()`| Logical Grouping `[]`| Index (0-based) `.`| Property de-reference String comparisons `MUST` be case insensitive. ##### Fixed Fields Field Name | Type | Description ---|:---:|--- context | `{expression}` | A [runtime expression](#runtime-expressions) used to set the context for the condition to be applied on. If `type` is specified, then the `context` MUST be provided (e.g. `$response.body` would set the context that a JSONPath query expression could be applied to). condition | `string` | **REQUIRED**. The condition to apply. Conditions can be simple (e.g. `$statusCode == 200` which applies an operator on a value obtained from a runtime expression), or a regex, or a JSONPath expression. For regex or JSONPath, the `type` and `context` MUST be specified. type | `string` \| [Criterion Expression Type Object](#criterion-expression-type-object) | The type of condition to be applied. If specified, the options allowed are `simple`, `regex`, `jsonpath` or `xpath`. If omitted, then the condition is assumed to be `simple`, which at most combines literals, operators and [Runtime Expressions](#runtime-expressions). If `jsonpath`, then the expression MUST conform to [JSONPath](https://tools.ietf.org/html/rfc9535). If `xpath` the expression MUST conform to [XML Path Language 3.1](https://www.w3.org/TR/xpath-31/#d2e24229). Should other variants of JSONPath or XPath be required, then a [Criterion Expression Type Object](#criterion-expression-type-object) MUST be specified. This object MAY be extended with [Specification Extensions](#specification-extensions). ##### Criterion Object Example **Simple Condition Example** ```yaml - condition: $statusCode == 200 ``` **Regex Condition Example** ```yaml - context: $statusCode condition: '^200$' type: regex ``` **JSONPath Condition Example** ```yaml - context: $response.body condition: $[?count(@.pets) > 0] type: jsonpath ``` #### Criterion Expression Type Object An object used to describe the type and version of an expression used within a [Criterion Object](#criterion-object). If this object is not defined, then the following defaults apply: - JSONPath as described by [RFC9535](https://tools.ietf.org/html/rfc9535) - XPath as described by [XML Path Language 3.1](https://www.w3.org/TR/xpath-31) Defining this object gives the ability to utilize tooling compatible with older versions of either JSONPath or XPath. ##### Fixed Fields Field Name | Type | Description ---|:---:|--- type | `string` | **REQUIRED**. The type of condition to be applied. The options allowed are `jsonpath` or `xpath`. version | `string` | **REQUIRED**. A short hand string representing the version of the expression type being used. The allowed values for JSONPath are `draft-goessner-dispatch-jsonpath-00`. The allowed values for XPath are `xpath-30`, `xpath-20`, or `xpath-10`. This object MAY be extended with [Specification Extensions](#specification-extensions). ##### Criterion Expression Type Example **JSONPath Example** ```yaml type: jsonpath version: draft-goessner-dispatch-jsonpath-00 ``` **XPath Example** ```yaml type: xpath version: xpath-30 ``` #### Request Body Object A single request body describing the `Content-Type` and request body content to be passed by a step to an operation. ##### Fixed Fields Field Name | Type | Description ---|:---:|--- contentType | `string` | The Content-Type for the request content. If omitted then refer to Content-Type specified at the targeted operation to understand serialization requirements. payload | Any | A value representing the request body payload. The value can be a literal value or can contain [Runtime Expressions](#runtime-expressions) which MUST be evaluated prior to calling the referenced operation. To represent examples of media types that cannot be naturally represented in JSON or YAML, use a string value to contain the example, escaping where necessary. replacements | [[Payload Replacement Object](#payload-replacement-object)] | A list of locations and values to set within a payload. This object MAY be extended with [Specification Extensions](#specification-extensions). ##### RequestBody Object Example **JSON Templated Example** ```yaml contentType: application/json payload: | { "petOrder": { "petId": "{$inputs.pet_id}", "couponCode": "{$inputs.coupon_code}", "quantity": "{$inputs.quantity}", "status": "placed", "complete": false } } ``` **JSON Object Example** ```yaml contentType: application/json payload: petOrder: petId: $inputs.pet_id couponCode: $inputs.coupon_code quantity: $inputs.quantity status: placed complete: false ``` **Complete Runtime Expression** ```yaml contentType: application/json payload: $inputs.petOrderRequest ``` **XML Templated Example** ```yaml contentType: application/xml payload: | {$inputs.pet_id} {$inputs.coupon_code} {$inputs.quantity} placed false ``` **Form Data Example** ```yaml contentType: application/x-www-form-urlencoded payload: client_id: $inputs.clientId grant_type: $inputs.grantType redirect_uri: $inputs.redirectUri client_secret: $inputs.clientSecret code: $steps.browser-authorize.outputs.code scope: $inputs.scope ``` **Form Data String Example** ```yaml contentType: application/x-www-form-urlencoded payload: "client_id={$inputs.clientId}&grant_type={$inputs.grantType}&redirect_uri={$inputs.redirectUri}&client_secret={$inputs.clientSecret}&code{$steps.browser-authorize.outputs.code}&scope=$inputs.scope}" ``` #### Payload Replacement Object Describes a location within a payload (e.g., a request body) and a value to set within the location. ##### Fixed Fields Field Name | Type | Description ---|:---:|--- target | `string` | **REQUIRED**. A [JSON Pointer](https://tools.ietf.org/html/rfc6901) or [XPath Expression](https://www.w3.org/TR/xpath-31/#id-expressions) which MUST be resolved against the request body. Used to identify the location to inject the `value`. value | Any \| {expression} | **REQUIRED**. The value set within the target location. The value can be a constant or a [Runtime Expression](#runtime-expressions) to be evaluated and passed to the referenced operation or workflow. This object MAY be extended with [Specification Extensions](#specification-extensions). ##### Payload Replacement Object Example **Runtime Expression Example** ```yaml target: /petId value: $inputs.pet_id ``` **Literal Example** ```yaml target: /quantity value: 10 ``` ### Runtime Expressions A runtime expression allows values to be defined based on information that will be available within an HTTP message, an event message, and within objects serialized from the Arazzo document such as [workflows](#workflow-object) or [steps](#step-object). The runtime expression is defined by the following [ABNF](https://tools.ietf.org/html/rfc5234) syntax: ```abnf expression = ( "$url" / "$method" / "$statusCode" / "$request." source / "$response." source / "$message." source / "$inputs." name / "$outputs." name / "$steps." name / "$workflows." name / "$sourceDescriptions." name / "$components." name / "$components.parameters." parameter-name) parameter-name = name ; Reuses 'name' rule for parameter names source = ( header-reference / query-reference / path-reference / body-reference ) header-reference = "header." token query-reference = "query." name path-reference = "path." name body-reference = "body" ["#" json-pointer ] json-pointer = *( "/" reference-token ) reference-token = *( unescaped / escaped ) unescaped = %x00-2E / %x30-7D / %x7F-10FFFF ; %x2F ('/') and %x7E ('~') are excluded from 'unescaped' escaped = "~" ( "0" / "1" ) ; representing '~' and '/', respectively name = *( CHAR ) token = 1*tchar tchar = "!" / "#" / "$" / "%" / "&" / "'" / "*" / "+" / "-" / "." / "^" / "_" / "`" / "|" / "~" / DIGIT / ALPHA ``` #### Examples Source Location | example expression | notes ---|:---|:---| HTTP Method | `$method` | The allowable values for the `$method` will be those for the HTTP operation. Requested media type | `$request.header.accept` | Request parameter | `$request.path.id` | Request parameters MUST be declared in the `parameters` section of the parent operation or they cannot be evaluated. This includes request headers. Request body property | `$request.body#/user/uuid` | In operations which accept payloads, references may be made to portions of the `requestBody` or the entire body. Request URL | `$url` | Response value | `$response.body#/status` | In operations which return payloads, references may be made to portions of the response body or the entire body. Response header | `$response.header.Server` | Single header values only are available workflow input | `$inputs.username` or `$workflows.foo.inputs.username` | Single input values only are available Step output value | `$steps.someStep.pets` | In situations where the output named property return payloads, references may be made to portions of the response body or the entire body. Workflow output value | `$outputs.bar` or `$workflows.foo.outputs.bar` | Single input values only are available Components parameter | `$components.parameters.foo` | Accesses a foo parameter defined within the Components Object. Runtime expressions preserve the type of the referenced value. Expressions can be embedded into string values by surrounding the expression with `{}` curly braces. ### Specification Extensions While the Arazzo Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points. The extension properties are implemented as patterned fields that are always prefixed by `"x-"`. Field Pattern | Type | Description ---|:---:|--- ^x- | Any | Allows extensions to the Arazzo Specification. The field name MUST begin with `x-`, for example, `x-internal-id`. Field names beginning `x-oai-`, `x-oas-`, and `x-arazzo` are reserved for uses defined by the [OpenAPI Initiative](https://www.openapis.org/). The value MAY be `null`, a primitive, an array or an object. The extensions may or may not be supported by the available tooling, but those may be extended as well to add requested support (if tools are internal or open-sourced). ## Security Considerations The Arazzo Specification does not enforce a security mechanism. Security is left to the implementer, though TLS, specifically HTTPS may be recommended for exchanging sensitive workflows. Arazzo Descriptions can be JSON or YAML values. As such, all security considerations defined in [RFC8259](https://tools.ietf.org/html/rfc8259) and within YAML version [1.2](https://yaml.org/spec/1.2/spec.html) apply. Arazzo Descriptions are frequently written by untrusted third parties, to be deployed on public Internet servers. Processing an Arazzo Description can cause both safe and unsafe operations to be performed on arbitrary network resources. It is the responsibility of the description consumer to ensure that the operations performed are not harmful. ## IANA Considerations The proposed MIME media types for the Arazzo Specification are described below. ### application/vnd.oai.workflows The default (or general) MIME type for Arazzo documents (e.g. workflows) is defined as follows:   Media type name: application   Media subtype name: vnd.oai.workflows   Required parameters: N/A   Optional parameters: version (e.g. version=1.0.0 to indicate that the type of workflow conforms to version 1.0.0 of the Arazzo Specification).   Encoding considerations: Encoding considerations are identical to those specified for the `application/json` and `application/yaml` media types, respectively.   Security considerations: See [security considerations](#security-considerations) above.   Interoperability considerations: N/A **Note:** When using the `application/vnd.oai.workflows` media type the consumer should be prepared to receive YAML formatted content ### application/vnd.oai.workflows+json The proposed MIME media type for Arazzo documents (e.g. workflows) that require a JSON-specific media type is defined as follows:   Media type name: application   Media subtype name: vnd.oai.workflows+json   Required parameters: N/A   Optional parameters: version (e.g. version=1.0.0 to indicate that the type of Arazzo document conforms to version 1.0.0 of the Arazzo Specification).   Encoding considerations: Encoding considerations are identical to those specified for the `application/json` media type.   Security considerations: See [security considerations](#security-considerations) above.   Interoperability considerations: N/A ### application/vnd.oai.workflows+yaml The proposed MIME media type for Arazzo documents (e.g. workflows) that require a YAML-specific media type is defined as follows:   Media type name: application   Media subtype name: vnd.oai.workflows+yaml   Required parameters: N/A   Optional parameters: version (e.g. version=1.0.0 to indicate that the type of Arazzo document conforms to version 1.0.0 of the Arazzo Specification).   Encoding considerations: Encoding considerations are identical to those specified for the `application/yaml` media type.   Security considerations: See [security considerations](#security-considerations) above.   Interoperability considerations: N/A ## Appendix A: Revision History Version | Date | Notes --- | --- | --- 1.0.0 | 2024-05-29 | First release of the Arazzo Specification ================================================ FILE: versions/1.0.1.md ================================================ # Arazzo Specification #### Version 1.0.1 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [BCP 14](https://tools.ietf.org/html/bcp14) [RFC2119](https://tools.ietf.org/html/rfc2119) [RFC8174](https://tools.ietf.org/html/rfc8174) when, and only when, they appear in all capitals, as shown here. This document is licensed under [The Apache License, Version 2.0](https://www.apache.org/licenses/LICENSE-2.0.html). ## Introduction Being able to express specific sequences of calls and articulate the dependencies between them to achieve a particular goal is desirable in the context of API descriptions. The aim of the Arazzo Specification is to provide a mechanism that can define sequences of calls and their dependencies to be woven together and expressed in the context of delivering a particular outcome or set of outcomes when dealing with API descriptions (such as OpenAPI descriptions). The Arazzo Specification can articulate these workflows in a human-readable and machine-readable manner, thus improving the capability of API specifications to tell the story of the API in a manner that can improve the consuming developer experience. ## Table of Contents - [Definitions](#definitions) - [Arazzo Description](#arazzo-description) - [Specification](#specification) - [Versions](#versions) - [Format](#format) - [Arazzo Description Structure](#arazzo-description-structure) - [Data Types](#data-types) - [Relative References in URLs](#relative-references-in-urls) - [Schema](#schema) - [Arazzo Specification Object](#arazzo-specification-object) - [Info Object](#info-object) - [Source Description Object](#source-description-object) - [Workflow Object](#workflow-object) - [Step Object](#step-object) - [Parameter Object](#parameter-object) - [Success Action Object](#success-action-object) - [Failure Action Object](#failure-action-object) - [Components Object](#components-object) - [Reusable Object](#reusable-object) - [Criterion Object](#criterion-object) - [Request Body Object](#request-body-object) - [Payload Replacement Object](#payload-replacement-object) - [Runtime Expressions](#runtime-expressions) - [Specification Extensions](#specification-extensions) - [Security Considerations](#security-considerations) - [IANA Considerations](#iana-considerations) - [Appendix A: Revision History](#appendix-a-revision-history) ## Definitions ##### Arazzo Description A self-contained document (or set of documents) which defines or describes API workflows (specific sequence of calls to achieve a particular goal in the context of an API definition). An Arazzo Description uses and conforms to the Arazzo Specification, and `MUST` contain a valid Arazzo Specification version field (`arazzo`), an [info](#info-object) field, a `sourceDescriptions` field with at least one defined [Source Description](#source-description-object), and there `MUST` be at least one [Workflow](#workflow-object) defined in the `workflows` fixed field. ## Specification ### Versions The Arazzo Specification is versioned using a `major`.`minor`.`patch` versioning scheme. The `major`.`minor` portion of the version string (for example 1.0) SHALL designate the Arazzo feature set. `.patch` versions address errors in, or provide clarifications to, this document, not the feature set. The patch version SHOULD NOT be considered by tooling, making no distinction between 1.0.0 and 1.0.1 for example. ### Format An Arazzo Description that conforms to the Arazzo Specification is itself a JSON object, which may be represented either in JSON or YAML format. All field names in the specification are **case sensitive**. This includes all fields that are used as keys in a map, except where explicitly noted that keys are **case insensitive**. In order to preserve the ability to round-trip between YAML and JSON formats, YAML version [1.2](https://yaml.org/spec/1.2/spec.html) is RECOMMENDED along with some additional constraints: - Tags MUST be limited to those allowed by the [JSON Schema ruleset](https://yaml.org/spec/1.2/spec.html#id2803231). - Keys used in YAML maps MUST be limited to a scalar string, as defined by the [YAML Failsafe schema ruleset](https://yaml.org/spec/1.2/spec.html#id2802346). ### Arazzo Description Structure It is RECOMMENDED that the entry Arazzo document be named: `arazzo.json` or `arazzo.yaml`. An Arazzo Description MAY be made up of a single document or be divided into multiple, connected parts at the discretion of the author. If workflows from other documents are being referenced, they MUST be included as a [Source Description Object](#source-description-object). In a multi-document description, the document containing the [Arazzo Specification Object](#arazzo-specification-object) is known as the **entry Arazzo document**. ### Data Types Data types in the Arazzo Specification are based on the types supported by the [JSON Schema Specification Draft 2020-12](https://tools.ietf.org/html/draft-bhutton-json-schema-00#section-4.2.1). Note that integer as a type is also supported and is defined as a JSON number without a fraction or exponent part. As defined by the [JSON Schema Validation vocabulary](https://tools.ietf.org/html/draft-bhutton-json-schema-validation-00#section-7), data types can have an optional modifier property: `format`. Arazzo additionally supports the formats (similar to the OpenAPI specification) to provide fine detail for primitive data types. The formats defined are: [`type`](#data-types) | `format` | Comments ------ | -------- | -------- `integer` | `int32` | signed 32 bits `integer` | `int64` | signed 64 bits (a.k.a long) `number` | `float` | | `number` | `double` | | `string` | `password` | A hint to UIs to obscure input. ### Relative References in URLs Unless specified otherwise, all properties that are URLs MAY be relative references as defined by [RFC3986](https://tools.ietf.org/html/rfc3986#section-4.2). Unless specified otherwise, relative references are resolved using the URL of the referring document. ### Schema In the following description, if a field is not explicitly **REQUIRED** or described with a MUST or SHALL, it can be considered OPTIONAL. #### Arazzo Specification Object This is the root object of the [Arazzo Description](#arazzo-description). ##### Fixed Fields Field Name | Type | Description ---|:---:|--- arazzo | `string` | **REQUIRED**. This string MUST be the [version number](#versions) of the Arazzo Specification that the Arazzo Description uses. The `arazzo` field MUST be used by tooling to interpret the Arazzo Description. info | [Info Object](#info-object) | **REQUIRED**. Provides metadata about the workflows contain within the Arazzo Description. The metadata MAY be used by tooling as required. sourceDescriptions | [[Source Description Object](#source-description-object)] | **REQUIRED**. A list of source descriptions (such as an OpenAPI description) this Arazzo Description SHALL apply to. The list MUST have at least one entry. workflows | [[Workflow Object](#workflow-object)] | **REQUIRED**. A list of workflows. The list MUST have at least one entry. components | [Components Object](#components-object) | An element to hold various schemas for the Arazzo Description. This object MAY be extended with [Specification Extensions](#specification-extensions). ##### Arazzo Specification Object Example ```yaml arazzo: 1.0.1 info: title: A pet purchasing workflow summary: This Arazzo Description showcases the workflow for how to purchase a pet through a sequence of API calls description: | This Arazzo Description walks you through the workflow and steps of `searching` for, `selecting`, and `purchasing` an available pet. version: 1.0.1 sourceDescriptions: - name: petStoreDescription url: https://github.com/swagger-api/swagger-petstore/blob/master/src/main/resources/openapi.yaml type: openapi workflows: - workflowId: loginUserAndRetrievePet summary: Login User and then retrieve pets description: This workflow lays out the steps to login a user and then retrieve pets inputs: type: object properties: username: type: string password: type: string steps: - stepId: loginStep description: This step demonstrates the user login step operationId: loginUser parameters: # parameters to inject into the loginUser operation (parameter name must be resolvable at the referenced operation and the value is determined using {expression} syntax) - name: username in: query value: $inputs.username - name: password in: query value: $inputs.password successCriteria: # assertions to determine step was successful - condition: $statusCode == 200 outputs: # outputs from this step tokenExpires: $response.header.X-Expires-After rateLimit: $response.header.X-Rate-Limit sessionToken: $response.body - stepId: getPetStep description: retrieve a pet by status from the GET pets endpoint operationPath: '{$sourceDescriptions.petstoreDescription.url}#/paths/~1pet~1findByStatus/get' parameters: - name: status in: query value: 'available' - name: Authorization in: header value: $steps.loginUser.outputs.sessionToken successCriteria: - condition: $statusCode == 200 outputs: # outputs from this step availablePets: $response.body outputs: available: $steps.getPetStep.outputs.availablePets ``` #### Info Object The object provides metadata about API workflows defined in this Arazzo document. The metadata MAY be used by the clients if needed. ##### Fixed Fields Field Name | Type | Description ---|:---:|--- title | `string` | **REQUIRED**. A human readable title of the Arazzo Description. summary | `string` | A short summary of the Arazzo Description. description | `string` | A description of the purpose of the workflows defined. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. version | `string` | **REQUIRED**. The version identifier of the Arazzo document (which is distinct from the [Arazzo Specification version](#versions)). This object MAY be extended with [Specification Extensions](#specification-extensions). ##### Info Object Example ```yaml title: A pet purchasing workflow summary: This workflow showcases how to purchase a pet through a sequence of API calls description: | This workflow walks you through the steps of searching for, selecting, and purchasing an available pet. version: 1.0.1 ``` #### Source Description Object Describes a source description (such as an OpenAPI description) that will be referenced by one or more workflows described within an Arazzo Description. An object storing a map between named description keys and location URLs to the source descriptions (such as an OpenAPI description) this Arazzo Description SHALL apply to. Each source location `string` MUST be in the form of a URI-reference as defined by [RFC3986](https://tools.ietf.org/html/rfc3986#section-4.1). ##### Fixed Fields Field Name | Type | Description ---|:---:|--- name | `string` | **REQUIRED**. A unique name for the source description. Tools and libraries MAY use the `name` to uniquely identify a source description, therefore, it is RECOMMENDED to follow common programming naming conventions. SHOULD conform to the regular expression `[A-Za-z0-9_\-]+`. url | `string` | **REQUIRED**. A URL to a source description to be used by a workflow. If a relative reference is used, it MUST be in the form of a URI-reference as defined by [RFC3986](https://tools.ietf.org/html/rfc3986#section-4.2). type | `string` | The type of source description. Possible values are `"openapi"` or `"arazzo"`. This object MAY be extended with [Specification Extensions](#specification-extensions). ##### Source Description Object Example ```yaml name: petStoreDescription url: https://github.com/swagger-api/swagger-petstore/blob/master/src/main/resources/openapi.yaml type: openapi ``` #### Workflow Object Describes the steps to be taken across one or more APIs to achieve an objective. The workflow object MAY define inputs needed in order to execute workflow steps, where the defined steps represent a call to an API operation or another workflow, and a set of outputs. ##### Fixed Fields Field Name | Type | Description ---|:---:|--- workflowId | `string` | **REQUIRED**. Unique string to represent the workflow. The id MUST be unique amongst all workflows described in the Arazzo Description. The `workflowId` value is **case-sensitive**. Tools and libraries MAY use the `workflowId` to uniquely identify a workflow, therefore, it is RECOMMENDED to follow common programming naming conventions. SHOULD conform to the regular expression `[A-Za-z0-9_\-]+`. summary | `string` | A summary of the purpose or objective of the workflow. description | `string` | A description of the workflow. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. inputs | `JSON Schema` | A JSON Schema 2020-12 object representing the input parameters used by this workflow. dependsOn | [`string`] | A list of workflows that MUST be completed before this workflow can be processed. Each value provided MUST be a `workflowId`. If the workflow depended on is defined within the current Workflow Document, then specify the `workflowId` of the relevant local workflow. If the workflow is defined in a separate Arazzo Document then the workflow MUST be defined in the `sourceDescriptions` and the `workflowId` MUST be specified using a [Runtime Expression](#runtime-expressions) (e.g., `$sourceDescriptions..`) to avoid ambiguity or potential clashes. steps | [[Step Object](#step-object)] | **REQUIRED**. An ordered list of steps where each step represents a call to an API operation or to another workflow. successActions | [[Success Action Object](#success-action-object) \| [Reusable Object](#reusable-object)] | A list of success actions that are applicable for all steps described under this workflow. These success actions can be overridden at the step level but cannot be removed there. If a Reusable Object is provided, it MUST link to success actions defined in the [components/successActions](#components-object) of the current Arazzo document. The list MUST NOT include duplicate success actions. failureActions | [[Failure Action Object](#failure-action-object) \| [Reusable Object](#reusable-object)] | A list of failure actions that are applicable for all steps described under this workflow. These failure actions can be overridden at the step level but cannot be removed there. If a Reusable Object is provided, it MUST link to failure actions defined in the [components/failureActions](#components-object) of the current Arazzo document. The list MUST NOT include duplicate failure actions. outputs | Map[`string`, {expression}] | A map between a friendly name and a dynamic output value. The name MUST use keys that match the regular expression: `^[a-zA-Z0-9\.\-_]+$`. parameters | [[Parameter Object](#parameter-object) \| [Reusable Object](#reusable-object)] | A list of parameters that are applicable for all steps described under this workflow. These parameters can be overridden at the step level but cannot be removed there. Each parameter MUST be passed to an operation or workflow as referenced by `operationId`, `operationPath`, or `workflowId` as specified within each step. If a Reusable Object is provided, it MUST link to a parameter defined in the [components/parameters](#components-object) of the current Arazzo document. The list MUST NOT include duplicate parameters. This object MAY be extended with [Specification Extensions](#specification-extensions). ##### Workflow Object Example ```yaml workflowId: loginUser summary: Login User description: This workflow lays out the steps to login a user inputs: type: object properties: username: type: string password: type: string steps: - stepId: loginStep description: This step demonstrates the user login step operationId: loginUser parameters: # parameters to inject into the loginUser operation (parameter name must be resolvable at the referenced operation and the value is determined using {expression} syntax) - name: username in: query value: $inputs.username - name: password in: query value: $inputs.password successCriteria: # assertions to determine step was successful - condition: $statusCode == 200 outputs: # outputs from this step tokenExpires: $response.header.X-Expires-After rateLimit: $response.header.X-Rate-Limit outputs: tokenExpires: $steps.loginStep.outputs.tokenExpires ``` #### Step Object Describes a single workflow step which MAY be a call to an API operation ([OpenAPI Operation Object](https://spec.openapis.org/oas/latest.html#operation-object)) or another [Workflow Object](#workflow-object). ##### Fixed Fields Field Name | Type | Description ---|:---:|--- description | `string` | A description of the step. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. stepId | `string` | **REQUIRED**. Unique string to represent the step. The `stepId` MUST be unique amongst all steps described in the workflow. The `stepId` value is **case-sensitive**. Tools and libraries MAY use the `stepId` to uniquely identify a workflow step, therefore, it is RECOMMENDED to follow common programming naming conventions. SHOULD conform to the regular expression `[A-Za-z0-9_\-]+`. operationId | `string` | The name of an existing, resolvable operation, as defined with a unique `operationId` and existing within one of the `sourceDescriptions`. The referenced operation will be invoked by this workflow step. If multiple (non `arazzo` type) `sourceDescriptions` are defined, then the `operationId` MUST be specified using a [Runtime Expression](#runtime-expressions) (e.g., `$sourceDescriptions..`) to avoid ambiguity or potential clashes. This field is mutually exclusive of the `operationPath` and `workflowId` fields respectively. operationPath | `string` | A reference to a [Source Description Object](#source-description-object) combined with a [JSON Pointer](https://tools.ietf.org/html/rfc6901) to reference an operation. This field is mutually exclusive of the `operationId` and `workflowId` fields respectively. The operation being referenced MUST be described within one of the `sourceDescriptions` descriptions. A [Runtime Expression](#runtime-expressions) syntax MUST be used to identify the source description document. If the referenced operation has an `operationId` defined then the `operationId` SHOULD be preferred over the `operationPath`. workflowId | `string` | The [workflowId](#fixed-fields-2) referencing an existing workflow within the Arazzo Description. If the referenced workflow is contained within an `arazzo` type `sourceDescription`, then the `workflowId` MUST be specified using a [Runtime Expression](#runtime-expressions) (e.g., `$sourceDescriptions..`) to avoid ambiguity or potential clashes. The field is mutually exclusive of the `operationId` and `operationPath` fields respectively. parameters | [[Parameter Object](#parameter-object) \| [Reusable Object](#reusable-object)] | A list of parameters that MUST be passed to an operation or workflow as referenced by `operationId`, `operationPath`, or `workflowId`. If a parameter is already defined at the [Workflow](#workflow-object), the new definition will override it but can never remove it. If a Reusable Object is provided, it MUST link to a parameter defined in the [components/parameters](#components-object) of the current Arazzo document. The list MUST NOT include duplicate parameters. requestBody | [Request Body Object](#request-body-object) | The request body to pass to an operation as referenced by `operationId` or `operationPath`. The `requestBody` is fully supported in HTTP methods where the HTTP 1.1 specification [RFC9110](https://tools.ietf.org/html/rfc9110#section-9.3) explicitly defines semantics for "content" like request bodies, such as within POST, PUT, and PATCH methods. For methods where the HTTP specification provides less clarity—such as GET, HEAD, and DELETE—the use of `requestBody` is permitted but does not have well-defined semantics. In these cases, its use SHOULD be avoided if possible. successCriteria | [[Criterion Object](#criterion-object)] | A list of assertions to determine the success of the step. Each assertion is described using a [Criterion Object](#criterion-object). All assertions `MUST` be satisfied for the step to be deemed successful. onSuccess | [[Success Action Object](#success-action-object) \| [Reusable Object](#reusable-object)] | An array of success action objects that specify what to do upon step success. If omitted, the next sequential step shall be executed as the default behavior. If multiple success actions have similar `criteria`, the first sequential action matching the criteria SHALL be the action executed. If a success action is already defined at the [Workflow](#workflow-object), the new definition will override it but can never remove it. If a Reusable Object is provided, it MUST link to a success action defined in the [components](#components-object) of the current Arazzo document. The list MUST NOT include duplicate success actions. onFailure | [[Failure Action Object](#failure-action-object) \| [Reusable Object](#reusable-object)] | An array of failure action objects that specify what to do upon step failure. If omitted, the default behavior is to break and return. If multiple failure actions have similar `criteria`, the first sequential action matching the criteria SHALL be the action executed. If a failure action is already defined at the [Workflow](#workflow-object), the new definition will override it but can never remove it. If a Reusable Object is provided, it MUST link to a failure action defined in the [components](#components-object) of the current Arazzo document. The list MUST NOT include duplicate failure actions. outputs | Map[`string`, {expression}] | A map between a friendly name and a dynamic output value defined using a [Runtime Expression](#runtime-expressions). The name MUST use keys that match the regular expression: `^[a-zA-Z0-9\.\-_]+$`. This object MAY be extended with [Specification Extensions](#specification-extensions). ##### Step Object Example **Single step** ```yaml stepId: loginStep description: This step demonstrates the user login step operationId: loginUser parameters: # parameters to inject into the loginUser operation (parameter name must be resolvable at the referenced operation and the value is determined using {expression} syntax) - name: username in: query value: $inputs.username - name: password in: query value: $inputs.password successCriteria: # assertions to determine step was successful - condition: $statusCode == 200 outputs: # outputs from this step tokenExpires: $response.header.X-Expires-After rateLimit: $response.header.X-Rate-Limit ``` **Multiple steps** ```yaml steps: - stepId: loginStep description: This step demonstrates the user login step operationId: loginUser parameters: # parameters to inject into the loginUser operation (parameter name must be resolvable at the referenced operation and the value is determined using {expression} syntax) - name: username in: query value: $inputs.username - name: password in: query value: $inputs.password successCriteria: # assertions to determine step was successful - condition: $statusCode == 200 outputs: # outputs from this step tokenExpires: $response.header.X-Expires-After rateLimit: $response.header.X-Rate-Limit sessionToken: $response.body - stepId: getPetStep description: retrieve a pet by status from the GET pets endpoint operationPath: '{$sourceDescriptions.petStoreDescription.url}#/paths/~1pet~1findByStatus/get' parameters: - name: status in: query value: 'available' - name: Authorization in: header value: $steps.loginUser.outputs.sessionToken successCriteria: - condition: $statusCode == 200 outputs: # outputs from this step availablePets: $response.body ``` #### Parameter Object Describes a single step parameter. A unique parameter is defined by the combination of a `name` and `in` fields. There are four possible locations specified by the `in` field: - path - Used together with OpenAPI style [Path Templating](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#path-templating), where the parameter value is actually part of the operation's URL. This does not include the host or base path of the API. For example, in `/items/{itemId}`, the path parameter is `itemId`. - query - Parameters that are appended to the URL. For example, in `/items?id=###`, the query parameter is `id`. - header - Custom headers that are expected as part of the request. Note that [RFC9110](https://tools.ietf.org/html/rfc9110#name-field-names) states field names (which includes header) are case-insensitive. - cookie - Used to pass a specific cookie value to the source API. ##### Fixed Fields Field Name | Type | Description ---|:---:|--- name | `string` | **REQUIRED**. The name of the parameter. Parameter names are _case sensitive_. in | `string` | The location of the parameter. Possible values are `"path"`, `"query"`, `"header"`, or `"cookie"`. When the step in context specifies a `workflowId`, then all parameters map to workflow inputs. In all other scenarios (e.g., a step specifies an `operationId`), the `in` field MUST be specified. value | Any \| {expression} | **REQUIRED**. The value to pass in the parameter. The value can be a constant or a [Runtime Expression](#runtime-expressions) to be evaluated and passed to the referenced operation or workflow. This object MAY be extended with [Specification Extensions](#specification-extensions). ##### Parameter Object Example **Query Example** ```yaml - name: username in: query value: $inputs.username ``` **Header Example** ```yaml - name: X-Api-Key in: header value: $inputs.x-api-key ``` #### Success Action Object A single success action which describes an action to take upon success of a workflow step. There are two possible values for the `type` field. - end - The workflow ends, and context returns to the caller with applicable outputs - goto - A one-way transfer of workflow control to the specified label (either a `workflowId` or `stepId`) ##### Fixed Fields Field Name | Type | Description ---|:---:|--- name | `string` | **REQUIRED**. The name of the success action. Names are _case sensitive_. type | `string` | **REQUIRED**. The type of action to take. Possible values are `"end"` or `"goto"`. workflowId | `string` | The [workflowId](#fixed-fields-2) referencing an existing workflow within the Arazzo Description to transfer to upon success of the step. This field is only relevant when the `type` field value is `"goto"`. If the referenced workflow is contained within an `arazzo` type `sourceDescription`, then the `workflowId` MUST be specified using a [Runtime Expression](#runtime-expressions) (e.g., `$sourceDescriptions..`) to avoid ambiguity or potential clashes. This field is mutually exclusive to `stepId`. stepId | `string` | The `stepId` to transfer to upon success of the step. This field is only relevant when the `type` field value is `"goto"`. The referenced `stepId` MUST be within the current workflow. This field is mutually exclusive to `workflowId`. criteria | [[Criterion Object](#criterion-object)] | A list of assertions to determine if this action SHALL be executed. Each assertion is described using a [Criterion Object](#criterion-object). All criteria assertions `MUST` be satisfied for the action to be executed. This object MAY be extended with [Specification Extensions](#specification-extensions). ##### Success Action Object Example ```yaml name: JoinWaitingList type: goto stepId: joinWaitingListStep criteria: # assertions to determine if this success action should be executed - context: $response.body condition: $[?count(@.pets) > 0] type: jsonpath ``` #### Failure Action Object A single failure action which describes an action to take upon failure of a workflow step. There are three possible values for the `type` field. - end - The workflow ends, and context returns to the caller with applicable outputs - retry - The current step will be retried. The retry will be constrained by the `retryAfter` and `retryLimit` fields. If a `stepId` or `workflowId` are specified, then the reference is executed and the context is returned, after which the current step is retried. - goto - A one-way transfer of workflow control to the specified label (either a `workflowId` or `stepId`) ##### Fixed Fields Field Name | Type | Description ---|:---:|--- name | `string` | **REQUIRED**. The name of the failure action. Names are _case sensitive_. type | `string` | **REQUIRED**. The type of action to take. Possible values are `"end"`, `"retry"`, or `"goto"`. workflowId | `string` | The [workflowId](#fixed-fields-2) referencing an existing workflow within the Arazzo Description to transfer to upon failure of the step. This field is only relevant when the `type` field value is `"goto"` or `"retry"`. If the referenced workflow is contained within an `arazzo` type `sourceDescription`, then the `workflowId` MUST be specified using a [Runtime Expression](#runtime-expressions) (e.g., `$sourceDescriptions..`) to avoid ambiguity or potential clashes. This field is mutually exclusive to `stepId`. When used with `"retry"`, context transfers back upon completion of the specified workflow. stepId | `string` | The `stepId` to transfer to upon failure of the step. This field is only relevant when the `type` field value is `"goto"` or `"retry"`. The referenced `stepId` MUST be within the current workflow. This field is mutually exclusive to `workflowId`. When used with `"retry"`, context transfers back upon completion of the specified step. retryAfter | `number` | A non-negative decimal indicating the seconds to delay after the step failure before another attempt SHALL be made. **Note:** if an HTTP [Retry-After](https://tools.ietf.org/html/rfc9110.html#name-retry-after) response header was returned to a step from a targeted operation, then it SHOULD overrule this particular field value. This field only applies when the `type` field value is `"retry"`. retryLimit | `integer` | A non-negative integer indicating how many attempts to retry the step MAY be attempted before failing the overall step. If not specified then a single retry SHALL be attempted. This field only applies when the `type` field value is `"retry"`. The `retryLimit` MUST be exhausted prior to executing subsequent failure actions. criteria | [[Criterion Object](#criterion-object)] | A list of assertions to determine if this action SHALL be executed. Each assertion is described using a [Criterion Object](#criterion-object). This object MAY be extended with [Specification Extensions](#specification-extensions). ##### Failure Action Object Example ```yaml name: retryStep type: retry retryAfter: 1 retryLimit: 5 criteria: # assertions to determine if this action should be executed - condition: $statusCode == 503 ``` #### Components Object Holds a set of reusable objects for different aspects of the Arazzo Specification. All objects defined within the components object will have no effect on the Arazzo Description unless they are explicitly referenced from properties outside the components object. Components are scoped to the Arazzo document they are defined in. For example, if a step defined in Arazzo document "A" references a workflow defined in Arazzo document "B", the components in "A" are not considered when evaluating the workflow referenced in "B". ##### Fixed Fields Field Name | Type | Description ---|:---|--- inputs | Map[`string`, `JSON Schema`] | An object to hold reusable JSON Schema objects to be referenced from workflow inputs. parameters | Map[`string`, [Parameter Object](#parameter-object)] | An object to hold reusable Parameter Objects successActions | Map[`string`, [Success Action Object](#success-action-object)] | An object to hold reusable Success Actions Objects. failureActions | Map[`string`, [Failure Action Object](#failure-action-object)] | An object to hold reusable Failure Actions Objects. This object MAY be extended with [Specification Extensions](#specification-extensions). All the fixed fields declared above are objects that MUST use keys that match the regular expression: `^[a-zA-Z0-9\.\-_]+$`. The key is used to refer to the input or parameter in other parts of the Workflow Description. Field Name Examples: ``` User User_1 User_Name user-name my.org.User ``` ##### Components Object Example ```yaml components: parameters: storeId: name: storeId in: header value: $inputs.x-store-id inputs: pagination: type: object properties: page: type: integer format: int32 pageSize: type: integer format: int32 failureActions: refreshToken: name: refreshExpiredToken type: retry retryAfter: 1 retryLimit: 5 workflowId: refreshTokenWorkflowId criteria: # assertions to determine if this action should be executed - condition: $statusCode == 401 ``` ```json "components": { "parameters": { "storeId": { "name": "storeId", "in": "header", "value": "$inputs.x-store-id" } }, "inputs": { "pagination": { "type": "object", "properties": { "page": { "type": "integer", "format": "int32" }, "pageSize": { "type": "integer", "format": "int32" } } } }, "failureActions": { "refreshToken": { "name": "refreshExpiredToken", "type": "retry", "retryAfter": 1, "retryLimit": 5, "workflowId": "refreshTokenWorkflowId", "criteria": [ { "condition": "{$statusCode == 401}" } ] } } } ``` #### Reusable Object A simple object to allow referencing of objects contained within the [Components Object](#components-object). It can be used from locations within steps or workflows in the Arazzo Description. **Note** - Input Objects MUST use standard JSON Schema referencing via the `$ref` keyword while all non JSON Schema objects use this object and its expression based referencing mechanism. ##### Fixed Fields Field Name | Type | Description ---|:---:|--- reference | `{expression}` | **REQUIRED**. A [Runtime Expression](#runtime-expressions) used to reference the desired object. value | `string` | Sets a value of the referenced parameter. This is only applicable for parameter object references. This object cannot be extended with additional properties and any properties added MUST be ignored. ##### Reusable Object Example ```yaml reference: $components.successActions.notify ``` ```json { "reference": "$components.successActions.notify" } ``` ```yaml reference: $components.parameters.page value: 1 ``` ```json { "reference": "$components.parameters.page", "value": 1 } ``` #### Criterion Object An object used to specify the context, conditions, and condition types that can be used to prove or satisfy assertions specified in [Step Object](#step-object) `successCriteria`, [Success Action Object](#success-action-object) `criteria`, and [Failure Action Object](#failure-action-object) `criteria`. There are four flavors of conditions supported: - simple - where basic literals, operators, and loose comparisons are used in combination with [Runtime Expressions](#runtime-expressions). - regex - where a regex pattern is applied on the supplied context. The context is defined by a [Runtime Expression](#runtime-expressions). - jsonpath - where a JSONPath expression is applied. The root node context is defined by a [Runtime Expression](#runtime-expressions). - xpath - where an XPath expression is applied. The root node context is defined by a [Runtime Expression](#runtime-expressions). ##### Literals As part of a condition expression, you can use `boolean`, `null`, `number`, or `string` data types. Type | Literal value ---|--- `boolean` | `true` or `false` `null` | `null` `number` | Any number format supported in [Data Types](#data-types) `string` | Strings MUST use single quotes (') around the string. To use a literal single quote, escape the literal single quote using an additional single quote (''). ##### Operators Operator | Description ---|--- `<`| Less than `<=`| Less than or equal `>`| Greater than `>=`| Greater than or equal `==`| Equal `!=`| Not equal `!`| Not `&&`| And \|\|| Or `()`| Logical Grouping `[]`| Index (0-based) `.`| Property de-reference String comparisons `MUST` be case insensitive. ##### Fixed Fields Field Name | Type | Description ---|:---:|--- context | `{expression}` | A [Runtime Expression](#runtime-expressions) used to set the context for the condition to be applied on. If `type` is specified, then the `context` MUST be provided (e.g. `$response.body` would set the context that a JSONPath query expression could be applied to). condition | `string` | **REQUIRED**. The condition to apply. Conditions can be simple (e.g. `$statusCode == 200` which applies an operator on a value obtained from a runtime expression), or a regex, or a JSONPath expression. For regex or JSONPath, the `type` and `context` MUST be specified. type | `string` \| [Criterion Expression Type Object](#criterion-expression-type-object) | The type of condition to be applied. If specified, the options allowed are `simple`, `regex`, `jsonpath` or `xpath`. If omitted, then the condition is assumed to be `simple`, which at most combines literals, operators and [Runtime Expressions](#runtime-expressions). If `jsonpath`, then the expression MUST conform to [JSONPath](https://tools.ietf.org/html/rfc9535). If `xpath` the expression MUST conform to [XML Path Language 3.1](https://www.w3.org/TR/xpath-31/#d2e24229). Should other variants of JSONPath or XPath be required, then a [Criterion Expression Type Object](#criterion-expression-type-object) MUST be specified. This object MAY be extended with [Specification Extensions](#specification-extensions). ##### Criterion Object Example **Simple Condition Example** ```yaml - condition: $statusCode == 200 ``` **Regex Condition Example** ```yaml - context: $statusCode condition: '^200$' type: regex ``` **JSONPath Condition Example** ```yaml - context: $response.body condition: $[?count(@.pets) > 0] type: jsonpath ``` #### Criterion Expression Type Object An object used to describe the type and version of an expression used within a [Criterion Object](#criterion-object). If this object is not defined, then the following defaults apply: - JSONPath as described by [RFC9535](https://tools.ietf.org/html/rfc9535) - XPath as described by [XML Path Language 3.1](https://www.w3.org/TR/xpath-31) Defining this object gives the ability to utilize tooling compatible with older versions of either JSONPath or XPath. ##### Fixed Fields Field Name | Type | Description ---|:---:|--- type | `string` | **REQUIRED**. The type of condition to be applied. The options allowed are `jsonpath` or `xpath`. version | `string` | **REQUIRED**. A short hand string representing the version of the expression type being used. The allowed values for JSONPath are `draft-goessner-dispatch-jsonpath-00`. The allowed values for XPath are `xpath-30`, `xpath-20`, or `xpath-10`. This object MAY be extended with [Specification Extensions](#specification-extensions). ##### Criterion Expression Type Example **JSONPath Example** ```yaml type: jsonpath version: draft-goessner-dispatch-jsonpath-00 ``` **XPath Example** ```yaml type: xpath version: xpath-30 ``` #### Request Body Object A single request body describing the `Content-Type` and request body content to be passed by a step to an operation. ##### Fixed Fields Field Name | Type | Description ---|:---:|--- contentType | `string` | The Content-Type for the request content. If omitted then refer to Content-Type specified at the targeted operation to understand serialization requirements. payload | Any | A value representing the request body payload. The value can be a literal value or can contain [Runtime Expressions](#runtime-expressions) which MUST be evaluated prior to calling the referenced operation. To represent examples of media types that cannot be naturally represented in JSON or YAML, use a string value to contain the example, escaping where necessary. replacements | [[Payload Replacement Object](#payload-replacement-object)] | A list of locations and values to set within a payload. This object MAY be extended with [Specification Extensions](#specification-extensions). ##### RequestBody Object Example **JSON Templated Example** ```yaml contentType: application/json payload: | { "petOrder": { "petId": "{$inputs.pet_id}", "couponCode": "{$inputs.coupon_code}", "quantity": "{$inputs.quantity}", "status": "placed", "complete": false } } ``` **JSON Object Example** ```yaml contentType: application/json payload: petOrder: petId: $inputs.pet_id couponCode: $inputs.coupon_code quantity: $inputs.quantity status: placed complete: false ``` **Complete Runtime Expression** ```yaml contentType: application/json payload: $inputs.petOrderRequest ``` **XML Templated Example** ```yaml contentType: application/xml payload: | {$inputs.pet_id} {$inputs.coupon_code} {$inputs.quantity} placed false ``` **Form Data Example** ```yaml contentType: application/x-www-form-urlencoded payload: client_id: $inputs.clientId grant_type: $inputs.grantType redirect_uri: $inputs.redirectUri client_secret: $inputs.clientSecret code: $steps.browser-authorize.outputs.code scope: $inputs.scope ``` **Form Data String Example** ```yaml contentType: application/x-www-form-urlencoded payload: "client_id={$inputs.clientId}&grant_type={$inputs.grantType}&redirect_uri={$inputs.redirectUri}&client_secret={$inputs.clientSecret}&code{$steps.browser-authorize.outputs.code}&scope=$inputs.scope}" ``` #### Payload Replacement Object Describes a location within a payload (e.g., a request body) and a value to set within the location. ##### Fixed Fields Field Name | Type | Description ---|:---:|--- target | `string` | **REQUIRED**. A [JSON Pointer](https://tools.ietf.org/html/rfc6901) or [XPath Expression](https://www.w3.org/TR/xpath-31/#id-expressions) which MUST be resolved against the request body. Used to identify the location to inject the `value`. value | Any \| {expression} | **REQUIRED**. The value set within the target location. The value can be a constant or a [Runtime Expression](#runtime-expressions) to be evaluated and passed to the referenced operation or workflow. This object MAY be extended with [Specification Extensions](#specification-extensions). ##### Payload Replacement Object Example **Runtime Expression Example** ```yaml target: /petId value: $inputs.pet_id ``` **Literal Example** ```yaml target: /quantity value: 10 ``` ### Runtime Expressions A runtime expression allows values to be defined based on information that will be available within the HTTP message in an actual API call, or within objects serialized from the Arazzo document such as [workflows](#workflow-object) or [steps](#step-object). The runtime expression is defined by the following [ABNF](https://tools.ietf.org/html/rfc5234) syntax: ```abnf expression = ( "$url" / "$method" / "$statusCode" / "$request." source / "$response." source / "$inputs." name / "$outputs." name / "$steps." name / "$workflows." name / "$sourceDescriptions." name / "$components." name / "$components.parameters." parameter-name) parameter-name = name ; Reuses 'name' rule for parameter names source = ( header-reference / query-reference / path-reference / body-reference ) header-reference = "header." token query-reference = "query." name path-reference = "path." name body-reference = "body" ["#" json-pointer ] json-pointer = *( "/" reference-token ) reference-token = *( unescaped / escaped ) unescaped = %x00-2E / %x30-7D / %x7F-10FFFF ; %x2F ('/') and %x7E ('~') are excluded from 'unescaped' escaped = "~" ( "0" / "1" ) ; representing '~' and '/', respectively name = *( CHAR ) token = 1*tchar tchar = "!" / "#" / "$" / "%" / "&" / "'" / "*" / "+" / "-" / "." / "^" / "_" / "`" / "|" / "~" / DIGIT / ALPHA ``` #### Examples Source Location | example expression | notes ---|:---|:---| HTTP Method | `$method` | The allowable values for the `$method` will be those for the HTTP operation. Requested media type | `$request.header.accept` | Request parameter | `$request.path.id` | Request parameters MUST be declared in the `parameters` section of the parent operation or they cannot be evaluated. This includes request headers. Request body property | `$request.body#/user/uuid` | In operations which accept payloads, references may be made to portions of the `requestBody` or the entire body. Request URL | `$url` | Response value | `$response.body#/status` | In operations which return payloads, references may be made to portions of the response body or the entire body. Response header | `$response.header.Server` | Single header values only are available workflow input | `$inputs.username` or `$workflows.foo.inputs.username` | Single input values only are available Step output value | `$steps.someStepId.outputs.pets` | In situations where the output named property return payloads, references may be made to portions of the response body (e.g., `$steps.someStepId.outputs.pets#/0/id`) or the entire body. Workflow output value | `$outputs.bar` or `$workflows.foo.outputs.bar` | In situations where the output named property return payloads, references may be made to portions of the response body (e.g., `$workflows.foo.outputs.mappedResponse#/name`) or the entire body. Components parameter | `$components.parameters.foo` | Accesses a foo parameter defined within the Components Object. Runtime expressions preserve the type of the referenced value. Expressions can be embedded into string values by surrounding the expression with `{}` curly braces. ### Specification Extensions While the Arazzo Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points. The extension properties are implemented as patterned fields that are always prefixed by `"x-"`. Field Pattern | Type | Description ---|:---:|--- ^x- | Any | Allows extensions to the Arazzo Specification. The field name MUST begin with `x-`, for example, `x-internal-id`. Field names beginning `x-oai-`, `x-oas-`, and `x-arazzo` are reserved for uses defined by the [OpenAPI Initiative](https://www.openapis.org/). The value MAY be `null`, a primitive, an array or an object. The extensions may or may not be supported by the available tooling, but those may be extended as well to add requested support (if tools are internal or open-sourced). ## Security Considerations The Arazzo Specification does not enforce a security mechanism. Security is left to the implementer, though TLS, specifically HTTPS may be recommended for exchanging sensitive workflows. Arazzo Descriptions can be JSON or YAML values. As such, all security considerations defined in [RFC8259](https://tools.ietf.org/html/rfc8259) and within YAML version [1.2](https://yaml.org/spec/1.2/spec.html) apply. Arazzo Descriptions are frequently written by untrusted third parties, to be deployed on public Internet servers. Processing an Arazzo Description can cause both safe and unsafe operations to be performed on arbitrary network resources. It is the responsibility of the description consumer to ensure that the operations performed are not harmful. ## IANA Considerations The proposed MIME media types for the Arazzo Specification are described below. ### application/vnd.oai.workflows The default (or general) MIME type for Arazzo documents (e.g. workflows) is defined as follows:   Media type name: application   Media subtype name: vnd.oai.workflows   Required parameters: N/A   Optional parameters: version (e.g. version=1.0.0 to indicate that the type of workflow conforms to version 1.0.0 of the Arazzo Specification).   Encoding considerations: Encoding considerations are identical to those specified for the `application/json` and `application/yaml` media types, respectively.   Security considerations: See [security considerations](#security-considerations) above.   Interoperability considerations: N/A **Note:** When using the `application/vnd.oai.workflows` media type the consumer should be prepared to receive YAML formatted content ### application/vnd.oai.workflows+json The proposed MIME media type for Arazzo documents (e.g. workflows) that require a JSON-specific media type is defined as follows:   Media type name: application   Media subtype name: vnd.oai.workflows+json   Required parameters: N/A   Optional parameters: version (e.g. version=1.0.0 to indicate that the type of Arazzo document conforms to version 1.0.0 of the Arazzo Specification).   Encoding considerations: Encoding considerations are identical to those specified for the `application/json` media type.   Security considerations: See [security considerations](#security-considerations) above.   Interoperability considerations: N/A ### application/vnd.oai.workflows+yaml The proposed MIME media type for Arazzo documents (e.g. workflows) that require a YAML-specific media type is defined as follows:   Media type name: application   Media subtype name: vnd.oai.workflows+yaml   Required parameters: N/A   Optional parameters: version (e.g. version=1.0.0 to indicate that the type of Arazzo document conforms to version 1.0.0 of the Arazzo Specification).   Encoding considerations: Encoding considerations are identical to those specified for the `application/yaml` media type.   Security considerations: See [security considerations](#security-considerations) above.   Interoperability considerations: N/A ## Appendix A: Revision History Version | Date | Notes --- | --- | --- 1.0.1 | 2025-01-16 | Patch release of the Arazzo Specification 1.0.1 1.0.0 | 2024-05-29 | First release of the Arazzo Specification