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

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

`;\n preface += `

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

`;\n preface += `

${abstract}

`;\n 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).';\n preface += '
';\n preface += '
';\n preface += '

Status of This Document

';\n preface += 'The source-of-truth for the specification is the GitHub markdown file referenced above.';\n preface += '
';\n }\n else {\n preface += '';\n }\n return preface;\n}\n\nfunction doMaintainers() {\n let m = fs.readFileSync(argv.maintainers,'utf8');\n let h = md.render(m);\n let $ = cheerio.load(h);\n let u = $('ul').first();\n $(u).children('li').each(function(e){\n let t = $(this).text().split('@')[0];\n maintainers.push({name:t});\n });\n if ($(\"ul\").length < 2) return;\n u = $(\"ul\").last();\n $(u).children('li').each(function(e){\n let t = $(this).text().split('@')[0];\n emeritus.push({name:t});\n });\n}\n\nfunction getPublishDate(m) {\n let result = new Date();\n let h = md.render(m);\n let $ = cheerio.load(h);\n $('table').each(function(i,table){\n const h = $(table).find('th');\n const headers = [];\n $(h).each(function(i,header){\n headers.push($(header).text());\n });\n if (headers.length >= 2 && headers[0] === 'Version' && headers[1] === 'Date') {\n let c = $(table).find('tr').find('td');\n let v = $(c[0]).text();\n let d = $(c[1]).text();\n argv.subtitle = v;\n if (d !== 'TBA') result = new Date(d);\n }\n });\n return result;\n}\n\nif (argv.maintainers) {\n doMaintainers();\n}\n\nlet s = fs.readFileSync(argv._[0],'utf8');\n\nif (argv.respec) {\n argv.publishDate = getPublishDate(s);\n}\n\nlet lines = s.split(/\\r?\\n/);\n\nlet prevHeading = 0;\nlet lastIndent = 0;\nlet inTOC = false;\nlet inDefs = false;\nlet inCodeBlock = false;\nlet bsFix = true;\n\nlet indents = [0];\n\n// process the markdown\nfor (let l in lines) {\n let line = lines[l];\n let linkTarget;\n\n if (line.startsWith('## Table of Contents')) inTOC = true;\n if (line.startsWith('\n## Table of Contents\n\n- [Definitions](#definitions)\n - [Arazzo Description](#arazzo-description)\n- [Specification](#specification)\n - [Versions](#versions)\n - [Format](#format)\n - [Arazzo Description Structure](#arazzo-description-structure)\n - [Data Types](#data-types)\n - [Relative References in URLs](#relative-references-in-urls)\n - [Schema](#schema)\n - [Arazzo Specification Object](#arazzo-specification-object)\n - [Info Object](#info-object)\n - [Source Description Object](#source-description-object)\n - [Workflow Object](#workflow-object)\n - [Step Object](#step-object)\n - [Parameter Object](#parameter-object)\n - [Success Action Object](#success-action-object)\n - [Failure Action Object](#failure-action-object)\n - [Components Object](#components-object)\n - [Reusable Object](#reusable-object)\n - [Criterion Object](#criterion-object)\n - [Request Body Object](#request-body-object)\n - [Payload Replacement Object](#payload-replacement-object)\n - [Runtime Expressions](#runtime-expressions)\n - [Specification Extensions](#specification-extensions)\n - [Security Considerations](#security-considerations)\n - [IANA Considerations](#iana-considerations)\n- [Appendix A: Revision History](#appendix-a-revision-history)\n\n\n## Definitions\n\n##### Arazzo Description\nA 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.\n\n## Specification\n\n### Versions\n\nThe 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.\n\n### Format\n\nAn Arazzo Description that conforms to the Arazzo Specification is itself a JSON object, which may be represented either in JSON or YAML format.\n\nAll field names in the specification are **case sensitive**.\nThis includes all fields that are used as keys in a map, except where explicitly noted that keys are **case insensitive**.\n\nIn 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:\n\n- Tags MUST be limited to those allowed by the [JSON Schema ruleset](https://yaml.org/spec/1.2/spec.html#id2803231).\n- 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).\n\n### Arazzo Description Structure\n\nIt is RECOMMENDED that the entry Arazzo document be named: `arazzo.json` or `arazzo.yaml`.\n\nAn 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**. \n\n### Data Types\n\nData 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.\n\nAs 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.\n\nThe formats defined are:\n[`type`](#data-types) | `format` | Comments\n------ | -------- | --------\n`integer` | `int32` | signed 32 bits\n`integer` | `int64` | signed 64 bits (a.k.a long)\n`number` | `float` | |\n`number` | `double` | |\n`string` | `password` | A hint to UIs to obscure input.\n\n\n### Relative References in URLs\n\nUnless specified otherwise, all properties that are URLs MAY be relative references as defined by [RFC3986](https://tools.ietf.org/html/rfc3986#section-4.2).\nUnless specified otherwise, relative references are resolved using the URL of the referring document.\n\n### Schema\n\nIn the following description, if a field is not explicitly **REQUIRED** or described with a MUST or SHALL, it can be considered OPTIONAL.\n\n#### Arazzo Specification Object\n\nThis is the root object of the [Arazzo Description](#arazzo-description).\n\n##### Fixed Fields\n\nField Name | Type | Description\n---|:---:|---\narazzo | `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.\ninfo | [Info Object](#info-object) | **REQUIRED**. Provides metadata about the workflows contain within the Arazzo Description. The metadata MAY be used by tooling as required.\nsourceDescriptions | [[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.\nworkflows | [[Workflow Object](#workflow-object)] | **REQUIRED**. A list of workflows. The list MUST have at least one entry.\ncomponents | [Components Object](#components-object) | An element to hold various schemas for the Arazzo Description.\n\nThis object MAY be extended with [Specification Extensions](#specification-extensions).\n\n##### Arazzo Specification Object Example\n\n```yaml\narazzo: 1.0.0\ninfo:\n title: A pet purchasing workflow\n summary: This Arazzo Description showcases the workflow for how to purchase a pet through a sequence of API calls\n description: |\n This Arazzo Description walks you through the workflow and steps of `searching` for, `selecting`, and `purchasing` an available pet.\n version: 1.0.1\nsourceDescriptions:\n- name: petStoreDescription\n url: https://github.com/swagger-api/swagger-petstore/blob/master/src/main/resources/openapi.yaml\n type: openapi\n\nworkflows:\n- workflowId: loginUserAndRetrievePet\n summary: Login User and then retrieve pets\n description: This workflow lays out the steps to login a user and then retrieve pets\n inputs:\n type: object\n properties:\n username:\n type: string\n password:\n type: string\n steps:\n - stepId: loginStep\n description: This step demonstrates the user login step\n operationId: loginUser\n parameters:\n # parameters to inject into the loginUser operation (parameter name must be resolvable at the referenced operation and the value is determined using {expression} syntax)\n - name: username\n in: query\n value: $inputs.username\n - name: password\n in: query\n value: $inputs.password\n successCriteria:\n # assertions to determine step was successful\n - condition: $statusCode == 200\n outputs:\n # outputs from this step\n tokenExpires: $response.header.X-Expires-After\n rateLimit: $response.header.X-Rate-Limit\n sessionToken: $response.body\n - stepId: getPetStep\n description: retrieve a pet by status from the GET pets endpoint\n operationPath: '{$sourceDescriptions.petstoreDescription.url}#/paths/~1pet~1findByStatus/get'\n parameters:\n - name: status\n in: query\n value: 'available'\n - name: Authorization\n in: header\n value: $steps.loginUser.outputs.sessionToken\n successCriteria:\n - condition: $statusCode == 200\n outputs:\n # outputs from this step\n availablePets: $response.body\n outputs:\n available: $steps.getPetStep.availablePets\n```\n\n#### Info Object\n\nThe object provides metadata about API workflows defined in this Arazzo document.\nThe metadata MAY be used by the clients if needed.\n\n##### Fixed Fields\n\nField Name | Type | Description\n---|:---:|---\ntitle | `string` | **REQUIRED**. A human readable title of the Arazzo Description.\nsummary | `string` | A short summary of the Arazzo Description.\ndescription | `string` | A description of the purpose of the workflows defined. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.\nversion | `string` | **REQUIRED**. The version identifier of the Arazzo document (which is distinct from the [Arazzo Specification version](#versions)).\n\n\nThis object MAY be extended with [Specification Extensions](#specification-extensions).\n\n##### Info Object Example\n\n```yaml\ntitle: A pet purchasing workflow\nsummary: This workflow showcases how to purchase a pet through a sequence of API calls\ndescription: |\n This workflow walks you through the steps of searching for, selecting, and purchasing an available pet.\nversion: 1.0.1\n```\n\n#### Source Description Object\n\nDescribes a source description (such as an OpenAPI description) that will be referenced by one or more workflows described within an Arazzo Description.\n\nAn 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).\n\n##### Fixed Fields\n\nField Name | Type | Description\n---|:---:|---\nname | `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_\\-]+`.\nurl | `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).\ntype | `string` | The type of source description. Possible values are `\"openapi\"` or `\"arazzo\"`.\n\n\nThis object MAY be extended with [Specification Extensions](#specification-extensions).\n\n##### Source Description Object Example\n\n```yaml\nname: petStoreDescription\nurl: https://github.com/swagger-api/swagger-petstore/blob/master/src/main/resources/openapi.yaml\ntype: openapi\n```\n\n#### Workflow Object\n\nDescribes 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.\n\n##### Fixed Fields\n\nField Name | Type | Description\n---|:---:|---\nworkflowId | `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_\\-]+`.\nsummary | `string` | A summary of the purpose or objective of the workflow.\ndescription | `string` | A description of the workflow. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.\ninputs | `JSON Schema` | A JSON Schema 2020-12 object representing the input parameters used by this workflow.\ndependsOn | [`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.\nsteps | [[Step Object](#step-object)] | **REQUIRED**. An ordered list of steps where each step represents a call to an API operation or to another workflow.\nsuccessActions | [[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.\nfailureActions | [[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.\noutputs | 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\\.\\-_]+$`.\nparameters | [[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.\n\n\nThis object MAY be extended with [Specification Extensions](#specification-extensions).\n\n##### Workflow Object Example\n\n```yaml\nworkflowId: loginUser\nsummary: Login User\ndescription: This workflow lays out the steps to login a user\ninputs:\n type: object\n properties:\n username:\n type: string\n password:\n type: string\nsteps:\n - stepId: loginStep\n description: This step demonstrates the user login step\n operationId: loginUser\n parameters:\n # parameters to inject into the loginUser operation (parameter name must be resolvable at the referenced operation and the value is determined using {expression} syntax)\n - name: username\n in: query\n value: $inputs.username\n - name: password\n in: query\n value: $inputs.password\n successCriteria:\n # assertions to determine step was successful \n - condition: $statusCode == 200\n outputs:\n # outputs from this step\n tokenExpires: $response.header.X-Expires-After\n rateLimit: $response.header.X-Rate-Limit\noutputs:\n tokenExpires: $steps.loginStep.outputs.tokenExpires\n```\n\n#### Step Object\n\nDescribes 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)).\n\n##### Fixed Fields\n\nField Name | Type | Description\n---|:---:|---\ndescription | `string` | A description of the step. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.\nstepId | `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_\\-]+`.\noperationId | `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.\noperationPath | `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`.\nworkflowId | `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.\nparameters | [[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.\nrequestBody | [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.\nsuccessCriteria | [[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.\nonSuccess | [[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.\nonFailure | [[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.\noutputs | 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\\.\\-_]+$`.\n\nThis object MAY be extended with [Specification Extensions](#specification-extensions).\n\n##### Step Object Example\n\n**Single step**\n\n```yaml\nstepId: loginStep\ndescription: This step demonstrates the user login step\noperationId: loginUser\nparameters:\n # parameters to inject into the loginUser operation (parameter name must be resolvable at the referenced operation and the value is determined using {expression} syntax)\n - name: username\n in: query\n value: $inputs.username\n - name: password\n in: query\n value: $inputs.password\nsuccessCriteria:\n # assertions to determine step was successful\n - condition: $statusCode == 200\noutputs:\n # outputs from this step\n tokenExpires: $response.header.X-Expires-After\n rateLimit: $response.header.X-Rate-Limit\n```\n\n**Multiple steps**\n\n```yaml\nsteps:\n - stepId: loginStep\n description: This step demonstrates the user login step\n operationId: loginUser\n parameters:\n # parameters to inject into the loginUser operation (parameter name must be resolvable at the referenced operation and the value is determined using {expression} syntax)\n - name: username\n in: query\n value: $inputs.username\n - name: password\n in: query\n value: $inputs.password\n successCriteria:\n # assertions to determine step was successful\n - condition: $statusCode == 200\n outputs:\n # outputs from this step\n tokenExpires: $response.header.X-Expires-After\n rateLimit: $response.header.X-Rate-Limit\n sessionToken: $response.body\n - stepId: getPetStep\n description: retrieve a pet by status from the GET pets endpoint\n operationPath: '{$sourceDescriptions.petStoreDescription.url}#/paths/~1pet~1findByStatus/get'\n parameters:\n - name: status\n in: query\n value: 'available'\n - name: Authorization\n in: header\n value: $steps.loginUser.outputs.sessionToken\n successCriteria:\n - condition: $statusCode == 200\n outputs:\n # outputs from this step\n availablePets: $response.body\n```\n\n#### Parameter Object\n\nDescribes 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:\n - 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.\n - query - Parameters that are appended to the URL. For example, in `/items?id=###`, the query parameter is `id`.\n - 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.\n - cookie - Used to pass a specific cookie value to the source API.\n\n##### Fixed Fields\nField Name | Type | Description\n---|:---:|---\n name | `string` | **REQUIRED**. The name of the parameter. Parameter names are _case sensitive_.\n 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.\n 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.\n\nThis object MAY be extended with [Specification Extensions](#specification-extensions).\n\n##### Parameter Object Example\n**Query Example**\n\n```yaml\n- name: username\n in: query\n value: $inputs.username\n```\n\n**Header Example**\n\n```yaml\n- name: X-Api-Key\n in: header\n value: $inputs.x-api-key\n```\n\n#### Success Action Object\n\nA single success action which describes an action to take upon success of a workflow step. There are two possible values for the `type` field.\n - end - The workflow ends, and context returns to the caller with applicable outputs\n - goto - A one-way transfer of workflow control to the specified label (either a `workflowId` or `stepId`)\n\n##### Fixed Fields\nField Name | Type | Description\n---|:---:|---\n name | `string` | **REQUIRED**. The name of the success action. Names are _case sensitive_.\n type | `string` | **REQUIRED**. The type of action to take. Possible values are `\"end\"` or `\"goto\"`.\n 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`.\n 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`.\n 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.\n\n\n\nThis object MAY be extended with [Specification Extensions](#specification-extensions).\n\n##### Success Action Object Example\n\n```yaml\nname: JoinWaitingList\ntype: goto\nstepId: joinWaitingListStep\ncriteria:\n # assertions to determine if this success action should be executed\n - context: $response.body\n condition: $[?count(@.pets) > 0]\n type: jsonpath\n```\n\n#### Failure Action Object\n\nA single failure action which describes an action to take upon failure of a workflow step. There are three possible values for the `type` field.\n - end - The workflow ends, and context returns to the caller with applicable outputs\n - 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.\n - goto - A one-way transfer of workflow control to the specified label (either a `workflowId` or `stepId`)\n\n##### Fixed Fields\nField Name | Type | Description\n---|:---:|---\n name | `string` | **REQUIRED**. The name of the failure action. Names are _case sensitive_.\n type | `string` | **REQUIRED**. The type of action to take. Possible values are `\"end\"`, `\"retry\"`, or `\"goto\"`.\n 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.\n 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.\n 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\"`.\n 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.\n 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).\n\n\nThis object MAY be extended with [Specification Extensions](#specification-extensions).\n\n##### Failure Action Object Example\n\n```yaml\nname: retryStep\ntype: retry\nretryAfter: 1\nretryLimit: 5\ncriteria:\n # assertions to determine if this action should be executed\n - condition: $statusCode == 503\n```\n\n#### Components Object\n\nHolds 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.\n\nComponents 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\".\n\n##### Fixed Fields\n\nField Name | Type | Description\n---|:---|---\n inputs | Map[`string`, `JSON Schema`] | An object to hold reusable JSON Schema objects to be referenced from workflow inputs.\nparameters | Map[`string`, [Parameter Object](#parameter-object)] | An object to hold reusable Parameter Objects\nsuccessActions | Map[`string`, [Success Action Object](#success-action-object)] | An object to hold reusable Success Actions Objects.\nfailureActions | Map[`string`, [Failure Action Object](#failure-action-object)] | An object to hold reusable Failure Actions Objects.\n\nThis object MAY be extended with [Specification Extensions](#specification-extensions).\n\n\nAll 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.\n\nField Name Examples:\n\n```\nUser\nUser_1\nUser_Name\nuser-name\nmy.org.User\n```\n\n##### Components Object Example\n\n```yaml\ncomponents:\n parameters:\n storeId:\n name: storeId\n in: header\n value: $inputs.x-store-id\n inputs:\n pagination:\n type: object\n properties:\n page:\n type: integer\n format: int32\n pageSize:\n type: integer\n format: int32\n failureActions:\n refreshToken:\n name: refreshExpiredToken\n type: retry\n retryAfter: 1\n retryLimit: 5\n workflowId: refreshTokenWorkflowId\n criteria:\n # assertions to determine if this action should be executed\n - condition: $statusCode == 401 \n```\n\n```json\n\"components\": {\n \"parameters\": {\n \"storeId\": {\n \"name\": \"storeId\",\n \"in\": \"header\",\n \"value\": \"$inputs.x-store-id\"\n }\n },\n \"inputs\": {\n \"pagination\": {\n \"type\": \"object\",\n \"properties\": {\n \"page\": {\n \"type\": \"integer\",\n \"format\": \"int32\"\n },\n \"pageSize\": {\n \"type\": \"integer\",\n \"format\": \"int32\"\n }\n }\n }\n },\n \"failureActions\": {\n \"refreshToken\": {\n \"name\": \"refreshExpiredToken\",\n \"type\": \"retry\",\n \"retryAfter\": 1,\n \"retryLimit\": 5,\n \"workflowId\": \"refreshTokenWorkflowId\",\n \"criteria\": [\n {\n \"condition\": \"{$statusCode == 401}\"\n }\n ]\n }\n }\n}\n```\n\n#### Reusable Object\n\nA 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.\n\n\n##### Fixed Fields\nField Name | Type | Description\n---|:---:|---\nreference | `{expression}` | **REQUIRED**. A [runtime expression](#runtime-expressions) used to reference the desired object.\nvalue | `string` | Sets a value of the referenced parameter. This is only applicable for parameter object references.\n\nThis object cannot be extended with additional properties and any properties added MUST be ignored.\n\n##### Reusable Object Example\n\n```yaml\n reference: $components.successActions.notify\n```\n\n```json\n {\n \"reference\": \"$components.successActions.notify\"\n }\n```\n\n```yaml\n reference: $components.parameters.page\n value: 1\n```\n\n```json\n {\n \"reference\": \"$components.parameters.page\",\n \"value\": 1\n }\n```\n\n#### Criterion Object\n\nAn 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`.\n\nThere are four flavors of conditions supported:\n- simple - where basic literals, operators, and loose comparisons are used in combination with [Runtime Expressions](#runtime-expressions).\n- regex - where a regex pattern is applied on the supplied context. The context is defined by a [Runtime Expression](#runtime-expressions).\n- jsonpath - where a JSONPath expression is applied. The root node context is defined by a [Runtime Expression](#runtime-expressions).\n- xpath - where an XPath expression is applied. The root node context is defined by a [Runtime Expression](#runtime-expressions).\n\n##### Literals\nAs part of a condition expression, you can use `boolean`, `null`, `number`, or `string` data types.\n\nType | Literal value\n---|---\n`boolean` | `true` or `false`\n`null` | `null`\n`number` | Any number format supported in [Data Types](#data-types)\n`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 ('').\n\n##### Operators\nOperator | Description\n---|---\n`<`| Less than\n`<=`| Less than or equal\n`>`| Greater than\n`>=`| Greater than or equal\n`==`| Equal\n`!=`| Not equal\n`!`| Not\n`&&`| And\n\\|\\|| Or\n`()`| Logical Grouping\n`[]`| Index (0-based)\n`.`| Property de-reference\n\nString comparisons `MUST` be case insensitive.\n\n##### Fixed Fields\nField Name | Type | Description\n---|:---:|---\ncontext | `{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).\ncondition | `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.\ntype | `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.\n\n\nThis object MAY be extended with [Specification Extensions](#specification-extensions).\n\n##### Criterion Object Example\n\n**Simple Condition Example**\n\n```yaml\n- condition: $statusCode == 200\n```\n\n**Regex Condition Example**\n```yaml\n- context: $statusCode\n condition: '^200$'\n type: regex\n```\n\n**JSONPath Condition Example**\n```yaml\n- context: $response.body\n condition: $[?count(@.pets) > 0]\n type: jsonpath\n```\n\n#### Criterion Expression Type Object\n\nAn 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:\n - JSONPath as described by [RFC9535](https://tools.ietf.org/html/rfc9535)\n - XPath as described by [XML Path Language 3.1](https://www.w3.org/TR/xpath-31)\n\nDefining this object gives the ability to utilize tooling compatible with older versions of either JSONPath or XPath.\n\n##### Fixed Fields\nField Name | Type | Description\n---|:---:|---\ntype | `string` | **REQUIRED**. The type of condition to be applied. The options allowed are `jsonpath` or `xpath`. \nversion | `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`.\n\nThis object MAY be extended with [Specification Extensions](#specification-extensions).\n\n##### Criterion Expression Type Example\n\n**JSONPath Example**\n```yaml\n type: jsonpath\n version: draft-goessner-dispatch-jsonpath-00\n```\n\n**XPath Example**\n```yaml\n type: xpath\n version: xpath-30\n```\n\n#### Request Body Object\n\nA single request body describing the `Content-Type` and request body content to be passed by a step to an operation.\n\n##### Fixed Fields\nField Name | Type | Description\n---|:---:|---\ncontentType | `string` | The Content-Type for the request content. If omitted then refer to Content-Type specified at the targeted operation to understand serialization requirements.\npayload | 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.\nreplacements | [[Payload Replacement Object](#payload-replacement-object)] | A list of locations and values to set within a payload.\n\nThis object MAY be extended with [Specification Extensions](#specification-extensions).\n\n##### RequestBody Object Example\n\n**JSON Templated Example**\n```yaml\n contentType: application/json\n payload: |\n {\n \"petOrder\": {\n \"petId\": \"{$inputs.pet_id}\",\n \"couponCode\": \"{$inputs.coupon_code}\",\n \"quantity\": \"{$inputs.quantity}\",\n \"status\": \"placed\",\n \"complete\": false\n }\n }\n```\n\n**JSON Object Example**\n```yaml\n contentType: application/json\n payload: \n petOrder:\n petId: $inputs.pet_id\n couponCode: $inputs.coupon_code\n quantity: $inputs.quantity\n status: placed\n complete: false\n```\n\n**Complete Runtime Expression**\n```yaml\n contentType: application/json\n payload: $inputs.petOrderRequest\n```\n\n**XML Templated Example**\n```yaml\n contentType: application/xml\n payload: |\n \n {$inputs.pet_id}\n {$inputs.coupon_code}\n {$inputs.quantity}\n placed\n false\n \n```\n\n**Form Data Example**\n```yaml\n contentType: application/x-www-form-urlencoded\n payload: \n client_id: $inputs.clientId\n grant_type: $inputs.grantType\n redirect_uri: $inputs.redirectUri\n client_secret: $inputs.clientSecret\n code: $steps.browser-authorize.outputs.code\n scope: $inputs.scope \n``` \n\n**Form Data String Example**\n```yaml\n contentType: application/x-www-form-urlencoded\n 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}\"\n```\n\n#### Payload Replacement Object\nDescribes a location within a payload (e.g., a request body) and a value to set within the location. \n\n##### Fixed Fields\nField Name | Type | Description\n---|:---:|---\ntarget | `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`.\n 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.\n\nThis object MAY be extended with [Specification Extensions](#specification-extensions).\n\n##### Payload Replacement Object Example\n\n**Runtime Expression Example**\n```yaml\n target: /petId\n value: $inputs.pet_id\n```\n\n**Literal Example**\n```yaml\n target: /quantity\n value: 10\n```\n\n\n### Runtime Expressions\nA 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).\n\nThe runtime expression is defined by the following [ABNF](https://tools.ietf.org/html/rfc5234) syntax:\n\n```abnf\n 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)\n parameter-name = name ; Reuses 'name' rule for parameter names\n source = ( header-reference / query-reference / path-reference / body-reference )\n header-reference = \"header.\" token\n query-reference = \"query.\" name\n path-reference = \"path.\" name\n body-reference = \"body\" [\"#\" json-pointer ]\n json-pointer = *( \"/\" reference-token )\n reference-token = *( unescaped / escaped )\n unescaped = %x00-2E / %x30-7D / %x7F-10FFFF\n ; %x2F ('/') and %x7E ('~') are excluded from 'unescaped'\n escaped = \"~\" ( \"0\" / \"1\" )\n ; representing '~' and '/', respectively\n name = *( CHAR )\n token = 1*tchar\n tchar = \"!\" / \"#\" / \"$\" / \"%\" / \"&\" / \"'\" / \"*\" / \"+\" / \"-\" / \".\" /\n \"^\" / \"_\" / \"`\" / \"|\" / \"~\" / DIGIT / ALPHA\n```\n\n#### Examples\n\nSource Location | example expression | notes\n---|:---|:---|\nHTTP Method | `$method` | The allowable values for the `$method` will be those for the HTTP operation.\nRequested media type | `$request.header.accept` |\nRequest 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.\nRequest body property | `$request.body#/user/uuid` | In operations which accept payloads, references may be made to portions of the `requestBody` or the entire body.\nRequest URL | `$url` |\nResponse value | `$response.body#/status` | In operations which return payloads, references may be made to portions of the response body or the entire body.\nResponse header | `$response.header.Server` | Single header values only are available\nworkflow input | `$inputs.username` or `$workflows.foo.inputs.username` | Single input values only are available\nStep 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.\nWorkflow output value | `$outputs.bar` or `$workflows.foo.outputs.bar` | Single input values only are available\nComponents parameter | `$components.parameters.foo` | Accesses a foo parameter defined within the Components Object.\n\nRuntime expressions preserve the type of the referenced value.\nExpressions can be embedded into string values by surrounding the expression with `{}` curly braces.\n\n\n### Specification Extensions\n\nWhile the Arazzo Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points.\n\nThe extension properties are implemented as patterned fields that are always prefixed by `\"x-\"`.\n\nField Pattern | Type | Description\n---|:---:|---\n^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.\n\nThe 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).\n\n## Security Considerations\n\nThe 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.\n\nArazzo 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.\n\nArazzo 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.\n\n## IANA Considerations\n\nThe proposed MIME media types for the Arazzo Specification are described below.\n\n### application/vnd.oai.workflows\n\nThe default (or general) MIME type for Arazzo documents (e.g. workflows) is defined as follows:\n\n  Media type name: application\n\n  Media subtype name: vnd.oai.workflows\n\n  Required parameters: N/A\n\n  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).\n\n  Encoding considerations: Encoding considerations are identical to those specified for the `application/json` and `application/yaml` media types, respectively.\n\n  Security considerations: See [security considerations](#security-considerations) above.\n\n  Interoperability considerations: N/A\n\n**Note:** When using the `application/vnd.oai.workflows` media type the consumer should be prepared to receive YAML formatted content\n\n### application/vnd.oai.workflows+json\n\nThe proposed MIME media type for Arazzo documents (e.g. workflows) that require a JSON-specific media type is defined as follows:\n\n  Media type name: application\n\n  Media subtype name: vnd.oai.workflows+json\n\n  Required parameters: N/A\n\n  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).\n\n  Encoding considerations: Encoding considerations are identical to those specified for the `application/json` media type.\n\n  Security considerations: See [security considerations](#security-considerations) above.\n\n  Interoperability considerations: N/A\n\n### application/vnd.oai.workflows+yaml\n\nThe proposed MIME media type for Arazzo documents (e.g. workflows) that require a YAML-specific media type is defined as follows:\n\n  Media type name: application\n\n  Media subtype name: vnd.oai.workflows+yaml\n\n  Required parameters: N/A\n\n  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).\n\n  Encoding considerations: Encoding considerations are identical to those specified for the `application/yaml` media type.\n\n  Security considerations: See [security considerations](#security-considerations) above.\n\n  Interoperability considerations: N/A\n\n## Appendix A: Revision History\n\nVersion | Date | Notes\n--- | --- | ---\n1.0.0 | 2024-05-29 | First release of the Arazzo Specification" }, { "path": "versions/1.0.1.md", "content": "# Arazzo Specification\n\n#### Version 1.0.1\n\nThe 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.\n\nThis document is licensed under [The Apache License, Version 2.0](https://www.apache.org/licenses/LICENSE-2.0.html).\n\n## Introduction\n\nBeing 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).\n\nThe 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.\n\n\n## Table of Contents\n\n- [Definitions](#definitions)\n - [Arazzo Description](#arazzo-description)\n- [Specification](#specification)\n - [Versions](#versions)\n - [Format](#format)\n - [Arazzo Description Structure](#arazzo-description-structure)\n - [Data Types](#data-types)\n - [Relative References in URLs](#relative-references-in-urls)\n - [Schema](#schema)\n - [Arazzo Specification Object](#arazzo-specification-object)\n - [Info Object](#info-object)\n - [Source Description Object](#source-description-object)\n - [Workflow Object](#workflow-object)\n - [Step Object](#step-object)\n - [Parameter Object](#parameter-object)\n - [Success Action Object](#success-action-object)\n - [Failure Action Object](#failure-action-object)\n - [Components Object](#components-object)\n - [Reusable Object](#reusable-object)\n - [Criterion Object](#criterion-object)\n - [Request Body Object](#request-body-object)\n - [Payload Replacement Object](#payload-replacement-object)\n - [Runtime Expressions](#runtime-expressions)\n - [Specification Extensions](#specification-extensions)\n - [Security Considerations](#security-considerations)\n - [IANA Considerations](#iana-considerations)\n- [Appendix A: Revision History](#appendix-a-revision-history)\n\n\n## Definitions\n\n##### Arazzo Description\nA 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.\n\n## Specification\n\n### Versions\n\nThe 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.\n\n### Format\n\nAn Arazzo Description that conforms to the Arazzo Specification is itself a JSON object, which may be represented either in JSON or YAML format.\n\nAll field names in the specification are **case sensitive**.\nThis includes all fields that are used as keys in a map, except where explicitly noted that keys are **case insensitive**.\n\nIn 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:\n\n- Tags MUST be limited to those allowed by the [JSON Schema ruleset](https://yaml.org/spec/1.2/spec.html#id2803231).\n- 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).\n\n### Arazzo Description Structure\n\nIt is RECOMMENDED that the entry Arazzo document be named: `arazzo.json` or `arazzo.yaml`.\n\nAn 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**.\n\n### Data Types\n\nData 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.\n\nAs 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.\n\nThe formats defined are:\n[`type`](#data-types) | `format` | Comments\n------ | -------- | --------\n`integer` | `int32` | signed 32 bits\n`integer` | `int64` | signed 64 bits (a.k.a long)\n`number` | `float` | |\n`number` | `double` | |\n`string` | `password` | A hint to UIs to obscure input.\n\n\n### Relative References in URLs\n\nUnless specified otherwise, all properties that are URLs MAY be relative references as defined by [RFC3986](https://tools.ietf.org/html/rfc3986#section-4.2).\nUnless specified otherwise, relative references are resolved using the URL of the referring document.\n\n### Schema\n\nIn the following description, if a field is not explicitly **REQUIRED** or described with a MUST or SHALL, it can be considered OPTIONAL.\n\n#### Arazzo Specification Object\n\nThis is the root object of the [Arazzo Description](#arazzo-description).\n\n##### Fixed Fields\n\nField Name | Type | Description\n---|:---:|---\narazzo | `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.\ninfo | [Info Object](#info-object) | **REQUIRED**. Provides metadata about the workflows contain within the Arazzo Description. The metadata MAY be used by tooling as required.\nsourceDescriptions | [[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.\nworkflows | [[Workflow Object](#workflow-object)] | **REQUIRED**. A list of workflows. The list MUST have at least one entry.\ncomponents | [Components Object](#components-object) | An element to hold various schemas for the Arazzo Description.\n\nThis object MAY be extended with [Specification Extensions](#specification-extensions).\n\n##### Arazzo Specification Object Example\n\n```yaml\narazzo: 1.0.1\ninfo:\n title: A pet purchasing workflow\n summary: This Arazzo Description showcases the workflow for how to purchase a pet through a sequence of API calls\n description: |\n This Arazzo Description walks you through the workflow and steps of `searching` for, `selecting`, and `purchasing` an available pet.\n version: 1.0.1\nsourceDescriptions:\n- name: petStoreDescription\n url: https://github.com/swagger-api/swagger-petstore/blob/master/src/main/resources/openapi.yaml\n type: openapi\n\nworkflows:\n- workflowId: loginUserAndRetrievePet\n summary: Login User and then retrieve pets\n description: This workflow lays out the steps to login a user and then retrieve pets\n inputs:\n type: object\n properties:\n username:\n type: string\n password:\n type: string\n steps:\n - stepId: loginStep\n description: This step demonstrates the user login step\n operationId: loginUser\n parameters:\n # parameters to inject into the loginUser operation (parameter name must be resolvable at the referenced operation and the value is determined using {expression} syntax)\n - name: username\n in: query\n value: $inputs.username\n - name: password\n in: query\n value: $inputs.password\n successCriteria:\n # assertions to determine step was successful\n - condition: $statusCode == 200\n outputs:\n # outputs from this step\n tokenExpires: $response.header.X-Expires-After\n rateLimit: $response.header.X-Rate-Limit\n sessionToken: $response.body\n - stepId: getPetStep\n description: retrieve a pet by status from the GET pets endpoint\n operationPath: '{$sourceDescriptions.petstoreDescription.url}#/paths/~1pet~1findByStatus/get'\n parameters:\n - name: status\n in: query\n value: 'available'\n - name: Authorization\n in: header\n value: $steps.loginUser.outputs.sessionToken\n successCriteria:\n - condition: $statusCode == 200\n outputs:\n # outputs from this step\n availablePets: $response.body\n outputs:\n available: $steps.getPetStep.outputs.availablePets\n```\n\n#### Info Object\n\nThe object provides metadata about API workflows defined in this Arazzo document.\nThe metadata MAY be used by the clients if needed.\n\n##### Fixed Fields\n\nField Name | Type | Description\n---|:---:|---\ntitle | `string` | **REQUIRED**. A human readable title of the Arazzo Description.\nsummary | `string` | A short summary of the Arazzo Description.\ndescription | `string` | A description of the purpose of the workflows defined. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.\nversion | `string` | **REQUIRED**. The version identifier of the Arazzo document (which is distinct from the [Arazzo Specification version](#versions)).\n\n\nThis object MAY be extended with [Specification Extensions](#specification-extensions).\n\n##### Info Object Example\n\n```yaml\ntitle: A pet purchasing workflow\nsummary: This workflow showcases how to purchase a pet through a sequence of API calls\ndescription: |\n This workflow walks you through the steps of searching for, selecting, and purchasing an available pet.\nversion: 1.0.1\n```\n\n#### Source Description Object\n\nDescribes a source description (such as an OpenAPI description) that will be referenced by one or more workflows described within an Arazzo Description.\n\nAn 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).\n\n##### Fixed Fields\n\nField Name | Type | Description\n---|:---:|---\nname | `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_\\-]+`.\nurl | `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).\ntype | `string` | The type of source description. Possible values are `\"openapi\"` or `\"arazzo\"`.\n\n\nThis object MAY be extended with [Specification Extensions](#specification-extensions).\n\n##### Source Description Object Example\n\n```yaml\nname: petStoreDescription\nurl: https://github.com/swagger-api/swagger-petstore/blob/master/src/main/resources/openapi.yaml\ntype: openapi\n```\n\n#### Workflow Object\n\nDescribes 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.\n\n##### Fixed Fields\n\nField Name | Type | Description\n---|:---:|---\nworkflowId | `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_\\-]+`.\nsummary | `string` | A summary of the purpose or objective of the workflow.\ndescription | `string` | A description of the workflow. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.\ninputs | `JSON Schema` | A JSON Schema 2020-12 object representing the input parameters used by this workflow.\ndependsOn | [`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.\nsteps | [[Step Object](#step-object)] | **REQUIRED**. An ordered list of steps where each step represents a call to an API operation or to another workflow.\nsuccessActions | [[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.\nfailureActions | [[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.\noutputs | 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\\.\\-_]+$`.\nparameters | [[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.\n\n\nThis object MAY be extended with [Specification Extensions](#specification-extensions).\n\n##### Workflow Object Example\n\n```yaml\nworkflowId: loginUser\nsummary: Login User\ndescription: This workflow lays out the steps to login a user\ninputs:\n type: object\n properties:\n username:\n type: string\n password:\n type: string\nsteps:\n - stepId: loginStep\n description: This step demonstrates the user login step\n operationId: loginUser\n parameters:\n # parameters to inject into the loginUser operation (parameter name must be resolvable at the referenced operation and the value is determined using {expression} syntax)\n - name: username\n in: query\n value: $inputs.username\n - name: password\n in: query\n value: $inputs.password\n successCriteria:\n # assertions to determine step was successful \n - condition: $statusCode == 200\n outputs:\n # outputs from this step\n tokenExpires: $response.header.X-Expires-After\n rateLimit: $response.header.X-Rate-Limit\noutputs:\n tokenExpires: $steps.loginStep.outputs.tokenExpires\n```\n\n#### Step Object\n\nDescribes 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).\n\n##### Fixed Fields\n\nField Name | Type | Description\n---|:---:|---\ndescription | `string` | A description of the step. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.\nstepId | `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_\\-]+`.\noperationId | `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.\noperationPath | `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`.\nworkflowId | `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.\nparameters | [[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.\nrequestBody | [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.\nsuccessCriteria | [[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.\nonSuccess | [[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.\nonFailure | [[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.\noutputs | 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\\.\\-_]+$`.\n\nThis object MAY be extended with [Specification Extensions](#specification-extensions).\n\n##### Step Object Example\n\n**Single step**\n\n```yaml\nstepId: loginStep\ndescription: This step demonstrates the user login step\noperationId: loginUser\nparameters:\n # parameters to inject into the loginUser operation (parameter name must be resolvable at the referenced operation and the value is determined using {expression} syntax)\n - name: username\n in: query\n value: $inputs.username\n - name: password\n in: query\n value: $inputs.password\nsuccessCriteria:\n # assertions to determine step was successful\n - condition: $statusCode == 200\noutputs:\n # outputs from this step\n tokenExpires: $response.header.X-Expires-After\n rateLimit: $response.header.X-Rate-Limit\n```\n\n**Multiple steps**\n\n```yaml\nsteps:\n - stepId: loginStep\n description: This step demonstrates the user login step\n operationId: loginUser\n parameters:\n # parameters to inject into the loginUser operation (parameter name must be resolvable at the referenced operation and the value is determined using {expression} syntax)\n - name: username\n in: query\n value: $inputs.username\n - name: password\n in: query\n value: $inputs.password\n successCriteria:\n # assertions to determine step was successful\n - condition: $statusCode == 200\n outputs:\n # outputs from this step\n tokenExpires: $response.header.X-Expires-After\n rateLimit: $response.header.X-Rate-Limit\n sessionToken: $response.body\n - stepId: getPetStep\n description: retrieve a pet by status from the GET pets endpoint\n operationPath: '{$sourceDescriptions.petStoreDescription.url}#/paths/~1pet~1findByStatus/get'\n parameters:\n - name: status\n in: query\n value: 'available'\n - name: Authorization\n in: header\n value: $steps.loginUser.outputs.sessionToken\n successCriteria:\n - condition: $statusCode == 200\n outputs:\n # outputs from this step\n availablePets: $response.body\n```\n\n#### Parameter Object\n\nDescribes 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:\n - 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`.\n - query - Parameters that are appended to the URL. For example, in `/items?id=###`, the query parameter is `id`.\n - 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.\n - cookie - Used to pass a specific cookie value to the source API.\n\n##### Fixed Fields\nField Name | Type | Description\n---|:---:|---\n name | `string` | **REQUIRED**. The name of the parameter. Parameter names are _case sensitive_.\n 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.\n 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.\n\nThis object MAY be extended with [Specification Extensions](#specification-extensions).\n\n##### Parameter Object Example\n**Query Example**\n\n```yaml\n- name: username\n in: query\n value: $inputs.username\n```\n\n**Header Example**\n\n```yaml\n- name: X-Api-Key\n in: header\n value: $inputs.x-api-key\n```\n\n#### Success Action Object\n\nA single success action which describes an action to take upon success of a workflow step. There are two possible values for the `type` field.\n - end - The workflow ends, and context returns to the caller with applicable outputs\n - goto - A one-way transfer of workflow control to the specified label (either a `workflowId` or `stepId`)\n\n##### Fixed Fields\nField Name | Type | Description\n---|:---:|---\n name | `string` | **REQUIRED**. The name of the success action. Names are _case sensitive_.\n type | `string` | **REQUIRED**. The type of action to take. Possible values are `\"end\"` or `\"goto\"`.\n 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`.\n 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`.\n 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.\n\n\n\nThis object MAY be extended with [Specification Extensions](#specification-extensions).\n\n##### Success Action Object Example\n\n```yaml\nname: JoinWaitingList\ntype: goto\nstepId: joinWaitingListStep\ncriteria:\n # assertions to determine if this success action should be executed\n - context: $response.body\n condition: $[?count(@.pets) > 0]\n type: jsonpath\n```\n\n#### Failure Action Object\n\nA single failure action which describes an action to take upon failure of a workflow step. There are three possible values for the `type` field.\n - end - The workflow ends, and context returns to the caller with applicable outputs\n - 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.\n - goto - A one-way transfer of workflow control to the specified label (either a `workflowId` or `stepId`)\n\n##### Fixed Fields\nField Name | Type | Description\n---|:---:|---\n name | `string` | **REQUIRED**. The name of the failure action. Names are _case sensitive_.\n type | `string` | **REQUIRED**. The type of action to take. Possible values are `\"end\"`, `\"retry\"`, or `\"goto\"`.\n 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.\n 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.\n 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\"`.\n 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.\n 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).\n\n\nThis object MAY be extended with [Specification Extensions](#specification-extensions).\n\n##### Failure Action Object Example\n\n```yaml\nname: retryStep\ntype: retry\nretryAfter: 1\nretryLimit: 5\ncriteria:\n # assertions to determine if this action should be executed\n - condition: $statusCode == 503\n```\n\n#### Components Object\n\nHolds 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.\n\nComponents 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\".\n\n##### Fixed Fields\n\nField Name | Type | Description\n---|:---|---\n inputs | Map[`string`, `JSON Schema`] | An object to hold reusable JSON Schema objects to be referenced from workflow inputs.\nparameters | Map[`string`, [Parameter Object](#parameter-object)] | An object to hold reusable Parameter Objects\nsuccessActions | Map[`string`, [Success Action Object](#success-action-object)] | An object to hold reusable Success Actions Objects.\nfailureActions | Map[`string`, [Failure Action Object](#failure-action-object)] | An object to hold reusable Failure Actions Objects.\n\nThis object MAY be extended with [Specification Extensions](#specification-extensions).\n\n\nAll 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.\n\nField Name Examples:\n\n```\nUser\nUser_1\nUser_Name\nuser-name\nmy.org.User\n```\n\n##### Components Object Example\n\n```yaml\ncomponents:\n parameters:\n storeId:\n name: storeId\n in: header\n value: $inputs.x-store-id\n inputs:\n pagination:\n type: object\n properties:\n page:\n type: integer\n format: int32\n pageSize:\n type: integer\n format: int32\n failureActions:\n refreshToken:\n name: refreshExpiredToken\n type: retry\n retryAfter: 1\n retryLimit: 5\n workflowId: refreshTokenWorkflowId\n criteria:\n # assertions to determine if this action should be executed\n - condition: $statusCode == 401 \n```\n\n```json\n\"components\": {\n \"parameters\": {\n \"storeId\": {\n \"name\": \"storeId\",\n \"in\": \"header\",\n \"value\": \"$inputs.x-store-id\"\n }\n },\n \"inputs\": {\n \"pagination\": {\n \"type\": \"object\",\n \"properties\": {\n \"page\": {\n \"type\": \"integer\",\n \"format\": \"int32\"\n },\n \"pageSize\": {\n \"type\": \"integer\",\n \"format\": \"int32\"\n }\n }\n }\n },\n \"failureActions\": {\n \"refreshToken\": {\n \"name\": \"refreshExpiredToken\",\n \"type\": \"retry\",\n \"retryAfter\": 1,\n \"retryLimit\": 5,\n \"workflowId\": \"refreshTokenWorkflowId\",\n \"criteria\": [\n {\n \"condition\": \"{$statusCode == 401}\"\n }\n ]\n }\n }\n}\n```\n\n#### Reusable Object\n\nA 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.\n\n\n##### Fixed Fields\nField Name | Type | Description\n---|:---:|---\nreference | `{expression}` | **REQUIRED**. A [Runtime Expression](#runtime-expressions) used to reference the desired object.\nvalue | `string` | Sets a value of the referenced parameter. This is only applicable for parameter object references.\n\nThis object cannot be extended with additional properties and any properties added MUST be ignored.\n\n##### Reusable Object Example\n\n```yaml\n reference: $components.successActions.notify\n```\n\n```json\n {\n \"reference\": \"$components.successActions.notify\"\n }\n```\n\n```yaml\n reference: $components.parameters.page\n value: 1\n```\n\n```json\n {\n \"reference\": \"$components.parameters.page\",\n \"value\": 1\n }\n```\n\n#### Criterion Object\n\nAn 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`.\n\nThere are four flavors of conditions supported:\n- simple - where basic literals, operators, and loose comparisons are used in combination with [Runtime Expressions](#runtime-expressions).\n- regex - where a regex pattern is applied on the supplied context. The context is defined by a [Runtime Expression](#runtime-expressions).\n- jsonpath - where a JSONPath expression is applied. The root node context is defined by a [Runtime Expression](#runtime-expressions).\n- xpath - where an XPath expression is applied. The root node context is defined by a [Runtime Expression](#runtime-expressions).\n\n##### Literals\nAs part of a condition expression, you can use `boolean`, `null`, `number`, or `string` data types.\n\nType | Literal value\n---|---\n`boolean` | `true` or `false`\n`null` | `null`\n`number` | Any number format supported in [Data Types](#data-types)\n`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 ('').\n\n##### Operators\nOperator | Description\n---|---\n`<`| Less than\n`<=`| Less than or equal\n`>`| Greater than\n`>=`| Greater than or equal\n`==`| Equal\n`!=`| Not equal\n`!`| Not\n`&&`| And\n\\|\\|| Or\n`()`| Logical Grouping\n`[]`| Index (0-based)\n`.`| Property de-reference\n\nString comparisons `MUST` be case insensitive.\n\n##### Fixed Fields\nField Name | Type | Description\n---|:---:|---\ncontext | `{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).\ncondition | `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.\ntype | `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.\n\n\nThis object MAY be extended with [Specification Extensions](#specification-extensions).\n\n##### Criterion Object Example\n\n**Simple Condition Example**\n\n```yaml\n- condition: $statusCode == 200\n```\n\n**Regex Condition Example**\n```yaml\n- context: $statusCode\n condition: '^200$'\n type: regex\n```\n\n**JSONPath Condition Example**\n```yaml\n- context: $response.body\n condition: $[?count(@.pets) > 0]\n type: jsonpath\n```\n\n#### Criterion Expression Type Object\n\nAn 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:\n - JSONPath as described by [RFC9535](https://tools.ietf.org/html/rfc9535)\n - XPath as described by [XML Path Language 3.1](https://www.w3.org/TR/xpath-31)\n\nDefining this object gives the ability to utilize tooling compatible with older versions of either JSONPath or XPath.\n\n##### Fixed Fields\nField Name | Type | Description\n---|:---:|---\ntype | `string` | **REQUIRED**. The type of condition to be applied. The options allowed are `jsonpath` or `xpath`. \nversion | `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`.\n\nThis object MAY be extended with [Specification Extensions](#specification-extensions).\n\n##### Criterion Expression Type Example\n\n**JSONPath Example**\n```yaml\n type: jsonpath\n version: draft-goessner-dispatch-jsonpath-00\n```\n\n**XPath Example**\n```yaml\n type: xpath\n version: xpath-30\n```\n\n#### Request Body Object\n\nA single request body describing the `Content-Type` and request body content to be passed by a step to an operation.\n\n##### Fixed Fields\nField Name | Type | Description\n---|:---:|---\ncontentType | `string` | The Content-Type for the request content. If omitted then refer to Content-Type specified at the targeted operation to understand serialization requirements.\npayload | 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.\nreplacements | [[Payload Replacement Object](#payload-replacement-object)] | A list of locations and values to set within a payload.\n\nThis object MAY be extended with [Specification Extensions](#specification-extensions).\n\n##### RequestBody Object Example\n\n**JSON Templated Example**\n```yaml\n contentType: application/json\n payload: |\n {\n \"petOrder\": {\n \"petId\": \"{$inputs.pet_id}\",\n \"couponCode\": \"{$inputs.coupon_code}\",\n \"quantity\": \"{$inputs.quantity}\",\n \"status\": \"placed\",\n \"complete\": false\n }\n }\n```\n\n**JSON Object Example**\n```yaml\n contentType: application/json\n payload: \n petOrder:\n petId: $inputs.pet_id\n couponCode: $inputs.coupon_code\n quantity: $inputs.quantity\n status: placed\n complete: false\n```\n\n**Complete Runtime Expression**\n```yaml\n contentType: application/json\n payload: $inputs.petOrderRequest\n```\n\n**XML Templated Example**\n```yaml\n contentType: application/xml\n payload: |\n \n {$inputs.pet_id}\n {$inputs.coupon_code}\n {$inputs.quantity}\n placed\n false\n \n```\n\n**Form Data Example**\n```yaml\n contentType: application/x-www-form-urlencoded\n payload: \n client_id: $inputs.clientId\n grant_type: $inputs.grantType\n redirect_uri: $inputs.redirectUri\n client_secret: $inputs.clientSecret\n code: $steps.browser-authorize.outputs.code\n scope: $inputs.scope \n``` \n\n**Form Data String Example**\n```yaml\n contentType: application/x-www-form-urlencoded\n 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}\"\n```\n\n#### Payload Replacement Object\nDescribes a location within a payload (e.g., a request body) and a value to set within the location. \n\n##### Fixed Fields\nField Name | Type | Description\n---|:---:|---\ntarget | `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`.\n 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.\n\nThis object MAY be extended with [Specification Extensions](#specification-extensions).\n\n##### Payload Replacement Object Example\n\n**Runtime Expression Example**\n```yaml\n target: /petId\n value: $inputs.pet_id\n```\n\n**Literal Example**\n```yaml\n target: /quantity\n value: 10\n```\n\n\n### Runtime Expressions\nA 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).\n\nThe runtime expression is defined by the following [ABNF](https://tools.ietf.org/html/rfc5234) syntax:\n\n```abnf\n expression = ( \"$url\" / \"$method\" / \"$statusCode\" / \"$request.\" source / \"$response.\" source / \"$inputs.\" name / \"$outputs.\" name / \"$steps.\" name / \"$workflows.\" name / \"$sourceDescriptions.\" name / \"$components.\" name / \"$components.parameters.\" parameter-name)\n parameter-name = name ; Reuses 'name' rule for parameter names\n source = ( header-reference / query-reference / path-reference / body-reference )\n header-reference = \"header.\" token\n query-reference = \"query.\" name\n path-reference = \"path.\" name\n body-reference = \"body\" [\"#\" json-pointer ]\n json-pointer = *( \"/\" reference-token )\n reference-token = *( unescaped / escaped )\n unescaped = %x00-2E / %x30-7D / %x7F-10FFFF\n ; %x2F ('/') and %x7E ('~') are excluded from 'unescaped'\n escaped = \"~\" ( \"0\" / \"1\" )\n ; representing '~' and '/', respectively\n name = *( CHAR )\n token = 1*tchar\n tchar = \"!\" / \"#\" / \"$\" / \"%\" / \"&\" / \"'\" / \"*\" / \"+\" / \"-\" / \".\" /\n \"^\" / \"_\" / \"`\" / \"|\" / \"~\" / DIGIT / ALPHA\n```\n\n#### Examples\n\nSource Location | example expression | notes\n---|:---|:---|\nHTTP Method | `$method` | The allowable values for the `$method` will be those for the HTTP operation.\nRequested media type | `$request.header.accept` |\nRequest 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.\nRequest body property | `$request.body#/user/uuid` | In operations which accept payloads, references may be made to portions of the `requestBody` or the entire body.\nRequest URL | `$url` |\nResponse value | `$response.body#/status` | In operations which return payloads, references may be made to portions of the response body or the entire body.\nResponse header | `$response.header.Server` | Single header values only are available\nworkflow input | `$inputs.username` or `$workflows.foo.inputs.username` | Single input values only are available\nStep 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.\nWorkflow 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.\nComponents parameter | `$components.parameters.foo` | Accesses a foo parameter defined within the Components Object.\n\nRuntime expressions preserve the type of the referenced value.\nExpressions can be embedded into string values by surrounding the expression with `{}` curly braces.\n\n\n### Specification Extensions\n\nWhile the Arazzo Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points.\n\nThe extension properties are implemented as patterned fields that are always prefixed by `\"x-\"`.\n\nField Pattern | Type | Description\n---|:---:|---\n^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.\n\nThe 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).\n\n## Security Considerations\n\nThe 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.\n\nArazzo 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.\n\nArazzo 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.\n\n## IANA Considerations\n\nThe proposed MIME media types for the Arazzo Specification are described below.\n\n### application/vnd.oai.workflows\n\nThe default (or general) MIME type for Arazzo documents (e.g. workflows) is defined as follows:\n\n  Media type name: application\n\n  Media subtype name: vnd.oai.workflows\n\n  Required parameters: N/A\n\n  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).\n\n  Encoding considerations: Encoding considerations are identical to those specified for the `application/json` and `application/yaml` media types, respectively.\n\n  Security considerations: See [security considerations](#security-considerations) above.\n\n  Interoperability considerations: N/A\n\n**Note:** When using the `application/vnd.oai.workflows` media type the consumer should be prepared to receive YAML formatted content\n\n### application/vnd.oai.workflows+json\n\nThe proposed MIME media type for Arazzo documents (e.g. workflows) that require a JSON-specific media type is defined as follows:\n\n  Media type name: application\n\n  Media subtype name: vnd.oai.workflows+json\n\n  Required parameters: N/A\n\n  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).\n\n  Encoding considerations: Encoding considerations are identical to those specified for the `application/json` media type.\n\n  Security considerations: See [security considerations](#security-considerations) above.\n\n  Interoperability considerations: N/A\n\n### application/vnd.oai.workflows+yaml\n\nThe proposed MIME media type for Arazzo documents (e.g. workflows) that require a YAML-specific media type is defined as follows:\n\n  Media type name: application\n\n  Media subtype name: vnd.oai.workflows+yaml\n\n  Required parameters: N/A\n\n  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).\n\n  Encoding considerations: Encoding considerations are identical to those specified for the `application/yaml` media type.\n\n  Security considerations: See [security considerations](#security-considerations) above.\n\n  Interoperability considerations: N/A\n\n## Appendix A: Revision History\n\nVersion | Date | Notes\n--- | --- | ---\n1.0.1 | 2025-01-16 | Patch release of the Arazzo Specification 1.0.1\n1.0.0 | 2024-05-29 | First release of the Arazzo Specification\n" } ]